Files
persionalBrand/docs/code-standards.md

51 lines
3.0 KiB
Markdown

# 代码结构与重构标准
这份标准用于控制现有模块继续膨胀,并约束后续大文件重构。它不是替代 `docs/engineering-delivery-checklist.md`,而是补充结构边界。
## 通用规则
- 页面、Controller、Service 只保留一个明确入口;独立业务规则、数据映射、授权判断和视图状态必须拆出命名模块。
- 单文件超过 500 行必须提供拆分计划;超过 800 行应拆分。拆分要按职责,不按行数机械切分。
- 禁止在页面组件内内联完整 API 调用、复杂 JSON 转换和多层级业务规则。
- 禁止新增全局工具函数堆积文件;按领域模块导出,不建 `utils.ts` 黑洞。
- 迁移、DTO、API Client 类型、页面、测试和文档随行为一起变更。
## Admin React 标准
- 页面组件负责组合布局和路由;不直接实现超过一个相关领域的业务逻辑。
- 一个页面由以下边界组成:
- 页面组件:布局、路由、页面状态组合。
- hooks:数据查询、mutation、表单初始化、草稿与预览状态。
- 领域工具:纯函数,可单测,不调用 `fetch`。
- feature 组件:局部 UI 区块。
- shared components:跨 feature 使用的表单字段、状态和基础控件。
- React Query 的 query key、失效和成功提示统一放在 hooks 中;页面不要散落 `invalidateQueries`。
- 表单初始化、同步字段、脏检查和失败恢复不能重复实现;优先复用同一模块。
- 类型边界使用 API Client 导出类型,不在页面重建后端响应形状。
## API NestJS 标准
- Controller 只处理认证入口、DTO、状态码、响应形状和路由。
- 授权、Prisma、模板安装、快照组装、工作流推进必须进入 Service 或 Guard。
- 同一个领域不要分散在根目录和 modules 中;新代码必须归入领域模块,旧 Controller 重构时逐步迁移。
- DTO 是唯一输入边界;禁止 `Partial<T>`、`any`、未验证 JSON 和 Controller 内私有 schema。
- 授权测试、成功行为、失败路径和品牌隔离测试是结构重构不可删除的回归线。
## API Client 标准
- 按资源拆分方法模块和类型模块;`index.ts` 只做聚合导出和 Client 组装。
- 一个资源定义一组类型、一组方法、一致的错误语义,不在 Client 内做页面专用逻辑。
## Config 与模板包标准
- manifest、runtime、admin 契约、示例内容分别放独立模块;避免一个大索引文件同时承载所有契约。
- 模板字段必须声明 binding、输入类型和预览目标;模板键使用 allow-list,不接受任意字符串。
## 重构流程
1. 先建立或修改标准,再动代码。
2. 每轮只处理一个高影响热点,保持外部行为不变。
3. 重构后运行 `pnpm format:check`、`pnpm lint`、`pnpm typecheck`、相关测试和生产构建。
4. 行为变化必须有测试;纯结构重构也必须保留所有授权、品牌隔离和关键 UI 状态测试。
5. 在分支完成并全量验证后合并回 `main`。