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

> 后端工程：`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 村批、选人、提交初审。
- 补发（含回盘失败待补发、恢复发放、调标差额）由镇级特殊业务写入当月全区明细。

### 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](./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)。