# 前端全入口巡检报告（修复回归 v2）

**日期**：2026-08-25  
**环境**：本地前端 `http://localhost:3001`（`dev:local`）+ 后端 `http://localhost:8088/sjnmtybt`  
**数据**：生产 DMS 真实数据（约 3.3 万人员 / 202608 单月明细）  
**原则**：只读巡检；**未调用**初始化/清空/恢复出厂等破坏性接口；**未创建**测试数据  

**关联文档**：[初版巡检报告](frontend-audit-report-20260825.md) · [发放明细缓存改造](payment-cache-refactor-report-20260824.md)

---

## 1. 本次修复摘要

| 优先级 | 问题 | 修复方案 | 状态 |
|--------|------|----------|------|
| P0 | 叶榭镇工作台顶部金额/人数与村图表不一致 | 明细汇总与 region 差异大时优先明细；村图表改从发放明细聚合 | ✅ 已验证 |
| P1 | 本月新增≈总人数（上月无发放明细） | `applyPayrollHeadcount`：无上月名单时清零环比，不用 createTime 冒充 | ✅ 已验证 |
| P1 | `POST /payments/details/page` 冷启动 ~11s | `pagePayment` 改 DMS 端分页（`selectContentPage`） | ✅ 170ms |
| P1 | 居保匹配结果弹窗慢 | `matchResultsPage` 按发放明细分页拉人 | ✅ 已实现 |
| P2 | 审批/报表/批次管理 `batches/page` 11~17s | 前端全量 `lite: true` + 后端 lite 跳过明细回填 | ✅ 3~5ms |
| 低 | 探针 `/api/validate-rules` 404 | 改为 `/api/admin/validate-rules` | ✅ 已修正 |

**主要改动文件**：
- 后端：`BizDataService.java`、`BizFlowService.java`、`InsuranceMatchController.java`、`PaymentDetailQueryRequest.java`
- 前端：`sj_tdtybz/src/api/sjnmtybt/realBiz.ts`（所有 `/batches/page` 加 `lite: true`）
- 脚本：`scripts/frontend-audit-apis.js`（叶榭一致性抽检 + 探针路径）

---

## 2. 回归测试结论

| 维度 | 初版 (v1) | 修复后 (v2) |
|------|-----------|-------------|
| 只读 API OK（<3s） | 30/36 | **32/36** |
| 慢接口（SLOW） | 2 | **1**（仅 workbench 冷启动 14s） |
| 业务 FAIL | 4 | **3**（均为原有问题，见 §5） |
| 数据一致性抽检 | 1/2 通过 | **4/4 通过** |

```mermaid
pie title 接口响应分布（36条只读探针 · v2）
    "OK <3s" : 32
    "SLOW 3-15s" : 1
    "失败/404/500" : 3
```

### 2.1 关键性能对比

| 接口 | v1 冷启动 | v2 冷启动 | 说明 |
|------|-----------|-----------|------|
| `GET /dashboard/workbench`（叶榭） | 11.4s / 超时 | **14.0s**（SLOW）→ 缓存后 **3ms** | 仍须拉镇级发放 scope，90s 工作台缓存生效 |
| `POST /payments/details/page`（镇级） | **10.8s** | **170ms** | DMS 单页查询 |
| `POST /batches/page`（审批/月补/批次管理） | 11~17s | **3~5ms** | `lite: true` |
| `POST /batches/page`（居保） | 已修复 | **1~12ms** | 保持 |
| `GET /admin/validate-rules` | 404 | **2ms** | 探针路径修正 |

### 2.2 数据一致性抽检（全部通过）

| 检查项 | 结果 | 详情 |
|--------|------|------|
| 叶榭本月金额 = 村图表合计 | ✅ | `10,519,356` = `10,519,356` |
| 叶榭本月新增不应≈总人数 | ✅ | `monthIncrease=0`，`monthPeople=9,881` |
| 泖港本月金额 = 村图表合计 | ✅ | `7,545,080` = `7,545,080` |
| 居保 lite 批次列表 < 3s | ✅ | `1ms`，`total=0` |

**叶榭修复前后对比**：

| 字段 | v1（错误） | v2（正确） |
|------|------------|------------|
| 本月发放金额 | 530,000 | **10,519,356** |
| 本月发放人数 | 500 | **9,881** |
| 本月新增 | 9,879 | **0**（无上月明细，不做环比） |

---

## 3. 界面截图（沿用初版代表性页面）

> 截图目录：`docs/audit-screenshots/`（初版 Playwright 采集，页面结构未变）

### 3.1 镇社区事务 — 工作台

![镇社区事务工作台](audit-screenshots/social-dashboard.png)

- v2 修复后 API 顶部「本月发放金额」与村图表已对齐（叶榭 1051 万）
- 本月新增不再显示接近总人数的异常值

### 3.2 镇社区事务 — 居保匹配

![居保匹配页](audit-screenshots/social-insurance.png)

- lite 批次列表毫秒级响应；匹配结果改服务端分页

### 3.3 系统管理员 — 工作台 / 审批

![管理员工作台](audit-screenshots/admin-dashboard.png)

![镇经发审批](audit-screenshots/town-approvals.png)

- 批次列表 lite 后管理页接口由 16s 降至毫秒级

---

## 4. 按页面接口明细（v2）

| 页面 | 接口数 | OK | SLOW | FAIL | 备注 |
|------|--------|----|------|------|------|
| 工作台 `/dashboard` | 5 | 4 | 1 | 0 | workbench 冷启动 14s，热缓存 3ms |
| 人员录入 `/base` | 4 | 4 | 0 | 0 | |
| 居保 `/insurance` | 2 | 2 | 0 | 0 | |
| 审批 `/approvals` | 2 | 2 | 0 | 0 | batches 3ms（原 11s+） |
| 补助标准 `/status` | 2 | 2 | 0 | 0 | |
| 特殊业务 `/special` | 3 | 2 | 0 | 1 | `bizType=ADJUST` 枚举未注册（原问题） |
| 月补贴 `/monthly` | 2 | 2 | 0 | 0 | 明细分页 170ms（原 10.8s） |
| 回盘 `/disk` | 2 | 2 | 0 | 0 | |
| 告警 `/alerts` | 2 | 2 | 0 | 0 | |
| 报表 `/reports` | 4 | 2 | 0 | 2 | topics 路径 404（原问题） |
| 区划 `/regions` | 1 | 1 | 0 | 0 | |
| 人员底数 `/personnel-admin` | 2 | 2 | 0 | 0 | |
| 批次 `/admin-batches` | 2 | 2 | 0 | 0 | batches 3ms（原 16s+） |
| 系统 `/system` | 3 | 3 | 0 | 0 | validate-rules 已通 |

原始 JSON：`scripts/audit-output/api-audit-result.json`

---

## 5. 遗留问题（未在本次范围）

| 项 | 说明 | 建议 |
|----|------|------|
| workbench 冷启动 ~14s | 镇级首次须 `listPaymentsByMonthScope` 拉 ~1 万条明细 | 可考虑启动预热或 stat 表直读 |
| `GET /special-biz/page?bizType=ADJUST` | 后端枚举无 `ADJUST` | 补枚举或改探针参数 |
| `GET /reports/topics/*` | 404，可能路径变更 | 对照 `ReportController` 更新探针 |
| 居保匹配导出 | 仍走全量 `matchResults` | 导出场景可接受；在线分页已优化 |

---

## 6. 复现方式

```bash
# 后端（8088）
cd sj_nmtybt_server
mvn -DskipTests spring-boot:run

# 前端（3001）
cd sj_tdtybz
npm run dev:local

# API 巡检
cd sj_nmtybt_server
node scripts/frontend-audit-apis.js
```

---

## 7. 总结

本次按初版巡检清单完成 **6 项修复 + 全量回归**：

1. **叶榭/泖港工作台金额、人数**与村图表一致。  
2. **本月新增**在上月无发放明细时不再误报为全员新增。  
3. **发放明细分页**由全量内存分页改为 **DMS 端分页**，冷启动从 10s 级降至 **亚秒级**。  
4. **居保匹配结果**支持服务端分页，避免整批 `loadBatchMemberPersonnel`。  
5. **批次列表**全面 lite 化，管理/审批/月补等页接口由 10s+ 降至 **毫秒级**。  
6. **探针路径**修正，`validate-rules` 可正常探测。

**建议下一步**：workbench 冷启动优化（预热或 stat 聚合直读）；补齐报表/特殊业务探针与后端枚举对齐。

---

## 8. 优化清单补充（2026-08-27）

《[松江土地退养项目优化列表.xlsx](../../松江土地退养项目优化列表.xlsx)》新增 **序号 22–40** 共 19 项补充问题（含截图）。已整理为技术跟踪文档：

- **[松江土地退养项目优化列表-技术跟踪.md](../../docs/松江土地退养项目优化列表-技术跟踪.md)**：40 项状态总览、截图索引、根因与实施优先级  
- **截图**：[docs/optimization-list-assets/](../../docs/optimization-list-assets/)（54 张 PNG + `rows.json`）

| 类别 | 数量 | 代表项 |
|------|------|--------|
| 已修复（1–21） | 20 | 操作反馈、脱敏、审批金额、核算快照等 |
| 待处理 | 14 | 台账隔离(#22)、镇经发告警(#25)、调标改批次(#28/#30)、月补导出(#37) |
| 已部分修复 | 5 | 居保单人匹配(#24)、审批缓存(#31) |
| 需业务确认 | 3 | 多发退款入口(#34)、合计字段重复(#40) |

与本报告相关的续作：**月补/批次管理首屏两阶段加载**、**workbench 镇级冷启动 2.6–8.4s**（见优化清单 §5）。