Team10： Code Standards — StudentSys / Campus Smart Service (Beta Phase)

date: 2025.12.29
tags: [SoftwareEngineering, BetaSprint, CodeStandards, StudentSys]

Project entry:http://159.75.26.213
This post defines our team’s coding and collaboration standards for the Beta stage, so we can reduce integration bugs, avoid “works on my machine” failures, and make deployment reproducible.

1. Why We Need Code Standards (Lessons from Alpha)

During Alpha, many problems were not caused by “hard algorithms”, but by:

• inconsistent endpoints and route prefixes

• environment variables not synchronized or not loaded by the running process

• ad-hoc server edits without PR review

• unclear ownership (“everyone fixes everything”)

So in Beta we enforce standards to make our workrepeatable, reviewable, and deployable.

2. Repository Structure (Single Source of Truth)

We keep a clear top-level structure so every member knows where to work.

Recommended layout

StudentSys/ backend/ # Node.js/Express REST API frontend/ # Web UI python_services/ # FastAPI services (face/takeout/crowd/traffic) docs/ # API + deployment + conventions scripts/ # health checks, setup helpers infra/ # nginx/systemd/pm2 config templates README.md .env.example

Rules

• No “random” files at root except repo-wide configs and README.

• Anything deployment-related must be tracked indocs/+infra/.

• A new module must include:

  • code folder

  • minimal README

  • known ports/endpoints documented indocs/

3. Branching Strategy (Simple & Enforceable)

We use a lightweight Git flow suitable for course projects.

• main: alwaysdemo-ready(stable, runnable)

• dev: integration branch for ongoing work (optional if team prefers main-only with PRs)

• feature/<module>-<short-desc>: new features

• fix/<bug>-<short-desc>: bugfixes

• docs/<topic>: documentation-only changes

Rules

• Never push directly tomain.

• All merges tomainmust go through PR + review.

• Hotfix allowed only when demo is blocked, but still via PR.

4. Issue Workflow (Everything Non-trivial Has an Issue)

For Beta sprint blogs, dev progress must be backed by Issues/PRs. We standardize that here.

Issue must include

• Title:[Module] short description

• Background / expected behavior

• Acceptance criteria (how we know it’s done)

• Labels:frontend,backend,ai-service,docs,bug,enhancement,deployment

• Assignee + estimated effort (small/medium/large)

Definition of Done

• Code merged via PR

• Basic local test passed

• Endpoint/docs updated if interface changed

• Screenshot/log evidence if required by sprint blog

5. Pull Request (PR) Rules

PRs are not optional—they are our safety net.

PR title format

• feat(frontend): ...

• fix(backend): ...

• docs: ...

• chore(deploy): ...

PR description must include

• What changed and why

• Linked Issues:Closes #123

• Test evidence: how you verified (commands + screenshots where needed)

• Deployment impact: does this require env/nginx/systemd updates?

Minimal review checklist

• Code compiles/runs

• No secrets committed

• Routes/endpoints match docs

• Error handling is user-friendly (not raw stack traces)

• Logging added for key operations

• No breaking changes without notice

Optional evidence placeholder for blog:
[IMG_PLACEHOLDER: PR_review_screenshot.png]

6. Commit Message Convention

We use conventional commits to keep history readable and searchable.

Format

• feat: add takeout detection UI

• fix: correct DB env loading

• refactor: simplify router structure

• docs: update deployment checklist

• chore: update dependencies

Rules

• One commit = one logical change (avoid mixing unrelated changes)

• Commit early and often, but don’t commit broken builds to shared branches

7. Backend Standards (Node.js / Express)

7.1 API Design

• All backend routes must be under a consistent prefix, e.g./api/...

• Add health check endpoint (backend):/api/health

• Use consistent JSON response format:

Success

{ "code": 0, "message": "ok", "data": { ... } }

Error

{ "code": 1001, "message": "Invalid input", "hint": "Check email format", "data": null }

7.2 Error Handling

• Never return raw stack traces to frontend

• Log the internal error; return a user-friendly message

7.3 Configuration

• All sensitive config must come from environment variables

• Backend must fail fast with clear log output if env is missing

8. Database Standards (MySQL/MariaDB)

• Useleast privilegeDB user for runtime (notroot)

• DB migrations/initialization must be documented:

  • schema changes

  • required tables

  • seed data (if any)

• Changes that break schema require:

  • a short migration note indocs/DEPLOYMENT.md

  • coordination with backend owners

9. Python AI Services Standards (FastAPI/Uvicorn)

We have multiple services (face/takeout/crowd/traffic). Consistency matters.

9.1 Health Endpoints

Every service must expose:

• /health(returns 200 + simple JSON)

When proxied by Nginx, external access should be consistent:

• /api/face/health

• /api/takeout/health

• /api/crowd/health

• /api/traffic/health

9.2 Dependency Rules

• requirements.txtmust beplatform-neutral(no Windows wheels)

• System dependencies (e.g., OpenCV runtime libs) must be listed indocs/DEPLOYMENT.md

9.3 Runtime Rules

• CPU-first by default (GPU only if infrastructure confirmed)

• Add warm-up strategy if cold start is slow

• Log request info and inference timing (p50/p95 later if possible)

10. Frontend Standards

10.1 UI Consistency

• Use consistent navigation labels and page layout spacing

• Forms must validate input and show actionable errors

10.2 API Integration

• Centralize API base URL and request wrapper

• Handle common error codes:

  • 401/403: show login prompt

  • 404: show “feature not available / wrong route”

  • 500: show “system busy, try again” with retry suggestion

11. Documentation Rules

Docs are part of the deliverable, not optional.

Must-have docs

• docs/DEPLOYMENT.md

  • ports

  • env variables

  • system packages

  • restart commands (pm2/systemd)

  • nginx routing notes

• docs/API.md

  • routes + request/response examples

  • error codes

Rule

• If you change an endpoint, you must updatedocs/API.mdin the same PR.

12. Testing & Quality Baseline (Minimum Standard)

We keep it minimal but effective.

Required

• A simple “health check script” (bash) that curls all services

• Smoke test steps recorded in sprint blog (screenshots or terminal output)

Recommended

• ESLint/Prettier for frontend/backend formatting

• Python formatting tool (e.g., black) if feasible

13. Deployment Discipline (No More “Edit on Server”)

Rule

• No direct editing on production server without PR

• Deployment changes must be recorded:

  • updateinfra/configs

  • document indocs/DEPLOYMENT.md

Standard deployment checklist

• env check → DB check → service status check → health check → public access check

14. Ownership & Communication

To avoid duplicated work and missing tasks, we define module owners:

• Backend owner: API + DB integration

• Frontend owner: UI + integration

• Deployment owner: Nginx + pm2/systemd + env

• AI services owner: FastAPI services

If a change impacts another module, it must be communicated in Issue/PR description.

15. Conclusion

These standards are designed to reduce integration failures, increase collaboration efficiency, and make our Beta sprint outputsreviewable and demo-ready. In the next sprint blogs, we will enforce evidence-based reporting (Issues/PRs/results) and keep documentation synchronized with code changes.