应用工程脚手架基线设计

功能编号：GOV-009
设计版本：0.1
状态：review
日期：2026-08-13

总体结构

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 只用于一致安装和根命令调度。

契约方向

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；生产运行只依靠 systemd EnvironmentFile 注入，不从源码目录寻找生产 env。配置解析采用白名单 Schema，未知键可以保留给其他进程，但当前进程只解析最小集合。

敏感值只用于建立连接，错误对象和日志使用键名而不输出实际值。Web 构建只加载 web.env.local 中的 VITE_ 变量。

数据库基线

Schema 工具优先读取 api.env.local，不存在时才退回 api.env.example。开发数据库主机允许回环地址和代码内固定白名单 112.192.20.11，不能由命令行临时追加。其余环境、库名、版本、字符集和排序规则继续严格校验。

当前远程开发库为空。空库仍然是“已启用且已检查”的事实，不应标记为 MySQL 未启用。生成器将保存 format v2 的 captured_empty 结构化清单，其中 object_counts 全部为零、客户端和服务端版本真实可验证，并对规范化的空结构计算确定性摘要；不创建空 schema.sql。验证器继续只读兼容既有 format v1 清单，禁止借格式升级重写历史目录。首次迁移产生对象后，下一发布版本开始生成完整 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 入口执行真实构建验证；源码发布门禁同时核对 systemd 和 Nginx 模板。
E2E 在启动 API 前只读检查现有本机 Redis；不可达时明确失败，不启动替代基础设施。

安全策略与评估

配置按 API、Scheduler、Worker 最小权限拆分，生产只由 systemd EnvironmentFile 注入；Web 只允许公开的 VITE_ 变量进入构建产物。
Schema 工具硬编码开发环境、固定库名和主机白名单，密码只通过子进程环境传递；本功能禁止连接、探测或读取生产数据库。
Redis/MySQL 健康检查和启动错误只返回脱敏状态；RocketMQ 未验证时明确禁用，不以进程内队列伪降级。
OpenAPI 契约、Web/Server 源码边界和消息契约隔离由自动门禁验证。残余风险是 RocketMQ Node 客户端和真实行情数据源尚未接入，必须在各自功能中重新做依赖与安全评估。

性能目标与评估

脚手架目标是保持 Web 和三个 Server 进程可独立构建、启动和扩容；根 workspace 只编排质量命令，不进入生产运行时。
健康检查只执行有限的 Redis/MySQL 只读操作，禁止自动重试风暴；Scheduler 与 Worker 采用独立进程，避免任务执行阻塞 HTTP API。
OpenAPI 和边界扫描只在开发、测试和发布阶段运行，不增加线上请求路径开销。当前尚无行情吞吐、数据库查询或消息积压业务，因此不伪造业务性能指标；后续功能必须按刷新周期、数据量和延迟重新设定基线。

回退原则

GOV-009 不迁移业务数据。回退时恢复上一 Git 标签即可移除脚手架；本地 *.env.local 和基础设施数据不随 Git 回退。若 Schema 工具变化失败，恢复旧工具后仍保留已发布基线，禁止改写历史目录。

实施后架构论证门禁

本文档描述的是实施前目标架构。完成代码、测试、构建和 Review 后，必须根据 GitNexus 实际依赖图、Web/Server 目录、三个 Server 进程、OpenAPI 生成链路和源码部署产物另写 architecture-review.md。复核需要说明实际实现与目标的偏差、当前选择优于替代方案的理由、何时应拆分或调整。用户再次确认前不发布 v0.0.8，也不把本功能视为彻底完成。

7.9 KiB Raw Permalink Blame History Unescape Escape