docs(GOV-010): 确认开发质量与架构规范设计

docs/features/GOV-010-development-quality-architecture/requirements.md

@@ -0,0 +1,72 @@
+# 工程需求
+
+## 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 请求封装相互独立。