diff --git a/AGENTS.md b/AGENTS.md index 3b2f210..9b330cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,33 @@ - Any delivered backend endpoint must have an automated test covering its authorization and successful behavior before it is considered complete. - Keep personal-brand trust details explicit: biography, positioning, credentials, portfolio/proof, process, expectations, availability, contact methods, and clear follow-up status. +# Engineering Architecture Rules + +## Backend boundaries + +- NestJS controllers only handle transport concerns: authentication, DTO binding, status codes, and response shape. +- Domain behavior belongs in services; Prisma access must not be duplicated across controllers. +- DTOs are the runtime validation boundary. Do not use `Partial` or plain TypeScript interfaces as request bodies for validated endpoints. +- Every protected endpoint must test missing credentials, invalid credentials or wrong role, and the successful authorized path. +- Public endpoints may only expose published content and must enforce brand isolation through the configured brand identifier. + +## Admin frontend boundaries + +- React pages must be split by feature under `apps/admin/src/features//`; a page component should coordinate UI, not contain the entire application. +- Shared API construction, authentication-aware `fetch`, query keys, and error handling belong under `apps/admin/src/lib/`. +- Shared visual elements belong under `apps/admin/src/components/`; feature-specific forms and tables stay inside their feature module. +- Routing belongs in `apps/admin/src/app/` and navigation must use React Router. Do not use a local state variable as the primary page router. +- A mutation must close or reset a form only after `onSuccess`; failed requests must preserve user input and show an actionable error. +- API base URLs must come from `VITE_API_BASE_URL` with a documented local fallback; no feature may hard-code an environment-specific host. +- Admin session expiry must clear the token, notify the user, and return to the login screen consistently. + +## Formatting, testing, and delivery + +- Prettier is the formatting source of truth. New or changed files must pass `pnpm format:check`. +- Before delivery, run relevant type checks, API integration tests, and frontend production builds. Do not claim an endpoint is delivered without a passing automated test. +- Prefer cohesive commits that complete a reviewable unit of work; do not submit speculative fragments while the feature is broken. +- When a code review identifies a recurring design issue, update this file or a focused architecture document before implementing the next related feature. + # Codex Code Guidelines ## 中文回复