docs(GOV-009): 封存脚手架复核材料

2026-08-13 19:55:45 +08:00
parent 95b8611bd9
commit f50268b70f
15 changed files with 290 additions and 2 deletions
@@ -24,7 +24,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence

-This project is indexed by GitNexus as **a-share-analysis** (1520 symbols, 2137 relationships, 47 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **a-share-analysis** (1577 symbols, 2199 relationships, 47 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.

@@ -0,0 +1,57 @@
+# 前后端项目架构复核与论证
+
+- 复核基线：`95b8611bd9bbc282193591e472e2e19c617e5035`
+- 状态：实现已验证，等待用户确认
+
+## 实际落地结构
+
+```text
+repository
+├── web/                         Vue 3 独立工程
+│   └── src/
+│       ├── app/                 应用装配、路由和根视图
+│       ├── api/generated/       OpenAPI 自动生成类型
+│       ├── api/adapters/        面向页面的稳定数据适配
+│       └── styles/              Sass 全局样式与后续 token 入口
+├── server/                      NestJS 独立工程
+│   ├── apps/api/                HTTP 与 OpenAPI 入口
+│   ├── apps/scheduler/          只负责任务触发的无 HTTP 进程
+│   ├── apps/worker/             任务执行的无 HTTP 进程
+│   └── libs/
+│       ├── config/              三进程最小权限配置契约
+│       ├── http-contracts/      Server DTO
+│       ├── message-contracts/   Server 内部 RocketMQ 信封
+│       └── infrastructure/      Redis、MySQL、消息与生命周期适配
+├── deploy/                      Compose、systemd、Nginx、env 模板
+└── tools/                       治理、Schema、契约、边界和部署验证
+```
+
+## 为什么当前拆分合适
+
+1. **前后端工程分开，但仓库不割裂。** Web 和 Server 有各自 package、构建与类型检查，责任清楚；根 workspace 只做质量编排。个人开发阶段仍能一次安装和验证，避免维护多个仓库与跨仓库版本同步。
+2. **不建立根共享 contracts 包。** HTTP 只有一个事实源：Server DTO 生成 OpenAPI，Web 再生成自己的类型。Web 无法直接引用 Server 源码，`.vue` 和 TypeScript 都有自动边界检查。这样比手工同步两份类型或共享内部类更明确。
+3. **一个 Server 工程、三个进程入口。** API、Scheduler、Worker 使用相同基础设施与消息契约，但启动、配置和部署彼此独立。当前规模下没有必要拆成三个仓库或三个重复 Nest 工程；未来可独立扩容进程而不复制公共代码。
+4. **配置是进程级最小权限。** API 不读取任务消费配置，Scheduler 不读取 MySQL/AI 密钥，Worker 不读取 API 端口。配置先校验和冻结，再通过动态模块注入，测试与生产使用同一装配路径。
+5. **基础设施通过 Adapter 隔离。** 业务代码将依赖 MessageBus、Repository 和数据源端口；RocketMQ 客户端尚未验证时明确禁用，避免以临时内存队列形成错误语义。
+6. **部署方式共享同一产物。** Ubuntu 源码部署使用 Web dist 与三个 Server dist 入口；现有 Docker Compose 只作为可选交付适配层复用这些产物，不形成第二套应用逻辑。按用户 2026-08-13 的决定，日常开发不再构建 Docker，待核心功能完成后再决定保留或移除。
+
+## 适合下一阶段的扩展方式
+
+- Web 市场概览应建立一个可连续阅读的 `features/market-overview/` 业务目录，内部按页面、数据适配和状态拆分；短线与中长线作为市场概览下的模式，不拆成两个独立应用。
+- Server 在 API/Scheduler/Worker 各入口内注册同一市场概览业务能力的不同适配面；共享领域模型和规则计算放入稳定业务库，HTTP DTO、消息 DTO 与数据库实体继续分离。
+- 用户体系、订阅和权限暂不加入当前业务模型；未来通过独立功能档案增加，不让其反向污染市场概览核心。
+- 当某个业务域出现独立发布节奏、团队所有权或明显扩容边界时，再论证拆包或拆服务；当前提前微服务化只会增加契约、部署和运维成本。
+
+## 已知限制
+
+- 当前 Web 只是工程外壳，没有市场概览 UI、行情图表和分析工作台。
+- RocketMQ 只有契约和禁用 Adapter，尚未选择并验证 Node 客户端。
+- TypeORM 已固定安全选项，但尚无业务实体和迁移。
+- 用户体系和订阅能力按用户决定后置，不在 GOV-009 范围。
+- Docker 交付方式尚未最终确认；现有文件和历史验证保留，但不能据此推定最终生产一定采用容器部署。
+
+## 复核结论
+
+现有架构适合“先做市场概览、个人使用为主、未来可扩展订阅”的阶段：边界清晰、运行方式简单、契约可自动校验，也保留 API/Scheduler/Worker 独立扩容路径。它不是不可变终局；完成市场概览真实业务后，仍应根据模块依赖和运行数据再次复核，而不是凭脚手架预判过度拆分。
+
+用户确认本论证前，GOV-009 保持 `reviewing/unreleased`，不得创建 `v0.0.8` 标签。
@@ -0,0 +1,19 @@
+# GitNexus 开发后基线
+
+- 记录时间：2026-08-13 GMT+8
+- 分支：`main`
+- 实现提交：`95b8611bd9bbc282193591e472e2e19c617e5035`
+- 远端：`origin/main` 已核对为同一 SHA
+
+```text
+Repository: a-share-analysis
+Indexed commit: 95b8611
+Current commit: 95b8611
+Status: up-to-date
+Nodes: 1568
+Relationships: 2190
+Clusters: 46
+Execution flows: 47
+```
+
+图谱已包含 Web、API、Scheduler、Worker、配置加载、健康检查、OpenAPI、消息信封、Schema、Docker 验证和治理门禁。GitNexus 本地索引未提交仓库。
@@ -0,0 +1,18 @@
+# GitNexus 前后对比
+
+| 项目 | 开发前 `c04184a6` | 开发后 `95b8611` | 变化 |
+| --- | ---: | ---: | ---: |
+| 符号 | 958 | 1568 | +610 |
+| 关系 | 1141 | 2190 | +1049 |
+| 执行流程 | 23 | 47 | +24 |
+
+开发前仓库以治理文档、环境模板和 Schema 工具为主，Web/Server 仍无可运行应用。开发后形成以下新边界：
+
+- Vue 3 Web 可启动、测试、构建，并通过生成的 OpenAPI 类型访问 API。
+- NestJS API、Scheduler、Worker 为独立入口和独立配置容器。
+- Scheduler/Worker 具备可验证的持续运行与 SIGTERM 优雅关闭生命周期。
+- HTTP 契约由 Server DTO 单向发布；RocketMQ 消息信封只存在于 Server。
+- Docker Compose 与 Ubuntu 源码部署共用同一配置语义和构建产物。
+- Schema 空库、MySQL 5.7.42、契约漂移和 `.vue` 工程边界均有自动门禁。
+
+新增关系数量符合“从占位目录建立应用基线”的预期。后续市场概览功能应在这些边界内增加业务模块，不应把 Web 与 Server 重新耦合。
@@ -0,0 +1,15 @@
+# GitNexus 变更检测
+
+- 对比基线：`c04184a6111da0cfad90d1a265dc3cd3a6d90a9c`
+- 实现提交：`95b8611bd9bbc282193591e472e2e19c617e5035`
+- 检测命令：`npx gitnexus detect-changes --scope compare --base-ref c04184a6 --repo a-share-analysis`
+- 变更范围：110 个文件、452 个符号、45 条执行流程
+- 风险：CRITICAL
+
+CRITICAL 来自一次建立完整 Web、API、Scheduler、Worker、契约生成、Schema 和部署验证链路，而不是单个未受控函数。主要流程为三进程配置加载、Schema 生成/验证、OpenAPI 发布、Web 客户端边界和 Docker/源码部署。
+
+Review 整改前对具体符号分别执行上游影响分析：三进程 bootstrap、动态模块、消息信封、空库捕获和 MySQL 健康检查大多为 LOW；`assertMysql57Metadata` 因位于 Schema 发布门禁核心为 CRITICAL。该变更只把服务端补丁版本固定到 5.7.42，历史 `v0.0.7` 清单回归和 `schema:verify` 均通过。
+
+最终代码复审补充发现无引号 Vue 外部 `script src` 可绕过早期正则门禁；影响分析为 LOW，只有 1 个直接调用者和 1 条边界检查流程。`95b8611` 改用 Vue 3.5.41 官方 SFC 解析器，并以单双引号、无引号和属性换序用例验证，未扩大应用运行影响面。
+
+检测范围与开发前影响计划一致，未出现用户体系、生产数据库、外部消息写入或其他项目流程。
@@ -609,3 +609,35 @@ Push current branch, compare local and remote SHA, create annotated tag `v0.0.8`
 - [ ] **Step 8: 刷新 GitNexus 并确认干净状态**

 Run `npx gitnexus status`; stale 时运行 analyze。最终要求工作区干净、`main` 与 `origin/main` 一致、远程 `v0.0.8^{}` 指向本地标签提交。
+
+---
+
+## 实际执行记录
+
+### 已完成任务与远端提交
+
+| Task | RED / GREEN 与验证摘要 | 提交 | 推送证据 |
+| --- | --- | --- | --- |
+| 1 Schema | 配置路径、固定远程白名单、历史 N/A 与空库用例先失败；实现后 Schema 27/27、治理 5/5、环境 7/7 | `b3d8e29` | 15:43:07 `origin/main update by push` |
+| 2 Workspace | 运行时模块缺失先失败；Node 22/pnpm 10 门禁与 frozen install 后通过 | `258a2d2` | 15:54:08 推送 |
+| 3 Web | App 缺失、模板 `import.meta.env` 与路由警告依次复现；Vitest、类型、构建、双视口 Playwright 后通过 | `28d5418`、`dcdf634` | 16:43:48、18:03:38 推送 |
+| 4 三进程 | 配置条件与启动入口先失败；三个 Nest 入口和独立配置 Schema 后通过 | `3fc703d` | 16:59:12 推送 |
+| 5 后端契约 | 消息、健康接口和 OpenAPI 先失败；Server 契约与只读客户端后通过 | `420aa22` | 17:26:53 推送 |
+| 6 Web 契约 | Web 越界导入与 adapter 行为先失败；OpenAPI 生成客户端和边界门禁后通过 | `4665336` | 17:36:58 推送 |
+| 7 部署 | Docker/systemd 产物断言先失败；双镜像、三入口和双部署文档后通过 | `c771a98` | 17:56:39 推送 |
+| 8 Review 整改 | 生命周期、配置注入、消息字段、5.7.42、空库、SFC、漂移、代理与 Docker 集成均有 RED/GREEN；最终补齐未跟踪契约、Vue 官方 SFC 解析、镜像摘要和容器生命周期门禁；`pnpm verify` 通过，Docker 留存历史验证 | `3a8120a`、`cb550e3`、`95b8611` | 18:31:10、18:51:16、19:49:46 推送 |
+
+上述推送时间来自项目级 `origin/main` reflog；所有阶段均在提交后 1–83 秒内推送。提交摘要全部为包含 `GOV-009` 的中文 Conventional Commit。
+
+### 计划状态
+
+- Task 1–7：已实现、验证、提交并推送；原始步骤复选框保留为开发前计划，不反向改写预期命令和 RED 描述。
+- Task 8 Step 1–3、5：已完成全量验证、视觉证据、GitNexus 检测与发布/回退材料。
+- Task 8 Step 4：代码 Review 追加发现无引号外部脚本绕过，已用 Vue 官方 SFC 解析器整改；代码 Review 与规范 Review 最终结论均为 `passed`。
+- Task 8 Step 6：架构复核文档已生成，正在向用户论证并等待确认。
+- Task 8 Step 7：未执行；用户确认前禁止创建或推送 `v0.0.8`。
+- Task 8 Step 8：开发后图谱已刷新到 `95b8611`；最终档案提交后还需再次刷新并核对远端。
+
+### Docker 后续执行口径
+
+用户于 2026-08-13 决定：Docker 暂不作为后续日常开发与阶段验收的必跑项，待核心功能完整后再决定是否保留 Docker 部署。现有 Docker/Compose 文件与本次已通过的历史验证不删除；后续日常执行 `pnpm verify`，只有最终交付且用户确认继续采用 Docker 时才执行 `pnpm verify:docker` 或 `pnpm verify:release`。
@@ -1,7 +1,7 @@
 id: GOV-009
 name: 应用工程脚手架基线
 slug: application-scaffold-baseline
-status: approved
+status: reviewing
 owner: project
 created_at: 2026-08-13
 prd: prd.md
@@ -13,3 +13,4 @@ gitnexus_before: gitnexus/before.md
 gitnexus_impact: gitnexus/impact-plan.md
 release: unreleased
 completion_gate: 实施完成后必须基于实际前后端架构向用户论证并再次确认
+architecture_review: architecture-review.md
@@ -0,0 +1,48 @@
+# 测试结果
+
+- 日期：2026-08-13
+- 实现提交：`95b8611bd9bbc282193591e472e2e19c617e5035`
+- 状态：passed
+
+## 测试先行证据
+
+- 三进程配置 Token 缺失、Scheduler/Worker 启动后自行退出：RED；动态模块注入和生命周期锚点实现后 GREEN。
+- 消息信封缺少追溯字段、MySQL 接受 5.7.41、真实空库 dump 被误判：RED；完整信封、5.7.42 固定和对象计数判空后 GREEN。
+- `.vue` 越界导入未被发现、Vite 无 `/api` 代理：RED；SFC 脚本扫描和同源代理后 GREEN。
+- 契约漂移验证模块不存在：RED；生成后限定路径 Git diff 与 Git 跟踪门禁后 3/3 GREEN。
+- Vue 外部 `script src`、可变镜像标签和干净 checkout 生命周期用例依次 RED；禁止外部脚本、摘要校验与公开生产 fixture 实现后 GREEN。
+- Playwright 访问真实健康接口时代理连接拒绝：RED；同时启动测试 API 并复用可用本机 Redis 后 GREEN。
+
+## 完整验证
+
+`pnpm verify`：passed。
+
+- 运行时：Node.js 22.11.0、pnpm 10.25.0。
+- 治理：5/5。
+- MySQL 架构规范：2/2。
+- 环境与部署契约：11/11。
+- Schema 基线：28/28；`v0.0.7 (not_applicable)` 验证通过。
+- 生成契约漂移：3/3；OpenAPI 与 Web 生成类型同步，未跟踪生成物会阻断。
+- 工程边界：8/8，包含 Vue SFC 内联脚本，以及外部脚本单双引号、无引号和属性换序越界用例。
+- 生产镜像引用：5/5；拒绝空值、`latest`、普通 tag 和裸摘要。
+- Web Vitest：8/8。
+- Server Vitest：30/30，包含 API/Scheduler/Worker 与两个真实子进程生命周期用例。
+- Web、API、Scheduler、Worker 生产构建：passed。
+- Playwright：桌面/移动共 4/4；页面外壳与 Web → Vite → Nest API 健康链路均通过。
+- `git diff --check`、ESLint、Prettier、TypeScript：passed。
+
+`pnpm verify:docker`：passed。
+
+该结果是 2026-08-13 已完成的历史交付验证。按用户随后决定，Docker 不再作为日常开发必跑项；核心功能完成后再决定是否保留 Docker 部署，并仅在最终交付阶段按需重跑。
+
+- Web 与 Server 多阶段镜像真实构建成功。
+- Server 镜像以 `node` 非 root 用户运行。
+- API、Scheduler、Worker 三个镜像入口存在；Scheduler/Worker 均在容器内持续运行，并在 `SIGTERM` 后退出码为 0。
+- 隔离容器内 Redis/API/Web 启动，API 健康 200、Web 首页和 Nginx `/api` 代理通过。
+- 临时容器、网络和验证镜像已清理。
+
+## 本机与固定开发基础设施
+
+- 本机 Redis `127.0.0.1:6379` 的 DB 0、1、2 分别执行只读 `PING`，三次均返回 `PONG`；未读取或修改业务键。
+- 固定开发 MySQL 只读会话返回 `5.7.42-0ubuntu0.18.04.1`、库 `a_share_analysis_dev`、`utf8mb4`、`utf8mb4_general_ci`、会话时区 `+08:00`；Task 1 对象计数为 0。密码只通过临时进程环境传递，未输出或写入命令参数；未连接、探测或读取生产数据库。
+- 本机 RocketMQ 只读 TCP 可达性复核：NameServer `127.0.0.1:9876`、Broker `127.0.0.1:10911`、Proxy `127.0.0.1:8081` 均可达。Node Adapter 仍保持禁用，没有创建 Topic、消费或发送消息。
@@ -0,0 +1,21 @@
+# 视觉 QA
+
+- 日期：2026-08-13
+- 浏览器：Playwright Chromium
+- 状态：passed
+
+## 桌面 1440 × 900
+
+- 证据：`../screenshots/iterations/app-shell-ready-1440x900-3a8120a.png`
+- SHA-256：`79b3ef53178c9d35fc10b75aac2d844d34c886d4e2faab69762922f4cda17802`
+- 顶部品牌栏、应用标题和“工程基线已就绪”可见。
+- `main` 可见，无水平溢出、控制台 warning/error 或页面异常。
+
+## 移动 390 × 844
+
+- 证据：`../screenshots/iterations/app-shell-ready-390x844-3a8120a.png`
+- SHA-256：`12f56ae24d51c64b1e0dfc03a8a2e3538e5ce5a7a33c2863f9bff5d53efe3d1d`
+- 品牌栏与正文在窄屏正常换行和留白，无水平溢出。
+- 无控制台 warning/error 或页面异常。
+
+当前画面仅证明工程外壳与响应式基线，不代表市场概览产品视觉已经完成；市场概览页面将在后续功能档案中单独设计、实现和验收。
@@ -0,0 +1,15 @@
+# 发布说明
+
+GOV-009 建立了可运行的应用工程基线：
+
+- 根 pnpm workspace 编排独立的 Vue 3 Web 与 NestJS Server 工程。
+- Server 提供 API、Scheduler、Worker 三个独立入口、最小权限配置和优雅关闭生命周期。
+- HTTP 契约由 Server DTO/OpenAPI 单向生成 Web 客户端；RocketMQ 消息契约保持 Server 内部。
+- Redis/MySQL 只读健康检查、TypeORM MySQL 5.7.42 基线和 RocketMQ 禁用 Adapter 已建立。
+- 开发/生产模板、Docker Compose、Ubuntu systemd/Nginx 与源码部署路径已对齐。
+- Schema 支持固定远程开发库与真实空库 `captured_empty`，历史清单保持不可变。
+- 新增契约漂移、Vue SFC 边界、三进程生命周期、Playwright 真实 API 和 Docker 集成门禁。
+
+当前状态为 `reviewing/unreleased`。实现提交已推送至 `origin/main`，但按用户要求，必须完成基于真实实现的架构论证并再次确认后才能创建和推送 `v0.0.8` 标签。
+
+Docker Compose 当前降级为待定的可选交付能力：保留既有文件和历史验证，不进入后续日常开发必跑流程；核心功能完成后由用户决定最终保留 Docker 还是仅采用源码部署。
@@ -0,0 +1,24 @@
+# 代码 Review
+
+- 审查范围：`c04184a6111da0cfad90d1a265dc3cd3a6d90a9c..95b8611bd9bbc282193591e472e2e19c617e5035`
+- 审查方式：独立只读复审
+- 日期：2026-08-13
+
+## 发现与处置
+
+第一轮发现三进程生命周期依赖本地 env、未跟踪生成契约可绕过漂移检查、Vue 外部脚本可绕过边界、生产镜像允许可变 tag，以及 Docker 未验证镜像内 Scheduler/Worker 生命周期。上述问题已在 `cb550e3` 完成整改并通过针对性测试。
+
+最终复审进一步发现早期外部脚本正则不能识别合法的无引号 `src` 属性。GitNexus 单符号影响分析为 LOW，只有 `verifyProjectBoundaries` 一个直接调用者和一条边界检查流程。`95b8611` 改用固定版本 `@vue/compiler-sfc@3.5.41`，直接拒绝普通脚本或 setup 脚本的外部 `src`，测试覆盖双引号、单引号、无引号和属性换序，边界用例 8/8 通过。
+
+## 最终证据
+
+- `pnpm verify` 完整通过：静态检查、类型、全部测试、Web/Server 构建和 Playwright 4/4。
+- 契约漂移 3/3、工程边界 8/8、镜像引用 5/5、Web 8/8、Server 30/30。
+- Scheduler/Worker 的源码子进程生命周期使用公开 production fixture，可在干净 checkout 复现。
+- HTTP 契约保持 Server DTO → OpenAPI → Web 单向发布；RocketMQ 消息契约只在 Server 内部。
+- 未发现新的配置泄漏、安全、生命周期、错误处理或生产风险。
+- Docker 是已验证过的历史可选交付能力；按用户决定不再作为后续日常门禁，最终开发完成后再决定是否保留。
+
+Critical、Important、Minor 均无未关闭问题。
+
+最终结论：passed
@@ -0,0 +1,21 @@
+# 开发规范符合性 Review
+
+- 审查范围：`c04184a6111da0cfad90d1a265dc3cd3a6d90a9c..95b8611bd9bbc282193591e472e2e19c617e5035`
+- 审查方式：独立只读复审
+- 日期：2026-08-13
+
+## 规范核对
+
+- 所有 GOV-009 实现提交均为包含功能编号的中文 Conventional Commit，并在验证后及时推送 Gitea。
+- GitNexus 前置、影响分析、开发后索引和前后对比完整；最终索引提交为 `95b8611`。
+- 公共导出、契约字段、安全边界和架构取舍均有准确中文注释，未发现无意义逐行注释或过度拆分。
+- MySQL 固定为 5.7.42、`utf8mb4`、`utf8mb4_general_ci` 和 `+08:00`；Schema 流程只允许固定开发库和白名单主机。
+- Redis DB 0/1/2 均只读 `PING` 成功；RocketMQ NameServer/Broker/Proxy 均只读验证可达，未创建 Topic 或发送消息。
+- 截图位于 `screenshots/iterations/`，文件名包含页面、状态、视口和实现版本，文档引用与 SHA-256 一致。
+- 未发现密钥、真实 env、生产数据或 GitNexus 本地索引被 Git 跟踪。
+- Docker 最新决定已统一记录为历史验证、可选交付、非日常必跑，不篡改此前真实验证记录。
+- manifest 保持 `reviewing/unreleased`，本地与远端均不存在 `v0.0.8`。
+
+Critical、Important、Minor 均无未关闭问题。
+
+最终结论：passed
@@ -0,0 +1,17 @@
+# 回退说明
+
+GOV-009 没有创建业务表、执行迁移、写入生产数据库、创建 RocketMQ Topic 或发送消息。回退重点是应用代码与部署产物，不包含数据回滚。
+
+## 代码回退
+
+- 以中文 Conventional Commit 新建回退提交，按逆序撤销 GOV-009 提交；禁止 `reset --hard`、强推或改写 Gitea 历史。
+- 若只回退 Review 整改，目标提交为 `3a8120a33aff3fc4e1f73059eed78d88d57d33a2`，必须同时恢复消息契约、三进程生命周期、契约漂移和部署门禁，禁止形成半套状态。
+- 若整体移除脚手架，回到基线 `c04184a6111da0cfad90d1a265dc3cd3a6d90a9c` 的等价内容，并保留既有 `v0.0.7` Schema 历史目录。
+
+## 部署回退
+
+- Docker 恢复上一组 Web/Server 不可变镜像摘要；源码部署把 `/opt/a-share-analysis/current` 切回上一完整发布目录并重启三个 systemd 服务。
+- `/etc/a-share-analysis/*.env`、本地 `*.env.local`、Redis、MySQL 和 RocketMQ 数据不随应用回退覆盖或删除。
+- 回退后重新执行健康检查、契约门禁和可用性验证。
+
+当前尚未创建 `v0.0.8` 标签，因此无需删除或移动标签。用户确认发布后，若发布回退也只能新建更高版本修复或明确的回退提交，不能移动已推送标签。