# 前端全入口巡检报告

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

---

## 1. 巡检范围

| 维度 | 说明 |
|------|------|
| 角色 | 7 种：村合作社 / 镇经发 / 镇社区事务 / 分管领导 / 区农委 / 区人社局 / 系统管理员 |
| 页面 | 14 个业务路由（按 `menus.ts` + `rolePermissions`） |
| 接口 | 36 条只读 API（按页面分组） |
| UI | Playwright 自动访问 37 个「角色×页面」组合并截图 |

**脚本位置**：
- API：`sj_nmtybt_server/scripts/frontend-audit-apis.js`
- UI：`\_e2e_pw/frontend-ui-audit.js`
- 原始 JSON：`sj_nmtybt_server/scripts/audit-output/`

---

## 2. 总体结论

| 项 | 结论 |
|----|------|
| 页面渲染 | **37/37 页面可正常打开**，无持续 Loading 卡死、无全局报错弹窗 |
| 接口可用 | **30/36** 只读接口 < 3s 且 `code=200` |
| 数据计算 | 泖港镇已修复；**叶榭镇仍存在顶部指标与村图表不一致** |
| 性能 | 工作台/发放明细分页 **冷启动 10~11s**（DMS 翻页），命中缓存后 < 1s |
| 流程 BUG | 见第 5 节 |

```mermaid
pie title 接口响应分布（36条只读探针）
    "OK <3s" : 30
    "SLOW 3-15s" : 2
    "失败/404" : 4
```

---

## 3. 界面截图（代表性页面）

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

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

- 渲染正常：指标卡、告警条、待办、村图表均展示
- **问题**：顶部「本月发放金额」显示 **53 万**，下方村金额柱状图合计约 **1051 万**（见第 5.1 节）

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

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

- `lite` 批次列表 **< 2s** 加载，不再 15s 超时
- 叶榭镇当前无待办居保批次（`total=0`），属数据状态，非渲染异常

### 3.3 系统管理员 — 工作台

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

### 3.4 镇经发 — 审批管理

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

---

## 4. 接口响应时间

> 阈值：OK ≤ 3000ms · SLOW 3000–15000ms · FAIL 超时或 `code≠200`

### 4.1 按页面汇总

| 页面 | 接口数 | OK | SLOW | FAIL | 备注 |
|------|--------|----|------|------|------|
| 工作台 `/dashboard` | 5 | 4 | 1 | 0 | workbench 冷启动 11.4s |
| 人员录入 `/base` | 4 | 4 | 0 | 0 | |
| 居保 `/insurance` | 2 | 2 | 0 | 0 | lite 后 2~3ms |
| 审批 `/approvals` | 2 | 2 | 0 | 0 | |
| 补助标准 `/status` | 2 | 2 | 0 | 0 | |
| 特殊业务 `/special` | 3 | 2 | 0 | 1 | `bizType=ADJUST` 500 |
| 月补贴 `/monthly` | 2 | 1 | 1 | 0 | 发放明细分页冷启动 10.8s |
| 回盘 `/disk` | 2 | 2 | 0 | 0 | |
| 告警 `/alerts` | 2 | 2 | 0 | 0 | |
| 报表 `/reports` | 4 | 2 | 0 | 2 | 探针路径有误（见 5.3） |
| 区划 `/regions` | 1 | 1 | 0 | 0 | |
| 人员底数 `/personnel-admin` | 2 | 2 | 0 | 0 | |
| 批次 `/admin-batches` | 2 | 2 | 0 | 0 | |
| 系统 `/system` | 3 | 2 | 0 | 1 | validate-rules 路径 |

### 4.2 慢接口明细

| 接口 | 冷启动 | 热启动（缓存后） | 影响页面 |
|------|--------|------------------|----------|
| `GET /dashboard/workbench` | **11.4s** | ~50ms（90s 工作台缓存） | 所有角色首页 |
| `POST /payments/details/page`（镇级） | **10.8s** | ~200ms（scope 缓存） | 月补贴清单明细 |

### 4.3 UI 整页加载耗时（Playwright `networkidle`）

| 页面 | 管理员 | 镇社区事务 | 说明 |
|------|--------|------------|------|
| `/dashboard` | 1.7s | 1.6s | 正常 |
| `/approvals` | **11.8s** | — | 人员+批次聚合偏重 |
| `/special` | **16.9s** | 1.7s | 管理员全区视角慢 |
| `/reports` | **16.8s** | 1.8s | 管理员多专题并行 |
| `/admin-batches` | **16.6s** | — | 批次列表含回填逻辑 |
| 其余页面 | 1.5~2.2s | 1.5~1.8s | 正常 |

---

## 5. 业务与数据问题

### 5.1 【高】叶榭镇工作台金额不一致

| 字段 | API 值 | 村图表合计 | 是否一致 |
|------|--------|------------|----------|
| 本月发放金额 | **530,000** | **10,519,356** | ❌ |
| 本月发放人数 | 500 | 9,881（明细口径） | ❌ |
| 本月新增 | 9,879 | — | ⚠️ 接近总人数 9,886 |

**根因分析**：
- 顶部指标取自 `region.currentMonth`（批次/stat 口径，镇切片 `totalAmount=0` 时 stat 残留 53 万/500 人）
- 村图表取自发放明细汇总（正确）
- 昨日对「金额为 0」做了明细回退，但 **非零错误值未覆盖**

**泖港镇（已修复）**：`monthAmount=7,545,080` = 村图表合计 ✅

**建议**：当 `|明细合计 - region金额| > 阈值` 时，优先采用明细汇总（与村图表同源）。

### 5.2 【中】本月新增人数异常偏大

叶榭镇 `monthIncreaseCount=9879`，几乎等于在册 9886 人。

**原因**：`applyPayrollHeadcount` 对比上月发放名单，上月（202607）叶榭无明细 → 本月全员算「新增」。  
**建议**：无上月明细时回退到人员 `createTime` 口径，或展示「—」并附说明。

### 5.3 【低】探针/接口路径问题（非页面必现）

| 探针路径 | 实际 | 结果 |
|----------|------|------|
| `GET /api/validate-rules` | 应为 `/api/admin/validate-rules` | 404 |
| `GET /reports/topics/personnel` | 应为 `personnel-change` | 404 |
| `GET /special-biz/page?bizType=ADJUST` | 枚举无 `ADJUST` | 500 |

前端实际调用路径正确，**系统管理页、报表页在 UI 巡检中渲染正常**。

### 5.4 【中】居保匹配结果弹窗仍可能慢

打开「匹配结果」调用 `GET /insurance-match/batches/{id}/results`，后端 `loadBatchMemberPersonnel` 按批拉全镇明细（~7000 条），首开 **5~15s**。  
列表页已通过 `lite` 修复；弹窗建议后续做 **服务端分页 + DMS 条件查询**。

### 5.5 【低】叶榭镇社区事务居保待办为空

`T_YEXIE` 镇级居保批次 `total=0`（可能全区批在 `PENDING_STATUS_MAINTAIN` 但镇切片未生成/状态不匹配）。需业务确认数据，非纯前端问题。

---

## 6. 各角色可见入口巡检表

| 角色 | 可见菜单 | UI 结果 | 主要接口状态 |
|------|----------|---------|--------------|
| 村合作社 | 工作台、人员录入、告警 | ✅ 3/3 | 正常 |
| 镇经发 | 工作台、审批、报表 | ✅ 3/3 | 正常 |
| 镇社区事务 | 工作台、居保、标准、特殊、月补、回盘、告警、报表 | ✅ 8/8 | 工作台金额见 5.1 |
| 分管领导 | 工作台、审批、报表、告警 | ✅ 4/4 | 正常 |
| 区农委 | 工作台、报表 | ✅ 2/2 | 正常 |
| 区人社局 | 工作台、报表、告警 | ✅ 3/3 | 正常 |
| 系统管理员 | 全部 14 项 | ✅ 14/14 | 审批/特殊/报表/admin-batches 偏慢 |

---

## 7. 已修复项（本轮巡检前）

| 问题 | 状态 |
|------|------|
| 居保列表 15s 超时 | ✅ `lite` + 镇级查询 |
| 泖港工作台金额为 0 | ✅ 明细回退 + 工作台缓存 |
| 工作台首开 20s+ | ✅ 合并明细查询 + 90s 缓存（二次 < 100ms） |

---

## 8. 建议优先级

| 优先级 | 项 | 工作量 |
|--------|-----|--------|
| P0 | 叶榭等非零错误金额时仍用明细覆盖顶部指标 | 小 |
| P1 | 发放明细分页改 DMS 端分页，避免先拉全量再内存分页 | 中 |
| P1 | 居保匹配结果接口服务端分页 | 中 |
| P2 | 本月新增：无上月明细时的展示策略 | 小 |
| P2 | 管理员审批/特殊/报表页并行请求优化 | 中 |

---

## 9. 复现命令

```bash
# API 探针
cd sj_nmtybt_server && node scripts/frontend-audit-apis.js

# UI + 截图（需先启动前后端）
cd _e2e_pw && node frontend-ui-audit.js
```

---

**报告人**：自动化巡检（API 探针 + Playwright）  
**关联改造报告**：[payment-cache-refactor-report-20260824.md](./payment-cache-refactor-report-20260824.md)