fix(GOV-009): 完成最终复审整改

AGENTS.md

@@ -24,7 +24,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **a-share-analysis** (1454 symbols, 2032 relationships, 44 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** (1520 symbols, 2137 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.
 

docs/deployment/docker-compose-production.md

@@ -18,6 +18,7 @@ docker build -f server/Dockerfile -t registry.example/a-share-server:<提交SHA>
 ```bash
 export A_SHARE_WEB_IMAGE='registry.example/a-share-web@sha256:<摘要>'
 export A_SHARE_SERVER_IMAGE='registry.example/a-share-server@sha256:<摘要>'
+pnpm check:images
 docker compose -f deploy/compose/production.yml.example config
 docker compose -f deploy/compose/production.yml.example up -d
 docker compose -f deploy/compose/production.yml.example ps

package.json

@@ -22,15 +22,17 @@
     "check:contracts": "pnpm --filter @a-share-analysis/server openapi:generate && pnpm --filter @a-share-analysis/web api:generate && pnpm exec prettier --write server/openapi/openapi.json web/src/api/generated/schema.ts && node tools/contracts/verify-generated-contracts.mjs && node tools/boundaries/verify-project-boundaries.mjs",
     "test:contracts": "node --test tools/contracts/verify-generated-contracts.test.mjs",
     "test:boundaries": "node --test tools/boundaries/verify-project-boundaries.test.mjs",
+    "test:deployment": "node --test tools/deployment/verify-image-references.test.mjs",
     "lint": "pnpm --filter @a-share-analysis/web --if-present lint && pnpm --filter @a-share-analysis/server --if-present lint",
     "format:check": "pnpm exec prettier --check .",
     "typecheck": "pnpm --filter @a-share-analysis/web --if-present typecheck && pnpm --filter @a-share-analysis/server --if-present typecheck",
-    "test": "pnpm test:runtime && pnpm test:governance && pnpm test:mysql-baseline && pnpm test:environment-baseline && pnpm test:schema-baseline && pnpm test:contracts && pnpm test:boundaries && pnpm --filter @a-share-analysis/web --if-present test && pnpm --filter @a-share-analysis/server --if-present test",
+    "test": "pnpm test:runtime && pnpm test:governance && pnpm test:mysql-baseline && pnpm test:environment-baseline && pnpm test:schema-baseline && pnpm test:contracts && pnpm test:boundaries && pnpm test:deployment && pnpm --filter @a-share-analysis/web --if-present test && pnpm --filter @a-share-analysis/server --if-present test",
     "build": "pnpm --filter @a-share-analysis/web --if-present build && pnpm --filter @a-share-analysis/server --if-present build",
     "verify:e2e": "pnpm --filter @a-share-analysis/web test:e2e",
+    "check:images": "node tools/deployment/verify-image-references.mjs",
     "verify:docker": "node tools/deployment/verify-docker.mjs",
     "verify": "pnpm check:runtime && pnpm check:contracts && pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build && pnpm verify:e2e",
-    "verify:release": "pnpm verify && pnpm verify:docker"
+    "verify:release": "pnpm verify && pnpm check:images && pnpm verify:docker"
   },
   "devDependencies": {
     "@eslint/js": "9.39.5",

server/test/process-smoke.test.ts

@@ -130,8 +130,8 @@ describe('NestJS 三进程入口', () => {
     const child = spawn(process.execPath, [launcher, entry], {
       cwd: path.resolve(__dirname, '..'),
       env: {
-        ...process.env,
-        APP_ENV: 'development',
+        PATH: process.env.PATH,
+        APP_ENV: 'production',
         LOG_LEVEL: 'error',
         REDIS_HOST: '127.0.0.1',
         REDIS_PORT: '6379',
@@ -162,7 +162,7 @@ describe('NestJS 三进程入口', () => {
         ROCKETMQ_CONSUMER_CONCURRENCY: '4',
         SCHEDULER_ENABLED: 'true',
         SCHEDULER_TIMEZONE: 'Asia/Shanghai',
-        MARKET_DATA_MODE: 'mock',
+        MARKET_DATA_MODE: 'live',
         MARKET_DATA_PROVIDER: 'deterministic-fixture',
         MARKET_DATA_BASE_URL: '',
         MARKET_DATA_API_KEY: '',

tools/boundaries/verify-project-boundaries.mjs

@@ -20,6 +20,12 @@ async function collectSourceFiles(directory) {
 
 function extractTypeScriptSource(sourcePath, sourceText) {
   if (path.extname(sourcePath) !== '.vue') return sourceText;
+  const externalScript = sourceText.match(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/i);
+  if (externalScript) {
+    throw new Error(
+      `Web Vue 组件禁止使用外部 script src：${path.basename(sourcePath)} -> ${externalScript[1]}`,
+    );
+  }
   // 边界门禁只需解析 SFC 的脚本块；模板和样式不会产生 TypeScript 模块依赖。
   return [...sourceText.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)]
     .map((match) => match[1])
@@ -65,6 +71,9 @@ function resolvesInsideServer(specifier, sourcePath, repositoryRoot, compilerOpt
   return candidate === serverRoot || candidate.startsWith(`${serverRoot}${path.sep}`);
 }
 
+/**
+ * 扫描 Web TypeScript 与 Vue 脚本，阻断对 Server 源码和内部消息契约的反向依赖。
+ */
 export async function verifyProjectBoundaries(repositoryRoot) {
   const webSourceRoot = path.join(repositoryRoot, 'web', 'src');
   const configPath = path.join(repositoryRoot, 'web', 'tsconfig.json');

tools/boundaries/verify-project-boundaries.test.mjs

@@ -108,6 +108,20 @@ const value: Internal | undefined = undefined;
   assert.match(result.stderr, /IllegalView\.vue/);
 });
 
+test('拒绝 Vue 外部 script src 绕过源码边界', async () => {
+  const repositoryRoot = await createFixture();
+  await writeFile(
+    path.join(repositoryRoot, 'web/src/ExternalScript.vue'),
+    `<script setup lang="ts" src="../../server/libs/internal.ts"></script>\n<template><main /></template>\n`,
+  );
+
+  const result = await runChecker(repositoryRoot);
+
+  assert.equal(result.exitCode, 1);
+  assert.match(result.stderr, /禁止使用外部 script src/);
+  assert.match(result.stderr, /ExternalScript\.vue/);
+});
+
 test('接受只消费公开 OpenAPI 类型的 Web 工程', async () => {
   const repositoryRoot = await createFixture();
   await writeFile(

tools/contracts/verify-generated-contracts.mjs

@@ -8,6 +8,18 @@ import { fileURLToPath } from 'node:url';
  * 避免用户其他工作区改动干扰契约门禁。
  */
 export function assertGeneratedContractsUnchanged(repositoryRoot, contractFiles) {
+  for (const contractFile of contractFiles) {
+    try {
+      execFileSync('git', ['ls-files', '--error-unmatch', '--', contractFile], {
+        cwd: repositoryRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'ignore', 'pipe'],
+      });
+    } catch {
+      throw new Error(`生成契约未纳入 Git 跟踪：${contractFile}`);
+    }
+  }
+
   try {
     execFileSync('git', ['diff', '--exit-code', '--', ...contractFiles], {
       cwd: repositoryRoot,

tools/contracts/verify-generated-contracts.test.mjs

@@ -34,3 +34,13 @@ test('生成契约发生漂移时以明确错误阻断', () => {
     /生成契约与 Git 提交版本不一致：contract\.json/,
   );
 });
+
+test('生成文件未纳入 Git 跟踪时阻断', () => {
+  const repositoryRoot = createGitFixture();
+  writeFileSync(path.join(repositoryRoot, 'untracked-contract.json'), '{"version":1}\n');
+
+  assert.throws(
+    () => assertGeneratedContractsUnchanged(repositoryRoot, ['untracked-contract.json']),
+    /生成契约未纳入 Git 跟踪：untracked-contract\.json/,
+  );
+});

tools/deployment/verify-docker.mjs

@@ -7,8 +7,10 @@ const serverImage = `a-share-analysis-server:verify-${suffix}`;
 const network = `a-share-analysis-verify-${suffix}`;
 const redis = `a-share-analysis-verify-redis-${suffix}`;
 const api = `a-share-analysis-verify-api-${suffix}`;
+const scheduler = `a-share-analysis-verify-scheduler-${suffix}`;
+const worker = `a-share-analysis-verify-worker-${suffix}`;
 const web = `a-share-analysis-verify-web-${suffix}`;
-const containers = [web, api, redis];
+const containers = [web, worker, scheduler, api, redis];
 
 function docker(args, options = {}) {
   return execFileSync('docker', args, {
@@ -32,6 +34,34 @@ function waitForContainerCommand(container, command, description) {
   throw new Error(`${description} 未在 6 秒内就绪：${String(lastError?.stderr ?? '')}`);
 }
 
+function verifyLongRunningProcess(container, entry, environment) {
+  const environmentArguments = environment.flatMap(([key, value]) => ['--env', `${key}=${value}`]);
+  docker(
+    [
+      'run',
+      '--detach',
+      '--name',
+      container,
+      ...environmentArguments,
+      serverImage,
+      'node',
+      `/app/dist/apps/${entry}/main.js`,
+    ],
+    { capture: true },
+  );
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 500);
+  const running = docker(['inspect', container, '--format', '{{.State.Running}}'], {
+    capture: true,
+  }).trim();
+  if (running !== 'true') throw new Error(`${entry} 容器未保持运行`);
+
+  docker(['stop', '--time', '5', container], { capture: true });
+  const exitCode = docker(['inspect', container, '--format', '{{.State.ExitCode}}'], {
+    capture: true,
+  }).trim();
+  if (exitCode !== '0') throw new Error(`${entry} 容器未优雅退出，退出码 ${exitCode}`);
+}
+
 try {
   docker(['build', '--file', 'web/Dockerfile', '--tag', webImage, '.']);
   docker(['build', '--file', 'server/Dockerfile', '--tag', serverImage, '.']);
@@ -48,6 +78,50 @@ try {
     );
   }
 
+  const sharedProcessEnvironment = [
+    ['APP_ENV', 'production'],
+    ['LOG_LEVEL', 'error'],
+    ['REDIS_HOST', '127.0.0.1'],
+    ['REDIS_PORT', '6379'],
+    ['REDIS_USERNAME', ''],
+    ['REDIS_PASSWORD', ''],
+    ['REDIS_DATABASE', '1'],
+    ['REDIS_TLS', 'false'],
+    ['ROCKETMQ_ENABLED', 'false'],
+    ['ROCKETMQ_NAMESRV_ADDR', '127.0.0.1:9876'],
+    ['ROCKETMQ_ENDPOINT', '127.0.0.1:8081'],
+    ['ROCKETMQ_TOPIC_PREFIX', 'a-share-analysis'],
+  ];
+  verifyLongRunningProcess(scheduler, 'scheduler', [
+    ...sharedProcessEnvironment,
+    ['SCHEDULER_TIMEZONE', 'Asia/Shanghai'],
+    ['SCHEDULER_ENABLED', 'true'],
+    ['ROCKETMQ_SEND_TIMEOUT_MS', '3000'],
+  ]);
+  verifyLongRunningProcess(worker, 'worker', [
+    ...sharedProcessEnvironment,
+    ['MARKET_DATA_MODE', 'live'],
+    ['MARKET_DATA_PROVIDER', 'deterministic-fixture'],
+    ['MARKET_DATA_BASE_URL', ''],
+    ['MARKET_DATA_API_KEY', ''],
+    ['MYSQL_ENABLED', 'false'],
+    ['MYSQL_HOST', '127.0.0.1'],
+    ['MYSQL_PORT', '3306'],
+    ['MYSQL_DATABASE', 'a_share_analysis_dev'],
+    ['MYSQL_USERNAME', ''],
+    ['MYSQL_PASSWORD', ''],
+    ['MYSQL_CHARSET', 'utf8mb4'],
+    ['MYSQL_COLLATION', 'utf8mb4_general_ci'],
+    ['MYSQL_TIMEZONE', '+08:00'],
+    ['AI_ENABLED', 'false'],
+    ['AI_BASE_URL', ''],
+    ['AI_API_KEY', ''],
+    ['AI_MODEL', ''],
+    ['AI_TIMEOUT_MS', '30000'],
+    ['ROCKETMQ_CONSUMER_GROUP', 'a-share-analysis-worker'],
+    ['ROCKETMQ_CONSUMER_CONCURRENCY', '4'],
+  ]);
+
   docker(['network', 'create', network], { capture: true });
   docker(['run', '--detach', '--name', redis, '--network', network, 'redis:7.4.8-alpine3.21'], {
     capture: true,
@@ -134,7 +208,7 @@ try {
     'Web 到 API 的 Nginx 代理',
   );
 
-  process.stdout.write('Docker 镜像、非 root 用户、三进程入口与 Web/API 链路验证通过\n');
+  process.stdout.write('Docker 镜像、非 root 用户、三进程生命周期与 Web/API 链路验证通过\n');
 } finally {
   for (const container of containers) {
     try {

tools/deployment/verify-image-references.mjs

@@ -0,0 +1,26 @@
+import process from 'node:process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const IMMUTABLE_IMAGE_PATTERN = /^\S+@sha256:[a-f0-9]{64}$/;
+
+/**
+ * Compose 变量语法只能阻断空值，无法拒绝 latest 或普通 tag；发布前必须先通过
+ * 该校验器，确保 Web/Server 都使用包含仓库名的内容摘要引用。
+ */
+export function assertImmutableImageReferences(environment) {
+  for (const key of ['A_SHARE_WEB_IMAGE', 'A_SHARE_SERVER_IMAGE']) {
+    const value = environment[key] ?? '';
+    if (!IMMUTABLE_IMAGE_PATTERN.test(value)) {
+      throw new Error(`${key} 必须使用仓库名@sha256摘要`);
+    }
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
+) {
+  assertImmutableImageReferences(process.env);
+  process.stdout.write('生产镜像引用验证通过\n');
+}

tools/deployment/verify-image-references.test.mjs

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { assertImmutableImageReferences } from './verify-image-references.mjs';
+
+const digest = `sha256:${'a'.repeat(64)}`;
+
+test('接受包含仓库名和 sha256 摘要的不可变镜像', () => {
+  assert.doesNotThrow(() =>
+    assertImmutableImageReferences({
+      A_SHARE_WEB_IMAGE: `registry.invalid/web@${digest}`,
+      A_SHARE_SERVER_IMAGE: `registry.invalid/server@${digest}`,
+    }),
+  );
+});
+
+for (const [name, image] of [
+  ['latest', 'registry.invalid/web:latest'],
+  ['普通 tag', 'registry.invalid/web:3a8120a'],
+  ['裸摘要', digest],
+  ['空值', ''],
+]) {
+  test(`拒绝 Web ${name} 镜像引用`, () => {
+    assert.throws(
+      () =>
+        assertImmutableImageReferences({
+          A_SHARE_WEB_IMAGE: image,
+          A_SHARE_SERVER_IMAGE: `registry.invalid/server@${digest}`,
+        }),
+      /A_SHARE_WEB_IMAGE 必须使用仓库名@sha256摘要/,
+    );
+  });
+}

web/src/api/adapters/health.adapter.ts

@@ -3,8 +3,10 @@ import type { components } from '../generated/schema';
 type HealthResponseDto = components['schemas']['HealthResponseDto'];
 type DependencyHealthDto = components['schemas']['DependencyHealthDto'];
 
+/** 页面级健康状态把后端 disabled 映射为 degraded，避免与真实故障混为一谈。 */
 export type HealthViewState = 'healthy' | 'degraded' | 'unavailable';
 
+/** 单项依赖的展示模型隐藏后端 DTO 结构，只保留名称、可用性和安全说明。 */
 export interface HealthServiceViewModel {
   key: 'redis' | 'mysql' | 'rocketMq';
   name: 'Redis' | 'MySQL' | 'RocketMQ';
@@ -12,6 +14,7 @@ export interface HealthServiceViewModel {
   note: string;
 }
 
+/** 健康页稳定展示契约；Vue 组件不直接依赖 OpenAPI 生成类型。 */
 export interface HealthViewModel {
   state: HealthViewState;
   stateLabel: '运行正常' | '部分能力停用' | '服务异常';
@@ -39,6 +42,7 @@ function toServiceViewModel(
   };
 }
 
+/** 将版本化 HTTP DTO 转为页面展示模型，并拒绝未知的服务端状态枚举。 */
 export function toHealthViewModel(dto: HealthResponseDto): HealthViewModel {
   const dependencies = Object.values(dto.dependencies);
   for (const dependency of dependencies) assertDependencyStatus(dependency.status);

web/src/api/client.ts

@@ -1,6 +1,7 @@
 import createClient, { type Client } from 'openapi-fetch';
 import type { paths } from './generated/schema';
 
+/** 统一的安全请求错误，不把浏览器或代理底层异常直接展示给用户。 */
 export class ApiRequestError extends Error {
   constructor() {
     super('API 请求失败，请稍后重试');
@@ -8,6 +9,7 @@ export class ApiRequestError extends Error {
   }
 }
 
+/** 创建受 OpenAPI paths 约束的客户端，并在边界统一清洗网络异常。 */
 export function createApiClient(
   baseUrl: string,
   fetchImplementation: (request: Request) => Promise<Response> = globalThis.fetch,

web/src/app/providers.ts

@@ -3,6 +3,7 @@ import type { App } from 'vue';
 
 import { createAppRouter } from './router';
 
+/** 集中安装全局 Provider，防止页面自行创建重复的 Pinia 或 Router 实例。 */
 export function installAppProviders(app: App) {
   app.use(createPinia());
   app.use(createAppRouter());

web/src/app/router.ts

@@ -17,6 +17,7 @@ const routes: RouteRecordRaw[] = [
   },
 ];
 
+/** 创建可注入 history 的路由实例，使浏览器运行与单元测试共享同一路由表。 */
 export function createAppRouter(history: RouterHistory = createWebHistory()) {
   return createRouter({ history, routes });
 }