From c04184a6111da0cfad90d1a265dc3cd3a6d90a9c Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Thu, 13 Aug 2026 15:07:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(GOV-009):=20=E6=98=8E=E7=A1=AE=E5=BA=94?= =?UTF-8?q?=E7=94=A8=E8=84=9A=E6=89=8B=E6=9E=B6=E8=AE=BE=E8=AE=A1=E8=BE=B9?= =?UTF-8?q?=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../design.md | 95 +++++++++++++++++++ .../implementation-plan.md | 14 +++ .../manifest.yaml | 13 +++ .../prd.md | 59 ++++++++++++ .../requirements.md | 51 ++++++++++ .../test-plan.md | 28 ++++++ docs/index.md | 1 + 7 files changed, 261 insertions(+) create mode 100644 docs/features/GOV-009-application-scaffold-baseline/design.md create mode 100644 docs/features/GOV-009-application-scaffold-baseline/implementation-plan.md create mode 100644 docs/features/GOV-009-application-scaffold-baseline/manifest.yaml create mode 100644 docs/features/GOV-009-application-scaffold-baseline/prd.md create mode 100644 docs/features/GOV-009-application-scaffold-baseline/requirements.md create mode 100644 docs/features/GOV-009-application-scaffold-baseline/test-plan.md diff --git a/docs/features/GOV-009-application-scaffold-baseline/design.md b/docs/features/GOV-009-application-scaffold-baseline/design.md new file mode 100644 index 0000000..a3cfc3a --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/design.md @@ -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/.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 工具变化失败，恢复旧工具后仍保留已发布基线，禁止改写历史目录。 diff --git a/docs/features/GOV-009-application-scaffold-baseline/implementation-plan.md b/docs/features/GOV-009-application-scaffold-baseline/implementation-plan.md new file mode 100644 index 0000000..b9f9606 --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/implementation-plan.md @@ -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、版本与发布留痕。 + diff --git a/docs/features/GOV-009-application-scaffold-baseline/manifest.yaml b/docs/features/GOV-009-application-scaffold-baseline/manifest.yaml new file mode 100644 index 0000000..e813f6e --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/manifest.yaml @@ -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 + diff --git a/docs/features/GOV-009-application-scaffold-baseline/prd.md b/docs/features/GOV-009-application-scaffold-baseline/prd.md new file mode 100644 index 0000000..c47c716 --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/prd.md @@ -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`。 +- 单元测试、契约测试、构建、开发启动冒烟和适用的浏览器验证全部通过。 + diff --git a/docs/features/GOV-009-application-scaffold-baseline/requirements.md b/docs/features/GOV-009-application-scaffold-baseline/requirements.md new file mode 100644 index 0000000..d71924d --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/requirements.md @@ -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` 生成类型安全客户端。 diff --git a/docs/features/GOV-009-application-scaffold-baseline/test-plan.md b/docs/features/GOV-009-application-scaffold-baseline/test-plan.md new file mode 100644 index 0000000..ab79010 --- /dev/null +++ b/docs/features/GOV-009-application-scaffold-baseline/test-plan.md @@ -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 键或消息契约。 +- 连接错误和测试日志不得输出密码。 + diff --git a/docs/index.md b/docs/index.md index 0bdbe0e..ba2d6ac 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,5 +44,6 @@ - [GOV-006：开发、生产环境与双部署方式](features/GOV-006-environment-deployment-baseline/manifest.yaml) - [GOV-007：开发数据库 Schema 基线与版本门禁](features/GOV-007-development-schema-baseline/manifest.yaml) - [GOV-008：RocketMQ 消息队列架构调整](features/GOV-008-rocketmq-adoption/manifest.yaml) +- [GOV-009：应用工程脚手架基线](features/GOV-009-application-scaffold-baseline/manifest.yaml) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。