Inicio Explorar Axuda
Iniciar sesión
skyversation
/
sj_tdtybz
9
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Árbore: 2228b57bf6
Ramas Etiquetas
sj_tdtybz
/
docs
/
api-integration.md

api-integration.md 9.9 KB
Histórico Raw

sj_tdtybz ↔ sj_nmtybt_server 接口联调说明

修订：2026-08-07
正式前端：sj_tdtybz（本仓库）
联调后端：sj_nmtybt_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. 启动后端：sj_nmtybt_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 环境）见后端文档 sj_nmtybt_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 历史联调页，停用；接口路径仍可对照
sj_nmtybt_server/docs/api-business-flow-guide.md 后端权威接口与状态机文档