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 工具变化失败，恢复旧工具后仍保留已发布基线，禁止改写历史目录。
@@ -0,0 +1,14 @@
+# 实施计划
+
+书面设计确认后，使用 `superpowers:writing-plans` 将本文件细化为带文件路径、测试先行步骤、验证命令和独立提交点的执行清单。在用户确认详细计划前不生成应用代码。
+
+预定阶段：
+
+1. 修正 Schema 配置加载、固定远程白名单和空库结构基线。
+2. 建立 Node 22、pnpm 10 workspace 和统一质量命令。
+3. 建立 Vue 3 Web 工程、测试和 OpenAPI 消费边界。
+4. 建立 NestJS API、Scheduler、Worker 与进程级配置。
+5. 建立 Server 内 HTTP/消息契约及基础设施 adapter。
+6. 对齐 Docker、systemd、生产 Compose 和本地开发文档。
+7. 完成全量测试、构建、浏览器验证、Review、版本与发布留痕。
+
@@ -0,0 +1,13 @@
+id: GOV-009
+name: 应用工程脚手架基线
+slug: application-scaffold-baseline
+status: designing
+owner: project
+created_at: 2026-08-13
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+test_plan: test-plan.md
+release: unreleased
+
@@ -0,0 +1,59 @@
+# 应用工程脚手架基线 PRD
+
+- 功能编号：GOV-009
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-13
+
+## 问题
+
+项目已经完成工程治理、部署配置、MySQL 5.7、Redis 和 RocketMQ 5.x 的架构基线，但 `web/` 与 `server/` 仍只有占位文件，尚不能启动、构建或承载市场概览功能。现有 Schema 工具也没有读取项目约定的 `*.env.local`，并只允许回环主机，无法对已经确认的固定远程开发库执行版本化结构备份。
+
+## 目标
+
+- 建立可独立开发和部署的 Vue 3 Web 与 NestJS Server 工程。
+- Server 在同一工程内提供 API、Scheduler、Worker 三个独立进程入口。
+- 建立统一的 Node.js 22 LTS、pnpm 10、TypeScript、检查、测试和构建入口。
+- HTTP 契约由 Server 的 DTO 与 OpenAPI 定义，Web 使用生成客户端，不共享后端源码。
+- RocketMQ 消息契约只在 Server 内由 Scheduler 与 Worker共享。
+- 本地进程加载现有 `deploy/env/development/*.env.local`，同时保持真实配置不进入 Git。
+- Schema 工具只允许读取固定开发配置，支持经过白名单批准的远程开发库。
+- 为 FEAT-MO-001 提供能够直接开始页面开发的工程底座。
+
+## 用户价值
+
+开发者可以用明确命令安装依赖、启动 Web/API/Scheduler/Worker、运行测试和构建，并能在不复制接口类型、不泄漏密钥、不误触生产数据库的前提下持续开发市场分析功能。
+
+## 范围
+
+- 根 pnpm workspace 与统一版本约束。
+- Vue 3、Vite、TypeScript、Vue Router、Pinia、Naive UI、Dart Sass、Vitest 和 Playwright 基础工程。
+- NestJS API、Scheduler、Worker 多应用工程及共享后端库边界。
+- Server 配置解析、条件必填和启动失败策略。
+- API 健康检查、OpenAPI 产物与 Web 客户端生成链路。
+- Redis 与 MySQL 开发连接健康检查；RocketMQ 保持配置可选和默认关闭。
+- 源码构建所需 Dockerfile 与现有生产 Compose 命令对齐。
+- Schema 开发配置路径、固定远程开发库白名单及空库基线处理。
+
+## 非目标
+
+- 不实现市场概览页面和业务指标。
+- 不实现正式行情采集、AI 分析或付费功能。
+- 不实现用户、邀请、权限、会员或订阅。
+- 不把 HTTP DTO、数据库实体或消息事件做成前后端共享源码包。
+- 不实现未经验证的 RocketMQ Node SDK；本功能只建立 Adapter 边界、配置校验和禁用态启动能力。
+- 不创建、删除或修改生产基础设施与生产数据。
+
+## 验收标准
+
+- Node.js 非 22.x 时安装或校验入口明确失败，pnpm 主版本固定为 10。
+- 根命令可以分别启动、测试和构建 Web、API、Scheduler、Worker。
+- 三个 Server 进程共享配置和后端库，但拥有独立入口与最小配置读取范围。
+- Web 不导入 `server/` 源码；前端 API 类型来自提交或构建生成的 OpenAPI 客户端。
+- RocketMQ 事件类型不进入 Web 构建产物。
+- API 健康检查能够报告进程状态，并分别区分 Redis、MySQL 和禁用的 RocketMQ。
+- 开发配置从 `*.env.local` 加载，真实值继续被 Git 忽略，生产模板不获得开发地址或密码。
+- Schema 工具只接受 `development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定主机白名单；其他远程主机立即拒绝。
+- 空开发库可以生成可验证的 captured Schema 基线，不用空 SQL 冒充结构，也不退回 `not_applicable`。
+- 单元测试、契约测试、构建、开发启动冒烟和适用的浏览器验证全部通过。
+
@@ -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` 生成类型安全客户端。
@@ -0,0 +1,28 @@
+# 测试计划
+
+## 自动化
+
+- Node 22 与 pnpm 10 版本门禁测试。
+- Web 与 Server 配置键、敏感值脱敏和条件必填测试。
+- Web 禁止导入 Server 源码的边界测试。
+- OpenAPI 生成与漂移检测测试。
+- API、Scheduler、Worker 独立启动与关闭测试。
+- Redis/MySQL/RocketMQ disabled 健康状态测试。
+- RocketMQ 消息信封版本、幂等键和载荷校验测试。
+- Schema 固定远程白名单、未知远程拒绝和 `api.env.local` 优先级测试。
+- Schema 空库 captured 清单、摘要和历史目录不可覆盖测试。
+- Web、Server 类型检查、单元测试和生产构建。
+
+## 真实环境冒烟
+
+- Redis `127.0.0.1:6379` 的 DB 0、1、2 分别只读 PING。
+- 固定开发 MySQL 验证认证、5.7 服务端、数据库名、字符集、排序规则和 `+08:00` 会话时区。
+- RocketMQ 验证 NameServer、Broker 和 Proxy 可达；不创建 Topic，不发送消息。
+- 浏览器访问 Web 与 API 健康检查，无控制台阻断错误。
+
+## 安全检查
+
+- Git 跟踪文件不得包含本地密码、开发库凭据、AI Key 或生产地址。
+- Web 构建产物不得包含 Server env 键或消息契约。
+- 连接错误和测试日志不得输出密码。
+