sj_nmtybt_server/docs/README.md

松江农民退养补贴 — 技术文档索引

后端工程：sj_nmtybt_server（Maven 构件名仍为 sjnmtybt-server）
正式前端工程：sj_tdtybz（页面流程以新前端为准；联调说明见 sj_tdtybz/docs/api-integration.md）
旧演示前端 sjnmtybt-web：停用作业务入口，仅可作接口对照
最近整理：2026-08-27（优化清单技术跟踪；对接 sj_tdtybz；e2e：scripts/e2e-lifecycle-full.js）

文档清单

文档	用途	读者
../../docs/松江土地退养项目优化列表-技术跟踪.md	优化清单跟踪：Excel 40 项状态、截图索引、补充项分析与实施顺序	产品/研发/测试
../../sj_tdtybz/docs/api-integration.md	新前端联调：页面流程 → 接口映射、代理/鉴权、字段转换	前端联调
district-month-batch.md	全区月批 + 资格审批（现行主线）	产品/研发/测试
../../docs/全生命周期业务测试-全区月批.md	前端入口级全生命周期测试记录	测试/联调
flow-260804.md	流程图角色与泳道业务说明（对齐《流程图260804》）	产品/业务/研发
dms-model-migration-2026-08-04.md	DMS 栏目/字段迁移与模型对照	后端、DMS 运维
dms-mock-data.md	联调 Mock/种子数据说明	联调

在线接口文档（Swagger）

• 地址：http://localhost:8088/sjnmtybt/swagger-ui.html
• OpenAPI JSON：http://localhost:8088/sjnmtybt/v3/api-docs
• 标签编号：00 流程/字典 → 01 区划 → … → 08 回盘 → 08b 待补发 → … → 12 看板 → 13 附件

---

近期业务约定（相对初版流程图的落地澄清）

以下约定已在代码与 api-business-flow-guide.md 中落实，联调以本文 + 主文档为准。

1. 村合作社：只做人员与资格，不看见批次

• 村页录入/导入人员后为「待提交资格」，点「提交资格」由镇经发按人审批。
• 不再 ensure 村批、选人、提交初审。
• 补发（含回盘失败待补发、恢复发放、调标差额）由镇级特殊业务写入当月全区明细。

2. 调标差额补发（STANDARD_ADJUST）

• 入口 A：金额标准页 POST /api/amount-standards/yearly-adjust（手填新标准并落库）。
• 入口 B：特殊业务页只选街镇，可选备注/附件；新旧土地标准与生效月从金额标准历史自动带出（skipSaveStandards）。
• 批次形态：差额挂当年/当月 全区批 补发明细，不再新建 VB{year}99-* 村批。
• 审批：特殊业务单走分管领导；出盘可走对照文件 adjustOnly=true。
• 同镇同自然年未归档调标批不可重复提交（409）；差额须为正；重建前软删同号残留。

3. 回盘与待补发台账

• 仅待回盘批次可确认；已回盘只读 + 可归档。
• 失败：实发记 0 → RETURN_FAIL 告警 + 流程表台账 c_action=RETURN_ARREARS（PENDING）。
• 补发闭环：POST /api/return-arrears/reissue（镇级审批后）；核销：/waive。
• 不自动写入下月名单。
• 出盘逾期：常规批可传 bypassDeadline=true（前端勾选「补办出盘」）。

3b. 特殊业务门禁（联调后固化）

• 月度清单「提交分管领导」前：该镇该发放月特殊业务不能有「待分管领导审批」。
• 仅「待分管领导审批」可审；通过后写人员状态/继承人/丧葬/恢复补发等副作用。
• 创建校验：RESUME 仅暂停/停止；PAUSE 仅正常/草稿；FUNERAL 不重复；调标必选镇且标准有正差额。
• 全链路脚本：scripts/e2e-lifecycle-full.js。

4. 历月发放查询：应发 / 实发

• PaymentDetailVO 附带：totalAmount（应发）、actualAmount（实发）、returnSuccess / returnResult、batchStatus。
• 口径：回盘成功实发=应发；失败=0；未回盘显示「未回盘」。
• DMS 已落库：c_actual_amount / c_return_success / c_return_result / c_fail_reason_code（兼容旧备注解析）。
• 前端「本村发放查询」可打开批次详情/流程时间线核对业务流。

5. 金额标准

• 年度标准（YEARLY_ADJUST）：一行双金额 — c_amount 土地月补 + c_funeral_amount 丧葬。
• 日常核算优先读当前年度标准；兼容历史 MONTHLY/FUNERAL 单行。
• 脏数据：POST /api/amount-standards/cleanup-legacy-pairs 将成对历史两行合并为一行。

6. 前端列表展示

• 列表不展示非批次 UUID/单号列；保留批次 ID及业务码（身份证、区划代码、出盘编号等）。
• 详情/表单可为运维保留人员 ID。

---

推荐阅读顺序

1. flow-260804.md — 先建立泳道与角色心智模型
   
2. api-business-flow-guide.md §0.5 状态字典 → §6 调用顺序速查
   
3. Swagger 按 Tag 试接口
   
4. 需要落库细节时再看 DMS 两篇
   

前端角色菜单与启动说明见：../../sjnmtybt-web/README.md。