业务流程接口调用指南

对齐《流程图260804》
Base URL：http://localhost:8088/sjnmtybt
Swagger：http://localhost:8088/sjnmtybt/swagger-ui.html
统一响应：{ "code": 200, "message": "...", "data": ... }（code≠200 为失败）
正式前端：sj_tdtybz（页面流程以新前端为准；联调映射见 sj_tdtybz/docs/api-integration.md）。旧 sjnmtybt-web 停用作业务入口。
现行主线（2026-08-13）：村/镇经发不再提交村批，改为资格审批 + 每月 1 号全区一批次。详见 district-month-batch.md。下文 §0.5 / 泳道一已按此修订；历史 VILLAGE 批只读。

文档结构速览

§0 公共约定（鉴权、分页、业务 ID）
§0.5 状态字典与变更流程 ← 各状态含义 + 怎么变
§1 前置主数据
§2～§4 三条泳道接口
§6 调用顺序速查
§9 修订记录

0. 公共约定

0.0 鉴权（Token）

环境	配置	行为
本地/联调（默认）	`sjnmtybt.auth.enabled=false`	`/api/**` 可不带 Token；Swagger 直接试接口
正式环境	`spring.profiles.active=prod`（或显式 `auth.enabled=true`）	必须请求头 `Token: <JWT>`，否则 `code=401`

前端正式调用：

POST {oauth}/user/login（userName / password / clientId）
取响应 message 中的 JWT
业务请求头带：Token: <JWT>（也兼容 token、Authorization: Bearer <JWT>）

Swagger： 右上角 Authorize → 填入 JWT → 再试业务接口。

说明：后端访问 DMS 使用配置里的服务账号（sjnmtybt.oauth.*），与前端用户 Token 分离。

121环境《松江农民土地退养补助》演示用户：角色（说明）-roleId 用户名

密码

村合作社(人员新增录入；死亡信息录入)-roleId：66 VILLAGE_COOP01

p_VILLAGE_COOP01

镇经发中心(材料完整性与资格初审（可驳回）)-roleId：67 TOWN_ECONOMIC_CENTER01

p_TOWN_ECONOMIC_CENTER01

社区事务中心-业务部门(居保匹配、月补贴清单/对照文件、特殊业务申请与出盘、回盘确认)-roleId：68 TOWN_COMMUNITY_BIZ01

p_TOWN_COMMUNITY_BIZ01

社区事务中心-分管领导(月度清单与特殊业务线上审批（可驳回）)-roleId：69 TOWN_COMMUNITY_LEADER01

p_TOWN_COMMUNITY_LEADER01

镇领导(线下签字（对照文件/特殊业务出盘文件）)-roleId：70 TOWN_LEADER01

p_TOWN_LEADER01

社区事务中心-财务(财政发放（线下）)-roleId：71 TOWN_COMMUNITY_FINANCE01

p_TOWN_COMMUNITY_FINANCE01

区农业农村委/区人社(全区数据查询与监管（不参与操作）)-roleId：72 DISTRICT_SUPERVISOR01 p_DISTRICT_SUPERVISOR01

0.1 分页请求（多数 POST 列表接口）

字段	类型	含义
pageNum	int	页码，从 1 开始，默认 1
pageSize	int	每页条数，默认 20

0.2 分页响应 `PageResult`

字段	含义
pageNum	当前页
pageSize	每页条数
total	总条数
list	当前页数据数组

0.3 常用业务 ID

ID	示例	含义
街镇 ID	`T_YEXIE`	叶榭镇等 7 镇
村居 ID	`V_YX_001`	叶榭村
人员业务 ID	`P001`	人员底数编号
批次业务 ID	`VB202604001` / `MB202603001`	村级 VB / 镇级 MB
发放年月	`202604`	yyyyMM

0.4 状态总览（详见下一节）

前端字典接口（推荐）：

方法	路径	说明
GET	`/api/dicts/statuses`	全部状态字典（含 code / label / description）
GET	`/api/dicts/statuses/{type}`	按类型取一类，如 `batchStatus`、`personnelStatus`
GET	`/api/dicts/types`	类型清单（type → 中文名）

响应项字段：code（状态码）、label（中文名）、description（含义）；分组另有 field（对应业务字段名）。

系统里同一批次有两套并行字段，不要混用：

字段	类型	回答什么问题
`currentStage`	流程阶段	做到流程图哪一步了？（录入/初审/居保/清单…）
`status`	业务状态	当前业务卡在哪、能不能往下走？（待审/可出盘/已回盘…）

人员另有 bizStatus（能不能发）、insuranceMatchResult（居保是否过）。
详细含义与变更见 §0.5 状态字典与变更流程。

0.5 状态字典与变更流程

0.5.1 流程阶段 `FlowStageEnum`（`currentStage`）

对应流程图 260804 月度主线 8 个节点。

值	中文	含义	责任角色	线上/线下
STAGE1_PERSONNEL_INPUT	人员新增录入	村合作社维护本村人员底数；驳回后也回到这里改材料	村合作社	线上
STAGE2_TOWN_PRECHECK	材料完整性与资格初审	镇经发中心审材料与资格，可驳回	镇经发中心	线上
STAGE3_INSURANCE_MATCH	居保状态匹配	业务部门触发居保比对；失败可人工确认	社区事务中心-业务	线上
STAGE4_MONTHLY_LIST	生成月补贴清单	生成当月发放清单（批次头+发放明细）	社区事务中心-业务	线上
STAGE5_LEADER_ONLINE_APPROVE	分管领导线上审批	审合规性与金额，可驳回调清单	分管领导	线上
STAGE6_COMPARE_FILE	生成月补贴对照文件	导出对照/出盘文件，进入线下签批	社区事务中心-业务	线上
STAGE7_OFFLINE_SIGN_PAY	线下签字与财政发放	镇领导签字 → 财务财政发放（系统不走资金支付）	镇领导/财务	线下
STAGE8_RETURN_CONFIRM	回盘信息确认	确认回盘结果，异常反馈下月清单	社区事务中心-业务	线上

0.5.2 批次业务状态 `BatchStatusEnum`（`status`）

值	中文	含义	典型所处阶段
DRAFT	草稿	已停用新建。历史村批只读	STAGE1（历史）
PENDING_TOWN_APPROVE	待镇经发初审	已停用。人员资格审批不再走村批此状态	STAGE2（历史）
PENDING_INSURANCE_MATCH	待居保匹配	全区月批刚生成，等自动/手动居保	STAGE3
PENDING_STATUS_MAINTAIN	待状态维护	全区主批匹配后停在此状态，不因一镇提交领导而改全区状态	STAGE3～4
PENDING_LEADER_APPROVE	待分管领导审批	镇统计记录提交领导后的状态	STAGE4～5
READY_EXPORT	可出盘	镇统计记录领导已通过	STAGE5～6
EXPORTED	已出盘	对照/出盘文件已生成，进入线下签字发放	STAGE6～7
RETURNED	已回盘	回盘已确认（可含部分失败）	STAGE8
ARCHIVED	已归档	本月闭环结束，供区级台账查询	STAGE8
REJECTED	已驳回	初审或领导审批驳回，需回退修改后再提交	STAGE1 或 STAGE4

0.5.3 批次：阶段 + 状态如何一起变（主线）

flowchart TD
  A0[每月1号或管理员手动<br/>生成全区 DISTRICT 批] --> C[STAGE3<br/>PENDING_INSURANCE_MATCH]
  C --> M[自动居保]
  M --> D[全区主批 STAGE4 / PENDING_STATUS_MAINTAIN]
  D --> T[各镇 TOWN 统计记录]
  T --> L{本镇特殊业务是否全部通过}
  L -->|否| BLOCK[禁止提交领导]
  L -->|是| SUB[镇统计 PENDING_LEADER_APPROVE]
  SUB --> LDR{分管领导}
  LDR -->|PASS| E[镇统计 READY_EXPORT]
  LDR -->|REJECT| T

主线接口（现行）

接口	结果
`POST /api/personnel/{id}/qualify/submit`	人员 `PENDING_TOWN_APPROVE`（待资格审批）
`POST /api/personnel/{id}/qualify/review` PASS	人员 `NEW`（新增）
`POST /api/batches/generate-district-month`	全区批 `PENDING_INSURANCE_MATCH` → 匹配完 `PENDING_STATUS_MAINTAIN`；各镇 upsert TOWN 统计
`POST /api/batches/{id}/submit-leader`	镇统计 → `PENDING_LEADER_APPROVE`（不改全区主批）
`POST /api/batches/leader-approve`	镇统计 `READY_EXPORT` / `REJECTED`

已停用：POST /api/batches/ensure-current-month、POST /api/batches/{id}/submit、POST /api/batches/town-approve。

出盘/回盘仍按镇统计记录操作（明细挂全区父批）。

历史村批接口（已停用，勿再作为主线）：ensure-current-month / submit / town-approve。出盘、回盘、归档接口仍有效，对象改为镇统计记录。

说明：exportStatus（未出盘/已导出…）、returnStatus（未回盘/全部成功/部分异常）是批次上的辅助文案字段，与 status 枚举配合使用，用于列表展示。

0.5.4 人员业务状态 `PersonnelStatusEnum`（`bizStatus`）

值	中文	含义	是否本月可发（常规）
DRAFT	待提交资格	村已录入，尚未提交资格审批	否
PENDING_TOWN_APPROVE	待资格审批	已提交，等镇经发按人审资格	否
NEW	新增	资格已通过，等待下个 1 号纳入全区月发	否（1 号自动纳入）
PENDING_INSURANCE_MATCH	待居保匹配	等居保结果	否
NORMAL	正常发放	资格正常，可纳入月补贴清单	是（`payThisMonth=true`）
PAUSED	暂停发放	临时停发，可经特殊业务恢复	否
STOPPED	停止发放	长期/资格终止停发	否
FUNERAL	死亡丧葬处理中	已死亡，走丧葬补贴，不再按月续发	否（可发丧葬一次性）
ABNORMAL	异常待处理	居保失败、无资格等，需人工处理	否
ARCHIVED	已归档	历史人员归档，不再参与当月业务	否

人员状态常见变更

场景	接口	状态变化
村合作社新建人员	`POST /api/personnel`	→ `DRAFT`
提交退养资格	`POST /api/personnel/{id}/qualify/submit`	→ `PENDING_TOWN_APPROVE`，写资格日志
镇经发资格通过	`POST /api/personnel/{id}/qualify/review` pass=true	→ `NEW`，资格 `WITH_LAND`/`WITHOUT_LAND`
镇经发认定无资格	同上 pass=false + INELIGIBLE	→ `ABNORMAL`
每月 1 号纳入	`generate-district-month`	`NEW`/`NORMAL` 写入全区发放明细
居保失败	`trigger`	→ `ABNORMAL` + 告警
居保死亡	`trigger`	→ `FUNERAL`，土地月补清零或按规则保留，写入丧葬金额
居保人工确认通过	`POST /api/insurance-match/manual-confirm`（pass=true）	`insuranceMatchResult→MANUAL_PASS`，`bizStatus→NORMAL`

flowchart LR
  DRAFT --> PENDING_TOWN_APPROVE
  PENDING_TOWN_APPROVE --> NEW
  PENDING_TOWN_APPROVE --> ABNORMAL
  PENDING_TOWN_APPROVE --> DRAFT
  NEW --> NORMAL
  PENDING_INSURANCE_MATCH --> NORMAL
  PENDING_INSURANCE_MATCH --> ABNORMAL
  PENDING_INSURANCE_MATCH --> FUNERAL
  NORMAL --> PAUSED
  NORMAL --> STOPPED
  NORMAL --> FUNERAL
  PAUSED --> NORMAL
  ABNORMAL --> NORMAL
  FUNERAL --> ARCHIVED
  STOPPED --> ARCHIVED

0.5.5 居保匹配结果 `InsuranceMatchResultEnum`

挂在人员上的 insuranceMatchResult，决定能否进入月补贴清单。

值	中文	含义	后续动作
PENDING	未匹配	尚未比对	等触发匹配
SUCCESS	匹配成功	居保侧正常，可进清单	继续生成月补贴清单
LOSE_ELIGIBILITY	丧失资格	不符合继续享受条件	终止发放（人员宜改 STOPPED 等）
FAIL	匹配失败/无法判定	未命中或数据矛盾	人工确认；可出告警
MANUAL_PASS	人工确认通过	工作人员核实后放行	等同成功，可进清单

变更

接口	结果
新建人员	默认 `PENDING`
`POST /api/insurance-match/trigger`	按人员已有/比对结果汇总 SUCCESS/FAIL/待人工
`POST /api/insurance-match/manual-confirm` pass=true	→ `MANUAL_PASS`
`POST /api/insurance-match/manual-confirm` pass=false	保持/记为 `FAIL`

0.5.6 告警处理状态 `AlertHandleStatusEnum`

值	中文	含义
PENDING	待处理	新建告警，尚未有人处置
PROCESSING	处理中	已接手，尚未闭环
CLOSED	已关闭	处置完成（恢复发放/纳入下月补发/确认停发等）

变更：POST /api/alerts/handle 写入 handleStatus、handleResult、handler。
常见类型：DEATH_STATUS（死亡停发预警）、RETURN_FAIL（回盘失败）、INSURANCE_MATCH_FAIL（居保失败，中级）、LAND_MATCH_FAIL（土地匹配不符合，低级）等。

0.5.7 特殊业务审批状态（字符串，非枚举）

落在特殊业务单的 approveStatus：

值	含义	何时出现
待分管领导审批	业务部门已申请，等领导审	`POST /api/special-biz` 创建后
已通过	领导同意，可出特殊业务盘	`leader-approve` + PASS
已驳回	退回业务部门修改	`leader-approve` + REJECT

0.5.8 审批动作 `ApproveActionEnum`

值	含义	用于
PASS	通过，流程前进	镇初审、领导审月度清单、领导审特殊业务
REJECT	驳回，流程回退	同上（红线）

0.5.9 回盘失败码 `FailReasonCodeEnum`

值	含义
CODE_001	社会保险登记码不存在
CODE_002	清户
CODE_003	冻结
CODE_004	用户撤销
CODE_005	保险号不存在 / 账号不一致 / 金额不足
OTHER	其他

用于回盘明细 failReasonCode、告警关联失败原因。确认回盘失败后：登记待补发台账（RETURN_ARREARS）+ RETURN_FAIL 告警；补发由镇级特殊业务走审批后纳入后续发放（村级批次提交仅选人，不可调补发；不自动入下月名单）。

0.5.10 三条泳道状态关系（一句话）

泳道	主看哪些状态
月度补助金申请	批次 `currentStage` + `status`；人员 `bizStatus` + `insuranceMatchResult`
特殊业务申请	人员 `bizStatus`；告警 `handleStatus`；特殊业务 `approveStatus`
回盘信息更新	批次 → `RETURNED`/`ARCHIVED`；明细成败；统计应发/实发/失败；待补发台账 PENDING→REISSUED/WAIVED

1. 前置主数据（所有流程共用）

进入业务页前先拉区划与金额标准。

1.1 查街镇

GET /api/regions?level=TOWN&parentId=D_SJ

参数	含义
level	`DISTRICT` / `TOWN` / `VILLAGE`
parentId	上级区划 ID，区下街镇传 `D_SJ`

返回 RegionVO[]

字段	含义
id / code	业务区划 ID（如 `T_YEXIE`）
name	名称
level	层级
parentId	上级 ID
entrustPlanCode	委托方案代码（街镇级）
enabled	是否启用

1.2 查村居

GET /api/regions?level=VILLAGE&parentId=T_YEXIE

1.3 查金额标准（土地 + 丧葬）

GET /api/amount-standards/current?townId=T_YEXIE&standardType=MONTHLY

参数	含义
townId	街镇 ID（必填）
standardType	`MONTHLY` 取土地额 / `FUNERAL` 取丧葬额；均优先读当前 `YEARLY_ADJUST`

返回 AmountStandardVO

字段	含义
amount	土地月补；`standardType=FUNERAL` 时为丧葬额视图
funeralAmount	丧葬金额（年度标准 `YEARLY_ADJUST` 一行双金额时有值）
standardType	`YEARLY_ADJUST` / 历史 `MONTHLY` / `FUNERAL`
current	是否当前有效
effectiveTime / expireTime	生效/失效时间戳
adjustReason	调整原因

列表/历史：GET /api/amount-standards?townId=&standardType=&current=（列表拆「土地补贴」「丧葬补贴」两列）。
维护：POST /api/amount-standards，推荐 standardType=YEARLY_ADJUST + amount + funeralAmount。
脏数据清理：POST /api/amount-standards/cleanup-legacy-pairs?townId=，将成对 MONTHLY+FUNERAL 合并为年度标准一行。
调标补发读「当前有效 − 上一档」土地标准，见 §3.2。

1.4（可选）流程元数据

接口	用途
`GET /api/workflow/roles`	角色清单
`GET /api/workflow/lanes`	三条泳道说明
`GET /api/workflow/stages`	月度 8 个节点
`GET /api/workflow/special-biz-nodes`	特殊业务节点说明
`GET /api/workflow/batches/{batchId}/overview`	某批次当前阶段、可执行动作、最近留痕

overview 返回要点

字段	含义
currentStage / status	当前阶段与状态
availableActions	前端按钮编码，如 `TOWN_PRECHECK_PASS`
recentLogs	最近流程记录

2. 泳道一：月度补助金申请（主线）

录入人员 → 提交资格 → 镇经发按人审批 →（新增）等待每月 1 号
    └─ 生成全区月批 → 自动居保 → 本镇月度清单 → 特殊业务门禁 → 分管领导 → 出盘回盘
1 号之后新录入默认进下月；本月要发走特殊业务（纳入/补发）。

步骤 A. 村合作社：人员录入与提交资格

顺序	方法	路径	说明
1	POST	`/api/personnel`	新增/编辑人员，状态 `DRAFT`（待提交资格）
2	POST	`/api/personnel/page`	查询本村人员
3	GET	`/api/personnel/{id}`	详情（含资格时间线）
4	POST	`/api/personnel/{id}/qualify/submit`	提交退养资格审批
可选	POST	`/api/personnel/import`	Excel 导入

村页 不出现批次、不选人进批、不提交村批。

步骤 B. 镇经发：退养资格审批

顺序	方法	路径
1	POST	`/api/personnel/page`（`bizStatus=PENDING_TOWN_APPROVE`）
2	POST	`/api/personnel/{id}/qualify/review`（pass + 资格类型）

通过 → NEW；无资格 → ABNORMAL；驳回补材料 → DRAFT。写流程日志 RETIRE_QUALIFY。

步骤 B2. 生成全区月批（替代原村批 ensure/submit）

顺序	方法	路径
定时	cron `0 0 1 1 * ?`	每月 1 日 01:00
手动	POST	`/api/batches/generate-district-month?payMonth=&matchInsurance=`
查询	POST	`/api/batches/page`（`batchLevel=DISTRICT` / `TOWN`）

纳入规则、镇统计、c_parent_batch_id 见 district-month-batch.md。

已停用：ensure-current-month、PUT /batches/{id}/members 作为村入口、POST /batches/{id}/submit、town-approve。

保存请求 PersonnelSaveRequest

字段	必填	含义
id	否	有则编辑
name	是	姓名
idNumber	是	身份证号
townId / villageId	是	街镇/村居
bankCardNumber	建议	银行卡号
payeeName	否	收款人，默认姓名
bankName / bankType / bankBranchCode	否	开户行/行别/行号
socialInsuranceCode	否	个人社保登记码
phoneNumber / address / householdType	否	手机/住址/户籍性质
enjoyStartMonth	否	享受起始年月 yyyyMM
monthlyStandard	否	月补标准金额
entrustPlanCode	否	委托方案代码
source	否	录入来源，如「村级录入」
remarks	否	备注

人员返回 PersonnelVO（常用）

字段	含义
id	业务人员 ID（如 P001）
bizStatus	业务状态
insuranceMatchResult	居保匹配结果
payThisMonth	是否本月发放
monthlyStandard	月补标准
deathDate / heir*	死亡与继承人信息

分页查询额外条件：name（模糊）、idNumber、townId、villageId、bizStatus、payMonth

步骤 C. 历史村批接口（已停用）

ensure-current-month、PUT /batches/{id}/members、POST /batches/{id}/submit、town-approve 不再作为业务入口（调用返回 400）。历史 VILLAGE 批只读。

批次返回 BatchVO（常用）

字段	含义
id	批次业务号（VB/MB…）
batchNo	统一批次号/发放年月
currentStage / status	流程阶段 / 业务状态
peopleCount	应发人数
normalAmount / supplementAmount / funeralAmount / deductAmount / totalAmount	金额分项与合计
exportStatus / returnStatus	出盘/回盘状态
exportDiskNo / exportFileName	出盘编号与文件名
townOpinion	镇/领导审批意见

步骤 D. 镇经发中心：资格审批（现行，替代原村批初审）

见上文步骤 B。town-approve 已停用。

步骤 E. 业务部门：居保匹配

顺序	方法	路径
1	POST	`/api/insurance-match/trigger`
2	GET	`/api/insurance-match/batches/{batchId}/results`
3	POST	`/api/insurance-match/manual-confirm`（FAIL 时）

匹配结果分流（必须落库人员状态，禁止只推批次）

情况	处理
SUCCESS	人员 `bizStatus=NORMAL` + `insuranceMatchResult=SUCCESS`
FAIL / 非死亡异常	人员 `ABNORMAL` + FAIL；MEDIUM 告警；批次 → `PENDING_STATUS_MAINTAIN`
已是 `FUNERAL` 且确有丧葬特殊业务/已发丧葬	`applyDeathSettlement`（刷新丧葬结算）
误标 `FUNERAL`（无死亡登记/丧葬特殊业务且未发丧葬）	回正为 `NORMAL`，清零死亡/丧葬脏字段，按正常匹配继续
非丧葬态仅有死亡日期或备注含「死亡」	不得改 `FUNERAL`；残留丧葬差额可清零
仍有 PENDING/FAIL	不可进领导审；`submit-leader` 亦会拒绝
本批匹配结束	全区主批停在 `PENDING_STATUS_MAINTAIN`（不因一镇提交而改）

死亡只能经「死亡登记/丧葬」特殊业务领导审批落地；居保匹配禁止因 deathDate/备注把正常人改成死亡。

资格通过后人员为 NEW，1 号纳入全区明细后再居保。比对范围=发放明细人员，按 townId 切本镇。

触发请求

字段	含义
batchId	批次 ID
personnelIds	指定人员；空=按批次街镇/村范围

匹配项 InsuranceMatchVO

字段	含义
personnelId / name / idNumber	人员
matchResult	匹配结果枚举
insuranceStatus	居保侧状态文案
message	说明
matchTime	匹配时间戳

人工确认

字段	含义
personnelId / batchId	人员与批次
pass	true=人工通过 → `MANUAL_PASS`
remark / operator	说明与操作人

步骤 E. 生成月补贴清单并提交领导

顺序	方法	路径
1	POST	`/api/payments/batches/{batchId}/generate`（补齐发放明细）
2	POST	`/api/batches/{id}/submit-leader`（居保 FAIL 人工确认后必调；推进到 `PENDING_LEADER_APPROVE`）
3	POST	`/api/payments/details/page`（核对名单）

submit-leader 规则

提交对象必须是 镇统计记录（batchLevel=TOWN），禁止对全区 DISTRICT 主批调用。

当前状态	行为
`PENDING_STATUS_MAINTAIN`	本镇特殊业务无「待分管领导审批」→ 镇统计 `PENDING_LEADER_APPROVE`（不改全区主批）
`PENDING_LEADER_APPROVE`	幂等
其他 / DISTRICT	`400` 拒绝

仍有居保 FAIL 未人工确认时返回 400（提示先到居保页处理）。

明细查询条件：batchId / batchNo / townId / villageId / name / idNumber + 分页

发放明细 PaymentDetailVO

字段	含义
batchId / batchNo	所属批次
personnelId / name / idNumber	人员
payMonth	发放年月
monthlyAmount	月发标准
oneTimeAmount	一次性代发
supplementAmount	补发（镇级业务写入；村级提交页不调）
funeralAmount	丧葬费
deductAmount	扣减
totalAmount	应发合计（标准+一次+补发+丧葬−扣减）
actualAmount	实发：回盘成功=应发，失败=0；未回盘为空
returnSuccess / returnResult	回盘成败；文案：成功 / 失败 / 未回盘
batchStatus	所属批次业务状态（查询时附带）
payBank / bankCardNumber	银行与卡号
exported	是否已纳入出盘
remarks	备注（可含 `回盘成功` / `回盘失败

历月查询：POST /api/payments/details/page（可按 idNumber/name 跨批）→ 前端展示应发/实发，并可打开批次流程时间线核对。

步骤 F. 分管领导：线上审批清单

POST /api/batches/leader-approve
参数同初审（bizId + action + opinion）

门禁（防“人员未过却批次通过”）：

批次须为 PENDING_LEADER_APPROVE（须先 submit-leader）
PASS 前校验本批明细人员居保均已 SUCCESS/MANUAL_PASS（FAIL/PENDING 禁止通过）
PASS → STAGE6_COMPARE_FILE / READY_EXPORT
REJECT → STAGE4_MONTHLY_LIST / REJECTED；业务调整后可再次 submit-leader（镇初审驳回的 REJECTED+STAGE1 仍不可直提领导）

步骤 G. 业务部门：生成对照文件（出盘）

POST /api/payments/export-disk

门禁：批次状态须为 READY_EXPORT 或 EXPORTED（未领导通过禁止出盘）。

字段	含义
batchId	批次 ID
payBank	按银行拆分：农行/农商；空=全部
adjustOnly	true=调标单独出盘（一年一次；可绕过常规截止校验）
bypassDeadline	true=补办出盘，跳过当月截止日（逾期补办/历史月）；前端「对照文件出盘」逾期时勾选
operator	操作人

出盘截止：WorkdayService 内置 2025–2027 国定假日+调休；截止日 = 不晚于当月 20 日的最近工作日。今天 > 截止日且非 adjustOnly/bypassDeadline → HTTP/业务 400。查询：GET /api/amount-standards/export-deadline?payMonth=。

返回 DiscExportResultVO

字段	含义
exportDiskNo	出盘编号
fileName / fileUrl	文件名与下载路径
detailCount	明细条数
exportDeadline	本发放月出盘截止日 yyyy-MM-dd
offlineTip	线下提示：交镇领导签字后财务财政发放

之后 STAGE7 为线下：镇领导签字 → 财务发放（系统只留状态/文件，不走资金支付）。

步骤 H. 过程跟踪（任意节点可查）

方法	路径	用途
POST	`/api/process-logs/page`	按 batchId/batchNo/stage/personnelId 查留痕
GET	`/api/process-logs/batches/{batchId}/timeline`	流程时间轴

流程记录 ProcessLogVO（常用）：stage、action、operator/operatorRole/operatorOrg、opinion、result、operateTime

3. 泳道二：特殊业务申请

死亡录入/状态变更 → 系统告警(红) → 特殊业务申请
    → 分管领导审批 → 特殊业务出盘 →（线下签字发放）
其他：暂停/恢复/补发、调标补发（调标一年一次单独出盘）

3.1 死亡 / 停发路径

顺序	方法	路径	说明
1	PUT	`/api/personnel/status`	置 `FUNERAL`/`STOPPED`，可触发告警
2	POST	`/api/alerts/page`	查 `type=DEATH_STATUS`
3	POST	`/api/alerts/handle`	处置告警
4	POST	`/api/special-biz`	创建丧葬等特殊业务
5	GET	`/api/special-biz/page`	查询待审单
6	POST	`/api/special-biz/leader-approve`	领导审批
7	POST	`/api/special-biz/{id}/export-disk`	特殊业务出盘

状态更新 PersonnelStatusUpdateRequest

字段	含义
personnelId	人员 ID
bizStatus	目标状态
payThisMonth	是否本月发放
remarks / operator	说明与操作人

创建特殊业务 SpecialBizCreateRequest

字段	必填	含义
personnelId	非调标必填	人员；`STANDARD_ADJUST` 可不传
bizType	是	见下表
townId	调标必填	街镇；新旧土地标准与生效月从金额标准历史自动带出，不再手填
fileUrls	否	附件 URL，逗号分隔（调标等）
batchNo	否	关联发放批次号
amount	否	涉及金额（非调标）
reason	否	原因/备注
heirName / heirIdNumber / heirBankCard / heirPhone	丧葬建议填	继承人信息
operator	否	操作人

SpecialBizTypeEnum

值	含义
FUNERAL	丧葬补助（一生一次；可先录死亡再随时申请；已发/在途不可重复；随月度清单或特殊出盘）
PAUSE / STOP / RESUME	暂停 / 停止 / 恢复
STANDARD_ADJUST	调标差额补发：只选镇，按村生成 `YYYY99` 批单独出盘
SUPPLEMENT	纳入下月补发
REFUND	多发退款
HEIR_UPDATE	继承人变更

特殊业务返回 SpecialBizVO

字段	含义
id	特殊业务单 ID
bizType / amount / reason	类型、金额、原因/备注
townId / relatedBatchIds / batchNo	调标：街镇、关联村批 ID 列表、业务号 `{year}99`
fileUrls	附件 URL（调标等；与继承人编码共用存储字段时按前缀区分）
approveStatus	待分管领导审批 / 已通过 / 已驳回
heir*	继承人
opinion	审批意见

特殊业务领导审批：POST /api/special-biz/leader-approve，body 同通用 ApproveRequest（bizId 填特殊业务单 ID）。

仅 approveStatus=待分管领导审批 可审；已通过/已驳回再审 → 400。
PASS 副作用：PAUSE/STOP/FUNERAL/RESUME/HEIR_UPDATE 回写人员状态、继承人、丧葬额、恢复补发等。
调标：PASS 前须关联村批均已领导通过（READY_EXPORT/EXPORTED/RETURNED/ARCHIVED）；REJECT 则软删关联村批。实质审批在各村补发批：POST /api/batches/leader-approve。
特殊出盘 POST /api/special-biz/{id}/export-disk：须已通过；STANDARD_ADJUST 禁止走此接口（改用对照文件出盘 adjustOnly）；已出盘不可重复。

3.2 年调标路径（推荐）

两条入口等价（共用 submitYearlyAdjust）：

顺序	方法	路径
1a	POST	`/api/amount-standards/yearly-adjust`
1b	POST	`/api/special-biz`
2	POST	`/api/batches/leader-approve`
3	POST	`/api/payments/export-disk`

YearlyAdjustRequest / 调标字段：金额标准页入口传 townId、monthlyAmount、funeralAmount、effectiveMonth(yyyyMM)、adjustReason（会落库新标准）。特殊业务入口只传 townId，服务端按「当前有效土地标准 − 上一档」算差额，skipSaveStandards=true 不再改标准。

规则	说明
批次	业务号 `{year}99`（如 `202699`）；每个有在发人员的村一批：`VB{year}99-{villageId}`（村级）；`c_pay_month` 为 `YYYY9x`（每村不同，避免 DMS「镇+月」唯一互盖），备注含 `YEARLY_ADJUST\\|{year}99`
个人补发	`(新土地月标 − 旧月标) × K`；`K`=当年 1 月～生效前一月应发月数（正常/草稿计满月）
差额	新土地月标必须高于旧档，否则 `400`
名单标准	本批只记补发差额；次月 ensure/明细生成取新月标
频次	同镇同自然年已有未归档调标批（ID/备注含 `{year}99`）→ `409`；重建前会软删同号残留行
返回	`batchIds[]` / `relatedBatchIds`、`byVillage[]`、`peopleCount`、`totalSupplement`
前置	特殊业务入口要求金额标准页已存在「当前有效 + 上一档」土地标准

双标准维护：POST /api/amount-standards（推荐 YEARLY_ADJUST 一行写土地 amount + 丧葬 funeralAmount；兼容历史 MONTHLY/FUNERAL 单行）。

3.2.1 恢复发放（RESUME）自动补发

顺序	方法	路径
1	GET	`/api/special-biz/resume-preview?personnelId=`
2	POST	`/api/special-biz`
3	POST	`/api/special-biz/leader-approve`

公式：暂停起止月（优先 enjoyEndMonth，缺省约往前 2 月）× monthlyStandard；默认原因形如「恢复发放补发：YYYYMM–YYYYMM 共 N 月」。

3.3 告警查询与处置

POST /api/alerts/page
条件：batchNo、townId、type、handleStatus、personnelName + 分页

AlertTypeEnum：DEATH_STATUS / RETURN_FAIL / INSURANCE_MATCH_FAIL / LAND_MATCH_FAIL / BANK_CARD_ABNORMAL / NAME_MISMATCH / AMOUNT_ABNORMAL / MATERIAL_PENDING

处置 POST /api/alerts/handle

字段	含义
alertId	告警 ID
handleStatus	`PENDING` / `PROCESSING` / `CLOSED`
handleResult	如：恢复发放、纳入下月补发、更新银行卡
handler / remarks	处理人与说明
fileUrls	附件 URL，逗号分隔（关闭时可上传证明）

告警返回 AlertVO（常用）：type、level、content、failReasonCode、handleStatus、personnelName、fileUrls、lifecycle、createTime

4. 泳道三：回盘信息更新

上传回盘文件 → 查回盘明细 → 确认回盘 → 失败入待补发台账 + 告警 → 镇级特殊业务审批补发 → 统计/看板 → 归档

顺序	方法	路径	说明
1	POST	`/api/return-disk/upload`	multipart：`batchId` + `file`
2	POST	`/api/return-disk/details/page`	回盘明细（含失败码）
3	POST	`/api/return-disk/confirm`	确认回盘；失败建告警+待补发台账
4	POST	`/api/return-arrears/page`	查待补发台账
5	GET	`/api/return-arrears/by-personnel/{id}`	某人待补发/历史
6	POST	`/api/return-arrears/reissue`	镇级审批通过后纳入目标批补发（村级提交页不开放调补发）
7	POST	`/api/return-arrears/waive`	核销不补发
8	POST	`/api/batch-stats/page`	应发/实发/失败汇总
9	POST	`/api/dashboard/archive/{batchId}`	归档（可选）

确认请求 DiscReturnImportRequest

字段	含义
batchId	批次 ID
fileName	回盘文件名
summaryNo	汇总表编号
returnDate	回盘日期 yyyy-MM-dd
manualAllSuccess	无 lines 时整批成功
lines	逐人成败（优先）
operator	操作人

回盘明细 ReturnDetailVO

字段	含义
success	是否成功
failReasonCode / failReasonDesc	失败码与描述
amount / actualAmount	应发 / 实发（失败为 0）
personnelId / name / idNumber	人员
returnDate	回盘日期

待补发台账 ReturnArrearsVO（落流程表 c_action=RETURN_ARREARS）

字段	含义
amount	待补发金额（= 失败时应发）
sourceBatchId / sourcePaymentDetailId / sourcePayMonth	来源
status	`PENDING` / `REISSUED` / `WAIVED`
failReasonCode / failReasonDesc	失败原因
alertId	关联 `RETURN_FAIL` 告警
reissueBatchId / reissuePaymentDetailId	补发落点
events	创建/补发/核销时间线

reissue：校验目标村批可调金额 → 累加明细 supplementAmount → 台账 REISSUED。不自动写入下月名单。

批次统计 BatchStatVO（常用）

字段	含义
shouldPayCount / shouldPayAmount	应支付人数/金额
actualPayCount / actualPayAmount	实支付
failCount / failAmount	失败
grain	粒度：全区/街镇/村居/银行
payBank	银行

确认后批次一般进入 STAGE8_RETURN_CONFIRM / RETURNED（或再归档为 ARCHIVED）。

5. 区级监管（只读）

方法	路径	说明
GET	`/api/dashboard/summary?payMonth=202603&townId=T_YEXIE`	发放汇总看板
POST	`/api/dashboard/history-batches`	历史回盘/归档批次（body 同批次查询）

看板 DashboardVO

字段	含义
payMonth	发放年月
totalPeople / totalAmount	应发人数/金额
actualAmount	实发金额
failPeople	失败人数
pendingAlertCount	待处理告警数
townStats	按街镇等统计明细

6. 前端调用顺序速查（推荐）

月度主线（通过）

GET /api/regions（镇→村）
GET /api/amount-standards/current
POST /api/personnel → POST /api/personnel/page
POST /api/personnel/{id}/qualify/submit
POST /api/personnel/{id}/qualify/review {pass:true, retireQualifyType:"WITH_LAND"}
POST /api/batches/generate-district-month（每月 1 号定时；今日已过 1 号由管理员手动）
POST /api/insurance-match/trigger（生成时已自动触发）→ GET .../results?townId=（FAIL 时 manual-confirm）
POST /api/payments/details/page（batchId=全区批 + townId 切本镇）
POST /api/batches/{镇统计id}/submit-leader（本镇特殊业务须全部通过）
POST /api/batches/leader-approve {action:"PASS"}
POST /api/payments/export-disk
（线下）→ 见回盘泳道

月度驳回

资格：qualify/review pass=false（无资格或补材料）
领导：leader-approve + REJECT（镇统计）

特殊业务（丧葬 / 恢复）

丧葬：PUT /api/personnel/status（FUNERAL）→ 告警处置 → POST /api/special-biz
恢复：GET /api/special-biz/resume-preview → POST /api/special-biz（RESUME）→ leader-approve（补发入当月全区明细）
leader-approve → 必要时出盘

年调标

金额标准页先维护新土地/丧葬标准（或走 yearly-adjust 一并落库）
特殊业务：POST /api/special-biz（STANDARD_ADJUST，只传 townId + 可选 reason/fileUrls）
——或金额标准页：POST /api/amount-standards/yearly-adjust
差额挂当月全区批补发明细，不再新建 VB{year}99-* 村批
POST /api/payments/export-disk（adjustOnly=true 仍可）

回盘

POST /api/return-disk/upload
POST /api/return-disk/details/page
POST /api/return-disk/confirm（失败 → 告警 + 待补发台账）
POST /api/return-arrears/page 或 GET /api/return-arrears/by-personnel/{id}
镇级审批后 POST /api/return-arrears/reissue（或 /waive 核销）
POST /api/batch-stats/page
POST /api/dashboard/archive/{batchId}

历月发放查询（村/镇查询页）

POST /api/personnel/page
POST /api/payments/details/page（按人）→ 看应发/实发/回盘
GET /api/process-logs/batches/{batchId}/timeline 或批次详情抽屉

7. 接口与角色对照

角色	主要接口 / 前端页
村合作社	regions、amount-standards/current、personnel*、batches ensure/选人/submit；发放查询（历月应发实发）
镇经发中心	batches/page、town-approve、process-logs、workflow/overview
社区事务中心-业务	insurance-match、payments、special-biz（含调标）、return-disk、return-arrears、alerts*、batch-stats、金额标准
社区事务中心-分管领导	batches/leader-approve（含调标村批）、special-biz/leader-approve
镇领导 / 财务	线下；系统仅出盘文件与提示
区农委 / 区人社	dashboard/summary、region-stats、history-batches

附件：POST /api/files/upload（Swagger Tag 13-附件上传）。

8. 相关文档

文档	说明
README.md	文档索引与近期业务约定
flow-260804.md	流程图角色与泳道
dms-model-migration-2026-08-04.md	DMS 模型迁移
dms-mock-data.md	Mock/种子数据
Swagger UI	`http://localhost:8088/sjnmtybt/swagger-ui.html`
联调脚本	`scripts/e2e-api-flow-test.js`、`scripts/e2e-biz-assert.js`
前端说明	`sjnmtybt-web/README.md`

9. 修订记录

日期	摘要
2026-08-07	闭环补齐：`POST /batches/{id}/submit-leader`；居保结果严禁回退全村；回盘页归档；审批人数按发放明细；选人默认剔除暂停/死亡；提交时间回填
2026-08-07	性能：发放明细先分页再 enrichment；批次/人员/发放短缓存；写后 invalidate；热路径 warm 宜 <300ms（脚本 `scripts/perf-hot-paths.js`）；闭环脚本 `scripts/e2e-submit-leader-loop.js`
2026-08-07	丧葬补贴一生一次：已发/在途不可再申请；允许先录死亡后补特殊业务；月度清单不再重复带入已发丧葬
2026-08-07	人员列表月补与顶部标准对齐：优先 YEARLY_ADJUST 土地额，再回退 MONTHLY
2026-08-07	发放明细弹窗实发按人员明细重算；恢复补发不写入已出盘/已回盘批次（改落次月）
2026-08-06	全生命周期联调修复：月度/特殊业务/回盘；脚本 `scripts/e2e-lifecycle-full.js`
2026-08-06	出盘增加 `bypassDeadline` 补办；前端「对照文件出盘」逾期可勾选补办
2026-08-06	特殊业务：审批门禁、PASS 副作用、调标须村批先通过、特殊出盘禁调标/禁重复
2026-08-06	调标批按村区分发放月键；`getBatch` 直扫 DMS；`pageBatch` 按业务号+村居去重；`purge` 软删全部同号行
2026-08-06	`DmsClient.selectContentList` 不再误信 total 提前停页
2026-08-06	前端：特殊业务提交后不跳领导页；调标/丧葬/继承人表单与提示；金额标准调标成功改通知
2026-08-06	村级批次仅选人、不调补发；补发归镇级特殊业务/待补发台账
2026-08-06	调标特殊业务只选镇+备注/附件；标准从金额标准历史带出；按村 `YYYY99` 批
2026-08-06	回盘失败台账 `RETURN_ARREARS`；确认回盘写实发统计与告警
2026-08-06	`PaymentDetailVO` 增加实发/回盘结果/批次状态；历月查询展示应发实发
2026-08-06	Swagger 补齐注解；Tag 增加 `08b` 待补发、`13` 附件；列表隐藏非批次 ID
2026-08-06	文档索引 `docs/README.md`；同步 `flow-260804.md` 与前后端 README
2026-08-06	年度标准 `YEARLY_ADJUST` 一行双金额（`c_amount`+`c_funeral_amount`）；`cleanup-legacy-pairs` 合并历史双行
2026-08-06	DMS 补字段：明细实发/回盘、区划 level/code、流程待补发结构化；脚本 `migrate-missing-biz-fields.js`

api-business-flow-guide.md 43 KB Riwayat Mentahan