# 工程需求

## 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 部署与质量

- Web 与 Server 分别提供可重复构建的 Dockerfile，生产 Compose 使用不可变镜像并与真实产物路径一致。
- 源码部署的 systemd 命令必须与 Server 构建产物一致。
- 根级检查必须覆盖格式、静态检查、类型、单元测试、契约测试和构建。
- 所有关键配置边界、契约生成和启动失败行为必须有自动化测试。
- Server 使用 `@nestjs/swagger` 输出稳定的 `openapi.json`；Web 使用 `openapi-typescript` 与 `openapi-fetch` 生成类型安全客户端。