docs: 完善工程治理与架构决策规范
This commit is contained in:
1 parent
3c24235ad4
commit
cfa183015b
2 files changed
+43
No files matched your search
@@ -35,6 +35,21 @@
|
||||
- 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.
|
||||
|
||||
## Production engineering standards
|
||||
|
||||
- Record material architectural decisions in `docs/adr/` using the format `NNNN-title.md`: context, decision, alternatives, consequences, and migration plan. Do not silently introduce a second state-management, validation, routing, or persistence pattern.
|
||||
- Treat the API Client types and DTOs as an explicit contract. Any response or request shape change must update the shared client, its tests, and the consuming feature in the same change.
|
||||
- Keep API responses consistent: successful payloads use the established envelope, errors use the global error filter with a stable machine-readable code and `requestId`. Never expose stack traces or database errors to clients.
|
||||
- Validate all external input at the boundary, use allow-lists for enums and template keys, and apply authorization before loading or mutating tenant/brand data. Never trust a client-supplied `brandId`.
|
||||
- Secrets and environment-specific URLs belong in environment configuration. Commit `.env.example`, never real credentials, and fail fast when a required production variable is missing.
|
||||
- Database changes must be additive and reversible where practical: update Prisma schema, migration, seed data, API behavior, and integration tests together. Avoid destructive migrations without an explicit migration plan.
|
||||
- Follow a testing pyramid: focused unit tests for pure domain rules, API integration tests for authorization and persistence, and a small number of frontend interaction tests for critical flows. Tests must isolate data and clean up fixtures.
|
||||
- Make asynchronous UI states explicit: loading, empty, error, success, and retry. Mutations must be idempotent where possible and must invalidate or update affected query caches.
|
||||
- Keep observability intentional: include `requestId` in errors and logs, log state-changing admin actions without secrets, and use structured log fields rather than concatenated messages.
|
||||
- Use dependency and type safety gates before merge: formatting, lint, typecheck, relevant tests, production build, and a clean diff. A known warning must be documented with an owner or follow-up issue.
|
||||
- Prefer small, cohesive modules with one reason to change. A feature may depend on shared infrastructure, but shared infrastructure must not import feature modules.
|
||||
- Public and admin behavior must be documented at the route or feature boundary, including authentication, roles, validation, status transitions, and failure behavior.
|
||||
|
||||
# Codex Code Guidelines
|
||||
|
||||
## 中文回复
|
||||
|
||||
Reference in new issue
Block a user