quyun-v2/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• backend/: Go API server (Fiber) + services + DB models/migrations.
  • backend/app/http/: HTTP modules (e.g. super/, tenant/, tenant_public/).
  • backend/app/services/: business logic; prefer GORM-Gen queries (backend/database/models/*).
  • backend/database/migrations/: SQL migrations.
  • backend/docs/: generated Swagger (swagger.json/yaml, docs.go).
• frontend/:
  • frontend/superadmin/: platform super admin UI (Vite + Vue 3 + PrimeVue).
  • frontend/portal/ : tenant admin/user apps.
• specs/: source-of-truth specs (e.g. DB schema).

Coding Style & Naming Conventions

• Backend rule of law: all backend development MUST follow backend/llm.txt (HTTP/module layout, generated-file rules, GORM-Gen usage, transactions, comments, and route conventions).
• Go: run gofmt on changed files; keep HTTP handlers thin (bind → services.* → return).
• Backend layering: controllers must not call models.*, models.Q.*, or raw *gorm.DB CRUD directly; all DAO/DB operations must live in backend/app/services/* (controller only does bind/validate → services.* → return).
• HTTP module directories are snake_case; path params are camelCase and prefer typed IDs like :orderID<int> to avoid route conflicts.
• Avoid editing generated files (e.g. backend/app/http/**/routes.gen.go, backend/docs/docs.go); regenerate via atomctl instead.

Testing Guidelines

• Go tests: go test ./... (some service tests exist under backend/app/services/*_test.go).
• Frontend: build + lint are the main checks (npm -C frontend/superadmin run build && npm -C frontend/superadmin run lint).

AI UI Testing References

When driving browser tests via Chrome DevTools MCP, consult:

• docs/seed_verification.md (full UI flow + MCP steps)
• frontend/portal/vite.config.js (proxy + port)
• frontend/superadmin/vite.config.mjs (proxy + port)
• frontend/portal/src/router/index.js (portal routes)
• frontend/superadmin/src/router/index.js (superadmin routes)
• backend/app/services/user.go (OTP rule: 1234)
• backend/app/commands/seed/seed.go (seed users/passwords)

Planning Requirements

• Before any non-trivial development work, first produce a complete plan document (tasks, sequence, dependencies, and acceptance criteria) and get confirmation to proceed.
• Plan format MUST follow spec-kit plan-template.md structure (Summary, Technical Context, Constitution Check, Project Structure, Plan Phases, Tasks, Dependencies, Acceptance Criteria, Risks). docs/plan.md MUST include a task breakdown list.
• Use the local template docs/templates/plan-template.md as the source of truth (no web fetch required).
• Use docs/plan.md as the active plan for the current phase.
• When the phase completes, move docs/plan.md to docs/plans/<date>.md for archival.
• After archiving, clear docs/plan.md to await the next plan.
• If a plan covers frontend interfaces, completion requires BOTH frontend functional testing of the impacted flows and backend go test ./...; only then may the plan be marked complete/archived.
• Acceptance for frontend-involved work must be validated via frontend page flows (browser/UI) to confirm front-back integration. curl/API smoke is allowed only for quick backend checks and does not count as acceptance for frontend-related tasks.

Commit & Pull Request Guidelines

• Commits generally follow a simple convention like feat: ... / fix: ... / chore: ... (keep subject short and imperative).
• PRs: describe behavior change, list impacted APIs/pages, and include screenshots for UI changes (especially frontend/superadmin/).

Security & Configuration Tips

• Configure API base via VITE_API_BASE_URL (superadmin).
• Keep secrets out of git; prefer local backend/config.toml overrides for DB/JWT settings.