From f178fb4044fce9a21069b091ace2c8ac5e721ff7 Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Thu, 13 Aug 2026 23:56:21 +0800 Subject: [PATCH] =?UTF-8?q?feat(GOV-010):=20=E5=AE=8C=E6=88=90=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E8=B4=A8=E9=87=8F=E4=B8=8E=E6=9E=B6=E6=9E=84=E6=B2=BB?= =?UTF-8?q?=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- .../development-summary.md | 6 +- .../gitnexus/after.md | 23 ++++++++ .../gitnexus/comparison.md | 26 +++++++++ .../gitnexus/detected-changes.md | 18 ++++++ .../implementation-plan.md | 38 ++++++------ .../manifest.yaml | 2 +- .../qa/test-results.md | 43 ++++++++++++++ .../qa/visual-qa.md | 19 ++++++ .../review/code-review.md | 54 ++++++++++++++++++ .../review/standards-review.md | 40 +++++++++++++ .../app-shell-desktop-1440x900-61f85e5.png | Bin 0 -> 12308 bytes .../iterations/app-shell-mobile-61f85e5.png | Bin 0 -> 5470 bytes tools/governance/feature-record.mjs | 3 +- tools/governance/feature-record.test.mjs | 18 ++++++ 15 files changed, 270 insertions(+), 22 deletions(-) create mode 100644 docs/features/GOV-010-development-quality-architecture/gitnexus/after.md create mode 100644 docs/features/GOV-010-development-quality-architecture/gitnexus/comparison.md create mode 100644 docs/features/GOV-010-development-quality-architecture/gitnexus/detected-changes.md create mode 100644 docs/features/GOV-010-development-quality-architecture/qa/test-results.md create mode 100644 docs/features/GOV-010-development-quality-architecture/qa/visual-qa.md create mode 100644 docs/features/GOV-010-development-quality-architecture/review/code-review.md create mode 100644 docs/features/GOV-010-development-quality-architecture/review/standards-review.md create mode 100644 docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-desktop-1440x900-61f85e5.png create mode 100644 docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-mobile-61f85e5.png diff --git a/AGENTS.md b/AGENTS.md index 2d57fc3..8ab0096 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (1613 symbols, 2260 relationships, 50 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** (1847 symbols, 2522 relationships, 50 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. diff --git a/docs/features/GOV-010-development-quality-architecture/development-summary.md b/docs/features/GOV-010-development-quality-architecture/development-summary.md index a26ecf6..1fc8717 100644 --- a/docs/features/GOV-010-development-quality-architecture/development-summary.md +++ b/docs/features/GOV-010-development-quality-architecture/development-summary.md @@ -37,7 +37,9 @@ 本次没有修复既有市场业务缺陷，因为仓库尚处基础治理与脚手架阶段。本次修复的是工程治理缺口：此前开发总结不是独立必备证据、安全与性能章节缺少结构化门禁、前端请求库和业务 API 边界未按用户确认的 Axios 范式落实、项目边界无法阻断直接 HTTP 绕过。对应回归测试位于治理规则、请求封装、Vite 配置、健康 API 和项目边界测试中。 -验证阶段使用 npm 官方审计端点发现 `@nestjs/swagger 11.4.6` 精确依赖的 `js-yaml 5.2.1` 存在 GHSA-pm4m-ph32-ghv5 高危拒绝服务漏洞；当前最新版 Swagger 仍锁定该版本。项目采用 pnpm 精确覆盖，仅把 `@nestjs/swagger>js-yaml` 更新到同补丁线修复版本 5.2.2，不影响其他 `js-yaml` 消费者。修复前 audit 失败输出与修复后 audit、OpenAPI、后端测试和构建结果将进入 QA 证据。 +验证阶段使用 npm 官方审计端点发现 `@nestjs/swagger 11.4.6` 精确依赖的 `js-yaml 5.2.1` 存在 GHSA-pm4m-ph32-ghv5 高危拒绝服务漏洞；当前最新版 Swagger 仍锁定该版本。项目采用 pnpm 精确覆盖，仅把 `@nestjs/swagger>js-yaml` 更新到同补丁线修复版本 5.2.2，不影响其他 `js-yaml` 消费者。修复前 audit 失败输出与修复后 audit、OpenAPI、后端测试和构建结果已进入 QA 证据。 + +代码 Review 初审另发现完成门禁可接受正文中间的 `最终结论：passed`，已新增失败测试并修复为只接受最后一个非空行；治理测试最终为 10/10，处置记录见两份 Review。 ## 未完成与延期项 @@ -63,7 +65,7 @@ ## 验证证据 - 已完成的局部证据：治理测试 9 项通过；请求与配置测试 10 项通过；Web 测试 11 项通过；项目边界测试 16 项通过；Web/Server 类型检查、lint、格式和 OpenAPI 契约检查均在对应阶段通过。 -- GitNexus 阶段检测：治理、规范和 Axios 请求层为 LOW；边界工具为 MEDIUM，原因是唯一的项目边界验证执行流发生变化，不进入生产运行时。该结果必须在最终比较与 Review 中复核。 +- GitNexus 阶段检测：治理、规范和 Axios 请求层为 LOW；最终 compare 为 MEDIUM（35 个文件、163 个变更符号、1 条 `CreateRequestClient → ApiRequestError` 执行流），边界工具变化只在开发门禁执行，不进入生产运行时。最新状态、前后比较和 Review 已复核该结果。 - 安全证据：请求错误脱敏、取消语义、有限超时和 HTTP 边界已有单元测试；依赖 audit、构建产物敏感字符串扫描和最终 Git diff 检查将在 `qa/test-results.md` 保存。 - 性能证据：迁移前 Web 构建基线为 JS 163908 字节、CSS 805 字节；最终构建体积、增量和 10 秒默认超时/无自动重试结论将在 `qa/test-results.md` 保存。 - 完整测试、源码发布验证和桌面/移动视觉证据将在 `qa/` 与 `screenshots/iterations/` 保存；代码 Review 和规范 Review 将保存于 `review/`。 diff --git a/docs/features/GOV-010-development-quality-architecture/gitnexus/after.md b/docs/features/GOV-010-development-quality-architecture/gitnexus/after.md new file mode 100644 index 0000000..b98dbdc --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/gitnexus/after.md @@ -0,0 +1,23 @@ +# GitNexus 开发后基线 + +- 功能编号：GOV-010 +- 完成前索引提交：`61f85e5` +- 当前工作提交：`61f85e5` + +## GitNexus 状态 + +```text +Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis +Indexed: 8/13/2026, 11:46:53 PM +Indexed commit: 61f85e5 +Current commit: 61f85e5 +Status: up-to-date +Nodes: 1,827 +Edges: 2,502 +Clusters: 49 +Flows: 50 +``` + +## 开发后检测 + +`gitnexus_detect_changes(scope="compare", base_ref="1c1b15e")`：35 个文件、163 个变更符号、1 条受影响执行流，风险 MEDIUM。详细内容见 `detected-changes.md` 和 `comparison.md`。 diff --git a/docs/features/GOV-010-development-quality-architecture/gitnexus/comparison.md b/docs/features/GOV-010-development-quality-architecture/gitnexus/comparison.md new file mode 100644 index 0000000..9d1ba56 --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/gitnexus/comparison.md @@ -0,0 +1,26 @@ +# GOV-010 GitNexus 计划与实际影响比较 + +## 直接与间接影响 + +- 计划中的治理门禁符号已实际改变：`getRequiredFeatureFiles`、`getInvalidFeatureEvidence`、`finish.mjs` 和 `start.mjs` 的测试与完成流程均通过治理测试覆盖。 +- 计划中的请求基础设施影响已实际发生：旧 `createApiClient`/`ApiRequestError` 调用方仅为旧测试；替换后的 `createRequestClient`、`ApiRequestError` 和健康 API 通过 11 项 Web 测试、类型检查、E2E 和构建验证。 +- GitNexus compare 的唯一受影响运行流为 `CreateRequestClient → ApiRequestError`，与计划一致；边界校验是开发期执行流，未进入生产运行时。 + +## 跨模块同步修改 + +| 领域 | 计划结论 | 实际结果 | 是否偏差 | +|---|---|---|---| +| HTTP/OpenAPI | 保留路由、字段和生成 Schema，仅切换浏览器执行器 | 契约生成无漂移，健康 API 使用生成 DTO，Axios 只在统一 request | 否 | +| Web API/adapter | 新增健康域 API，保持 DTO 到 ViewModel 隔离 | `api/health/index.ts` 新增，页面仍未消费健康 API，adapter 未被无谓迁移 | 否 | +| RocketMQ | 不修改消息契约 | 未修改 | 否 | +| MySQL/Schema | 不修改结构，开发前基线只读开发库 | 全量 Schema 测试通过，未触碰生产库 | 否 | +| Redis | 不修改缓存键、TTL 或连接 | 只做本机 `PONG` 健康验证，未改代码或数据 | 否 | +| API/Scheduler/Worker | 不改变运行行为 | 后端测试和三进程构建通过，行为未改 | 否 | +| 配置/部署 | 沿用 Web API 根地址，不改变源码部署 | 源码发布门禁通过，无 Docker 变更 | 否 | +| 治理/边界工具 | 增加结构化证据和 HTTP 边界门禁 | 9 项治理、16 项边界测试通过 | 否 | +| 依赖 | 移除 `openapi-fetch`，新增 Axios；补传递依赖安全修复 | Axios 1.19.0；`js-yaml` 5.2.2 override；官方 audit 0 漏洞 | 仅增加安全修复 | +| 测试/视觉 | 完整测试、构建、E2E、双视口截图 | 全部通过，截图和无回归结论已保存 | 否 | + +## 风险差异 + +相对基线 compare 输出 MEDIUM，而开发前单项影响多为 LOW/partial。差异来自新增的前端请求运行流和项目边界校验符号，不表示业务数据链路或三进程运行风险升级。复审阶段又收紧了 Review 最终结论校验，变更符号总数由 162 增至 163，仍只有同一条 `CreateRequestClient → ApiRequestError` 运行流受影响。`e992edc` 的传递依赖修复降低了安全风险，未改变 OpenAPI 或生产运行流。 diff --git a/docs/features/GOV-010-development-quality-architecture/gitnexus/detected-changes.md b/docs/features/GOV-010-development-quality-architecture/gitnexus/detected-changes.md new file mode 100644 index 0000000..58c59c6 --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/gitnexus/detected-changes.md @@ -0,0 +1,18 @@ +# GOV-010 GitNexus 开发后变更检测 + +- 检测提交：`61f85e5` +- 检测方式：重新执行 `npx gitnexus analyze` 后调用 `gitnexus_detect_changes(scope="compare", base_ref="1c1b15e")` +- GitNexus 状态：1,827 nodes、2,502 edges、49 clusters、50 flows；索引提交与当前提交均为 `61f85e5`，状态 up-to-date。 + +## 检测结果 + +- 变更文件：35 +- 变更符号：163（主要为治理文档章节、治理/边界工具符号及 Axios 请求测试/实现符号） +- 受影响执行流：1 +- 风险：MEDIUM + +受影响执行流为 `CreateRequestClient → ApiRequestError`，包含 `createRequestClient`、`toApiRequestError` 和 `ApiRequestError` 三步。它是本次 Axios 请求层迁移的预期运行时边界，已由 Web 单元测试、类型检查、E2E 和构建覆盖。 + +MEDIUM 还反映了项目边界验证流的变化：该工具增加了 Axios、fetch、业务 URL 和统一 request 的 AST 规则。它只在开发/发布门禁运行，不进入 API、Scheduler、Worker 或浏览器生产请求路径。 + +未检测到计划外的 RocketMQ 消息消费者、MySQL/Redis 数据访问、Schema 迁移或三进程运行流变化。GitNexus 对 Markdown 文档以章节符号记录，不能替代人工阅读，因此同步修改结论在 `comparison.md` 和 Review 中重复核对。 diff --git a/docs/features/GOV-010-development-quality-architecture/implementation-plan.md b/docs/features/GOV-010-development-quality-architecture/implementation-plan.md index a8f479a..5176780 100644 --- a/docs/features/GOV-010-development-quality-architecture/implementation-plan.md +++ b/docs/features/GOV-010-development-quality-architecture/implementation-plan.md @@ -629,7 +629,7 @@ git push origin main ### Task 5: GOV-010 档案、依赖评估与开发总结 -**实施状态：进行中。** 开发总结、发布说明、依赖评估和档案状态已补齐；安全审计发现并通过 `e992edc` 修复 Swagger 的 `js-yaml` 传递依赖漏洞，等待本阶段档案提交。 +**实施状态：已完成。** 开发总结、发布说明、依赖评估和档案状态已补齐；安全审计发现并通过 `e992edc` 修复 Swagger 的 `js-yaml` 传递依赖漏洞，Review 初审发现的结论行校验绕过也已通过测试先行修复。 **Files:** @@ -663,7 +663,7 @@ git status --short 若 audit 报告风险，先按可利用性和影响评估，Important 以上不得进入 passed Review；不得为了清零数字盲目升级无关依赖。 -- [ ] **Step 3: 完成性能证据** +- [x] **Step 3: 完成性能证据** 构建后记录实际 JS/CSS 文件字节数，与 Task 3 基线 `163908/805` 比较；确认 request 没有默认重试，默认超时为 10 秒。治理校验只在开发/发布路径运行，不做生产负载测试，并在“不适用”结论中写清边界。 @@ -671,7 +671,7 @@ git status --short `manifest.yaml` 状态改为 `verifying`，保留 `release: unreleased`。`release-notes.md` 说明治理门禁、架构规范和 Axios 迁移，不宣称市场概览、AI 或用户功能已完成。 -- [ ] **Step 5: 校验档案内容** +- [x] **Step 5: 校验档案内容** Run: @@ -683,7 +683,7 @@ git diff --check Expected: PASS，且开发总结不存在空章节或无解释占位词。 -- [ ] **Step 6: 检测变化并提交推送** +- [x] **Step 6: 检测变化并提交推送** Run GitNexus `detect_changes(scope="all")`，然后： @@ -697,6 +697,8 @@ git push origin main ### Task 6: 全量验证、视觉回归与 GitNexus 对比 +**实施状态：已完成。** 全量契约、lint、格式、类型、测试、构建、E2E、源码发布、audit、视觉截图和 GitNexus compare 证据已写入 `qa/` 与 `gitnexus/`。 + **Files:** - Create: `docs/features/GOV-010-development-quality-architecture/qa/test-results.md` @@ -712,7 +714,7 @@ git push origin main - Consumes: Tasks 1-5 的完整实现和档案。 - Produces: 最新、可复现的测试、安全、性能、视觉和 GitNexus 证据。 -- [ ] **Step 1: 执行全量非浏览器验证** +- [x] **Step 1: 执行全量非浏览器验证** Run: @@ -727,7 +729,7 @@ pnpm build Expected: 全部退出码 0。任何失败先按 systematic-debugging 查根因并修复，不能只在报告中标记忽略。 -- [ ] **Step 2: 检查构建产物和敏感信息** +- [x] **Step 2: 检查构建产物和敏感信息** Run: @@ -739,7 +741,7 @@ pnpm audit --prod Expected: 构建产物不含敏感标记；记录实际包体增量和 audit 结论。 -- [ ] **Step 3: 执行浏览器与源码发布验证** +- [x] **Step 3: 执行浏览器与源码发布验证** 确认本机 Redis 可用后运行： @@ -750,11 +752,11 @@ pnpm verify:release Expected: 桌面和移动 Chromium 均通过，API 健康契约通过，源码部署门禁通过；不启动 Docker 或替代基础设施。 -- [ ] **Step 4: 保存同视口视觉证据** +- [x] **Step 4: 保存同视口视觉证据** 使用 Playwright 截取 1440x900 和 390x844 的应用外壳；检查页面可见、无横向溢出、无控制台 error/warning、标题和主内容不重叠。因为本次不改 UI，视觉结论应为“无可观察回归”，而不是宣称新增页面设计。 -- [ ] **Step 5: 运行 GitNexus 开发后检测** +- [x] **Step 5: 运行 GitNexus 开发后检测** Run: @@ -765,11 +767,11 @@ npx gitnexus status 调用 `gitnexus_detect_changes(scope="compare", base_ref="1c1b15e")`，记录变更符号、执行流、风险和工具限制。`comparison.md` 逐项对照开发前同步修改表，特别确认 HTTP 字段、RocketMQ、MySQL、Redis、Scheduler 和 Worker 未发生计划外变化。 -- [ ] **Step 6: 填写 QA 与 GitNexus 报告** +- [x] **Step 6: 填写 QA 与 GitNexus 报告** `test-results.md` 记录命令、时间、退出码、关键输出、Axios 依赖评估、安全扫描和包体数据；`visual-qa.md` 链接两张截图并记录视口与结论；`detected-changes.md` 和 `comparison.md` 不得只写“通过”。 -- [ ] **Step 7: 执行完成门禁的预检** +- [x] **Step 7: 执行完成门禁的预检** 在 Review 尚未标记 passed 前，`governance:finish` 应明确只因 Review 或尚缺 Review 报告失败，不能因开发总结、安全、性能或影响章节失败。记录预检结果，但不要伪造 passed Review。 @@ -777,6 +779,8 @@ npx gitnexus status ### Task 7: 双 Review、完成门禁与最终推送 +**实施状态：进行中。** 两份自审报告已完成且最终结论均为 `passed`，最终门禁已通过；待提交和推送。 + **Files:** - Create: `docs/features/GOV-010-development-quality-architecture/review/code-review.md` @@ -793,19 +797,19 @@ npx gitnexus status - Produces: 两份 findings-first Review；只有 Critical 和 Important 全部关闭后才能以独占末行写 `最终结论：passed`。 - Produces: 通过 `governance:finish` 的 GOV-010 功能档案，但仍保持 `release: unreleased`，除非用户另行确认版本发布。 -- [ ] **Step 1: 使用代码 Review 流程审查实际实现** +- [x] **Step 1: 使用代码 Review 流程审查实际实现** 按严重程度先列发现，检查请求错误脱敏、取消语义、类型边界、URL/HTTP 绕过、门禁误判、安全和性能证据、测试真实性。没有发现时明确写“未发现 Critical/Important/Minor”，并列残余风险和测试边界。 -- [ ] **Step 2: 使用规范 Review 逐条审查** +- [x] **Step 2: 使用规范 Review 逐条审查** 检查中文注释、文件拆分、真实重复后抽象、后端按需分层、Axios/API 分域、OpenAPI 类型、GitNexus 同步修改、开发总结、中文提交和 Gitea 推送。不得把模板勾选框直接当证据，需引用文件和命令。 -- [ ] **Step 3: 修复所有 Critical 和 Important** +- [x] **Step 3: 修复所有 Critical 和 Important** 每个修复先补失败测试并重跑受影响验证；更新 GitNexus 开发后报告和 Review 处置。Minor 可延期，但必须记录理由与后续功能编号。 -- [ ] **Step 4: 运行最终完整验证** +- [x] **Step 4: 运行最终完整验证** Run: @@ -818,7 +822,7 @@ git status --short Expected: 所有命令通过；`governance:finish` 验证独立开发总结、证据章节和双 Review。 -- [ ] **Step 5: 提交前 GitNexus 检测** +- [x] **Step 5: 提交前 GitNexus 检测** 调用 `gitnexus_detect_changes(scope="all")`，确认实际影响与 `comparison.md` 一致；发现计划外进程时停止提交，先补设计、测试和用户风险说明。 @@ -840,6 +844,6 @@ npx gitnexus status Expected: 本地与远程 main SHA 一致；GitNexus 若因最终提交过期，运行 `npx gitnexus analyze`，单独以中文文档提交更新最终统计并再次推送。 -- [ ] **Step 7: 保持未发布状态** +- [x] **Step 7: 保持未发布状态** GOV-010 完成开发和 Review 后可将 `manifest.yaml` 状态设为 `reviewing` 或 `approved_for_release`（若现有状态机不支持后者则保持 `reviewing`），但 `release` 继续为 `unreleased`，不创建 `v0.0.8` 或更高标签。版本发布仍需结合 GOV-009 架构复核和用户后续确认。 diff --git a/docs/features/GOV-010-development-quality-architecture/manifest.yaml b/docs/features/GOV-010-development-quality-architecture/manifest.yaml index 161b344..b409f0a 100644 --- a/docs/features/GOV-010-development-quality-architecture/manifest.yaml +++ b/docs/features/GOV-010-development-quality-architecture/manifest.yaml @@ -1,7 +1,7 @@ id: GOV-010 name: 开发质量与前后端架构规范 slug: development-quality-architecture -status: verifying +status: reviewing owner: project created_at: 2026-08-13 prd: prd.md diff --git a/docs/features/GOV-010-development-quality-architecture/qa/test-results.md b/docs/features/GOV-010-development-quality-architecture/qa/test-results.md new file mode 100644 index 0000000..ab1f2ac --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/qa/test-results.md @@ -0,0 +1,43 @@ +# GOV-010 测试与质量证据 + +- 功能编号：GOV-010 +- 验证提交：`61f85e5` +- 验证日期：2026-08-13 + +## 全量命令 + +以下命令按顺序执行，均退出码为 0： + +| 命令 | 结果 | 关键证据 | +|---|---|---| +| `pnpm check:contracts` | passed | OpenAPI 与生成 TypeScript 契约无漂移；项目边界验证通过 | +| `pnpm lint` | passed | Web 与 Server ESLint 无错误 | +| `pnpm format:check` | passed | 全仓 Prettier 格式通过 | +| `pnpm typecheck` | passed | Web、Vite 配置和 Server TypeScript 检查通过 | +| `pnpm test` | passed | runtime 2、governance 9、MySQL 2、环境 10、Schema 28、contracts 3、boundaries 16、deployment 6、Web 11、Server 30 + API 预检 2 | +| `pnpm build` | passed | Web Vite 构建；API、Scheduler、Worker 三进程 Nest 构建 | +| `pnpm verify:e2e` | passed | Chromium 桌面和移动 4/4 通过 | +| `pnpm verify:source` | passed | 源码发布产物与 systemd/Nginx 配置通过 | + +## 安全验证 + +- `redis-cli -h 127.0.0.1 -p 6379 ping` 返回 `PONG`；只验证开发机本地 Redis 可达，不读取生产配置或数据。 +- 构建产物扫描 `MYSQL_PASSWORD|AI_API_KEY|Root@|mysql://root:|Authorization: Bearer` 未发现匹配。 +- 修复前官方 npm audit 发现 `server>@nestjs/swagger>js-yaml@5.2.1` 的 GHSA-pm4m-ph32-ghv5 High 拒绝服务漏洞；`@nestjs/swagger@11.4.6` 仍精确依赖 5.2.1。 +- 提交 `e992edc` 使用 pnpm 项目级精确 override 将 `@nestjs/swagger>js-yaml` 固定到修复版本 `5.2.2`。`pnpm why js-yaml --prod -r` 和解析路径检查均确认实际版本 5.2.2。 +- 修复后 `pnpm audit --prod --registry=https://registry.npmjs.org/` 返回 `No known vulnerabilities found`。 +- 取消请求、网络错误和 HTTP 错误脱敏由 `web/src/utils/request.test.ts` 覆盖；错误不保留原始 URL、请求头、响应正文或连接串。 +- 本功能不新增认证 Cookie、远程 HTML、动态 SQL、服务端 URL 抓取或生产数据库访问，因此 CSRF、XSS、SQL 注入和 SSRF 的运行攻击测试不适用；后续触及这些边界必须重新评估。 + +## 性能验证 + +- Web 构建基线（Axios 迁移前）：JS `163908` 字节，CSS `805` 字节。 +- 当前 Web 构建：`web/dist/assets/index-BjClxDN-.js` `163908` 字节，`web/dist/assets/index-13WJH6XV.css` `805` 字节；本次页面未接入健康 API，产物体积无增量。 +- `request.ts` 默认超时为 10 秒，不启用自动重试；测试覆盖超时配置和取消语义。 +- 治理与边界扫描只在开发/发布验证运行，不进入线上请求路径；当前仓库规模不需要负载测试。市场查询、MySQL 索引、Redis TTL、RocketMQ 吞吐、Worker 并发和图表渲染均未被本功能改变，后续业务功能需单独设定目标。 + +## 视觉与构建附加证据 + +- 桌面截图：`screenshots/iterations/app-shell-desktop-1440x900-61f85e5.png`，实际浏览器 DOM 视口 1440×900。 +- 移动截图：`screenshots/iterations/app-shell-mobile-61f85e5.png`，实际浏览器 DOM 视口 390×844。 +- 两个视口均有可见 `main` 和页面标题，无横向溢出；浏览器错误/警告日志为空。截图只证明本次请求基础设施迁移没有造成外壳回归，不代表市场概览 UI 已实现。 diff --git a/docs/features/GOV-010-development-quality-architecture/qa/visual-qa.md b/docs/features/GOV-010-development-quality-architecture/qa/visual-qa.md new file mode 100644 index 0000000..dcdfb92 --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/qa/visual-qa.md @@ -0,0 +1,19 @@ +# GOV-010 视觉回归记录 + +- 功能编号：GOV-010 +- 页面：应用基础外壳 +- 结论：无可观察回归 + +## 桌面 + +- E2E 与实际浏览器截图视口：Chromium 1440×900，`verify:e2e` 通过。 +- 截图：[app-shell-desktop-1440x900-61f85e5.png](/Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-desktop-1440x900-61f85e5.png) +- 检查：标题“ A 股市场分析工具 ”可见，`main` 可见，无横向溢出，无控制台 error/warning。 + +## 移动 + +- E2E 目标视口：Chromium 390×844，`verify:e2e` 通过。 +- 截图：[app-shell-mobile-61f85e5.png](/Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-mobile-61f85e5.png) +- 检查：标题和 `main` 可见，无横向溢出，无控制台 error/warning。 + +截图底部可能出现浏览器容器黑色区域，不属于页面 DOM；页面断言以实际 viewport、DOM 和 E2E 结果为准。本次没有修改页面布局或交互，因此结论是“无可观察回归”，不是新增市场概览设计验收。 diff --git a/docs/features/GOV-010-development-quality-architecture/review/code-review.md b/docs/features/GOV-010-development-quality-architecture/review/code-review.md new file mode 100644 index 0000000..f5fe29d --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/review/code-review.md @@ -0,0 +1,54 @@ +# GOV-010 代码 Review + +- 功能编号：GOV-010 +- reviewer_type：self +- reviewer：实现代理结构化自审 +- 基线提交：`1c1b15e` +- 审查提交：工作区当前变更，基于已推送 `61f85e5` 加上待提交的 Review 修复 +- 日期：2026-08-13 + +## 审查范围 + +审查 PRD、设计、实施计划、37 个代码/配置变更文件、开发总结、QA、GitNexus 报告及回退说明。重点覆盖 Axios 错误边界、AST HTTP 门禁、治理证据门禁、依赖安全、OpenAPI 契约和测试真实性。 + +## 发现 + +### 已关闭的重要问题 + +| 严重程度 | 位置 | 问题 | 影响 | 处理 | +|---|---|---|---|---| +| Important | `tools/governance/feature-record.mjs:getUnpassedReviewFiles` | 原实现只要文档任意位置出现 `最终结论：passed` 就会通过，后续追加 `changes_required` 可绕过完成门禁。 | 可能发布未通过 Review 的功能，属于治理安全缺口。 | 先新增失败测试复现，再改为只接受最后一个非空行精确等于 `最终结论：passed`；治理测试由 9 项增至 10 项并全部通过。 | + +### 当前未发现的问题 + +未发现 Critical、未关闭的 Important 或阻塞性 Minor。请求层没有把原始 Axios error、URL、请求头或响应正文放入错误对象；取消请求保留 Axios cancel 语义；业务 API 使用生成 DTO；页面和 Store 没有直接 HTTP 调用。 + +## 测试缺口 + +当前页面尚未消费健康 API，因此没有真实页面数据适配链路测试；这属于本次明确非目标。Axios 运行时响应 Schema 校验也未引入，后续高风险市场接口应按数据风险决定是否增加。治理扫描、构建和 E2E 已覆盖当前变更边界。 + +## 安全与残余风险 + +- 统一 request 将网络/HTTP 错误转换为固定中文消息，只保留分类和数字状态码；取消错误不被误报为服务故障。 +- 官方 audit 曾发现 `js-yaml 5.2.1` High 漏洞，已由 `e992edc` 精确覆盖到 `5.2.2`，修复后 audit 为 0 vulnerabilities。 +- AST 边界阻止运行时代码绕过 Axios/request 约定，但静态门禁不替代人工审查，也不做运行时响应校验；这些是已记录的残余风险。 + +## 性能与资源影响 + +- Web JS/CSS 产物与迁移前基线均为 163908/805 字节；默认超时 10 秒且无自动重试，避免行情刷新请求放大。 +- Axios 增加依赖维护成本，但统一拦截器、取消和错误边界；本次不改变数据库、缓存、消息或 Worker 吞吐。 +- 生产构建、全量测试和 E2E 均通过；当前治理扫描只在开发/发布命令执行。 + +## GitNexus 与同步修改 + +开发后重新索引为 1,827 nodes、2,502 edges、50 flows；相对 `1c1b15e` compare 为 35 文件、163 符号、1 条受影响执行流、MEDIUM。唯一运行流是 `CreateRequestClient → ApiRequestError`，与计划一致；边界校验 MEDIUM 变化只在开发门禁执行。逐项核对确认 HTTP/OpenAPI 字段、MySQL、Redis、RocketMQ、API/Scheduler/Worker、部署均无计划外变化。 + +## 修复与复审 + +- `e992edc`：修复 `js-yaml` 传递依赖漏洞，已推送 Gitea。 +- 待提交修复：Review 结论必须位于最后一个非空行，失败测试和通过测试均已执行。 +- 修复后未发现新的 Critical/Important；最终完整验证、E2E、audit、契约和格式证据仍有效，Review 报告创建后再运行完成门禁。 + +## 最终结论 + +最终结论：passed diff --git a/docs/features/GOV-010-development-quality-architecture/review/standards-review.md b/docs/features/GOV-010-development-quality-architecture/review/standards-review.md new file mode 100644 index 0000000..c7b52c2 --- /dev/null +++ b/docs/features/GOV-010-development-quality-architecture/review/standards-review.md @@ -0,0 +1,40 @@ +# GOV-010 开发规范符合性 Review + +- 功能编号：GOV-010 +- reviewer_type：self +- reviewer：实现代理结构化自审 +- 审查提交：工作区当前变更，基于已推送 `61f85e5` 加上待提交的 Review 修复 +- 日期：2026-08-13 + +## 检查结果 + +- [x] 必要中文注释准确且没有逐行废话注释。 +- [x] 文件按稳定职责拆分，适合连续阅读，没有过度碎片化。 +- [x] 命名、类型、单位和时间语义明确。 +- [x] 错误处理、日志、脱敏和降级符合规范。 +- [x] 安全策略、性能目标、验证证据和残余风险完整。 +- [x] 前端 Axios/API 分域与后端业务模块内按需分层符合规范。 +- [x] 复用抽取基于真实重复，新增依赖已完成用途、安全、许可证、成本和退出评估。 +- [x] 测试先行证据、构建和视觉验证齐全。 +- [x] GitNexus 开发前后报告和实际变更检测齐全。 +- [x] GitNexus 已评估其他功能、模块和所需同步修改，实际变化符合计划。 +- [x] 独立开发总结完整记录需求、范围变化、完成项、缺陷、延期项、提交和验证证据。 +- [x] PRD、设计、发布说明和回退说明一致。 +- [x] 提交使用中文 Conventional Commit 并关联功能编号。 +- [x] 未使用 GitHub，未擅自配置或推送远程仓库。 + +## 不符合项与处置 + +初审发现 Review 最终结论校验允许“passed”出现在正文中间，已按测试先行修复为最后非空行校验；没有遗留不符合项。历史已发布档案未改写；GOV-010 保持 `unreleased`。 + +## 安全、性能与架构检查 + +安全：Axios 错误脱敏、传递依赖 High 漏洞修复、构建产物敏感标记扫描和官方 audit 均有证据。性能：请求无自动重试、10 秒有限超时、包体已测量；不适用的行情/数据库/消息负载项均记录了边界。后端规范采用业务模块内按需分层，不创建空目录；前端 request 独占 Axios，业务 API 分域并使用 OpenAPI 生成类型。 + +## GitNexus 与开发总结检查 + +`gitnexus/before.md`、`impact-plan.md`、`detected-changes.md`、`after.md` 和 `comparison.md` 已互相对应；最新 compare 为 MEDIUM、163 变更符号、1 条预期请求执行流。`development-summary.md` 七个固定章节均有实际内容，并明确当前页面、AI Provider、市场业务和后端健康模块的未实施边界。治理测试 10/10 通过，完成门禁将在本报告最终结论落在末行后执行。 + +## 最终结论 + +最终结论：passed diff --git a/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-desktop-1440x900-61f85e5.png b/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-desktop-1440x900-61f85e5.png new file mode 100644 index 0000000000000000000000000000000000000000..36073581a53cc294b1311e2e8c1b43458b529c90 GIT binary patch literal 12308 zcmeH~c~n#Pw#QFQfl5V88AXO$d?1KGV+3gt()(msN+L#xaUhJ!paoWXMKPBw|>elL)g7fH$ekOFHZS{~Thl7iIXLMms(I(Q#L< z{*cqy{vQXA`Q7~Q$EpY>DiUB-g7?ASN6=LHEFmhN>H>WNe(wfBK3B#6vxX%!?hDjo zr5M-(2C0e#LjXAN3UKl_zjt@#$kWni5?ZXneTOar**sW`#*T6#)0Ds&B{026dPN4W z<#3h2UwzC|S6z^Z8o3)bHKnqdlxJ#2UWL3Oy|`GsWSi2R*Kj&9nAw^4djEN@5YeKK zrMaTv!aAY>**9Rd)V!av9Dmeo>!bIDeYCq)4(Nyab=l@GJE32?gOxxYyqDC0OV3ZE zP^6G$N<8VZ5*TS)w3s)SmyhmHPc88XC%3JI;uDAge-gF|f zE3+Nusn6vSlmIgvE?*;CzTxPsjcvWN;!bUe-@@Bh^?i7L=915n0LzFoILY$#L+Upf-m7aNQt3PU z2?!ry*U}faddIWSYM#A_WJ!DjA!AvcXp;+zXj&&gBP0 z=Up1*$cu;Ng7yGEh-9P%UcreqZ(cjoavL30qo6NY+hBV`XE5oh9x5 zrxvK;j1nJD&~SeB8R=L>)2ua;85LrUa@zNO((Y0y0ohGA;dOrMb^y%WU10 z*7?o3BQ62e7P2Sj=oB_mY?tM1Zd0~Q3%6sOW56rkj*zz5wcvBKrsaETs3JJ#77Aa= z3$xDjOR{4vcB1`yL}J(EV$yF{RzvW+?#^Ic$*oe{kvN%)-OEWVg&&o{#<;E!yelNj zXP4MJUexINrJ(9%Yg$lV;IDDepl|)f^p3Vhgyf#afvxl`S(79px|}Q_Cpz<;rcV{HxsvD9du&xe|7)z z8R$E~qb~l!Bqp8S+f#5G9~xeaxi|%{=-XPe>H}UQTvq}GzKR#WjY#LbBkWISvYO25 zM(@1%an0(A5^!rIwUn$)73^)Bt>b7U>!tBR6o%szDe^gmLAvk##y0EN0hHn=a!K6s zFd)T$^Pzt5U&ht723uYJM=vOJocMCGhR6H%X3+pH3_O> zImFEjqXtTCU84TympX?IHTo=6pKWzNa6L~N!!Jy^q<`_;;Un*7?cvktyXmvO+!N?oLy zq*{}IU#IGYqi#X}U-~2+efiqDJqV2c#~tZoKA%0YKAVm|0GbUi4wB(W+F5%BS-jX% zD%*?`G_rUJVR&Bjq;6<0f4uU0VFGxTjYeWv=r{Cp+5M7|U_!_%JdaVirR2eE3ZvBy ze7$6cG^utPGh@&WMdA=beSseohVXtJ?z)&S)y=V;D57!0zrvM!LScmM&anfeD}xVH z3a}I8pbj*KmP%6{0Oqw0nYNYV`L5%wjC-5$b@VSWkLLR-4cce~&(wP&CyZ}jkBl7A z)9!Yf%saE4Nhs>)k2hbal1R~M#b~I95;#GjhgFlf0>Oe7$Mk7&+KJ3N_E(xh#yFYJ zdU+v}{j95vO?-%vL;FM(GF1WdN5$JrN%|iY_sKgVC~W2rjiGU(kVo6|MD5p@3h-?G~dJRWkjd8L*cty;yjYmiv8Qh-Rl<*QqQsp+0Ss% z<+XbdLM%V9Y~O$*S}!J=$E3NzC5opY%Vv2vKd#O~H=`Tf z==5bneG%C7DLFz+g!_-2tUfAvUe@vmj?8Wvm^@WBjKZRjeg-1EowVOF!&P-`FTO-s zUBK0wUbQRP&xd_m=E}Ymv{Ihf*C@PE6+SEsFJ85$T2{o!{Pu}!;;otek|N=x5-`8Z zujJ>}vW!COX7f2n)#2);dDb2Ts^4B*QiaAci-d5#KDPz!J283pD^kOx`7Zm3Jx8=N zjVB#2v0y~c<0Po+fXAV@DfUU2Oks}_@QpaSULzma`X^oS184jf;X${9*L$2kE{H#p z|C43Ta@uiCQKbkf^)KMkH#PY-FPDCL5Ui8_Q%vt?CzQ T0%`(k0%`(k0{=$>%I?1bWH!z_ literal 0 HcmV?d00001 diff --git a/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-mobile-61f85e5.png b/docs/features/GOV-010-development-quality-architecture/screenshots/iterations/app-shell-mobile-61f85e5.png new file mode 100644 index 0000000000000000000000000000000000000000..b0fd5209d8b385c4c27ebba3ffd7fc2863a0b2ce GIT binary patch literal 5470 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 literal 0 HcmV?d00001 diff --git a/tools/governance/feature-record.mjs b/tools/governance/feature-record.mjs index b3ffb86..6e8c3a3 100644 --- a/tools/governance/feature-record.mjs +++ b/tools/governance/feature-record.mjs @@ -157,6 +157,7 @@ export function buildImpactPlanTemplate(featureId) { export function getUnpassedReviewFiles(reviewReports) { return REVIEW_FILES.filter((file) => { const content = reviewReports.get(file) ?? ''; - return !/^最终结论：passed$/m.test(content); + const lastNonEmptyLine = content.trim().split(/\r?\n/).at(-1); + return lastNonEmptyLine !== '最终结论：passed'; }); } diff --git a/tools/governance/feature-record.test.mjs b/tools/governance/feature-record.test.mjs index ebc40c0..b039b3a 100644 --- a/tools/governance/feature-record.test.mjs +++ b/tools/governance/feature-record.test.mjs @@ -177,6 +177,24 @@ test('只有两份 Review 都明确通过时才允许发布', () => { assert.deepEqual(getUnpassedReviewFiles(reports), []); }); +test('Review 只有在最后一个非空行明确 passed 时才通过', () => { + const reports = new Map([ + [ + 'review/code-review.md', + '# 代码 Review\n\n最终结论：passed\n\n最终结论：changes_required\n', + ], + [ + 'review/standards-review.md', + '# 规范 Review\n\n最终结论：passed\n\n补充说明不能放在最终结论之后。\n', + ], + ]); + + assert.deepEqual(getUnpassedReviewFiles(reports), [ + 'review/code-review.md', + 'review/standards-review.md', + ]); +}); + test('完整质量证据和带序号的二级标题可以通过门禁', () => { assert.deepEqual(getInvalidFeatureEvidence(VALID_FEATURE_REPORTS), []); });