docs(GOV-009): 明确应用脚手架设计边界

2026-08-13 15:07:36 +08:00
parent 19cc5f948d
commit c04184a611
7 changed files with 261 additions and 0 deletions
@@ -0,0 +1,51 @@
+# 工程需求
+
+## R1 运行时与包管理
+
+- 仓库声明 Node.js `22.x` 和 pnpm `10.x`，不得由项目脚本安装或替换系统 Node。
+- 使用根 `pnpm-workspace.yaml` 编排 `web` 与 `server`；两个工程保持独立 `package.json` 和独立构建产物。
+- 锁文件必须提交，依赖版本不得使用无上限的 `latest`。
+
+## R2 Web 工程
+
+- 使用 Vue 3、Vite、TypeScript、Vue Router、Pinia、Naive UI 和 Dart Sass。
+- 使用 Vitest 执行组件与状态测试，使用 Playwright 执行浏览器流程和视觉验证。
+- Web 只读取 `VITE_` 前缀配置，不接触数据库、Redis、RocketMQ 或 AI 密钥。
+- OpenAPI 生成代码与页面模型分层，页面不得直接绑定后端 DTO。
+
+## R3 Server 工程
+
+- 使用 NestJS 与 TypeScript，建立 `apps/api`、`apps/scheduler`、`apps/worker` 三个独立启动入口。
+- 后端库按稳定职责划分为配置、HTTP 契约、消息契约、领域和基础设施；禁止按单个类过度拆分。
+- API、Scheduler、Worker 分别校验自身所需配置，未使用的密钥不得成为必填项。
+- 配置错误必须在进程启动阶段失败，错误日志不得输出密码或访问令牌。
+
+## R4 契约边界
+
+- HTTP DTO 与 OpenAPI 定义归 Server 所有，Web 通过 OpenAPI 生成自己的 TypeScript 客户端。
+- Web 禁止直接引用 Server DTO、实体、领域模型或消息事件。
+- RocketMQ 消息契约只在 Server 内部共享，并包含版本、事件类型、幂等键、发生时间和载荷。
+- OpenAPI 生成漂移必须由自动化测试或 Git diff 检测发现。
+
+## R5 数据与基础设施
+
+- Redis 使用现有开发配置，API、Scheduler、Worker 使用独立逻辑库编号。
+- MySQL 使用 Nest 官方集成的 TypeORM 与 `mysql2` 驱动，并显式配置 MySQL 5.7、`utf8mb4`、`utf8mb4_general_ci` 和 `+08:00` 会话时区。
+- RocketMQ 默认关闭；未选定并验证 Node 客户端前，不得用虚假实现宣称消息收发可用。
+- 所有健康检查必须是只读操作，不创建表、不写入业务数据。
+
+## R6 Schema 基线
+
+- 固定真实配置路径为 `deploy/env/development/api.env.local`，不存在时才允许读取无秘密模板并生成禁用态基线。
+- 允许主机仅为回环地址或显式白名单 `112.192.20.11`；白名单不得通过命令参数或任意环境变量扩展。
+- 仍固定 `APP_ENV=development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4` 和 `utf8mb4_general_ci`。
+- 空库 captured 基线必须用结构化清单明确记录零对象，并产生确定性校验值；不得创建伪造 SQL 文件。
+- Schema 工具不得读取生产 env、连接生产数据库或导出任何表数据。
+
+## R7 部署与质量
+
+- Web 与 Server 分别提供可重复构建的 Dockerfile，生产 Compose 使用不可变镜像并与真实产物路径一致。
+- 源码部署的 systemd 命令必须与 Server 构建产物一致。
+- 根级检查必须覆盖格式、静态检查、类型、单元测试、契约测试和构建。
+- 所有关键配置边界、契约生成和启动失败行为必须有自动化测试。
+- Server 使用 `@nestjs/swagger` 输出稳定的 `openapi.json`；Web 使用 `openapi-typescript` 与 `openapi-fetch` 生成类型安全客户端。