61 lines
4.2 KiB
Markdown
61 lines
4.2 KiB
Markdown
# 工程需求
|
||
|
||
## 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` 标签。
|