docs(GOV-010): 记录开发需求与完成结果

2026-08-13 23:35:50 +08:00
parent e992edccce
commit 61f85e5fa4
6 changed files with 153 additions and 41 deletions
@@ -0,0 +1,69 @@
+# 开发质量与前后端架构规范开发总结
+
+- 功能编号：GOV-010
+- 总结版本：0.1
+- 日期：2026-08-13
+- 发布状态：未发布，当前处于验证阶段
+
+## 原始开发需求
+
+用户要求把安全性、性能优化、GitNexus 跨功能影响分析、基于真实重复的复用抽取和开发需求/完成需求/缺陷记录纳入强制开发规范与流程；后端参考成熟 NestJS 与 RuoYi 职责边界，按业务模块在模块内分层；前端参考 RuoYi Vue3 分离版的组织方式，统一封装 Axios，并在 `api` 目录按业务域管理接口。用户进一步确认 OpenAI 兼容仅指未来 AI Provider 的外部协议，浏览器请求继续使用 Axios，前后端架构规范采用独立文件维护。
+
+## 需求与范围变化
+
+- 需求确认过程中澄清了 `openapi-fetch`、OpenAPI 文档和 OpenAI 兼容 API 的职责：移除前端 `openapi-fetch` 执行器，但保留 `openapi-typescript` 生成契约；未来 AI Provider 不属于 GOV-010。
+- 后端分层从“固定生成完整目录树”收敛为“业务模块内按需建立职责层”，避免为了目录外观创建空层或透传层。
+- 当前 Vue 页面没有消费健康接口，因此本次只建立统一 request 和健康业务域 API 样例，没有制造页面调用链。
+- 开发环境、MySQL、Redis、RocketMQ、API、Scheduler、Worker 和源码部署行为均不在本次修改范围；没有访问生产数据库或生产配置。
+
+## 实际完成需求
+
+| 需求 | 状态 | 实际结果与证据 |
+|---|---|---|
+| FR-001 GitNexus 直接、间接和跨模块影响 | 已完成 | `gitnexus/impact-plan.md` 与完成门禁要求记录消费者、执行流、风险和同步修改；开始流程会生成影响计划骨架。 |
+| FR-002 安全策略与评估 | 已完成 | 设计、测试、代码 Review 模板和规范 Review 模板均有固定安全证据章节；请求错误测试覆盖内部地址、凭据和响应正文脱敏。 |
+| FR-003 性能目标与验证 | 已完成 | 设计和测试计划记录包体、超时、重试及治理扫描边界；最终生产构建字节数在 `qa/test-results.md` 补充。 |
+| FR-004 独立开发总结 | 已完成 | 新增本文件和通用模板，`governance:finish` 将其列为必备文件并校验七个固定章节。 |
+| FR-005 后端业务模块内按需分层 | 已完成（规范） | 代码规范和系统架构明确 Controller、Service、Domain、Repository、Adapter、DTO 的职责与依赖方向；现有健康模块未为目录外观迁移。 |
+| FR-006 统一 Axios 与业务域 API | 已完成 | 新增 `web/src/utils/request.ts` 和 `web/src/api/health/index.ts`；AST 边界拒绝页面、组件、Store 或 Composable 直接 HTTP。 |
+| FR-007 保留 OpenAPI 类型 | 已完成 | 健康 API 使用生成的 `HealthResponseDto`，契约生成与校验流程保持不变，没有 `any` 回退。 |
+| FR-008 真实重复后再抽取 | 已完成（规范与 Review 门禁） | 规范禁止预测性抽象；本次只抽取真实的统一 HTTP 边界，没有创建未被使用的后端层。 |
+| FR-009 新依赖评估 | 已完成 | 设计记录 Axios 1.19.0、MIT、官方来源、替代、成本、维护与退出方式；最终 audit 和包体证据进入 QA。 |
+| FR-010 自动阻断缺证据完成声明 | 已完成 | 治理测试覆盖缺文件、缺章节、空正文、裸占位词和未通过 Review；边界测试覆盖 HTTP 绕过。 |
+
+当前页面仍未接入健康 API，后端 AI Provider 尚未实现，市场概览、用户、会员和订阅功能也未由 GOV-010 实现。这些均为明确非目标，不计作本功能完成项。
+
+## 修复缺陷
+
+本次没有修复既有市场业务缺陷，因为仓库尚处基础治理与脚手架阶段。本次修复的是工程治理缺口：此前开发总结不是独立必备证据、安全与性能章节缺少结构化门禁、前端请求库和业务 API 边界未按用户确认的 Axios 范式落实、项目边界无法阻断直接 HTTP 绕过。对应回归测试位于治理规则、请求封装、Vite 配置、健康 API 和项目边界测试中。
+
+验证阶段使用 npm 官方审计端点发现 `@nestjs/swagger 11.4.6` 精确依赖的 `js-yaml 5.2.1` 存在 GHSA-pm4m-ph32-ghv5 高危拒绝服务漏洞；当前最新版 Swagger 仍锁定该版本。项目采用 pnpm 精确覆盖，仅把 `@nestjs/swagger>js-yaml` 更新到同补丁线修复版本 5.2.2，不影响其他 `js-yaml` 消费者。修复前 audit 失败输出与修复后 audit、OpenAPI、后端测试和构建结果将进入 QA 证据。
+
+## 未完成与延期项
+
+- 最终全量测试、浏览器视觉回归、GitNexus 开发后对比和两类 Review 正在验证阶段完成，证据将写入本功能档案后再执行完成门禁。
+- AI Provider 延期到独立功能设计，届时兼容 OpenAI API 协议；本次没有预留虚假实现或前端密钥。
+- 当前页面接入真实健康或市场概览 API 将随对应页面功能实施；本次不为了展示请求层而增加无产品价值调用。
+- 后端新业务模块会在实际出现职责时遵循按需分层；现有健康模块未迁移，避免没有业务收益的结构调整。
+- GOV-010 保持 `unreleased`，不创建版本标签；发布仍受 GOV-009 架构复核和用户确认约束。
+
+## 关键提交
+
+| 提交 | 中文摘要 | 推送状态 |
+|---|---|---|
+| `a8dcd06` | `docs(GOV-010): 制定开发质量治理实施计划` | 已推送 `origin/main` |
+| `e12c572` | `feat(GOV-010): 强制校验开发质量证据` | 已推送 `origin/main` |
+| `3a22fde` | `docs(GOV-010): 完善安全性能与架构规范` | 已推送 `origin/main` |
+| `4105336` | `refactor(GOV-010): 统一封装前端 Axios 请求` | 已推送 `origin/main` |
+| `d2c1863` | `feat(GOV-010): 建立前端 API 分域边界` | 已推送 `origin/main` |
+| `e992edc` | `fix(GOV-010): 修复 Swagger 传递依赖漏洞` | 已推送 `origin/main` |
+
+每个阶段提交后均核对本地 `HEAD` 与 Gitea `refs/heads/main`。本总结提交和最终验证提交将在成功推送后补充最终 SHA，禁止以计划中的摘要冒充已推送事实。
+
+## 验证证据
+
+- 已完成的局部证据：治理测试 9 项通过；请求与配置测试 10 项通过；Web 测试 11 项通过；项目边界测试 16 项通过；Web/Server 类型检查、lint、格式和 OpenAPI 契约检查均在对应阶段通过。
+- GitNexus 阶段检测：治理、规范和 Axios 请求层为 LOW；边界工具为 MEDIUM，原因是唯一的项目边界验证执行流发生变化，不进入生产运行时。该结果必须在最终比较与 Review 中复核。
+- 安全证据：请求错误脱敏、取消语义、有限超时和 HTTP 边界已有单元测试；依赖 audit、构建产物敏感字符串扫描和最终 Git diff 检查将在 `qa/test-results.md` 保存。
+- 性能证据：迁移前 Web 构建基线为 JS 163908 字节、CSS 805 字节；最终构建体积、增量和 10 秒默认超时/无自动重试结论将在 `qa/test-results.md` 保存。
+- 完整测试、源码发布验证和桌面/移动视觉证据将在 `qa/` 与 `screenshots/iterations/` 保存；代码 Review 和规范 Review 将保存于 `review/`。