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

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

@@ -0,0 +1,208 @@
+# 开发质量与前后端架构规范设计
+
+- 功能编号：GOV-010
+- 设计版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 1. 决策摘要
+
+采用“规范文档 + 功能模板 + 自动门禁”的可执行治理方案。安全、性能、GitNexus 影响和同步修改进入设计、测试与 Review；实际完成事实进入独立 `development-summary.md`。前端将现有 `openapi-fetch` 请求实现迁移为统一 Axios 封装，继续使用 OpenAPI 生成类型。后端采用业务模块垂直组织、模块内部按需分层，不强制空目录或透传层。
+
+## 2. 方案比较
+
+### 方案 A：文档、模板与关键门禁结合（采用）
+
+优点是关键证据可以自动阻断，架构职责仍保留工程判断空间；既不会让规范沦为建议，也不会因为一个固定目录生成器迫使小模块过度设计。成本是治理脚本和边界校验需要测试，并且后端分层仍需认真 Review。
+
+### 方案 B：只更新规范文档
+
+实施成本最低，但无法防止缺少开发总结、空安全评估和页面直连 HTTP。随着功能增加，违反约定往往只能在人工 Review 后期发现，不符合项目要求的可追溯和可执行治理目标。
+
+### 方案 C：固定目录生成器与全面架构 lint
+
+自动化最强，但会要求每个模块凑齐 Controller、Service、DTO、Repository 和 Adapter，容易制造无意义转发、文件碎片和错误抽象。当前业务模块尚未充分展开，固定全部结构为时过早。
+
+## 3. 治理证据链
+
+```text
+Schema 发布基线
+       ↓
+governance:start + GitNexus 开发前分析
+       ↓
+PRD / requirements / design / test-plan
+       ↓
+测试先行 → 实现 → 完整验证
+       ↓
+GitNexus detect_changes + 前后对比
+       ↓
+development-summary
+       ↓
+代码 Review + 规范 Review
+       ↓
+governance:finish
+```
+
+开发前影响计划必须显式列出 HTTP/OpenAPI、Web API、消息、数据库、缓存、三个服务进程、部署、测试和文档的同步修改结论。开发后变更检测将实际符号和执行流与计划对照，避免只分析主要模块而漏掉消费者。
+
+安全和性能采用贯穿式记录，不额外拆成孤立文件：
+
+- `design.md` 记录威胁、缓解、残余风险、性能目标和取舍。
+- `test-plan.md` 记录验证方法和风险相称的测试强度。
+- `review/*.md` 记录实现证据、问题、处置和遗留风险。
+- `development-summary.md` 记录实际需求完成、缺陷和验证结果。
+
+## 4. 独立开发总结
+
+新增 `docs/templates/development-summary-template.md`，并把 `development-summary.md` 加入所有后续功能档案的完成清单。固定章节为：
+
+1. 原始开发需求。
+2. 需求与范围变化。
+3. 实际完成需求。
+4. 修复缺陷。
+5. 未完成与延期项。
+6. 关键提交。
+7. 验证证据。
+
+自动校验验证标题存在且正文有实质说明。对于没有缺陷或延期项的功能，仍需说明“没有”的依据，不允许删除章节或只填写无解释的占位词。历史已发布档案不因新规则被批量改写；门禁以 GOV-010 生效范围和新建档案为边界，GOV-010 自身也提供该文件。
+
+## 5. 后端架构
+
+```text
+server/apps/api/src/modules/
+└── market-overview/
+    ├── market-overview.module.ts
+    ├── controllers/
+    ├── services/
+    ├── dto/
+    ├── domain/
+    ├── repositories/
+    ├── adapters/
+    ├── types/
+    └── utils/
+```
+
+业务模块是第一组织边界，目录只在有对应职责时创建。依赖方向为：
+
+```text
+Controller → Service / use case → Domain + Repository port
+                                      ↑
+                         Infrastructure Adapter
+```
+
+- Controller 处理协议、校验后的输入和响应映射，不包含市场计算或数据访问。
+- Service 编排用例、事务边界和降级，不成为所有逻辑的集中地。
+- Domain 保持纯 TypeScript 规则、口径和模型，不依赖 NestJS 或基础设施 SDK。
+- Repository 是业务所需的持久化端口；Adapter 实现 MySQL、Redis、RocketMQ、免费数据源或 AI Provider。
+- DTO、领域模型和数据库实体分别服务传输、业务和持久化，不互相冒充。
+- 模块间共享只有在重复已经出现、语义稳定且所有者明确后才上移到 `server/libs`。
+
+现有健康检查是脚手架基础能力，本功能不为展示目录形式而迁移其后端文件。新的业务模块从本规范开始执行；后续触及健康检查模块时再基于影响分析判断是否垂直归档。
+
+## 6. 前端架构与 Axios 数据流
+
+```text
+web/src/
+├── utils/
+│   └── request.ts
+├── api/
+│   ├── generated/
+│   │   └── schema.ts
+│   ├── health/
+│   │   └── index.ts
+│   ├── market-overview/
+│   │   └── index.ts
+│   ├── sectors/
+│   │   └── index.ts
+│   └── stocks/
+│       └── index.ts
+└── features/
+    └── <business-domain>/
+        ├── adapters/
+        ├── components/
+        ├── composables/
+        ├── stores/
+        └── views/
+```
+
+实际数据流为：
+
+```text
+NestJS DTO 与 Swagger 元数据
+        ↓
+server/openapi/openapi.json
+        ↓ openapi-typescript
+web/src/api/generated/schema.ts
+        ↓ 类型约束
+api/<业务域>/index.ts
+        ↓ 调用
+utils/request.ts（Axios）
+        ↓
+业务 adapter → ViewModel → 页面/组件
+```
+
+`request.ts` 创建唯一 Axios 实例，负责 base URL 规范化、超时、通用请求头、取消信号、错误归一化和后续认证扩展。响应拦截器只返回响应数据，API 函数不向功能层泄漏 `AxiosResponse`。错误类型保留稳定的用户安全消息，并可携带不敏感的错误分类和 HTTP 状态供界面决定重试或降级；原始配置、请求头、内网地址和上游正文不进入展示消息。
+
+业务 API 文件从生成 Schema 中提取请求与响应类型，并使用封装后的 request。Vue 页面、组件、Store 和 Composable 不得直接导入 Axios、调用浏览器 `fetch` 或拼接业务 URL。DTO 到 ViewModel 的转换保留在功能适配层，使后端传输字段不会扩散到展示组件。
+
+## 7. Axios 迁移
+
+迁移现有健康请求客户端脚手架，并建立业务 API 样例。当前页面尚未消费健康接口，现有 `client.ts` 只有直接单元测试，Playwright 则从测试进程直接请求后端；因此本次不虚构页面调用方：
+
+- 删除 `openapi-fetch` 依赖，新增锁定版本的 `axios`。
+- 以测试先行创建 `web/src/utils/request.ts`，覆盖根地址、超时、数据解包、取消和脱敏错误。
+- 创建 `web/src/api/health/index.ts`，使用生成的 `HealthResponseDto` 类型调用 `/api/v1/health`。
+- 更新旧客户端测试，并为健康业务 API 增加测试；保留 DTO 到 `HealthViewModel` 的适配器，暂不为了展示调用链而把健康状态接入页面。
+- 删除不再使用的 `web/src/api/client.ts` 及对应旧测试。
+- 扩展项目边界校验，拒绝 API 目录外直接使用 Axios/fetch，并拒绝 API 模块绕过统一 request。
+
+OpenAPI 文档与 OpenAI 兼容 API 是不同概念：前者是 NestJS 对本项目 HTTP 契约的机器可读描述；后者是未来后端 AI Provider 需要兼容的外部调用协议。本功能只改变浏览器到本项目 API 的 Axios 实现。
+
+## 8. 安全设计
+
+### 资产与信任边界
+
+- 浏览器输入和网络响应均不可信；Axios 封装是浏览器 HTTP 错误边界，业务 API 是传输契约边界。
+- OpenAPI 生成文件是可提交的公开契约，不得包含内部消息、实体或密钥。
+- 治理工具读取仓库文档和 Git 状态，不读取生产环境；Schema 门禁仍只允许既定开发库边界。
+
+### 主要风险与控制
+
+- 错误泄漏：统一转换网络和 HTTP 错误，用户消息不包含 URL、凭据、响应正文或底层异常。
+- 绕过请求策略：边界校验限制 Axios 实例和直接 fetch，减少遗漏超时、认证、错误处理和日志脱敏。
+- 供应链：Axios 使用固定版本并提交锁文件；安装前核对官方包、许可证、维护状态和依赖变化。
+- 注入与浏览器攻击：本功能不渲染远程 HTML、不添加认证 Cookie、不生成动态 SQL；后续涉及这些边界时仍必须分别评估 XSS、CSRF、SSRF 和注入。
+- 伪造治理证据：完成门禁检查必备章节及理由，Review 仍核对内容与 Git diff、测试输出是否一致。
+
+残余风险是自动校验无法判断文字结论是否真实，因此保留结构化人工 Review；Axios 响应数据的运行时 Schema 校验不在本次引入，现有健康适配器继续拒绝未知枚举，后续高风险接口按具体功能决定是否引入运行时校验。
+
+## 9. 性能设计
+
+- Axios 替代 `openapi-fetch` 会增加有限前端依赖体积，但换取项目已确认的统一请求范式、成熟拦截器和取消能力；构建产物记录迁移前后体积并在 Review 中评估变化。
+- 统一请求层不得默认无限重试，避免行情刷新时形成放大流量；本次不加入自动重试。
+- 超时采用有限默认值，业务域可在设计批准后缩短，但不得无上限等待。
+- API 函数返回解包后的 DTO，避免重复转换与组件订阅 Axios 对象；该差异不是性能热点，主要价值是边界稳定。
+- 治理扫描只在开发与发布验证执行，不进入线上请求路径；文件扫描保持线性遍历，当前仓库规模不要求负载测试。
+- 本功能不查询 MySQL、Redis 或行情数据，不改变 Scheduler/Worker 吞吐；这些项不适用于运行时性能验证，边界是后续业务功能必须重新评估。
+
+## 10. 自动校验边界
+
+适合自动化的规则：必备文件、必填章节、Review 固定结论、前端非法依赖、直接 HTTP 调用和生成契约泄漏。后端目录是否需要某一层、重复是否足以抽取、注释是否真正解释原因等需要语义判断，进入规范 Review，不用脆弱的固定目录规则代替。
+
+内容校验以结构为主：确认标题、标题下非空正文、明确的不适用理由格式；不通过搜索“安全”“性能”等零散词语来推定证据完整。校验函数保持纯函数并由 fixture 测试覆盖，`finish.mjs` 只负责编排。
+
+## 11. 错误与回退
+
+- 门禁失败必须列出具体文件和缺失章节，不能只返回布尔值。
+- Axios 遇到取消请求时保留可识别取消语义，不错误展示为服务故障。
+- 非取消错误转换为项目错误类型；调试细节只允许进入受控开发日志且必须脱敏，本次默认不记录原始错误。
+- 若迁移回归，可用中文回退提交恢复 `openapi-fetch` 客户端、依赖和调用方；规范、模板和校验必须作为一致变更回退，避免规范与基础代码不一致。
+
+## 12. 验证与完成标准
+
+- 治理单元测试覆盖开发总结和章节校验的通过、缺失和伪占位失败场景。
+- 边界测试覆盖 Axios/fetch 的非法与合法路径、Vue 脚本和路径别名。
+- Web 单元测试覆盖请求 URL、响应解包、网络错误、HTTP 错误和取消。
+- OpenAPI 生成、格式、lint、类型检查、全量测试、构建、Playwright 和源码发布门禁通过。
+- 现有页面在桌面与移动视口完成视觉回归，证明请求基础设施迁移没有造成布局或交互旁路变化。
+- GitNexus 开发后变更检测与前置计划一致，两类 Review 最终结论均为 `passed`。

docs/features/GOV-010-development-quality-architecture/gitnexus/before.md

@@ -0,0 +1,26 @@
+# GitNexus 开发前基线
+
+- 功能编号：GOV-010
+- 记录时间：2026年8月13日 GMT+8 22:12:32
+- 分支：main
+- 基线提交：bbda26fa4128
+
+## 工作区
+
+```text
+(干净)
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/13/2026, 9:36:14 PM
+Indexed commit: bbda26f
+Current commit: bbda26f
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。

docs/features/GOV-010-development-quality-architecture/gitnexus/impact-plan.md

@@ -0,0 +1,54 @@
+# GitNexus 开发前影响计划
+
+- 功能编号：GOV-010
+- 基线提交：`bbda26fa41288d4ae1f37c3e1c14593d5d8e910e`
+- 分析日期：2026-08-13
+- 总体风险：LOW；因部分遍历结果标记为 `partial`，按 MEDIUM 验证强度实施交叉检查
+
+## 查询与上下文
+
+GitNexus 查询了三类概念：功能档案完成门禁、前端 HTTP/OpenAPI 健康检查链路、NestJS 模块与项目边界。关键上下文结果：
+
+- `getRequiredFeatureFiles` 的直接使用者是 `tools/governance/finish.mjs` 和 `tools/governance/feature-record.test.mjs`。
+- `createApiClient` 与 `ApiRequestError` 位于 `web/src/api/client.ts`，只有旧客户端测试直接依赖两者；当前 Vue 页面尚未调用健康接口，Playwright 的健康请求属于测试进程直连后端，不应迁移为浏览器业务 API 调用；依赖锁文件包含 `openapi-fetch`。
+- 健康展示链路经过 `web/src/api/adapters/health.adapter.ts` 的 `toHealthViewModel`，需保留 DTO 到 ViewModel 的隔离。
+- API 端由 `HealthController.getHealth` 调用 `HealthService.check`；本次不改后端路由和 DTO。
+- 项目边界由 `verifyProjectBoundaries` 扫描 TypeScript 与 Vue 脚本，适合扩展前端 HTTP 边界规则。
+
+## 上游影响
+
+- `getRequiredFeatureFiles`：GitNexus 风险 LOW；图谱遍历返回 0 个影响但上下文明确存在两个直接调用者，因此必须同步修改测试和完成门禁验证。
+- `createApiClient`：风险 LOW、结果为 `partial`；静态引用确认只需迁移旧客户端测试并新增健康 API 样例，当前没有页面调用方需要改动。
+- `ApiRequestError`：风险 LOW、结果为 `partial`；新 Axios 错误类型必须保持现有安全消息行为。
+- `collectSourceFiles`：风险 LOW；边界扫描是开发验证路径，不影响生产执行流，但其测试 fixture 必须同步。
+
+没有 HIGH 或 CRITICAL 结果，不需要额外风险批准。`partial` 结果不得解释为没有调用方，实施前后使用 `rg`、类型检查、测试和 `detect_changes` 交叉验证。
+
+## 执行流影响
+
+- 治理完成流程：必备文件与内容校验会改变 `governance:finish` 的通过条件。
+- Web 健康请求脚手架：请求库、错误路径和类型引用变化；当前页面没有对应运行时请求流，后端健康检查与 Playwright 直连验证不变。
+- OpenAPI 生成流程：生成工具与输出协议不变，前端仍消费 `schema.ts`，仅请求执行器由 `openapi-fetch` 改为 Axios。
+- 项目边界验证流程：增加 Axios/fetch 使用位置检查，生产运行时不受影响。
+
+## 同步修改清单
+
+| 领域 | 是否修改 | 计划 |
+|---|---|---|
+| HTTP/OpenAPI | 是，文档与类型消费 | 保留后端 OpenAPI 输出和生成 Schema，不修改路由或字段 |
+| Web 请求/API | 是 | 新建统一 Axios request、健康业务域 API，迁移调用方和测试 |
+| Web adapter/ViewModel | 可能 | 仅调整导入或调用链，保持转换行为与类型边界 |
+| RocketMQ 消息契约 | 否 | 本功能不修改消息协议或进程通信 |
+| MySQL/迁移/Schema | 否 | 不修改结构；开发前只验证已发布 `v0.0.7` 基线 |
+| Redis/缓存 | 否 | 不修改缓存键、TTL、连接或数据 |
+| API/Scheduler/Worker | 否 | 不改变三个后端进程运行行为，只新增其架构规范 |
+| 配置与部署 | 可能 | Axios 沿用现有 Web API 根地址；若变量名不变则无需改模板 |
+| 治理工具 | 是 | 必备开发总结、结构化内容校验及错误信息 |
+| 边界工具 | 是 | 限制前端直接 HTTP 调用并增加测试 |
+| 文档与模板 | 是 | 更新代码规范、流程、追溯、PRD、Review、AGENTS 和模板 |
+| 依赖与锁文件 | 是 | Web 删除 `openapi-fetch`，新增固定版本 Axios |
+| 测试与视觉 QA | 是 | 补单元、边界、全量、构建体积和现有页面回归证据 |
+
+## GitNexus 状态限制
+
+CLI 在开发前运行后报告索引提交与当前 HEAD 均为 `bbda26f` 且状态最新。MCP 的 context 资源仍显示旧统计并提示落后 5 个提交，说明 MCP 资源缓存未同步；查询、符号上下文和影响结果仍能定位当前文件。开发后必须重新运行 CLI 分析、调用 `detect_changes`，并把该缓存差异记录在比较报告中。

docs/features/GOV-010-development-quality-architecture/manifest.yaml

@@ -0,0 +1,15 @@
+id: GOV-010
+name: 开发质量与前后端架构规范
+slug: development-quality-architecture
+status: approved
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+test_plan: test-plan.md
+development_summary: development-summary.md
+gitnexus_before: gitnexus/before.md
+gitnexus_impact: gitnexus/impact-plan.md
+release: unreleased

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

@@ -0,0 +1,113 @@
+# 开发质量与前后端架构规范 PRD
+
+- 功能编号：GOV-010
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 背景与问题
+
+现有仓库已经建立 PRD、GitNexus 双门禁、测试、Review、中文提交和 Gitea 推送流程，但安全与性能检查仍偏原则化，开发总结没有独立强制文件，GitNexus 开发前报告也没有强制回答跨模块同步修改问题。前后端基础工程已经能够运行，但后端业务模块的分层方式、前端 Axios 请求封装和 API 分域方式尚未成为可执行规范。
+
+若仅补充文字约定，新功能仍可能遗漏安全边界、性能目标、关联模块修改和实际完成情况；若过早强制所有模块创建固定目录，又会产生无意义的透传层和碎片化文件。因此需要在可自动验证的关键证据与按实际职责演进的代码结构之间建立边界。
+
+## 目标用户与使用场景
+
+- 项目开发者在开始功能或缺陷修复前，能够识别直接、间接和跨进程影响。
+- 实现者在设计、编码和验证阶段持续检查安全与性能，而不是在发布前临时补结论。
+- Review 者能够从独立开发总结中核对原始需求、需求变化、完成项、缺陷和验证证据。
+- 前端开发者使用统一 Axios 封装和业务域 API 文件，不在页面中散落请求细节。
+- 后端开发者以业务模块为一级边界，在模块内部按真实职责分层。
+
+## 产品目标
+
+- 将安全、性能、跨模块影响和同步修改分析纳入功能全生命周期。
+- 为每个功能档案增加独立且强制的 `development-summary.md`。
+- 建立可阅读、可演进、不过度拆分的前后端架构规则。
+- 用模板、测试和完成门禁验证关键要求，避免规范只停留在文字层面。
+- 将现有前端请求客户端脚手架迁移到 Axios，并补充健康 API 分域样例，使基础代码在新规范生效时立即合规。
+
+## 非目标
+
+- 不实现市场概览业务功能、用户体系、付费、会员或订阅。
+- 不实现后端 AI Provider；兼容 OpenAI API 的 AI 接入继续作为独立后端功能规划。
+- 不为每个后端模块强制生成完整目录树。
+- 不引入全局 Controller 或 Service 目录。
+- 不照搬 RuoYi 的弱类型 Axios 示例或 `any` 参数。
+- 不在本功能中变更 HTTP 接口业务字段、数据库结构、Redis 数据、RocketMQ 契约或生产部署方式。
+
+## 用户流程
+
+1. 开发者完成上一发布版本的开发库 Schema 基线门禁。
+2. 运行 `governance:start` 刷新 GitNexus，并记录功能、模块、进程和契约影响。
+3. 在设计和测试计划中明确安全策略、残余风险、性能目标和验证方法。
+4. 按前后端架构边界实施，以失败测试驱动行为变化。
+5. 开发后运行验证和 GitNexus 变更检测，填写独立开发总结。
+6. 代码 Review 与规范 Review 核对需求完成度、安全、性能、同步修改和架构边界。
+7. `governance:finish` 对必备文件和必填证据执行门禁。
+
+## 功能需求
+
+| 编号 | 优先级 | 需求 | 可观察结果 |
+|---|---|---|---|
+| FR-001 | Must | 开发前评估功能和缺陷的直接、间接及跨模块影响 | 影响计划明确列出受影响消费者、执行流、风险和同步修改清单 |
+| FR-002 | Must | 对代码安全进行完整策略设计与评估 | 设计、测试和 Review 均有适用的安全结论、证据与残余风险 |
+| FR-003 | Must | 对性能目标和风险进行设计与验证 | 设计包含目标和风险，测试计划包含与风险相称的验证方法 |
+| FR-004 | Must | 独立记录开发总结 | 每个新功能档案包含通过结构校验的 `development-summary.md` |
+| FR-005 | Must | 后端按业务模块垂直组织并在模块内按需分层 | Review 能从目录、依赖和职责证明模块边界合理且没有凑目录 |
+| FR-006 | Must | 前端使用统一 Axios 封装和业务域 API 文件 | 页面、组件和 Store 无直接 Axios、fetch 或 URL 拼接 |
+| FR-007 | Must | 保留 OpenAPI 生成类型 | Axios API 函数使用由后端 OpenAPI 生成的 TypeScript 请求或响应类型 |
+| FR-008 | Must | 只在出现真实重复后抽取工具或组件 | Review 记录抽取依据，或说明代码尚不足以形成稳定复用边界 |
+| FR-009 | Must | 新增依赖先完成评估 | 设计记录用途、替代方案、安全、体积、维护和退出风险 |
+| FR-010 | Must | 自动化阻断缺证据的完成声明 | 缺文件、空章节、无理由“不适用”或未通过 Review 时门禁失败 |
+
+## 数据与口径
+
+本功能不处理行情或用户数据。治理数据以功能编号为主键，以 Git 提交、GitNexus 报告、测试输出和 Review 记录为证据来源。`development-summary.md` 记录实际完成事实，不替代 PRD、设计、发布说明或 Git 历史。
+
+## 状态与异常
+
+- GitNexus 索引过期时必须先重新分析，再生成影响计划。
+- GitNexus MCP 依赖遍历返回 `partial` 或不可用时，必须记录限制，并以符号上下文、执行流、静态引用和 Git diff 交叉验证，不能将零结果解释为无影响。
+- 安全或性能不适用时必须给出具体原因和适用边界；空白、`无`、`不涉及`等无解释内容不能通过。
+- HIGH 或 CRITICAL 影响必须在编辑前告知用户并取得确认。
+- Axios 请求错误必须转换为稳定错误，不得把内部地址、凭据或上游原始错误直接展示给用户。
+
+## 权限、合规与安全
+
+- 治理检查只读取仓库和开发环境证据，不触碰生产数据库或生产配置。
+- 前端不得获得 AI、数据库、Redis、RocketMQ 或数据源密钥。
+- Axios 日志和错误不得泄露请求头、凭据、内部地址或敏感响应。
+- 新增依赖必须核对来源、维护状态、许可证、已知风险和锁文件变化。
+
+## 成功指标
+
+- 新功能档案缺少开发总结或必填章节时，自动化测试稳定失败。
+- 前端直接从页面、组件或 Store 使用 Axios/fetch 时，边界校验稳定失败。
+- 健康 API 样例经 Axios API 分域层完成，类型检查、测试和构建通过；现有页面虽然尚未消费健康接口，仍需完成视觉回归以证明迁移没有旁路影响。
+- 两类 Review 均能引用安全、性能、GitNexus 同步修改和开发总结证据。
+
+## 验收标准
+
+- Given 一个缺少 `development-summary.md` 的功能档案，When 执行完成门禁，Then 门禁明确指出缺失文件。
+- Given 开发总结缺少原始需求、完成需求、修复缺陷或验证证据，When 执行结构校验，Then 校验失败并指出缺失章节。
+- Given 安全或性能章节写成无解释的“不适用”，When 执行结构校验，Then 校验失败。
+- Given Vue 页面直接导入 Axios 或调用 `fetch`，When 执行项目边界校验，Then 校验失败。
+- Given 业务 API 文件调用统一 request 封装，When 执行边界校验与类型检查，Then 校验通过。
+- Given 健康检查发生网络或后端错误，When 前端请求失败，Then 调用者收到脱敏且可分类的稳定错误。
+- Given 一个小型后端模块只有 Controller 与 Service，When 其不存在 Repository 或 Adapter 职责，Then Review 不要求创建空目录或透传层。
+
+## 风险与依赖
+
+- 严格内容校验可能误伤合理的“不适用”，因此模板提供说明格式，校验只要求理由和边界，不按关键词判断业务结论。
+- Axios 迁移会改变请求返回与错误对象，需要测试锁定业务 API 只返回 DTO、不泄漏 `AxiosResponse`。
+- OpenAPI 生成类型与 Axios 的泛型需要建立明确映射，避免恢复手写重复 DTO。
+- 架构规则若全部交给目录 lint 会过度僵化，因此后端职责分层主要由 Review 执行，前端 HTTP 边界则适合自动校验。
+
+## 发布范围与回退触发条件
+
+本次发布包含规范、模板、治理校验、边界测试及现有前端请求层迁移。若门禁阻断合法功能且不能通过补充明确证据解决，或 Axios 迁移导致现有健康页面行为回归，则整体回退 GOV-010 代码与规范提交；不修改已发布历史档案。
+
+## 变更记录
+
+- 2026-08-13：根据用户确认建立初版，明确独立开发总结、后端模块内分层、Axios 封装和自动门禁。

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 请求封装相互独立。

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

@@ -0,0 +1,22 @@
+# 回退说明
+
+GOV-010 不修改数据库结构或数据，不操作 Redis，不创建 RocketMQ Topic，也不触碰生产配置。回退对象仅包括规范、模板、治理校验、前端边界规则、Axios 请求实现和依赖锁文件。
+
+## 代码回退
+
+- 使用中文 Conventional Commit 新建回退提交，禁止重写 Gitea 历史、强推或移动既有标签。
+- 整体回退时同时恢复 `openapi-fetch` 依赖、旧请求客户端、调用方、测试和锁文件，避免请求实现与规范不一致。
+- 若只回退治理内容，必须同时回退新增必备文件、章节校验、模板和 Review 检查项，不能留下无法满足的门禁。
+- 已经按 GOV-010 建立的功能档案与开发总结属于历史证据，不删除；规则回退通过后续治理记录说明。
+
+## 验证
+
+- 回退后重新执行 OpenAPI 生成、项目边界测试、Web 单元测试、类型检查、构建和 Playwright 回归。
+- 执行 `governance:finish` 相关测试，确认门禁清单与模板一致。
+- 运行 GitNexus 变更检测并记录回退实际影响。
+
+## 触发条件
+
+- Axios 迁移导致现有健康页面请求、错误处理或生产构建无法恢复。
+- 新门禁持续阻断具有充分证据的合法功能，且无法通过修正规则消除误判。
+- 前端边界校验产生无法接受的 Vue/TypeScript 误报。

docs/features/GOV-010-development-quality-architecture/test-plan.md

@@ -0,0 +1,61 @@
+# 测试计划
+
+## 1. 治理门禁测试
+
+- 验证新功能档案必须包含独立 `development-summary.md`。
+- 验证开发总结缺少任一必备章节、章节正文为空或只有无解释占位词时失败。
+- 验证设计、测试计划、GitNexus 影响计划和两类 Review 的安全、性能、同步修改证据校验。
+- 验证有具体理由与边界的“不适用”可以通过，防止强迫所有功能执行无意义负载或攻击测试。
+- 验证错误输出包含文件和章节，便于开发者修复。
+
+## 2. 前端边界测试
+
+- 拒绝 API 目录外直接导入 `axios`、创建 Axios 实例或调用全局 `fetch`。
+- 拒绝业务 API 文件自行创建 Axios 实例或绕过 `@/utils/request`。
+- 允许 `utils/request.ts` 使用 Axios，允许 `api/<业务域>/index.ts` 调用统一 request。
+- 覆盖 `.ts`、Vue `script`/`script setup`、动态导入和路径别名，避免简单字符串规则误判或漏检。
+- 继续验证 Web 不依赖 Server 源码、内部 RocketMQ 消息不进入生成契约。
+
+## 3. Axios 请求测试
+
+- 基础 URL 去除重复斜线并正确请求 `/api/v1/health`。
+- 成功响应只返回类型化 DTO，不暴露 `AxiosResponse`。
+- 网络错误和 HTTP 错误转换为不泄漏地址、凭据和原始响应的稳定错误。
+- `AbortSignal` 取消保持可识别的取消语义，不被当成普通服务故障。
+- 默认超时有限且可测试；不启用自动重试。
+- 健康 DTO 继续经 adapter 转换成现有 `HealthViewModel`，未知状态仍被拒绝。
+
+## 4. 契约与架构验证
+
+- 重新生成 OpenAPI 与前端类型，确认无非预期契约漂移。
+- TypeScript 编译证明 Axios API 包装使用生成响应类型且无 `any` 回退。
+- Review 检查后端规范采用业务模块内按需分层，没有要求空目录或透传层。
+- Review 检查依赖方向、DTO/Domain/Entity 边界和新增依赖评估。
+
+## 5. 安全验证
+
+- 对错误样本植入数据库连接串、内网地址和伪密钥，断言用户错误不包含这些内容。
+- 检查 Web 源码与构建产物不包含服务端配置键或密钥。
+- 检查 Axios 来源、锁定版本、许可证与已知依赖风险；保存不含凭据的结果。
+- Git diff 与秘密扫描确认没有 `.env`、Token、密码或生产数据。
+- 本功能不引入认证 Cookie、远程 HTML、动态 SQL 或服务端 URL 抓取，因此 CSRF、XSS、SQL 注入和 SSRF 的运行攻击测试不适用；后续触及对应边界的功能必须重新评估。
+
+## 6. 性能验证
+
+- 比较迁移前后 Web 生产构建产物大小，记录 Axios 引入的实际增量。
+- 验证请求封装没有默认重试和无上限超时。
+- 治理工具在当前仓库运行一次并记录耗时；其不进入生产请求路径，不执行负载测试。
+- 本功能不改变数据库查询、缓存读写、消息并发、行情计算或图表渲染，因此这些性能测试不适用；后续业务功能需各自提供目标和证据。
+
+## 7. 全量验证
+
+- `pnpm check:contracts`
+- `pnpm lint`
+- `pnpm format:check`
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm build`
+- `pnpm verify:e2e`
+- `pnpm verify:release`
+- 桌面与移动视口视觉截图和页面控制台检查。
+- `gitnexus_detect_changes`、重新索引和前后对比。