sj_tdtybz/docs/api-integration.md

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 宜 <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	后端权威接口与状态机文档