From 3c24235ad4e19e142e76ae1712ba0e664f9f5329 Mon Sep 17 00:00:00 2001 From: que01 Date: Sat, 19 Sep 2026 18:39:55 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E4=B8=8E=E4=BA=A4=E4=BB=98=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) 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 ## 中文回复