6.1 KiB
6.1 KiB
工程需求
R1 GitNexus 开发前影响分析
- 功能和缺陷修复使用同一套开发前门禁，不得以“仅修 Bug”为由跳过。
- 分析必须覆盖相关概念查询、关键符号上下文、上游影响、直接与间接消费者、受影响执行流和风险等级。
- 必须逐项判断 HTTP/OpenAPI、Web API 与适配器、消息契约、数据库迁移与 Schema、Redis、Scheduler、Worker、环境与部署、测试和文档是否需要同步修改。
- HIGH 或 CRITICAL 结果必须在编辑前报告用户；
partial、索引过期或工具不可用必须说明限制并补充交叉证据。 - 开发后
detect_changes必须比较计划影响与实际影响，计划外变化必须解释、补设计或回退。
R2 安全设计与评估
- 每个功能在
design.md中识别资产、数据、信任边界、攻击面、缓解措施和残余风险。 - 按适用性检查认证授权、输入校验、SQL/命令/模板注入、XSS、CSRF、CORS、SSRF、限流、凭据、敏感数据、日志、错误、依赖供应链、数据保留和滥用场景。
- AI 与外部数据源还需检查提示词与事实边界、密钥隔离、上游内容、超时重试、成本和不可用降级。
test-plan.md必须给出安全验证方法；代码 Review 必须记录实际证据和未消除风险。- 不适用项必须说明“不适用于什么、为什么、适用边界是什么”，禁止用空白或无解释短语通过。
R3 性能设计与评估
- 每个功能说明延迟、吞吐、数据新鲜度或资源预算中适用的目标。
- 按适用性评估数据量与算法复杂度、MySQL 查询和索引、N+1、Redis 目的/TTL/一致性/击穿、分页和响应体、前端包体/渲染/长列表/图表、Scheduler/Worker 并发/幂等/背压、外部数据源与 AI 的超时/重试/批处理/成本。
- 高风险路径必须提供 benchmark、profile 或负载测试证据；普通文档或低频管理逻辑可说明无需负载测试的理由。
- 性能优化不得牺牲数据口径、可观察性、安全或 MySQL 5.7 兼容性。
R4 独立开发总结
- 每个新功能档案必须有独立
development-summary.md，不得合并到release-notes.md。 - 必备章节为原始开发需求、需求与范围变化、实际完成需求、修复缺陷、未完成与延期项、关键提交、验证证据。
- 没有缺陷时也要写明本次未修复缺陷及判断依据；不能删除该章节。
- 开发总结描述实际完成事实，PRD 描述目标，发布说明面向版本使用者，三者职责不得混淆。
governance:finish必须验证文件存在、非空和必备章节有效。
R5 后端模块架构
- 后端以业务模块为一级目录，模块内部按实际职责建立
controllers、services、dto、domain、repositories、adapters、types、utils。 - 小模块不强制凑齐目录；没有独立职责时不得增加只做转发的层。
- Controller 只负责 HTTP 协议、边界参数和响应；Service 编排用例；Domain 保存纯业务规则与模型；Repository 描述持久化端口；Adapter 实现 MySQL、Redis、RocketMQ 和外部数据源边界。
- DTO、领域模型和数据库实体必须分离；基础设施实现依赖领域端口，领域不得反向依赖 NestJS、TypeORM、Redis 或 RocketMQ SDK。
- 禁止在应用级全局目录堆放全部 Controller 或 Service；跨模块共享只在出现稳定复用边界后进入
libs。 - 后端架构参考 RuoYi 的职责清晰性与优秀 NestJS 模块实践，不照搬 Java 分层或制造形式化目录。
R6 前端请求与模块架构
- 前端实际 HTTP 请求统一使用 Axios，
web/src/utils/request.ts是唯一 Axios 实例、拦截器和通用错误处理入口。 - 所有业务接口放在
web/src/api/<业务域>/index.ts，API 文件调用统一 request，不自行创建 Axios 实例。 - 页面、组件、Composable 和 Store 禁止直接导入 Axios、调用
fetch、拼接业务 URL 或依赖AxiosResponse。 - 保留
openapi-typescript和web/src/api/generated/schema.ts；生成类型是 HTTP 契约来源，API 函数不得以any取代可用的生成类型。 - API 函数向调用者返回类型化 DTO 或明确业务结果，不把 Axios 库类型扩散到功能层；DTO 到 ViewModel 的转换位于对应功能适配层。
- request 封装统一处理 base URL、超时、请求头、取消信号、网络错误、HTTP 错误和后端标准错误；认证刷新暂不实现，只保留可测试扩展点。
R7 抽象与依赖治理
- 重复代码或功能只有在至少出现真实复用、职责稳定且抽取能降低维护风险时才进入工具、组件或公共模块。
- 仅名称相似、预判未来复用或减少文件行数，不构成抽取依据。
- 新依赖安装前必须在设计中记录用途、现有替代、版本、维护状态、安全与许可证、前端体积或服务端运行成本和退出方式。
- 本次使用 Axios 替代
openapi-fetch，保留openapi-typescript；两者用途必须在规范和架构文档中区分。
R8 自动门禁与 Review
- 治理工具必须用测试先行补充必备文件与章节校验。
- 安全、性能、影响分析、同步修改和开发总结证据必须进入代码 Review 与规范符合性 Review 模板。
- 自动校验必须覆盖缺文件、空内容、缺章节、无解释不适用和未通过 Review；不得用难以维护的业务关键词判断结论真伪。
- 前端边界校验必须基于 TypeScript/Vue 语法结构检查导入和调用，避免简单字符串扫描被注释或别名绕过。
- 后端按需分层不能由固定目录清单强制，交由架构规范和结构化 Review 检查。
R9 兼容与非功能约束
- 不修改现有 HTTP OpenAPI 业务结构、RocketMQ 消息结构或数据库 Schema。
- 继续遵守 Node.js 22、pnpm 10、MySQL 5.7.42、
utf8mb4_general_ci、源码部署和项目专用 Gitea 约束。 - 前端 Axios 迁移必须保持健康页可观察行为、脱敏错误、类型检查和生产构建不回归。
- AI 兼容 OpenAI API 是后端 Provider 协议要求，与本次前端 Axios 请求封装相互独立。