58 lines
3.4 KiB
Markdown
58 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
## 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.
|