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,95 @@
+# 应用工程脚手架基线设计
+
+- 功能编号：GOV-009
+- 设计版本：0.1
+- 状态：review
+- 日期：2026-08-13
+
+## 总体结构
+
+```text
+repository
+├── web/                         Vue 3 独立前端工程
+│   ├── src/api/generated/       OpenAPI 生成的类型与客户端
+│   ├── src/api/adapters/        DTO 到页面模型的转换
+│   ├── src/app/                 路由、状态和应用外壳
+│   └── tests/                   组件与浏览器测试
+├── server/                      NestJS 独立后端工程
+│   ├── apps/api/                HTTP 与 OpenAPI 入口
+│   ├── apps/scheduler/          定时触发入口
+│   ├── apps/worker/             任务执行入口
+│   └── libs/
+│       ├── config/              进程级配置解析与脱敏
+│       ├── http-contracts/      DTO 与 OpenAPI 模型
+│       ├── message-contracts/   Server 内部 RocketMQ 事件
+│       ├── domain/              后端业务模型与端口
+│       └── infrastructure/      Redis、MySQL、消息适配器
+├── deploy/                      环境和部署契约
+└── tools/                       治理、Schema 与生成校验
+```
+
+根目录只负责编排命令和版本约束，不承载业务运行代码。Web 与 Server 各自拥有依赖、TypeScript 配置和构建产物，可以独立部署；pnpm workspace 只用于一致安装和根命令调度。
+
+## 契约方向
+
+```text
+Server DTO + Controller metadata
+          │
+          ▼
+      openapi.json
+          │
+          ▼
+Web generated client ──> Web adapter ──> Page model
+
+Scheduler ──> Server message contract ──> Worker
+```
+
+HTTP 契约由 Server 单向发布，Web 不导入任何 Server TypeScript 源码。生成客户端只负责传输类型和请求，页面通过 adapter 转换为适合展示的模型，避免后端字段调整直接渗透整个界面。
+
+Server 使用 `@nestjs/swagger` 从 DTO 和 Controller 元数据生成 `openapi.json`；Web 使用 `openapi-typescript` 生成类型，并由 `openapi-fetch` 提供轻量请求客户端。生成过程固定输入与输出路径，检查命令重新生成后要求 Git 无差异，从而发现契约漂移。
+
+RocketMQ 消息契约属于 Server 的进程间协议，只由 Scheduler 与 Worker 使用。数据库实体不会作为 HTTP DTO 或消息载荷直接暴露，避免持久化结构成为跨边界契约。
+
+## Server 进程边界
+
+- API 读取 API、Redis、MySQL 和可选 AI 配置，提供 HTTP 与 OpenAPI。
+- Scheduler 读取调度、Redis 和可选 RocketMQ 发送配置，只负责触发任务。
+- Worker 读取数据源、Redis、MySQL、可选 RocketMQ 消费和可选 AI 配置，负责执行任务。
+- 三个入口复用配置解析和基础设施 adapter，但分别建立 Nest 应用上下文，互不隐式启动。
+
+初始版本的 RocketMQ adapter 只定义接口和明确的 disabled 行为。项目不会选择名称可疑、维护状态不明或不兼容 RocketMQ 5.x Proxy 的 npm 包；真实收发将在客户端验证功能中通过测试 Topic 完成后启用。
+
+## 配置加载
+
+本地启动固定读取 `deploy/env/development/<process>.env.local`；生产运行依靠 Compose `env_file` 或 systemd `EnvironmentFile` 注入，不从源码目录寻找生产 env。配置解析采用白名单 Schema，未知键可以保留给其他进程，但当前进程只解析最小集合。
+
+敏感值只用于建立连接，错误对象和日志使用键名而不输出实际值。Web 构建只加载 `web.env.local` 中的 `VITE_` 变量。
+
+## 数据库基线
+
+Schema 工具优先读取 `api.env.local`，不存在时才退回 `api.env.example`。开发数据库主机允许回环地址和代码内固定白名单 `112.192.20.11`，不能由命令行临时追加。其余环境、库名、版本、字符集和排序规则继续严格校验。
+
+当前远程开发库为空。空库仍然是“已启用且已检查”的事实，不应标记为 MySQL 未启用。生成器将保存 `captured_empty` 结构化清单，其中对象计数为零、客户端和服务端版本真实可验证，并对规范化的空结构计算确定性摘要；不创建空 `schema.sql`。首次迁移产生对象后，下一发布版本开始生成完整 captured 基线。
+
+Server 数据访问使用 Nest 官方 `@nestjs/typeorm` 集成、TypeORM 和 `mysql2` 驱动。迁移是结构变更的唯一入口，应用启动禁止 `synchronize: true`；Repository 只能通过领域端口进入业务逻辑，不能把 TypeORM 实体直接暴露为 HTTP 或消息契约。
+
+## 错误处理
+
+- Node/pnpm 版本错误在安装或根校验命令开始时失败。
+- 必填配置缺失、MySQL 版本错误或字符规则错误时，相应 Server 进程拒绝启动。
+- Redis/MySQL 健康检查失败返回不可用状态，但不泄漏目标密码。
+- RocketMQ 关闭时报告 disabled；打开但无已验证 adapter 时启动失败，禁止静默退回内存队列。
+- OpenAPI 生成文件与 Server 定义不一致时 CI/本地检查失败。
+
+## 测试策略
+
+- 配置 Schema、消息信封、Schema 主机白名单和空库产物使用 Node/Vitest 单元测试。
+- API 使用 Nest 测试工具验证健康检查和 OpenAPI。
+- Web 使用 Vitest 验证启动外壳和生成客户端边界。
+- Playwright 验证 Web 能启动、路由可访问且无阻断错误；GOV-009 不进行业务页面视觉设计。
+- 使用真实 Redis 和固定开发 MySQL 执行只读冒烟；RocketMQ 只验证禁用态和既有管理链路，不宣称 Node 消息收发通过。
+- Web、三个 Server 入口和两个 Dockerfile均执行构建验证。
+
+## 回退原则
+
+GOV-009 不迁移业务数据。回退时恢复上一 Git 标签即可移除脚手架；本地 `*.env.local` 和基础设施数据不随 Git 回退。若 Schema 工具变化失败，恢复旧工具后仍保留已发布基线，禁止改写历史目录。