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

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

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

- 村页录入/导入人员后为「待提交资格」，点「提交资格」由镇经发按人审批。
- **不再** ensure 村批、选人、提交初审。
- 补发（含回盘失败待补发、恢复发放、调标差额）由镇级特殊业务写入当月全区明细。
- 全区月批每月 **15 日 01:00** 生成；资格通过日 ≤15 进本月起始月，≥16 进下月。详见 [district-month-batch.md](./district-month-batch.md)。

### 2. 调标差额补发（仅区人社）

- 调标只开给区人社：`POST /api/amount-standards/district-yearly-adjust`（或 `yearly-adjust` 且 `districtWide=true`）。标准只写全区一份。
- 街镇特殊业务 **不再发起** `STANDARD_ADJUST`（接口 400）。
- 完成后按村生成 `VB{year}99-{villageId}` 差额专批（`payMonth={year}99`，只记补发），**不**改写当月全区月批 `DB*`。
- 写流程通知 `DISTRICT_ADJUST_NOTICE`；街镇（经发/社区事务/分管领导）登录读 `GET /api/amount-standards/adjust-notice` 弹「已调标」。
- 同镇同自然年未归档调标批不可重复提交（`409`）；差额须为正。
- 收口后未出盘全区月批若仍停在街镇测试月标（如叶榭 1380、石湖荡 1100），用 `POST /api/amount-standards/realign-open-payments` 收到现行全区月标；领导审镇统计批前对齐父批本镇切片。

### 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. 金额标准

- 全区统一一份（`c_town_id=T_DISTRICT`），不按街镇分别维护。核算读全区当前 YEARLY_ADJUST。
- **年度标准**（`YEARLY_ADJUST`）：一行双金额 — `c_amount` 土地月补 + `c_funeral_amount` 丧葬。
- 收口脏数据：`POST /api/amount-standards/unify-district` 保留人员明细统一 1060/24868，软删各镇重复行与测试行。
- 兼容：`POST /api/amount-standards/cleanup-legacy-pairs` 将成对历史 MONTHLY+FUNERAL 两行合并。

### 6. 前端列表展示

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

### 7. 人员台账 / 资格 / 死亡预警（20260916）

- 台账列：姓名、身份证、街镇/村、银行卡、开户行、社保卡号、同城/异地、状态、退养资格；备注展示空。导出 `POST /api/personnel/export-ledger`。
- 同城/异地：`c_local_or_remote`（兼容备注 `LOCAL_REMOTE`）。
- 村级新增默认无土地有资格；接口/导入默认有土地。镇经发只通过/驳回本次新增（`PENDING_TOWN_APPROVE`），待审/已审为月人员表。新增名单 `POST /api/personnel/export-new-month` 导出纸质 xlsx。
- 无土地：城乡居保 + 退休（社保）+ 本区农业户口。有土地：城乡居保 + 退休 + 本区承包地。
- 死亡预警只提示：`c_death_status=已死亡` 或有死亡日期，且业务态不是丧葬/已退出；不改 `c_biz_status`。
- 社保卡号字段即 `c_social_insurance_code`。历史底数可用 `scripts/backfill-ssc-from-excel.py` 按身份证从「已匹配200编号」明细只补空值。

---

## 推荐阅读顺序

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

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