feat(GOV-009): 建立 Vue 前端工程基线

2026-08-13 16:42:25 +08:00
parent 258a2d21f6
commit 28d54186ad
27 changed files with 3909 additions and 14 deletions
@@ -93,3 +93,7 @@ Server 数据访问使用 Nest 官方 `@nestjs/typeorm` 集成、TypeORM 和 `my
 ## 回退原则

 GOV-009 不迁移业务数据。回退时恢复上一 Git 标签即可移除脚手架；本地 `*.env.local` 和基础设施数据不随 Git 回退。若 Schema 工具变化失败，恢复旧工具后仍保留已发布基线，禁止改写历史目录。
+
+## 实施后架构论证门禁
+
+本文档描述的是实施前目标架构。完成代码、测试、构建和 Review 后，必须根据 GitNexus 实际依赖图、Web/Server 目录、三个 Server 进程、OpenAPI 生成链路和部署镜像另写 `architecture-review.md`。复核需要说明实际实现与目标的偏差、当前选择优于替代方案的理由、何时应拆分或调整。用户再次确认前不发布 `v0.0.8`，也不把本功能视为彻底完成。
@@ -6,7 +6,7 @@

 **Architecture:** 根 pnpm workspace 只编排 `web` 与 `server`。HTTP 契约由 Server 的 DTO 和 OpenAPI 单向发布，Web 生成自己的客户端；RocketMQ 消息契约只在 Server 内共享。Schema 安全门禁继续固定开发环境与数据库，只增加代码内固定远程主机和 `captured_empty` 状态。

-**Tech Stack:** Node.js 22.x、pnpm 10.25.0、TypeScript 5.9.3、Vue 3.5.41、Vite 7.3.6、Naive UI 2.44.1、Dart Sass 1.102.0、Vitest 3.2.7、Playwright 1.62.1、NestJS 11.1.29、TypeORM 0.3.31、mysql2 3.23.3、ioredis 5.11.1、MySQL 5.7、Redis、RocketMQ 5.x。
+**Tech Stack:** Node.js 22.x、pnpm 10.25.0、TypeScript 5.9.3、Vue 3.5.41、Vite 6.4.3、Naive UI 2.44.1、Dart Sass 1.102.0、Vitest 3.2.7、Playwright 1.62.1、NestJS 11.1.29、TypeORM 0.3.31、mysql2 3.23.3、ioredis 5.11.1、MySQL 5.7、Redis、RocketMQ 5.x。

 ## Global Constraints

@@ -25,6 +25,7 @@
 ### Task 1: 修正 Schema 开发配置与空库基线

 **Files:**
+
 - Modify: `tools/database/schema-baseline.mjs`
 - Modify: `tools/database/schema-baseline.test.mjs`
 - Modify: `docs/governance/development-workflow.md`
@@ -32,6 +33,7 @@
 - Modify: `docs/deployment/local-development.md`

 **Interfaces:**
+
 - Produces: `resolveFixedDevelopmentEnv(repositoryRoot): string`，优先返回 `deploy/env/development/api.env.local`，缺失时退回模板。
 - Produces: `assertSafeDevelopmentConfiguration(config): Readonly<SchemaConfig>`，只接受回环地址或 `112.192.20.11`。
 - Produces: `buildCapturedEmptyArtifacts(metadata): BaselineArtifacts`，状态为 `captured_empty`、format v2，只保存结构化清单、`object_counts` 和空结构 SHA-256，不创建 `schema.sql`。
@@ -69,12 +71,7 @@ Expected: FAIL，原因分别为 `api.env.local` 未被选择、固定远程地
 在代码内使用不可变集合，不读取动态白名单变量：

 ```js
-const DEVELOPMENT_HOSTS = new Set([
-  '127.0.0.1',
-  'localhost',
-  '::1',
-  '112.192.20.11',
-]);
+const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '112.192.20.11']);

 export function resolveFixedDevelopmentEnv(repositoryRoot) {
  const localEnv = path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.local');
@@ -146,6 +143,7 @@ Push: `git push origin "$(git branch --show-current)"`
 ### Task 2: 建立 Node 22 与 pnpm workspace 质量基线

 **Files:**
+
 - Modify: `package.json`
 - Create: `pnpm-workspace.yaml`
 - Create: `pnpm-lock.yaml`
@@ -156,6 +154,7 @@ Push: `git push origin "$(git branch --show-current)"`
 - Create: `tools/runtime/verify-runtime.test.mjs`

 **Interfaces:**
+
 - Produces: `assertSupportedRuntime({ nodeVersion, pnpmVersion })`。
 - Produces root scripts: `check:runtime`, `lint`, `format:check`, `typecheck`, `test`, `build`, `verify`。

@@ -211,6 +210,7 @@ Push current branch and verify local/remote SHA equality.
 ### Task 3: 建立 Vue 3 Web 工程

 **Files:**
+
 - Delete: `web/.gitkeep`
 - Create: `web/package.json`
 - Create: `web/tsconfig.json`
@@ -229,6 +229,7 @@ Push current branch and verify local/remote SHA equality.
 - Create: `web/tests/smoke.spec.ts`

 **Interfaces:**
+
 - Produces: `createAppRouter()` 和 `installAppProviders(app)`。
 - Consumes: only `VITE_APP_ENV`, `VITE_API_BASE_URL`, `VITE_APP_TITLE` from `web.env.local`。
 - Preserves: FEAT-MO-001 将在 `src/features/market-overview/` 添加首屏，不需要重构应用入口。
@@ -245,7 +246,7 @@ Expected: FAIL，因为 Web 包和应用入口尚不存在。

 - [ ] **Step 3: 创建精确依赖和最小应用外壳**

-Web dependencies 精确锁定 Vue 3.5.41、Vue Router 4.6.4、Pinia 3.0.4、Naive UI 2.44.1；dev dependencies 锁定 Vite 7.3.6、plugin-vue 6.0.8、TypeScript 5.9.3、vue-tsc 3.3.9、Sass 1.102.0、Vitest 3.2.7、Vue Test Utils 2.4.11、jsdom 26.1.0、Playwright 1.62.1。
+Web dependencies 精确锁定 Vue 3.5.41、Vue Router 4.6.4、Pinia 3.0.4、Naive UI 2.44.1；dev dependencies 锁定 Vite 6.4.3、plugin-vue 5.2.4、TypeScript 5.9.3、vue-tsc 3.3.9、Sass 1.102.0、Vitest 3.2.7、Vue Test Utils 2.4.11、jsdom 26.1.0、Playwright 1.62.1。该组合兼容开发机 Node 22.11；Vite 7 要求 Node 22.12+，不在本基线采用。

 `main.ts` 固定从项目外部加载开发 env：

@@ -284,6 +285,7 @@ Push current branch and verify remote SHA.
 ### Task 4: 建立 NestJS 三进程与最小权限配置

 **Files:**
+
 - Delete: `server/.gitkeep`
 - Create: `server/package.json`
 - Create: `server/nest-cli.json`
@@ -301,6 +303,7 @@ Push current branch and verify remote SHA.
 - Create: `server/test/process-smoke.test.ts`

 **Interfaces:**
+
 - Produces: `loadApiConfig`, `loadSchedulerConfig`, `loadWorkerConfig`，返回冻结且不含未知字段的配置。
 - Produces: `bootstrapApi`, `bootstrapScheduler`, `bootstrapWorker`，支持依赖注入端口和优雅关闭。
 - Consumes: `deploy/env/development/<process>.env.local` only in development; production only consumes `process.env` injected by Compose/systemd.
@@ -367,6 +370,7 @@ Commit: `feat(GOV-009): 建立 NestJS 三进程基线`
 ### Task 5: 建立后端契约、基础设施与 API 健康检查

 **Files:**
+
 - Create: `server/libs/http-contracts/src/health.dto.ts`
 - Create: `server/libs/message-contracts/src/message-envelope.ts`
 - Create: `server/libs/message-contracts/src/message-envelope.test.ts`
@@ -387,6 +391,7 @@ Commit: `feat(GOV-009): 建立 NestJS 三进程基线`
 - Modify ignored local API/Worker env files to retain `MYSQL_TIMEZONE=+08:00` without staging them.

 **Interfaces:**
+
 - Produces: `GET /api/v1/health -> HealthResponseDto`。
 - Produces: `MessageEnvelope<TPayload>` with `version`, `eventType`, `idempotencyKey`, `occurredAt`, `payload`。
 - Produces: `MessageBusAdapter.publish/subscribe/close`，disabled adapter rejects publish/subscribe with a typed error。
@@ -454,6 +459,7 @@ Commit: `feat(GOV-009): 建立后端契约与健康检查`
 ### Task 6: 生成 Web OpenAPI 客户端并强制边界

 **Files:**
+
 - Create: `web/src/api/generated/schema.ts`
 - Create: `web/src/api/client.ts`
 - Create: `web/src/api/adapters/health.adapter.ts`
@@ -464,6 +470,7 @@ Commit: `feat(GOV-009): 建立后端契约与健康检查`
 - Modify: root `package.json`

 **Interfaces:**
+
 - Consumes: `server/openapi/openapi.json` as the only cross-project contract artifact.
 - Produces: `createApiClient(baseUrl)` using `openapi-fetch` and generated `paths` type.
 - Produces: `toHealthViewModel(dto): HealthViewModel`，页面模型不暴露后端枚举细节。
@@ -499,6 +506,7 @@ Commit: `feat(GOV-009): 建立前端 OpenAPI 客户端边界`
 ### Task 7: 对齐 Docker、Compose、systemd 与源码开发命令

 **Files:**
+
 - Create: `web/Dockerfile`
 - Create: `web/nginx.conf`
 - Create: `server/Dockerfile`
@@ -514,6 +522,7 @@ Commit: `feat(GOV-009): 建立前端 OpenAPI 客户端边界`
 - Modify: `tools/governance/environment-baseline.test.mjs`

 **Interfaces:**
+
 - Produces immutable Web image serving `/` and proxying `/api/` according to deployment contract.
 - Produces one Server image with commands `dist/apps/api/main.js`, `dist/apps/scheduler/main.js`, `dist/apps/worker/main.js`.

@@ -542,6 +551,7 @@ Commit: `build(GOV-009): 对齐应用部署与运行入口`
 ### Task 8: 完成全量验证、Review 与发布留痕

 **Files:**
+
 - Update: `docs/features/GOV-009-application-scaffold-baseline/manifest.yaml`
 - Create: `docs/features/GOV-009-application-scaffold-baseline/gitnexus/detected-changes.md`
 - Create: `docs/features/GOV-009-application-scaffold-baseline/gitnexus/after.md`
@@ -552,10 +562,12 @@ Commit: `build(GOV-009): 对齐应用部署与运行入口`
 - Create: `docs/features/GOV-009-application-scaffold-baseline/review/standards-review.md`
 - Create: `docs/features/GOV-009-application-scaffold-baseline/release-notes.md`
 - Create: `docs/features/GOV-009-application-scaffold-baseline/rollback.md`
+- Create: `docs/features/GOV-009-application-scaffold-baseline/architecture-review.md`
 - Modify: `VERSION`
 - Modify: `CHANGELOG.md`

 **Interfaces:**
+
 - Produces: reproducible evidence for tests, builds, browser screenshots, GitNexus changes, reviews, release and rollback.

 - [ ] **Step 1: 在固定 Node 22 环境运行完整验证**
@@ -584,12 +596,16 @@ Run GitNexus `detect_changes`，核对新增 API、Scheduler、Worker、OpenAPI

 将版本提升到 `0.0.8`，说明工程能力而不声称市场概览已实现。回退说明不得删除远程数据库或 Redis 数据，只回退应用代码和镜像。

- [ ] **Step 6: 最终提交、推送与标签**
+- [ ] **Step 6: 基于实际实现完成架构复核并向用户论证**
+
+`architecture-review.md` 必须引用真实文件和 GitNexus 流程，说明 Web 分层、Server 三进程、HTTP 与消息契约方向、基础设施边界、部署产物、替代方案、已知限制和后续调整触发条件。将 manifest 保持 `reviewing` 和 `unreleased`，提交并推送复核材料，然后向用户展示论证；未获得用户再次确认时在此停止，不创建标签。
+
+- [ ] **Step 7: 用户确认后执行最终提交、推送与标签**

 Commit: `docs(GOV-009): 封存应用脚手架验证结果`

 Push current branch, compare local and remote SHA, create annotated tag `v0.0.8`, then run `git push origin v0.0.8`。禁止 `--tags` 和任何 force 选项。

- [ ] **Step 7: 刷新 GitNexus 并确认干净状态**
+- [ ] **Step 8: 刷新 GitNexus 并确认干净状态**

 Run `npx gitnexus status`; stale 时运行 analyze。最终要求工作区干净、`main` 与 `origin/main` 一致、远程 `v0.0.8^{}` 指向本地标签提交。
@@ -12,3 +12,4 @@ test_plan: test-plan.md
 gitnexus_before: gitnexus/before.md
 gitnexus_impact: gitnexus/impact-plan.md
 release: unreleased
+completion_gate: 实施完成后必须基于实际前后端架构向用户论证并再次确认
@@ -56,4 +56,4 @@
 - Schema 工具只接受 `development`、`a_share_analysis_dev`、MySQL 5.7、`utf8mb4_general_ci` 和固定主机白名单；其他远程主机立即拒绝。
 - 空开发库可以生成可验证的 captured Schema 基线，不用空 SQL 冒充结构，也不退回 `not_applicable`。
 - 单元测试、契约测试、构建、开发启动冒烟和适用的浏览器验证全部通过。
-
+- 全部实施完成后必须基于真实代码和部署产物提交《实施架构复核》，向用户论证前后端职责、依赖方向、进程边界、替代方案和演进成本；获得用户再次确认前，GOV-009 不得标记完成或创建发布标签。
@@ -49,3 +49,10 @@
 - 根级检查必须覆盖格式、静态检查、类型、单元测试、契约测试和构建。
 - 所有关键配置边界、契约生成和启动失败行为必须有自动化测试。
 - Server 使用 `@nestjs/swagger` 输出稳定的 `openapi.json`；Web 使用 `openapi-typescript` 与 `openapi-fetch` 生成类型安全客户端。
+
+## R8 实施后架构复核
+
+- 开发阶段允许按批准设计实施，但设计文档不能代替对实际代码结构的复核。
+- 所有测试和 Review 通过后，必须新增 `architecture-review.md`，以实际文件、依赖图、进程入口、契约生成和部署产物为证据。
+- 复核必须比较至少一个替代架构，解释当前方案的收益、限制、后续拆分条件和可能的技术债。
+- 必须向用户展示并完成论证；用户确认前 manifest 保持 `reviewing`、版本保持 `unreleased`，不得创建 `v0.0.8` 标签。