diff --git a/changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md b/changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md new file mode 100644 index 00000000..95ed24c8 --- /dev/null +++ b/changelogs-v2/2026-10/02_8719_应收侧往来台账放开-修改接口-管理后台.md @@ -0,0 +1,309 @@ +--- +schema: "hl-changelog/v2" +ticket: "8719" +title: "应收侧往来台账放开——ledgerType 取值域扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER(#8719)" +consumer: "admin" +author: "yst" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-10-02" +status_note: "应收初始化录入的应收期初(客户应收/供应商应收)原在往来台账看不到,本期放开应收侧台账:/admin/finance/statements/page 与 /entries/page 两接口 ledgerType 取值域由仅 SUPPLIER 扩为 SUPPLIER/SUPPLIER_RECV/CUSTOMER(STAFF 仍未开放,传了报 596005)。应收账套本期无业务流水,increaseTotal/decreaseTotal 恒 0、entries 空页属正常;netAmount/openingAmount 符号方向按账套不同,详见正文对照表。" +updated_at: "2026-10-02" +base: "dev-v3" +--- + +# finance:应收侧往来台账放开——ledgerType 扩域(管理后台) + +> ⚠️ **修改接口(入参取值域扩大 + 出参符号语义按账套分化)**:`ledgerType` 新增 `SUPPLIER_RECV` / `CUSTOMER` 两个合法值;出参 `netAmount` / `openingAmount` 的正负方向随账套不同,前端展示层必须按账套区分正负含义并标红负值。 + +## 1. 接口背景 + +应收初始化录入的**应收期初**(客户应收 / 供应商应收)原先在往来台账页**完全看不到**——因为台账接口的 `ledgerType` 只开放 `SUPPLIER`(供应商应付)一个账套,应收侧的期初挂账没有查询入口。 + +本期放开应收侧台账,让期初挂账可见: +- 供应商应收(`SUPPLIER_RECV`):我们预付/多付给供应商、应向他收回的钱 +- 客户应收(`CUSTOMER`):客户欠我们的钱(该收未收) + +注意本期**只放开期初可见性**,应收账套暂无业务流水(后续版本接),所以应收账套下 `increaseTotal` / `decreaseTotal` 恒为 0、明细接口返回空页属于**正常行为**,不是接口坏了。 + +## 2. 变更清单 + +| # | 接口 | 变更点 | 类型 | +|---|------|--------|------| +| 1 | `GET /admin/finance/statements/page` | 入参 `ledgerType` 取值域扩大:`SUPPLIER` → `SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER` | ⚠️ 修改 | +| 2 | `GET /admin/finance/statements/page` | 出参 `netAmount` / `openingAmount` 符号方向按账套分化(详见 §5 对照表) | 🔧 语义扩展 | +| 3 | `GET /admin/finance/statements/page` | 出参 `ledgerType` 可能出现新值 `SUPPLIER_RECV` / `CUSTOMER` | ✨ 枚举扩域 | +| 4 | `GET /admin/finance/statements/entries/page` | 入参 `ledgerType` 取值域同步扩大 | ⚠️ 修改 | +| 5 | 两接口 | `STAFF` 账套仍未开放,传 `STAFF` 报 596005 | 📝 行为不变 | + +## 3. 接口详情 + +| 项 | statements/page | entries/page | +|---|---|---| +| 方法 + 路径 | `GET /admin/finance/statements/page` | `GET /admin/finance/statements/entries/page` | +| 接口名 | 往来台账分页(按往来单位汇总) | 台账明细分页(按往来单位看流水) | +| 使用场景 | 管理后台 → 财务 → 往来台账列表页 | 台账页点某往来单位后的明细流水 | +| 认证 | 管理后台登录态(JWT) | 同左 | +| 幂等性 | 只读查询,天然幂等 | 只读查询,天然幂等 | +| 限流 | 无特殊限流 | 无特殊限流 | + +## 4. 接口入参 + +### 4.1 `GET /admin/finance/statements/page`(Query 参数) + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| ledgerType | string | **必填** | 账套:`SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER`(本期新增后两个值);传 `STAFF` 报 596005 | +| refName | string | 可空 | 往来单位名称,模糊匹配 | +| negativeOnly | boolean | 可空 | 只看净额为负(多付/多收)的单位;语义随账套,见 §5 | +| page | int | 必填 | 页码,从 1 开始 | +| pageSize | int | 必填 | 每页条数 | + +### 4.2 `GET /admin/finance/statements/entries/page`(Query 参数) + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| ledgerType | string | **必填** | 账套,取值同 4.1;传 `STAFF` 报 596005 | +| refId | string | 必填 | 往来单位 ID(台账列表出参 `refId`) | +| direction | string | 可空 | 流水方向:`INCREASE` / `DECREASE` | +| sourceType | string | 可空 | 来源类型:`PAYMENT` / `PREPAY` | +| entryDateStart | string | 可空 | 流水日期起,格式 `yyyy-MM-dd` | +| entryDateEnd | string | 可空 | 流水日期止,格式 `yyyy-MM-dd` | +| teamNo | string | 可空 | 团号,精确过滤 | +| page | int | 必填 | 页码,从 1 开始 | +| pageSize | int | 必填 | 每页条数 | + +## 5. 出参字段 + +### 5.1 statements/page 出参 + +统一分页包装 `PageResult`:`{ list/records: [...], total, page, pageSize }`(以前端现行解析字段为准,按现有页面使用的那个读)。 + +`records[]` 字段: + +| 字段 | 类型 | 说明 | +|------|------|------| +| ledgerType | string | 账套,可能值:`SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER`(新增后两个值) | +| refId | string | 往来单位 ID(Long 序列化为字符串,防精度丢失) | +| refName | string | 往来单位名称 | +| openingAmount | number | 期初净额,方向按账套(见下表) | +| increaseTotal | number | 本期增加合计(应收账套本期恒 0) | +| decreaseTotal | number | 本期减少合计(应收账套本期恒 0) | +| writeoffTotal | number | 核销合计 | +| adjustTotal | number | 财务调账合计 | +| netAmount | number | 当前净额,方向按账套(见下表) | + +**金额符号语义对照表(前端展示必须按此区分)**: + +| 账套 | openingAmount 期初净额 | netAmount 正数含义 | netAmount 负数含义 | 前端提示文案建议 | +|------|------------------------|---------------------|---------------------|------------------| +| `SUPPLIER` 供应商应付 | 期初应付 − 期初应收 | 我欠他(该付未付) | 多付他 | 应付 / 多付 | +| `SUPPLIER_RECV` 供应商应收 | 期初应收 − 期初应付 | 他欠我(该收未收) | 多收他 | 应收 / 多收 | +| `CUSTOMER` 客户应收 | 期初应收 − 期初应付 | 他欠我(该收未收) | 多收他 | 应收 / 多收 | + +- **负值一律标红**(多付 / 多收属异常资金状态,需财务关注)。 +- 同一列在不同账套 tab 下正负含义**相反**,不能直接复用「正=欠」的单一判断。 + +### 5.2 entries/page 出参 + +`records[]` 字段: + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | string | 明细 ID | +| ledgerType | string | 账套,可能值同 5.1 | +| refId | string | 往来单位 ID | +| refName | string | 往来单位名称 | +| entryDate | string | 流水日期 | +| sourceType | string | 来源类型:`PAYMENT` / `PREPAY` | +| sourceId | string | 来源单据 ID | +| sourceNo | string | 来源单号 | +| direction | string | `INCREASE` / `DECREASE` | +| amount | number | 金额(正数,方向由 direction 表达) | +| teamNo | string | 团号,无挂团时为空 | +| summary | string | 摘要 | + +## 6. 枚举 / 数据字典 + +### ledgerType(账套类型) + +| 值 | 含义 | 本期状态 | +|----|------|----------| +| `SUPPLIER` | 供应商应付 | 原有,不变 | +| `SUPPLIER_RECV` | 供应商应收 | **本期新增开放** | +| `CUSTOMER` | 客户应收 | **本期新增开放** | +| `STAFF` | 员工往来 | **未开放**,传了报 596005 | + +### direction(流水方向) + +| 值 | 含义 | +|----|------| +| `INCREASE` | 增加 | +| `DECREASE` | 减少 | + +### sourceType(来源类型) + +| 值 | 含义 | +|----|------| +| `PAYMENT` | 付款/收款 | +| `PREPAY` | 预付 | + +## 7. 错误码 + +| 错误码 | 含义 | 触发场景 | +|--------|------|----------| +| 596005 | 账套非法或未开放 | `ledgerType` 传了 `STAFF` 或其他未开放/不存在的值 | + +## 8. 示例 + +### 8.1 典型:查供应商应收台账(新开放账套) + +请求: + +``` +GET /admin/finance/statements/page?ledgerType=SUPPLIER_RECV&page=1&pageSize=20 +``` + +响应 200: + +```json +{ + "code": 0, + "data": { + "list": [ + { + "ledgerType": "SUPPLIER_RECV", + "refId": "1927081523456789012", + "refName": "草原牧歌车队有限公司", + "openingAmount": 5000.00, + "increaseTotal": 0, + "decreaseTotal": 0, + "writeoffTotal": 0, + "adjustTotal": 0, + "netAmount": 5000.00 + } + ], + "total": 1 + } +} +``` + +读法:该供应商应收 5000,即「他欠我 5000 该收未收」(正 = 他欠我)。 + +### 8.2 边界:应收账套明细返回空页(正常)+ 负净额 + +查客户应收明细(本期无业务流水): + +``` +GET /admin/finance/statements/entries/page?ledgerType=CUSTOMER&refId=1927081523456789999&page=1&pageSize=20 +``` + +响应 200(**空页属正常**,应收账套本期只有期初无流水): + +```json +{ + "code": 0, + "data": { + "list": [], + "total": 0 + } +} +``` + +多收客户场景(负净额,前端标红): + +```json +{ + "ledgerType": "CUSTOMER", + "refId": "1927081523456789999", + "refName": "王某某", + "openingAmount": -800.00, + "increaseTotal": 0, + "decreaseTotal": 0, + "writeoffTotal": 0, + "adjustTotal": 0, + "netAmount": -800.00 +} +``` + +读法:CUSTOMER 账套净额 -800 = 多收该客户 800,前端标红。 + +### 8.3 业务失败:传未开放账套 STAFF + +请求: + +``` +GET /admin/finance/statements/page?ledgerType=STAFF&page=1&pageSize=20 +``` + +响应: + +```json +{ + "code": 596005, + "message": "账套非法或未开放" +} +``` + +## 9. 业务边界 + +**适用**: +- 管理后台财务查看供应商应付 / 供应商应收 / 客户应收三个账套的期初挂账与(应付侧)流水。 +- 应收侧(SUPPLIER_RECV / CUSTOMER)本期用于查看应收初始化录入的期初余额。 + +**不适用**: +- 员工往来(STAFF)查询——未开放,传了报 596005。 +- 应收账套查业务流水——本期应收侧尚无业务流水入账,明细空页属正常,不要当 bug 报。 + +**特殊边界**: +- 应收账套 `increaseTotal` / `decreaseTotal` / `writeoffTotal` / `adjustTotal` 本期恒 0,`netAmount` 就等于 `openingAmount`(方向见 §5 对照表)。 +- `refId` / `sourceId` 等 ID 字段为 Long 序列化的字符串,前端按字符串处理,不要转 number(防精度丢失)。 + +## 10. 修改前后对比 + +### 字段级对比 + +| 项 | 原来 | 现在 | +|----|------|------| +| 入参 `ledgerType` 取值域 | 仅 `SUPPLIER` 合法,其余报 596005 | `SUPPLIER` / `SUPPLIER_RECV` / `CUSTOMER` 合法;`STAFF` 仍报 596005 | +| 出参 `ledgerType` 实际出现值 | 只会是 `SUPPLIER` | 可能出现 `SUPPLIER_RECV` / `CUSTOMER` | +| 出参 `netAmount` 语义 | 只有应付口径:正 = 我欠他 / 负 = 多付他 | 按账套分化:应付口径不变;应收口径正 = 他欠我 / 负 = 多收他 | +| 出参 `openingAmount` 语义 | 期初应付 − 期初应收(单一口径) | 应付账 = 期初应付 − 期初应收;应收账 = 期初应收 − 期初应付(方向反过来) | + +### 行为级对比 + +| 行为 | 原来 | 现在 | +|------|------|------| +| 传 `ledgerType=CUSTOMER` | 报 596005 | 正常返回客户应收台账 | +| 传 `ledgerType=SUPPLIER_RECV` | 报 596005 | 正常返回供应商应收台账 | +| 应收期初可见性 | 期初挂账在台账页完全看不到 | 切到应收账套即可看到期初净额 | +| SUPPLIER 账套行为 | —— | **完全不变**,老页面无感知 | + +## 11. 影响评估 / 回滚 + +- **破坏兼容**:无。存量 `SUPPLIER` 账套的入参 / 出参 / 符号语义零变化,老前端不改也能跑。 +- **前端同步上线**:非强制。但若要展示应收侧数据,前端需: + 1. 台账页按账套 tab 切换:供应商应付(SUPPLIER)/ 供应商应收(SUPPLIER_RECV)/ 客户应收(CUSTOMER); + 2. 正负含义按 §5 对照表分账套判断,负值标红; + 3. 应收 tab 下明细为空是预期,建议展示「暂无流水」空态而非报错。 +- **回滚方案**:后端回滚 = 恢复原取值域校验(SUPPLIER_RECV/CUSTOMER 重新报 596005);无 DDL、无数据迁移,回滚无副作用。前端若已上 tab,回滚后应收 tab 会收到 596005,需前端同步下掉应收 tab。 + +## 12. 注意事项 + +1. **符号判断别偷懒**:`netAmount > 0` 在不同账套含义相反,前端任何「欠款/多付」文案、标红逻辑都必须先按 `ledgerType` 分支,不要写全局统一判断。 +2. **应收空明细是正常**:SUPPLIER_RECV / CUSTOMER 本期无业务流水,entries 返回空页、`increaseTotal`/`decreaseTotal` 恒 0,不要当缺陷上报。 +3. **STAFF 别放出入口**:员工往来账套未开放,前端不要给 STAFF 的 tab/选项;传了会吃 596005。 +4. **ID 按字符串处理**:`refId` / `sourceId` 是 Long 序列化字符串,转 number 会精度丢失。 +5. 页签展示名建议:SUPPLIER=供应商应付 / SUPPLIER_RECV=供应商应收 / CUSTOMER=客户应收。 + +## 13. 关联 / 联系人 + +- Issue:https://git.1814.love/wx/HL/issues/8719 +- PR:https://git.1814.love/wx/HL/pulls/8727 +- Commit:https://git.1814.love/wx/HL/commit/029000ef1f +- 后端负责人:@yst