73 lines
6.1 KiB
Markdown
73 lines
6.1 KiB
Markdown
# 工程需求
|
||
|
||
## 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 请求封装相互独立。
|