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
|
||||
|
||||
## 中文回复
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# ADR 0001:个人品牌平台架构边界
|
||||
|
||||
- 状态:已采纳
|
||||
- 日期:2026-09-19
|
||||
|
||||
## 背景
|
||||
|
||||
产品需要支持个人品牌信任建设,同时允许餐饮、咨询、设计、摄影等行业模板复用。后台负责配置内容,小程序和其他客户端负责渲染与提交。
|
||||
|
||||
## 决策
|
||||
|
||||
- API 使用 NestJS + Prisma,Controller 负责 HTTP 边界,Service 负责业务规则,DTO 负责运行时输入校验。
|
||||
- 共享 API Client 和 types 作为客户端契约,接口变更必须同步测试和调用方。
|
||||
- 管理后台使用 React + Ant Design + TanStack Query + React Router,按 feature 拆分页面。
|
||||
- 品牌内容、服务、信任内容和行业字段由后台配置驱动;客户端不得写死行业业务规则。
|
||||
- 认证、授权、品牌隔离和统一错误响应属于平台基础设施,业务 feature 不得各自实现一套。
|
||||
|
||||
## 备选方案
|
||||
|
||||
- 继续在单个 React 入口文件中实现所有页面:短期速度快,但会造成状态、请求和业务耦合,拒绝采用。
|
||||
- 让小程序直接维护服务和文案:上线简单,但无法支持后台配置和多行业模板,拒绝采用。
|
||||
- 让 Controller 直接操作 Prisma:初期代码少,但业务规则无法复用且测试困难,拒绝采用。
|
||||
|
||||
## 后果
|
||||
|
||||
- 初期需要更多目录和契约代码,但能够降低行业扩展和后台迭代的返工成本。
|
||||
- 每个接口都需要同步类型、测试和客户端调用,交付速度以可验证性为优先。
|
||||
- 后续新增行业时优先新增模板配置与校验,不修改个人品牌核心模型。
|
||||
Reference in new issue
Block a user