Files
persionalBrand/docs/adr/0023-code-structure-standards.md

49 lines
3.0 KiB
Markdown

# 0023. 代码结构与重构标准
## Context
项目已进入多模板、多品牌和完整编辑发布阶段。Admin 页面、API Client、Config 包和部分 API Controller 出现超过 500 行甚至 900 行的文件。页面组件内同时存在查询、mutation、表单同步、预览映射和业务校验;API Client 将所有资源类型和方法集中在单个文件;Config 包将契约、注册表、示例内容和查询函数混在一个索引中。这种结构已经开始增加回归风险、review 成本和模板扩展成本。
项目已有交付清单要求接口授权、集成测试、数据迁移、UI 状态和生产构建一起验证。但缺少专门的代码结构标准,无法在功能继续增长前约束模块边界。
## Decision
建立 `docs/code-standards.md` 作为前后端共享结构标准,并按技术边界补充专门规则:
- Admin React 页面由页面组件、hooks、纯函数领域工具、feature 组件和 shared components 组成;页面组件不承载完整 API 调用和多领域状态。
- API Controller 只处理路由、DTO、状态码、响应形状和传输入口;授权、Prisma、模板安装、快照组装和工作流推进进入 Service 或领域模块。
- API Client 按资源拆分类型和方法模块,`index.ts` 只做聚合导出和 Client 组装。
- Config 与模板包按 manifest、runtime、admin 契约、示例内容、注册表和查询函数拆分。
- 超过 500 行的文件必须给出拆分计划;超过 800 行应拆分。
- 结构重构优先保持外部行为不变,授权测试、品牌隔离测试、API Client 测试和生产构建必须保留并通过。
重构在专用分支完成,必须经过相关包测试、全仓 lint、typecheck、Admin 或相关应用生产构建后合并。
## Alternatives
1. 继续只在功能交付清单中约束行为:不能阻止模块继续膨胀,review 成本和冲突风险会继续上升。
2. 引入统一组件框架或后端 CQRS 框架:改动范围过大,会打断当前产品主线,且对现有热点没有直接收益。
3. 只按行数机械拆分:会生成缺少领域含义的小文件,降低可读性。
## Consequences
### Positive
- Admin 编辑器、工作台、业务和信任内容可以复用同一种状态与表单边界。
- API 授权和持久化边界更容易测试。
- API Client 和 Config 契约变更的影响面更清晰。
- 模板新增与多品牌扩展不再依赖膨胀的单一索引。
### Negative
- 短期内会出现更多文件,需要依赖明确的领域命名。
- 旧代码迁移需要多轮完成,不能一次替换所有结构。
## Migration Plan
1. 在 `refactor/code-standards` 分支先落地标准。
2. 优先重构当前热点:品牌编辑器、工作台、API Client、Config 包和 Admin Workspace Controller。
3. 每轮重构保持公共导出、endpoint、请求响应和授权行为兼容。
4. 后续新增文件直接按标准执行;旧文件在改动该领域时逐步迁移。
5. 分支通过全部相关测试和生产构建后合并回 `main`。