lislgosms/docs/code-quality-reassessment-20260828-v3.md

# CMPP 平台代码质量复评报告 V3

- 报告日期：2026-08-28
- 复评时间：2026-08-28 15:36～16:08（Asia/Shanghai）
- 复评基线：`3834d67a308acf89d0e6cb2e6009c89c93b2c139`
- 主要业务整改提交：`ad27acad7e02b787185c972c710c73c867429c36`
- 锁文件修正提交：`226527f1cef122e4dbd163da782485e8c0254dc5`
- 对比基线：V2 基线 `3af145abe5eb8cae567bb18e29116b4940889258`
- Git 状态：本地 `main` 比 `origin/main` 超前 3 个提交；当前提交尚未推送
- 工作区保护：保留既有 `docs/code-quality-reassessment-20260828-v2.md` 修改、未跟踪 `=` 和 `pnpm-lock.yaml`
- 明确未执行：提交、推送、部署、服务重启、数据库业务写入、短信发送、压力测试、预生产或生产操作

## 1. 执行摘要

本轮综合判定为：**代码质量有条件通过，持续治理尚未闭环；不建议仅凭本报告进入预生产发布。**

与 V2 相比，本轮取得了明确进步：

- 客户端凭据、Webhook、日志导出、文件上传、用户维护等写接口补充 class DTO、严格运行时校验和负向测试。
- 浏览器客户端请求不再发送或回退租户 ID，服务端可信租户边界进一步收紧。
- 登录保护从账号维度扩展为账号、来源 IP、账号+IP 和验证码请求频率，并使用 Redis 原子计数和摘要键。
- 建立 Vitest/Testing Library/jsdom/MSW 前端测试基座，4 个测试文件、34 项测试通过。
- API 增至 51 个测试套件、563 项测试并全部通过。
- 根依赖审计保持 0；API 审计从 V2 的 7 项降至 5 项，剩余项均位于 Prisma CLI 开发/迁移链。
- npm 10.9.4、两份正式 `package-lock.json`、ESLint flat config 和 Prettier 配置已建立。
- 测试环境已部署 `226527f...`；本次独立读取到的远端前端资源与本地构建资源一致，外部 API health 最终连续 5 次返回 200。

但本次独立复测发现两项不能忽略的问题：

1. **增量 lint/format 门禁存在假绿。** 默认比较 `HEAD` 时，提交后的整改文件不会进入检查；显式设置基线后，Windows 包装器又无错误信息地退出 1。绕过包装器直接检查 37 个整改代码文件，发现 6 个 ESLint error、2 个 warning，以及 2 个文件未通过 Prettier。
2. **客户端删除接口仍缺严格 DTO。** `ClientDeletionGovernanceController` 使用 TypeScript type `DeleteTargetDto`，没有 `strictValidationPipe`，额外字段、格式和长度仍不会按本轮统一规则拒绝。

综合参考分：**86/100**，较 V2 的 82/100 提升 4 分。P0 为 0，但仍有 2 项 P1 和若干 P2/验收边界。

## 2. 质量评级

| 维度 | V2 | V3 | 结论 |
|---|---:|---:|---|
| 业务正确性与并发设计 | B+ | B+ | API/Gateway 全量回归通过；未重跑真实 CMPP 全链。 |
| 安全性 | B+ | A- | 客户端租户边界、DTO 和登录保护明显增强；删除接口仍有校验缺口。 |
| 自动化测试 | B- | B+ | 前端 34 项、API 563 项通过；API “全源”指标仍未成为标准脚本默认口径。 |
| 前端性能 | B+ | B+ | 路由分包保持，入口 107.28 KiB gzip，图表异步包 181.65 KiB gzip。 |
| 可维护性 | C+ | C+ | 引入 ESLint/Prettier，但门禁未真实通过；两个 SendChain Service 未拆分。 |
| 数据库工程 | B+ | B+ | Prisma schema 和 95 项迁移发布记录正常；本轮未独立执行真实数据查询计划。 |
| 依赖与仓库卫生 | B- | B | 根审计 0，API 风险降至 Prisma CLI 5 项；正式包管理器已固定，旧未跟踪 pnpm 锁仍在。 |
| 运行与发布就绪 | B- | B | 测试环境公开入口及资源匹配；内部服务/队列状态仅有发布记录，本次 SSH 未独立复核。 |

## 3. V2 遗留项复核

| V2 项目 | V3 状态 | 复评结论 |
|---|---|---|
| 客户端写接口严格校验不完整 | **大部分关闭，仍有缺口** | 凭据、Webhook、导出、文件、用户等已补齐；客户端删除接口遗漏。 |
| 前端自动化测试为 0 | **已关闭** | 4 个文件、34 项通过；覆盖登录、请求错误、租户头、路由异常和用户列表关键状态。 |
| API 依赖公告 2 moderate/5 high | **部分关闭** | 当前为 2 moderate/3 high，共 5 项；均聚合在 Prisma CLI 链并有风险矩阵。 |
| 无真实 ESLint/Prettier | **实现未验收通过** | 配置与脚本已增加，但增量包装器有缺陷，整改代码本身仍有 lint/format 失败。 |
| SendChain 超大服务 | **未处理，按方案延期** | 文件仍约 86,253 和 53,421 字节；需要独立行为锁定与重构任务。 |
| 双锁文件口径 | **部分关闭** | `packageManager` 固定 npm 10.9.4，正式仅跟踪两份 npm lock；旧未跟踪 pnpm lock 仍受保护保留。 |
| 测试环境与登录后验收 | **部分关闭** | 测试环境已部署并健康；登录后深层页面和真实 CMPP 全链仍未复验。 |

## 4. 本轮独立验证结果

### 4.1 构建与自动化测试

| 检查项 | 结果 |
|---|---|
| 前端 TypeScript | 通过 |
| Vite production build | 通过 |
| Bundle budget | 通过；入口 107.28 KiB gzip，Chart 181.65 KiB gzip |
| 前端 Vitest | 4/4 文件、34/34 项通过 |
| 前端纳入覆盖范围的核心模块 | statements 88.34%、branches 84.71%、functions 84.00%、lines 88.02% |
| API TypeScript build | 通过 |
| Prisma validate | 通过；仓库 95 项 migration |
| API Jest | 51/51 套、563/563 项通过 |
| API 默认 coverage 脚本口径 | 70.44% / 53.77% / 71.76% / 73.61% |
| API 显式全源口径 | 60.46% / 51.54% / 60.75% / 63.04% |
| API 增量覆盖配置 | 86.92% / 77.03% / 95.91% / 90.07% |
| Gateway `go test ./... -count=1` | 通过 |
| Gateway `go vet ./...` | 通过 |
| Gateway 队列契约 | 5/5 通过 |
| 结构质量/依赖缓解/安全部署门禁 | 通过 |
| `npm ci --dry-run --include=dev` | 根项目与 API 均通过 |

覆盖率顺序均为 statements / branches / functions / lines。

首次并发执行前端测试时，4 个 Vitest worker 因本机同时运行多个高负载任务而启动超时，未执行测试；资源释放后以单 worker 串行重跑全部通过。首次从仓库根目录直接启动 API Jest 时误扫描受保护的 `outputs/` 历史快照；改为在 `api/` 目录按项目配置运行后全部通过。两次错误执行均未计为产品失败。

### 4.2 覆盖率口径校正

`api/jest.config.cjs` 仍未配置 `collectCoverageFrom`，因此标准 `test:coverage` 的 70.44% 只统计测试实际加载的源码，不能称为严格“全源覆盖率”。本报告显式加入 `src/**/*.ts` 后的全源结果为 60.46% / 51.54% / 60.75% / 63.04%，较 V2 的 59.84% / 51.29% / 60.15% / 62.60% 小幅提升，并继续满足 59% / 50% / 60% / 62% 门槛。

增量配置确实对指定新增模块建立了 80% / 70% / 80% / 80% 门槛，但运行时仍执行全部 51 套测试；覆盖率只收集列出的 7 个文件。该机制有效，但文档应准确称为“指定整改模块覆盖率”，不应与全源口径混用。

### 4.3 依赖审计

使用项目固定的 npm 10.9.4 直接审计正式锁文件：

- 根项目：0 项公告。
- API：5 项公告，2 moderate、3 high。
- 5 项均为 `prisma -> @prisma/config/@prisma/dev -> deepmerge-ts/valibot` 聚合路径，不进入 NestJS HTTP 请求运行时。
- 自动修复建议是 Prisma 7.9.0 降级到 6.12.0，属于破坏性主版本变更，本轮不执行 `audit fix --force` 的决定合理。
- `api/package-lock.json` 已实际解析 UUID 11.1.1、find-my-way 9.7.0；Swagger、js-yaml、fast-uri、brace-expansion 的既有公告已关闭。

判定：供应链风险已从“未治理”转为“有记录的开发工具链风险接受”，但仍需监控 Prisma 上游修复。

### 4.4 测试环境只读探测

- `curl --noproxy '*'` 绕过系统代理后，第一组 `/api/health` 3 次均为 HTTP 200。
- 同组客户端登录页、运营登录页和验证码接口均返回 200；运营登录页有一次总耗时约 9 秒。
- 随后一次 health 请求发生 10 秒连接超时；立即复测 5 次均返回 200，总耗时约 17～19 ms。
- 远端登录 HTML 引用 `index-BvZGIM6l.js` 和 `index-DyAqoJbu.css`，与本地 V3 构建产物一致。
- SSH 当前仍认证失败，无法独立读取 `.deployed-commit`、systemd、Redis Stream、migration 和服务器日志。
- 发布记录显示测试环境部署标记为 `226527f...`，95 项迁移一致、11 项服务 active、三条 Stream `pending=0/lag=0`、发布窗口 error 日志为 0；这些内部状态本次未独立复核。

判定：外部入口总体健康，单次超时暂记为网络瞬态，不设 P0；预生产前仍需用可用只读凭据复核内部状态。

边界说明：外部 smoke 曾请求一次验证码 GET 接口，该接口会在 Redis 写入一个 5 分钟 TTL 的一次性验证码记录；未提交登录、未创建用户或业务数据，未触发短信、余额、应用、通道或 MinIO 业务写入。

## 5. 当前问题清单

### CQ-QG-001 / P1：增量 lint/format 门禁假绿且整改代码未通过

**证据**

- `tools/quality/run-changed-code-quality.mjs:7-14` 默认基线为 `HEAD`，正常提交后执行 `npm run lint` 时不会检查已提交整改代码。
- 本次默认运行输出 `No changed code files require lint/format`，不能证明 `ad27aca` 中的代码通过。
- 设置 `QUALITY_BASE_REF=3af145a...` 后，Windows 包装器无错误信息退出 1；脚本没有输出 `spawnSync` 的 error。
- 绕过包装器直接对 37 个整改文件执行 ESLint，发现 6 个 error、2 个 warning：
  - `api/src/auth/auth.controller.ts`：2 个未使用变量。
  - `api/src/open-api/open-api.service.ts`：1 个未使用 import。
  - `src/api/client/client.api.ts`：2 个未使用 import。
  - `src/apps/client/ClientUsersPage.test.tsx`：1 个未使用变量。
  - `src/apps/LoginPage.tsx`：Fast Refresh 导出警告、`useEffect` 缺少 `refreshCaptcha` 依赖警告。
- Prettier 检查发现 `api/src/auth/auth.service.spec.ts`、`api/src/open-api/open-api.service.spec.ts` 未格式化。

**影响**

整改记录中的“ESLint/Prettier 门禁通过”不是当前可重复证据。CI 如果没有显式传入基线会漏检提交；Windows 本地即使传入基线也会无诊断失败。

**关闭要求**

1. 门禁显式接收并验证 base/head，CI 使用 merge-base；本地提供全量或最近提交模式。
2. Windows 调用方式可执行，并在 spawn 失败时输出 `result.error`。
3. 修复 6 个 error、2 个 warning 和 2 个格式文件后，直接 ESLint/Prettier 与包装脚本均通过。
4. 为“无变更”“有错误”“Windows 启动失败”和“CI 基线”增加脚本测试。

### CQ-API-001 / P1：客户端删除接口仍未纳入严格运行时校验

`api/src/deletion-governance/deletion-governance.controller.ts:34-38` 的客户端删除接口使用 `DeleteTargetDto`，但没有 `@UsePipes(strictValidationPipe)`；`api/src/deletion-governance/deletion-governance.service.ts:10-18` 的 DTO 仍为 TypeScript type，没有 class-validator 规则。请求中的额外字段、超长 reason、错误布尔类型、非法时间和幂等键格式不会按统一客户端策略拒绝。

关闭要求：建立 client deletion class DTO、严格管道和负向测试，并把结构门禁扩展为检查所有 `@Controller('client...')` 的 body 写接口，而不是仅靠人工清单。

### CQ-COV-001 / P2：API 标准覆盖率脚本仍不是全源口径

标准 `test:coverage` 未配置 `collectCoverageFrom`，容易把 70.44% 误写为全源覆盖率；严格全源只有 60.46%。应在正式配置中固化全源 include/exclude，并保留增量覆盖作为第二道门禁。

### CQ-MAINT-001 / P2：SendChain 超大服务仍未拆分

`send-inbound-entry.service.ts` 约 84.2 KiB，`send-gateway-submit.service.ts` 约 52.2 KiB。本轮明确延期是合理的风险控制，但不能记为质量治理完成。后续需先补行为锁定和性能基线，再分职责重构。

### CQ-REPO-001 / P2：本地提交尚未推送且旧 pnpm 锁仍存在

本地比 `origin/main` 超前 3 个提交，远端凭据拒绝已在进度文档记录；测试环境部署了代码提交 `226527f...`，但远端 Git 仍停留在 V2 基线。灾备、协作和可追溯性因此不完整。另有未跟踪旧 `pnpm-lock.yaml`，虽未纳入正式流程，仍可能误导人工命令。

### CQ-ACC-001 / P2：登录后浏览器和真实全链仍未复验

测试环境只验证了公开页面、验证码和 health；没有输入密码或代解验证码，没有验证登录后 loading/empty/error/refresh、权限和关键写操作，也没有重跑 PostgreSQL/Redis/MinIO/Gateway/CMPP 模拟器全链。自动化测试不能替代这些最终验收证据。

## 6. 发布建议

当前建议：**允许继续整改和测试环境验证，暂停预生产发布。**

最小充分关闭顺序：

1. 修复增量 lint/format 包装器并清零当前 lint/format 失败。
2. 补齐客户端删除 DTO、严格校验和负向测试。
3. 把 API 严格全源覆盖率固化为标准门禁，修正文档口径。
4. 使用可用只读凭据复核测试环境部署标记、11 项服务、95 项迁移、Redis Stream 和 error 日志。
5. 在真实登录态下完成客户端/运营端关键页面和请求状态验收。
6. 取得授权后解决远端 Git 凭据并推送；推送不是本次复评授权范围。
7. SendChain 拆分继续作为独立高风险任务，不与上述门禁修复混合。

## 7. 最终判定

- 原始安全 P0：**0 项未关闭**。
- 当前 P0：**0 项**。
- 当前 P1：**2 项**——质量门禁假绿、客户端删除校验遗漏。
- 当前 P2/验收边界：API 覆盖率口径、SendChain 重构、Git/锁文件治理、登录后与真实全链验收。
- 自动化：前端 34 项、API 563 项、Gateway 全包测试均通过。
- 构建与包体：通过。
- 依赖：根项目 0；API 5 项 Prisma CLI 风险已记录接受。
- 测试环境公开入口：通过，存在一次短暂超时后连续 5 次快速恢复。
- 代码质量：**86/100，有条件通过**。
- 持续治理闭环：**未通过**。
- 预生产发布建议：**暂停**。

本报告只对应固定提交和本次可重复证据，不把整改记录、单元测试或公开 health 冒充真实后端全链与登录后功能验收。