开发质量与前后端架构规范 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 契约或生产部署方式。

用户流程

开发者完成上一发布版本的开发库 Schema 基线门禁。
运行 governance:start 刷新 GitNexus，并记录功能、模块、进程和契约影响。
在设计和测试计划中明确安全策略、残余风险、性能目标和验证方法。
按前后端架构边界实施，以失败测试驱动行为变化。
开发后运行验证和 GitNexus 变更检测，填写独立开发总结。
代码 Review 与规范 Review 核对需求完成度、安全、性能、同步修改和架构边界。
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 封装和自动门禁。

8.2 KiB Raw Blame History Unescape Escape