From 89be26b98bd6ddaa86b53fc311dacbe12ca52aba Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 9 Sep 2026 16:14:38 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=B4=A2=E5=8A=A1=E5=9F=9F?= =?UTF-8?q?=20=E5=8F=82=E6=95=B0=E8=AE=BE=E7=BD=AE(#6951)+=E8=B5=84?= =?UTF-8?q?=E9=87=91=E8=B4=A6=E6=88=B7(#7003/#7141)=202=20=E7=AF=87?= =?UTF-8?q?=E5=85=A5=20changelogs-v2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 09_6951_财务系统参数设置：GET/PUT /admin/finance/params 2 端点 - 09_7003_资金账户：10 端点全量（含 #7141 三字段字典化 accountTypeName/natureName/channelName + /options 下拉） Co-Authored-By: Claude Opus 4.8 --- ...6951_财务系统参数设置-新增接口-管理后台.md | 95 ++++++++++ .../09_7003_资金账户-新增接口-管理后台.md | 174 ++++++++++++++++++ 2 files changed, 269 insertions(+) create mode 100644 changelogs-v2/2026-09/09_6951_财务系统参数设置-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-09/09_7003_资金账户-新增接口-管理后台.md diff --git a/changelogs-v2/2026-09/09_6951_财务系统参数设置-新增接口-管理后台.md b/changelogs-v2/2026-09/09_6951_财务系统参数设置-新增接口-管理后台.md new file mode 100644 index 00000000..0e42250a --- /dev/null +++ b/changelogs-v2/2026-09/09_6951_财务系统参数设置-新增接口-管理后台.md @@ -0,0 +1,95 @@ +--- +schema: "hl-changelog/v2" +ticket: "6951" +title: "财务系统参数设置（查询 + 改值）" +consumer: "admin" +author: "yst" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "hl-admin" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-09" +status_note: "后端已合 dev-v3（param 参数设置域）并部署测试服。参数键后端预置不开放增删，仅查询+按键改值，valueType 格式校验。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 财务系统参数设置（查询 + 改值） + +## 1. 接口背景 +财务域「参数设置」：财务侧预置的业务参数（如封账日、限额、开关等），后端预置键不开放增删，管理后台只提供「查询全部 + 按键改值」两个端点。属 Epic 财务域 param 参数设置域。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/params` | 查询全部财务系统参数（不分页，一次返回全量预置键） | +| 新增 | PUT `/admin/finance/params/{paramKey}` | 按参数键修改参数值（valueType 格式校验） | + +## 3. 接口详情 + +### 3.1 查询全部参数 +- **路径**：`GET /admin/finance/params` +- **入参**：无 +- **出参**：`Result>`，元素字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 参数ID（Long 序列化为字符串，防 JS 精度丢失） | +| paramKey | String | 参数键（预置，唯一） | +| paramValue | String | 参数值（字符串存储，按 valueType 解析） | +| valueType | String | 值类型：`DATE` / `BOOL` / `AMOUNT` / `STRING` | +| paramName | String | 参数中文名 | +| remark | String | 口径备注 | +| updatedByName | String | 最近操作人姓名快照 | + +### 3.2 修改参数值 +- **路径**：`PUT /admin/finance/params/{paramKey}` +- **路径参数**：`paramKey`（String，要修改的参数键） +- **入参**（AccountParamUpdateReqVO）： + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| paramValue | String | 是 | 新参数值（按 valueType 校验格式：DATE 须日期格式、BOOL 须 true/false、AMOUNT 须数值） | +| remark | String | 否 | 修改说明 | + +- **出参**：`Result`（返回改后完整参数行） + +## 4. 枚举 / 数据字典 +- `valueType`：`DATE`（日期）/ `BOOL`（布尔）/ `AMOUNT`（金额数值）/ `STRING`（字符串） +- 参数键 paramKey 由后端预置，前端不增删键，仅展示 + 改值。 + +## 5. 错误码 +| 码 | 含义 | +|---|---| +| 598001 | 参数键不存在 | +| 598002 | 参数值与 valueType 格式不符 | + +## 6. 示例 +**典型：查询全部** +``` +GET /admin/finance/params +→ { "code":200, "data":[ {"id":"...","paramKey":"close_day","paramValue":"25","valueType":"DATE","paramName":"封账日","remark":"...","updatedByName":"腰苏图"} ] } +``` +**改值（金额）** +``` +PUT /admin/finance/params/pay_limit {"paramValue":"50000.00","remark":"上调付款限额"} +→ 200，data.paramValue="50000.00" +``` +**异常：值类型不符** +``` +PUT /admin/finance/params/close_day {"paramValue":"abc"} +→ { "code":598002, "msg":"参数值与 valueType 格式不符" } +``` + +## 7. 注意事项 +- 参数键为后端预置集合，PUT 仅改值，不新增/删除键。 +- paramValue 一律字符串传输，前端按 valueType 渲染对应控件（日期/开关/数字输入）。 +- 全部长整型 ID 已序列化为字符串。 + +## 8. 关联 / 联系人 +- Issue：https://git.1814.love:8443/wx/HL/issues/6951 +- Commit：https://git.1814.love:8443/wx/HL/commit/fc87029a68 +- 负责人：腰苏图（yst） diff --git a/changelogs-v2/2026-09/09_7003_资金账户-新增接口-管理后台.md b/changelogs-v2/2026-09/09_7003_资金账户-新增接口-管理后台.md new file mode 100644 index 00000000..4b35247b --- /dev/null +++ b/changelogs-v2/2026-09/09_7003_资金账户-新增接口-管理后台.md @@ -0,0 +1,174 @@ +--- +schema: "hl-changelog/v2" +ticket: "7003" +title: "资金账户（增改停删 + 盘盈盘亏 + 期初调整 + 统计/下拉）" +consumer: "admin" +author: "yst" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "hl-admin" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-09" +status_note: "后端已合 dev-v3（#7003 account 域 + #7146 三字段字典化）并部署测试服；网关实测 E2E 通过。账户类型不可改、基本户唯一不可停用/改性质、有流水仅可停用。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 资金账户 + +## 1. 接口背景 +财务域「资金账户」：公司收付款的资金账户（银行户/现金户/第三方支付户/内部虚拟户）全生命周期管理——建档、编辑、停用、删除、盘盈盘亏、期初结存调整、结存统计、下拉选项。属 Epic 财务域 account 资金账户域（#7003），并经 #7141 三字段字典化增强（type/nature/channel 中文标签 + 下拉）。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/fund-accounts/page` | 账户分页列表（类型/性质/状态/关键词筛选） | +| 新增 | GET `/admin/finance/fund-accounts/stats` | 结存统计（总计/按类型/退款预留预警） | +| 新增 | GET `/admin/finance/fund-accounts/options` | 三组下拉（类型/性质/渠道，字典化） | +| 新增 | POST `/admin/finance/fund-accounts` | 新建账户 | +| 新增 | GET `/admin/finance/fund-accounts/{id}` | 账户详情 | +| 新增 | PUT `/admin/finance/fund-accounts/{id}` | 编辑账户 | +| 新增 | POST `/admin/finance/fund-accounts/{id}/disable` | 停用账户 | +| 新增 | DELETE `/admin/finance/fund-accounts/{id}` | 删除账户（无流水才可删） | +| 新增 | POST `/admin/finance/fund-accounts/{id}/inventory-adjust` | 盘盈盘亏 | +| 新增 | POST `/admin/finance/fund-accounts/{id}/opening-adjust` | 期初结存调整 | + +## 3. 接口详情 + +### 3.1 分页列表 GET /page +入参（Query + 分页）：`accountType`(BANK/CASH/THIRD_PARTY/INTERNAL_VIRTUAL) / `nature`(BASIC/GENERAL) / `status`(ACTIVE/DISABLED) / `keyword`(账号或账户名模糊) / pageNo / pageSize。 + +出参行（FundAccountRowRespVO，Long ID 均 String）： + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 账户ID | +| accountName | String | 账户名称 | +| accountNo | String | 账号（展示层脱敏） | +| bankName | String | 开户行 | +| accountType | String | 账户类型（枚举大写） | +| accountTypeName | String | 账户类型中文名（字典 fin_fund_account_type 标签，字典不可用为 null） | +| nature | String | 账户性质（仅 BANK，其余 null） | +| natureName | String | 性质中文名（字典标签） | +| channel | String | 第三方渠道（仅 THIRD_PARTY，其余 null） | +| channelName | String | 渠道中文名（字典标签） | +| shortName | String | 账户简称 | +| displayName | String | 对外展示名（空则展示账户名称） | +| sortOrder | Integer | 排序（越小越靠前） | +| feeRate | BigDecimal | 手续费率（仅 THIRD_PARTY，如 0.006） | +| refundReserve | BigDecimal | 退款预留额度（仅 THIRD_PARTY） | +| openingBalance | BigDecimal | 期初结存 | +| balance | BigDecimal | 当前结存 | +| currency | String | 币种（默认 CNY） | +| scopeCompanies | String | 适用公司范围 | +| status | String | ACTIVE / DISABLED | + +### 3.2 统计 GET /stats +出参：`totalBalance`（全部生效账户结存总计）/ `byType[]`（accountType + accountTypeName + accountCount + balance）/ `reserveWarnings[]`（余额低于 refundReserve 的三方户：accountId/accountName/当前结存）。 + +### 3.3 下拉 GET /options +出参三组：`accountTypes[]` / `natures[]` / `channels[]`，元素 `OptionItem{value, label, sortOrder}`（value=枚举大写名如 BANK/BASIC/WXPAY，label=中文，sortOrder 升序，仅 ACTIVE）。**账户性质仅 BANK 用、渠道仅 THIRD_PARTY 用**，前端按 accountType 联动展示。 + +### 3.4 新建 POST / +入参（FundAccountCreateReqVO）： + +| 字段 | 必填 | 说明 | +|---|---|---| +| accountName | 是 | 账户名称（全称化口径） | +| accountNo | 是 | 账号（原值入库，展示脱敏） | +| bankName | 否 | 开户行 | +| accountType | 是 | BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL | +| nature | BANK 必填 | BASIC / GENERAL | +| channel | THIRD_PARTY 必填 | WXPAY / ALIPAY | +| settleAccountNo | 否 | 绑定结算卡（仅 THIRD_PARTY，原值入库展示脱敏） | +| refundReserve | 否 | 退款预留额度（仅 THIRD_PARTY，默认 0） | +| shortName | 否 | 账户简称 | +| displayName | 否 | 对外展示名（空则展示账户名称） | +| sortOrder | 否 | 排序（越小越靠前） | +| openingBalance | 否 | 期初结存（默认 0） | +| feeRate | 否 | 手续费率（仅 THIRD_PARTY，如 0.006） | +| overdraftAllowed | 否 | 是否允许透支（布尔） | +| payQrUrl | 否 | 收款码影像 URL（仅 CASH/THIRD_PARTY 收款场景） | +| remark | 否 | 备注 | + +出参：`{id}`（新账户ID，String）。 + +### 3.5 详情 GET /{id} +出参 = Row 全字段 + `settleAccountNo`（结算卡脱敏）/ `overdraftAllowed` / `payQrUrl` / `remark` / `flows[]`（最近资金流水行）。 + +### 3.6 编辑 PUT /{id} +入参同新建（FundAccountUpdateReqVO，accountType 不可改；BASIC 基本户 nature 不可改成其他）。 + +### 3.7 停用 POST /{id}/disable +无入参。唯一基本户不允许停用（595005）；已停用重复停用幂等。 + +### 3.8 删除 DELETE /{id} +有流水账户不可删（595003），仅可停用。 + +### 3.9 盘盈盘亏 POST /{id}/inventory-adjust +入参：`direction`（SURPLUS 盘盈补收 / DEFICIT 盘亏补付，必填）/ `amount`（差额>0，必填）/ `reason`（原因，必填，进留痕）/ `voucherUrl`（佐证影像，选填）。 + +### 3.10 期初调整 POST /{id}/opening-adjust +入参：`newOpeningBalance`（新期初结存≥0，必填；调整后结存=新期初+历史流水净影响）/ `reason`（可空，缺省生成「期初调整 旧→新」）/ `voucherUrl`（选填）。 + +## 4. 枚举 / 数据字典 +| 字段 | 取值 | 字典表 | +|---|---|---| +| accountType | BANK 银行 / CASH 现金 / THIRD_PARTY 第三方支付 / INTERNAL_VIRTUAL 内部虚拟户（预留） | fin_fund_account_type | +| nature | BASIC 基本户 / GENERAL 一般户（仅 BANK） | fin_fund_account_nature | +| channel | WXPAY 微信支付 / ALIPAY 支付宝（仅 THIRD_PARTY） | fin_fund_account_channel | +| status | ACTIVE 生效 / DISABLED 停用 | - | +| direction | SURPLUS 盘盈 / DEFICIT 盘亏 | - | + +字典建在 user-service（部署顺序：先 user-service 后 order-v3）。**建议前端用 `/options` 拉下拉，channel 已彻底字典化（后续加渠道零发版）**。 + +## 5. 错误码（段位 595000-595099） +| 码 | 含义 | +|---|---| +| 595001 | 账户不存在 | +| 595002 | 基本户每公司唯一，已存在其他基本户 | +| 595003 | 有流水账户不可删除，仅可停用 | +| 595004 | 互转两方账户不能相同 | +| 595005 | 唯一基本户不允许停用 | +| 595006 | 账户已停用 | +| 595007 | 账户字段组合不合法（银行户必填账户性质，三方户必填渠道） | +| 595008 | 取现出账账户须为基本户 | +| 595009 | 存取方式无效 | +| 595010 | 存取方式与转出/转入账户类型不匹配 | + +## 6. 示例 +**新建银行基本户** +``` +POST /admin/finance/fund-accounts +{"accountName":"呼伦贝尔XX公司基本户","accountNo":"150XXX","bankName":"中国银行","accountType":"BANK","nature":"BASIC"} +→ 200 {"id":"2097..."} +``` +**三方户缺渠道（异常）** +``` +POST /admin/finance/fund-accounts {"accountName":"微信商户","accountNo":"...","accountType":"THIRD_PARTY"} +→ 595007 账户字段组合不合法 +``` +**删除有流水账户（异常）** +``` +DELETE /admin/finance/fund-accounts/{id} → 595003 有流水账户不可删除，仅可停用 +``` +**盘盈** +``` +POST /admin/finance/fund-accounts/{id}/inventory-adjust +{"direction":"SURPLUS","amount":100.00,"reason":"盘点溢余"} +→ 200 +``` + +## 7. 注意事项 +- 账号/结算卡**原值入库、展示层脱敏**，出参 accountNo 为脱敏值。 +- 全部长整型 ID 序列化为字符串。 +- 账户类型不可改；基本户唯一且不可停用/不可改性质。 +- 删除仅限无流水账户，有流水走停用。 + +## 8. 关联 / 联系人 +- Issue：https://git.1814.love:8443/wx/HL/issues/7003 ｜ 字典化增强 #7141（PR https://git.1814.love:8443/wx/HL/pulls/7146） +- Commit：https://git.1814.love:8443/wx/HL/commit/b46269a4d4 +- 负责人：腰苏图（yst）