a-share-analysis/docs/features/GOV-009-application-scaffold-baseline/requirements.md

工程需求

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 基线必须用 format v2 结构化清单的 object_counts 明确记录零对象，并产生确定性校验值；不得创建伪造 SQL 文件。验证器必须继续兼容既有 format v1 历史清单且不得重写。
• Schema 工具不得读取生产 env、连接生产数据库或导出任何表数据。

R7 部署与质量

• 项目只支持 Ubuntu 22.04/24.04 LTS x86_64 源码部署，不提供 Docker 运行、构建、测试或部署入口。
• Web、API、Scheduler、Worker 构建产物必须完整，源码部署的 systemd 命令必须与三个 Server 构建入口一致。
• 本地 Redis 和生产 Redis/MySQL/RocketMQ 均为外部系统服务，项目脚本不得安装、启动、停止或删除它们。
• verify:release 必须校验真实构建产物、systemd 最小权限和 Nginx Web/API 链路；Redis 不可达时 E2E 必须明确失败且不得提供容器兜底。
• 根级检查必须覆盖格式、静态检查、类型、单元测试、契约测试和构建。
• 所有关键配置边界、契约生成和启动失败行为必须有自动化测试。
• Server 使用 @nestjs/swagger 输出稳定的 openapi.json；Web 使用 openapi-typescript 与 openapi-fetch 生成类型安全客户端。

R8 实施后架构复核

• 开发阶段允许按批准设计实施，但设计文档不能代替对实际代码结构的复核。
• 所有测试和 Review 通过后，必须新增 architecture-review.md，以实际文件、依赖图、进程入口、契约生成和部署产物为证据。
• 复核必须比较至少一个替代架构，解释当前方案的收益、限制、后续拆分条件和可能的技术债。
• 必须向用户展示并完成论证；用户确认前 manifest 保持 reviewing、版本保持 unreleased，不得创建 v0.0.8 标签。