# sj_tdtybz ↔ sjnmtybt-server 接口联调说明

> 修订：2026-08-07  
> 正式前端：`sj_tdtybz`（本仓库）  
> 联调后端：`sjnmtybt-server`（Base：`http://localhost:8088/sjnmtybt`）  
> 旧演示前端 `sjnmtybt-web` **不再作为业务页面入口**，仅可作接口对照参考。

## 1. 目标与约束

| 项 | 约定 |
|----|------|
| 页面流程 | 按 **sj_tdtybz 新版菜单/页面** 走（基础信息→审批→居保→月补贴→出盘/回盘→特殊业务→告警…） |
| UI | **不改页面布局、不新增页面、不新增表单字段** |
| 对接方式 | 仅在 API 层适配：`useMock=false` 时走真实接口，并把后端 VO **映射**为页面已有模型字段 |
| Mock | `public/config/config.js` 中 `useMock: true` 仍可纯前端演示 |

## 2. 如何切换联调

1. 启动后端：`sjnmtybt-server`（端口 **8088**，context-path **`/sjnmtybt`**）
2. 编辑 `public/config/config.js`：
   - `useMock: false`
   - `apiBase: '/api'`（默认）
   - `currentMonth` 与后端发放月一致，如 `2026-08`
3. 前端：`npm install && npm run dev`（默认 `http://localhost:3001`）
4. Vite 代理：`/api/*` → `http://localhost:8088/sjnmtybt/api/*`

本地鉴权默认关闭（`sjnmtybt.auth.enabled=false`）时可直接调业务接口。正式环境请求头带：

```
Token: <JWT>
```

（登录 OAuth 后把 JWT 写入 `localStorage.sjnmtybt_token` 或 `token`）

## 3. 代码结构（只动接口层）

```
src/api/biz.ts                 # 页面调用入口；mock / real 分流
src/api/sjnmtybt/realBiz.ts    # 真实接口编排（对齐页面函数签名）
src/api/sjnmtybt/mappers.ts    # VO → 页面模型（镇村中文名、状态中文等）
src/api/sjnmtybt/regionStore.ts# /api/regions 缓存与名↔ID
src/utils/request.ts           # code=200、Token 头、FormData
vite.config.ts                 # /api 代理到 8088/sjnmtybt
```

## 4. 页面流程 → 后端接口对照

### 4.1 村合作社 · 基础信息 `/base`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 村批列表 | `fetchVillageBatches` | 先 `POST /api/batches/ensure-current-month` 再建本月草稿，再 `POST /api/batches/page`（VILLAGE）；统一批次号展示发放年月（如 `202608`） |
| 人员列表 | `fetchPeople` | `POST /api/personnel/page` |
| 保存人员 | `savePerson` | `POST /api/personnel` + `ensure-current-month` |
| 选人保存 | `updateBatchMembers` | `PUT /api/batches/{id}/members`（草稿/退回；暂停/停止/死亡默认不纳入） |
| 本批次人员明细 | `fetchBatchMemberPeople` | `POST /api/payments/details/page`（**必须按 batchId**；勿用全村 `/personnel/page`，勿单靠 batchNo） |
| 镇审批名单 | 同上 | 审批详情与批次详情同源：发放明细，不是人员库 |
| 提交初审 | `submitVillageBatch` | `POST /api/batches/{id}/submit` |
| 批次详情/流程 | `fetchBatchDetail` / `fetchBatchOverview` / `fetchBatchTimeline` | `GET /api/batches/{id}`、`GET /api/workflow/batches/{id}/overview`、`GET /api/process-logs/batches/{id}/timeline`；备注 `POST /api/process-logs/note` |

### 4.2 镇经发 / 分管领导 · 审批中心 `/approvals`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 待办列表 | `fetchApprovals` | 批次 `PENDING_TOWN_APPROVE` / `PENDING_LEADER_APPROVE` + 特殊业务「待分管领导审批」拼成审批单 |
| 资格核验 | `reviewPersonQualify` | `POST /api/personnel`（备注写入资格结论，不新增字段） |
| 通过/驳回 | `decideApproval` | `POST /api/batches/town-approve` 或 `leader-approve`；特殊单 `POST /api/special-biz/leader-approve` |

审批单 `id` 合成：`B:{batchId}` / `S:{specialId}`（仅适配层使用，页面仍显示原字段）。

### 4.3 社区事务 · 居保匹配 `/insurance`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 待匹配村批 | `fetchInsuranceBatches` | 批次 status→阶段映射为「居保状态匹配/比对结果已生成」 |
| 触发匹配 | `triggerInsuranceMatch` | `POST /api/insurance-match/trigger`；无 FAIL 时再 `generate` |
| 比对结果 | `fetchInsuranceResults` | `GET /api/insurance-match/batches/{id}/results`（**必须传 batchId**；禁止回退全村人员库） |
| 人工确认 | `confirmInsuranceManual` | `POST /api/insurance-match/manual-confirm` |
| 提交领导 | `submitToLeader` | `POST /api/batches/{id}/submit-leader`（推进状态，非仅 generate） |

### 4.4 月补贴清单 `/monthly`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 村级清单 | `fetchVillageMonthlyBatches` | `POST /api/batches/page` → 映射待提交/待审核/已审核/已出盘/已回盘 |
| 出盘 | `issueVillageMonthlyDisk` | `POST /api/payments/export-disk`（`bypassDeadline` 便于联调） |
| 导出 | `exportMonthlyFile` | 同上 |

**状态映射（后端 `status` → 页面）**

| 后端 BatchStatus | 页面 stage（流程） | 月补贴 status |
|------------------|-------------------|---------------|
| DRAFT | 人员新增录入 | — |
| PENDING_TOWN_APPROVE | 镇经发中心初审 | — |
| PENDING_INSURANCE_MATCH | 居保状态匹配 | — |
| PENDING_STATUS_MAINTAIN | 比对结果已生成 | 待提交 |
| PENDING_LEADER_APPROVE | 分管领导审批 | 待审核 |
| READY_EXPORT | 待线下发放 | 已审核 |
| EXPORTED | 回盘信息确认 | 已出盘 |
| RETURNED / ARCHIVED | 已回盘确认 / 已归档 | 已回盘 |
| REJECTED | 退回修改 | — |

### 4.5 回盘 `/disk`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 回盘列表 | `fetchDisks` | 批次 EXPORTED/RETURNED/ARCHIVED |
| 上传回盘 | `uploadReturnDiskFile` | `POST /api/return-disk/upload` + `confirm` |
| 失败人员 | `fetchDiskFailPeople` | `POST /api/return-disk/details/page`（success=false） |
| 归档 | `archiveToNextMonth` | `POST /api/dashboard/archive/{batchId}`（回盘页「归档」按钮） |

### 4.6 特殊业务 `/special`

| 页面动作 | 前端函数 | 后端接口 |
|----------|----------|----------|
| 列表 | `fetchSpecials` | `GET /api/special-biz/page` |
| 发起 | `createSpecialBiz` | `POST /api/special-biz`（按姓名反查 personnelId） |
| 调标触发 | `triggerAdjustReissue` | `POST /api/special-biz`（`STANDARD_ADJUST` + townId） |
| 调标名单 | `fetchAdjustReissueRoster` | 调标村批 + 发放明细；原/新标准优先解析批次备注「旧月标/新月标」，否则查 `/api/amount-standards` |
| 死亡录入 | `createDeathRecord` | 人员 FUNERAL / 状态更新 |
| 状态动作 | `applyPersonStatusAction` | `POST /api/special-biz`（PAUSE/STOP/RESUME/FUNERAL/SUPPLEMENT） |

### 4.7 告警 / 标准 / 工作台 / 报表

| 页面 | 前端函数 | 后端接口 |
|------|----------|----------|
| 告警 | `fetchAlerts` / `handleAlert` | `POST /api/alerts/page`、`/handle`；人员信息回写 `POST /api/personnel` |
| 补助标准 | `fetchStandards` / `createStandard` | `GET/POST /api/amount-standards`、`yearly-adjust` |
| 工作台 | `fetchDashboard` | `GET /api/dashboard/summary` + `GET /api/dashboard/region-stats`（按镇/村填近半年图表与本月人数金额；镇级另查村批拼各村柱图） |
| 报表批次 | `fetchReportBatches` | 同村批分页 |
| 操作日志 | `fetchOpLogs` | `POST /api/process-logs/page` |
| 账号管理 | `fetchAccounts` | **后端暂无账号接口**，返回空列表（不新增页面字段） |

## 5. 字段映射（页面字段不增，仅转换）

| 页面 Person | 后端 PersonnelVO |
|-------------|------------------|
| id | id（字符串业务 ID） |
| idCard | idNumber |
| town / village | townId / villageId → 中文名 |
| bankCard | bankCardNumber |
| standard | monthlyStandard |
| startMonth | enjoyStartMonth（yyyyMM↔yyyy-MM） |
| status | bizStatus 中文 |
| insuranceStatus | insuranceMatchResult 中文 |
| remark | remarks |

镇村中文名与 ID 由 `regionStore` 维护（含叶榭镇等联调兜底名）。

## 6. 角色与数据范围

`config.js` 中角色用中文 `town` / `village`（如「叶榭镇」「叶榭村」），须与区划接口真实名称一致；适配层解析为 `T_YEXIE` / `V_*` 再请求后端。  
切换角色：改 `currentRole`（village / town / social / leader / agri / hr / admin）。

演示账号（121 环境）见后端文档 `sjnmtybt-server/docs/api-business-flow-guide.md` §0.0。

## 7. 联调检查清单（闭环）

1. **村合作社**：录入 → 选人（暂停/死亡默认不勾）→ 提交初审（提交时间有值）  
2. **镇经发**：审批详情人数=发放明细 → 资格核验 → 通过（人员状态应变「待居保匹配」，不得仍为草稿）  
3. **业务部门**：居保触发 → 成功落库「正常在库+匹配通过」；有 FAIL 须人工确认；**未匹配不可提交领导**  
4. **分管领导**：审批通过 → 月补贴「已审核」  
5. **业务部门**：出盘 → 回盘上传 → 失败人员处理 → **归档**  
6. **系统管理员**：行政区划 / 人员底数 / 批次管理 / 系统管理菜单  
7. **性能**：热路径 warm 宜 &lt;300ms（发放明细先分页再 enrichment；批次/人员/发放短缓存；看板 region-stats 45s；冷启动首次拉 DMS 可能略慢）

## 8. 已知差异

1. **审批中心**无独立审批表，由批次状态 + 特殊业务状态拼装。  
2. **资格核验**结论写入人员 `remarks`（无独立枚举字段）。  
3. **账号管理**无后端接口，系统管理页未挂菜单。  
4. **比对清单 Excel 下载**未对接，页面提示在线查看结果。  
5. **出盘**返回文件名/说明供线下签字，系统不托管资金支付文件流。

## 9. 与旧前端关系

| 项目 | 用途 |
|------|------|
| `sj_tdtybz` | **正式业务前端**（本联调对象） |
| `sjnmtybt-web` | 历史联调页，**停用**；接口路径仍可对照 |
| `sjnmtybt-server/docs/api-business-flow-guide.md` | 后端权威接口与状态机文档 |