开发质量与前后端架构规范开发总结

功能编号：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/。

7.1 KiB Raw Blame History