diff --git a/changelogs-v2/2026-09/09_6951_财务账期设置-新增接口-管理后台.md b/changelogs-v2/2026-09/09_6951_财务账期设置-新增接口-管理后台.md new file mode 100644 index 00000000..ebd66075 --- /dev/null +++ b/changelogs-v2/2026-09/09_6951_财务账期设置-新增接口-管理后台.md @@ -0,0 +1,100 @@ +--- +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 参数设置域)并部署测试服。首期起始日任选;非首期须紧接上期;同时最多一个开账期。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 财务账期设置 + +## 1. 接口背景 +财务域「账期」:财务核算的会计期间。同一时间最多一个开账期,封账后进入下一期。属财务域 param 参数设置域。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/account-periods/page` | 账期分页列表 | +| 新增 | POST `/admin/finance/account-periods` | 开新账期 | +| 新增 | POST `/admin/finance/account-periods/{id}/close` | 封账 | + +## 3. 接口详情 + +### 3.1 分页列表 GET /page +入参(Query + 分页):`isClosed`(0 开着 / 1 已封账,空=全部)/ pageNo / pageSize。 + +出参行(AccountPeriodRowRespVO,Long ID 序列化为 String): + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 账期ID | +| periodName | String | 账期名称 | +| startDate | String | 起始日(yyyy-MM-dd) | +| endDate | String | 截止日(yyyy-MM-dd,开账中为 null) | +| isClosed | Integer | 0 开着 / 1 已封账 | +| closedByName | String | 封账操作人姓名 | +| closedTime | String | 封账时间(yyyy-MM-dd HH:mm:ss) | + +### 3.2 开新账期 POST / +入参(AccountPeriodCreateReqVO): + +| 字段 | 必填 | 说明 | +|---|---|---| +| periodName | 是 | 账期名称(≤50 字) | +| startDate | 是 | 起始日(yyyy-MM-dd;须为上期截止日的次日,首期任选) | + +出参:`{id}`(新账期ID,String)。 + +### 3.3 封账 POST /{id}/close +入参(AccountPeriodCloseReqVO,可空 body):`endDate`(可选,缺省=该账期起始日所在月的月末)。 + +## 4. 枚举 / 数据字典 +- `isClosed`:0 开着 / 1 已封账 + +## 5. 错误码(段位 598100-598199) +| 码 | 含义 | +|---|---| +| 598101 | 账期不存在 | +| 598102 | 账期已封账 | +| 598103 | 存在未封账的旧账期,请先封账 | +| 598104 | 账期起始日与现有账期重叠或更早 | +| 598105 | 账期起始日须为上期截止日的次日 | +| 598106 | 账期截止日不能早于起始日 | + +## 6. 示例 +**开新账期(紧接上期)** +``` +POST /admin/finance/account-periods {"periodName":"2026-09期","startDate":"2026-09-01"} +→ 200 {"id":"2097..."} +``` +**封账(缺省月末)** +``` +POST /admin/finance/account-periods/{id}/close {} +→ 200 +``` +**起始日不紧接上期(异常)** +``` +POST /admin/finance/account-periods {"periodName":"X","startDate":"2026-09-05"} +→ 598105 账期起始日须为上期截止日的次日 +``` + +## 7. 注意事项 +- 首期账期起始日任选;之后每期必须紧接上期截止日次日。 +- 同时最多一个开账期;封账后才能开下一期。 +- 长整型 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..ffe32279 --- /dev/null +++ b/changelogs-v2/2026-09/09_7003_收款账户-新增接口-管理后台.md @@ -0,0 +1,117 @@ +--- +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(account 资金账户域)并部署测试服。设默认/停用独立端点;设默认排他(同收款方其余自动降 0)。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 收款账户 + +## 1. 接口背景 +财务域「收款账户」:各类收款方(司导/员工、车队、导游公司、供应商)的收款方式档案(微信/支付宝收款码、银行卡、对公账户)。供付款、报销等场景选择收款对象账户。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/payee-accounts/page` | 收款账户分页 | +| 新增 | POST `/admin/finance/payee-accounts` | 新增收款账户 | +| 新增 | PUT `/admin/finance/payee-accounts/{id}` | 编辑 | +| 新增 | POST `/admin/finance/payee-accounts/{id}/set-default` | 设为默认(排他) | +| 新增 | POST `/admin/finance/payee-accounts/{id}/disable` | 停用(软删) | + +## 3. 接口详情 + +### 3.1 分页 GET /page +入参(Query + 分页,均可选):`payeeType` / `payeeName`(模糊)/ `accountType` / pageNo / pageSize。 + +出参行(PayeeAccountRowRespVO,Long ID 序列化为 String): + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 账户ID | +| payeeType | String | 收款方类型 | +| payeeRefId | String | 收款方关联ID(弱关联快照,可空) | +| payeeName | String | 收款方名称 | +| accountType | String | 账户类型 | +| qrUrl | String | 收款码影像 URL | +| bankAccount | String | 银行账号(展示层脱敏) | +| bankName | String | 开户行 | +| isDefault | Integer | 0 否 / 1 是(同收款方默认唯一) | + +### 3.2 新增 POST / +入参(PayeeAccountCreateReqVO): + +| 字段 | 必填 | 说明 | +|---|---|---| +| payeeType | 是 | STAFF / FLEET / GUIDE_CO / SUPPLIER | +| payeeRefId | 否 | 收款方关联ID(弱关联快照) | +| payeeName | 是 | 收款方名称(≤100) | +| accountType | 是 | WECHAT_QR / ALIPAY_QR / BANK_CARD / CORP_ACCOUNT | +| qrUrl | 否 | 收款码影像(≤500,收款码类用) | +| bankAccount | 银行卡/对公必填 | 银行账号(≤64;BANK_CARD/CORP_ACCOUNT 必填否则 595202) | +| bankName | 否 | 开户行(≤100) | +| isDefault | 否 | 默认 0;置 1 时同收款方原默认自动降 0 | + +出参 `{id}`。 + +### 3.3 编辑 PUT /{id} +入参均可选:`payeeName` / `accountType` / `qrUrl` / `bankAccount` / `bankName`。 + +### 3.4 设默认 POST /{id}/set-default +本账户置默认(isDefault=1),**同收款方其余账户自动降为 0**(默认排他,先降后升)。 + +### 3.5 停用 POST /{id}/disable +软删该收款账户。 + +## 4. 枚举 / 数据字典 +| 字段 | 取值 | +|---|---| +| payeeType | STAFF 司导/员工个人 / FLEET 车队 / GUIDE_CO 导游公司 / SUPPLIER 供应商(预留) | +| accountType | WECHAT_QR 微信收款码 / ALIPAY_QR 支付宝收款码 / BANK_CARD 银行卡 / CORP_ACCOUNT 对公账户 | +| isDefault | 0 否 / 1 是 | + +## 5. 错误码(段位 595200-595299) +| 码 | 含义 | +|---|---| +| 595201 | 收款方账户不存在 | +| 595202 | 收款方账户字段组合不合法(银行卡/对公账户必填账号) | + +## 6. 示例 +**新增银行卡收款账户** +``` +POST /admin/finance/payee-accounts +{"payeeType":"STAFF","payeeName":"张三","accountType":"BANK_CARD","bankAccount":"622XXX","bankName":"工商银行","isDefault":1} +→ 200 {"id":"2097..."} +``` +**银行卡缺账号(异常)** +``` +POST /admin/finance/payee-accounts {"payeeType":"STAFF","payeeName":"张三","accountType":"BANK_CARD"} +→ 595202 收款方账户字段组合不合法 +``` +**设默认** +``` +POST /admin/finance/payee-accounts/{id}/set-default → 200(同收款方其余自动降 0) +``` + +## 7. 注意事项 +- 同一收款方默认账户唯一;设默认会自动取消原默认。 +- 银行卡/对公账户必须填 bankAccount;收款码类填 qrUrl。 +- 银行账号原值入库、展示层脱敏。 +- 长整型 ID 序列化为字符串。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7003 +- Commit:https://git.1814.love:8443/wx/HL/commit/b46269a4d4 +- 负责人:腰苏图(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..8a326fa1 --- /dev/null +++ b/changelogs-v2/2026-09/09_7003_资金互转-新增接口-管理后台.md @@ -0,0 +1,120 @@ +--- +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(account 资金账户域)并部署测试服。双边成对记账(一转出一入账);幂等键防重复提交;不收转入金额(转出净减 amount+fee、转入净加 amount)。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 资金互转 + +## 1. 接口背景 +财务域「资金互转」:公司各资金账户间划转(银行取现、现金存银行、三方提现、账户互转等)。一次互转双边成对记账(转出户一笔 OUT、转入户一笔 IN,共享 transferGroupId)。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/fund-transfers/page` | 互转记录分页(按 transferGroupId 成对聚合) | +| 新增 | POST `/admin/finance/fund-transfers` | 发起互转(幂等) | + +## 3. 接口详情 + +### 3.1 分页 GET /page +入参(Query + 分页,均可选):`fromAccountId` / `toAccountId` / `mode` / `operatorName`(精确)/ `flowAtStart` / `flowAtEnd`(按 transferDate 过滤)/ pageNo / pageSize。 + +出参行(FundTransferRowRespVO,一转出一入账聚合成一行,Long ID 序列化为 String): + +| 字段 | 类型 | 说明 | +|---|---|---| +| transferGroupId | String | 互转组ID | +| mode | String | 存取方式 | +| fromAccountId / fromAccountName | String | 转出账户 | +| toAccountId / toAccountName | String | 转入账户 | +| transferDate | String | 业务日期(yyyy-MM-dd,可回溯补录) | +| amount | BigDecimal | 转出金额(转入实收同额) | +| fee | BigDecimal | 手续费(挂转出行) | +| outFlowId / inFlowId | String | 转出/入账流水ID | +| voucherUrl | String | 佐证影像 | +| flowAt | String | 落账时刻 | +| handlerName / operatorName | String | 经手人 / 经办人 | +| status | String | 恒 COMPLETED(本期无审批/撤销) | + +### 3.2 发起互转 POST / +**幂等**:`@Idempotent`,key=`fromAccountId:toAccountId:amount`,5 秒内重复提交返回「互转提交处理中,请勿重复提交」。 + +入参(FundTransferReqVO): + +| 字段 | 必填 | 说明 | +|---|---|---| +| mode | 是 | 存取方式(见枚举) | +| fromAccountId | 是 | 转出账户ID | +| toAccountId | 是 | 转入账户ID(不得与转出相同) | +| amount | 是 | 转出金额(>0) | +| fee | 否 | 手续费(≥0,默认 0,挂转出行) | +| transferDate | 是 | 业务日期(可回溯补录) | +| handlerName | 否 | 经手人(≤50) | +| voucherUrl | 否 | 佐证影像(≤500) | +| remark | 否 | 备注(≤200) | + +**口径**:不收转入金额——转出户净减 `amount+fee`、转入户净加 `amount`。 + +出参(FundTransferRespVO):`transferGroupId` / `outFlowId` / `inFlowId` / `fromBalanceAfter` / `toBalanceAfter`。 + +## 4. 枚举 / 数据字典 +| 字段 | 取值 | +|---|---| +| mode | BANK2CASH 银行取现金 / CASH2BANK 现金存银行 / THIRD2BANK 三方提现到银行 / BANK2THIRD 银行转三方 / BANK2BANK 银行转银行 / CASH2CASH 现金转现金 | +| status | COMPLETED(恒值,本期无审批/撤销) | + +## 5. 错误码 +| 码 | 含义 | +|---|---| +| 595001 | 账户不存在 | +| 595004 | 互转两方账户不能相同 | +| 595006 | 账户已停用 | +| 595008 | 取现出账账户须为基本户 | +| 595009 | 存取方式无效 | +| 595010 | 存取方式与转出/转入账户类型不匹配 | +| 595102 | 金额无效(须大于0) | +| 595103 | 余额不足且不允许透支 | +| 595104 | 资金写入并发冲突,请重试 | + +## 6. 示例 +**银行取现** +``` +POST /admin/finance/fund-transfers +{"mode":"BANK2CASH","fromAccountId":"2097...","toAccountId":"2098...","amount":5000.00,"transferDate":"2026-09-09","handlerName":"李四"} +→ 200 {"transferGroupId":"...","outFlowId":"...","inFlowId":"...","fromBalanceAfter":...,"toBalanceAfter":...} +``` +**两方同账户(异常)** +``` +POST /admin/finance/fund-transfers {"mode":"BANK2BANK","fromAccountId":"X","toAccountId":"X","amount":100,"transferDate":"2026-09-09"} +→ 595004 互转两方账户不能相同 +``` +**5 秒内重复提交(幂等拦截)** +``` +(同 fromAccountId:toAccountId:amount 再次 POST) +→ 互转提交处理中,请勿重复提交 +``` + +## 7. 注意事项 +- 互转即付即完成(status 恒 COMPLETED),无审批/撤销。 +- 银行取现(BANK2CASH)出账账户须为基本户(595008)。 +- 手续费 fee 只挂转出行,转入户实收=amount。 +- 长整型 ID 序列化为字符串。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7003 +- Commit:https://git.1814.love:8443/wx/HL/commit/b46269a4d4 +- 负责人:腰苏图(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..d073bd7c --- /dev/null +++ b/changelogs-v2/2026-09/09_7003_资金日报-新增接口-管理后台.md @@ -0,0 +1,100 @@ +--- +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(account 资金账户域)并部署测试服。closing=opening+收入−支出勾稽;收支聚合排除期初调整留痕流水。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 资金日报 + +## 1. 接口背景 +财务域「资金日报」:按账户(或全部账户汇总)统计某日期区间的收入/支出/结余,并给出逐日明细。用于财务每日资金看板。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/fund-stats/daily` | 资金日报(区间收支 + 逐日结余) | + +## 3. 接口详情 + +### 3.1 资金日报 GET /daily +入参(Query): + +| 字段 | 必填 | 说明 | +|---|---|---| +| accountId | 否 | 资金账户ID;空=全部账户汇总(全账户口径下互转双边计入) | +| startDate | 是 | 起始日(yyyy-MM-dd,含当日) | +| endDate | 是 | 截止日(yyyy-MM-dd,含当日) | + +出参(FundDailyStatsRespVO): + +| 字段 | 类型 | 说明 | +|---|---|---| +| openingBalance | BigDecimal | 期初结转(=当前结存−起点以来流水净影响) | +| priorIncome | BigDecimal | 起始日前累计收入 | +| priorExpense | BigDecimal | 起始日前累计支出 | +| totalIncome | BigDecimal | 区间总收入 | +| totalExpense | BigDecimal | 区间总支出 | +| closingBalance | BigDecimal | 期末结存 = openingBalance + totalIncome − totalExpense | +| days | Array | 逐日明细(仅有流水的日期,日期升序) | + +**days 行(DayRow)**: + +| 字段 | 类型 | 说明 | +|---|---|---| +| date | String | 日期(yyyy-MM-dd) | +| income | BigDecimal | 当日收入 | +| expense | BigDecimal | 当日支出 | +| dayNet | BigDecimal | 当日净额(income−expense) | +| runningBalance | BigDecimal | 累计结余(自期初结转逐日累加) | + +**口径**:收支聚合**排除** biz_type=OPENING 留痕流水(期初调整是重定基准,非业务收支)。 + +## 4. 枚举 / 数据字典 +无(数值统计)。 + +## 5. 错误码(段位 595300-595399) +| 码 | 含义 | +|---|---| +| 595301 | 账户不存在 | +| 595302 | 日期区间非法(起始日不能晚于截止日) | +| 595303 | 日期区间跨度超限(最长 366 天) | + +## 6. 示例 +**全账户 9 月日报** +``` +GET /admin/finance/fund-stats/daily?startDate=2026-09-01&endDate=2026-09-09 +→ 200 {"openingBalance":12000.00,"totalIncome":8000.00,"totalExpense":5000.00,"closingBalance":15000.00,"days":[{"date":"2026-09-03","income":5000.00,"expense":0,"dayNet":5000.00,"runningBalance":17000.00},...]} +``` +**单账户日报** +``` +GET /admin/finance/fund-stats/daily?accountId=2097...&startDate=2026-09-01&endDate=2026-09-09 +→ 200 {...} +``` +**区间非法(异常)** +``` +GET /admin/finance/fund-stats/daily?startDate=2026-09-09&endDate=2026-09-01 +→ 595302 日期区间非法 +``` + +## 7. 注意事项 +- 勾稽关系:closingBalance = openingBalance + totalIncome − totalExpense。 +- 逐日 days 仅含有流水的日期(无流水日期不返回,前端可自行补零)。 +- 期初调整流水不计入收支(避免重定基准被算成收支)。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7003 +- Commit:https://git.1814.love:8443/wx/HL/commit/b46269a4d4 +- 负责人:腰苏图(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..60b69a71 --- /dev/null +++ b/changelogs-v2/2026-09/09_7003_资金流水-新增接口-管理后台.md @@ -0,0 +1,95 @@ +--- +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(account 资金账户域)并部署测试服。只读;balanceAfter 勾稽;列表行+详情补 remark 字段(#7133)。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 资金流水 + +## 1. 接口背景 +财务域「资金流水」:资金账户每笔出入账的流水记录(只读)。来源包括付款、预付、报销、收款、业务外、互转、盘盈盘亏、期初调整等。本期列表行与详情补充 remark 字段(互转备注/盘盈盘亏/期初调整原因,#7133)。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/fund-flows/page` | 流水分页(flowAt 倒序) | +| 新增 | GET `/admin/finance/fund-flows/{id}` | 流水详情 | + +## 3. 接口详情 + +### 3.1 分页 GET /page +入参(Query + 分页,均可选):`fundAccountId` / `accountType` / `direction` / `bizType` / `flowNo`(模糊)/ `flowAtStart` / `flowAtEnd`(yyyy-MM-dd)/ pageNo / pageSize。 + +出参行(FundFlowRowRespVO,Long ID 序列化为 String): + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 流水ID | +| flowNo | String | 流水号(日期前缀) | +| fundAccountId | String | 资金账户ID | +| accountName | String | 账户名称 | +| accountType | String | 账户类型 | +| direction | String | OUT 出 / IN 入 | +| amount | BigDecimal | 金额 | +| bizType | String | 业务类型 | +| bizId | String | 业务单据ID(可空) | +| bizNo | String | 业务单号(手写动作 TRANSFER/INVENTORY/OPENING 恒为 null) | +| balanceAfter | BigDecimal | 本笔记完后结存快照(勾稽) | +| transferGroupId | String | 互转组ID(仅 TRANSFER) | +| fee | BigDecimal | 手续费(仅 TRANSFER,挂转出行) | +| counterparty | String | 对方账户/往来(脱敏) | +| flowAt | String | 记账时间(yyyy-MM-dd HH:mm:ss) | +| voucherUrl | String | 佐证影像 | +| remark | String | 备注(互转备注/盘盈盘亏/期初调整原因) | + +### 3.2 详情 GET /{id} +出参 = 行全字段 + `pairedFlowId`(互转对侧流水ID,仅 TRANSFER)+ `operatorName`(经办人)。 + +## 4. 枚举 / 数据字典 +| 字段 | 取值 | +|---|---| +| accountType | BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL | +| direction | OUT 出账 / IN 入账 | +| bizType | PAYMENT 付款 / PREPAY 预付 / EXPENSE 费用 / REIMBURSE 报销 / RECEIPT 收款 / STAFF_LOAN 员工借款 / COMPANY_LOAN 公司借款 / NONBIZ 业务外 / ADVANCE 预支 / TRANSFER 互转 / ORDER_PAY 订单支付 / INVENTORY 盘盈盘亏 / OPENING 期初调整 | + +## 5. 错误码(段位 595100-595199) +| 码 | 含义 | +|---|---| +| 595101 | 流水不存在(查询路径仅见此码) | +| 595102-595106 | 写入侧(金额无效/余额不足/并发冲突/期初调整非法/盘盈盘亏方向无效),查询不触发 | + +## 6. 示例 +**按账户+方向查** +``` +GET /admin/finance/fund-flows/page?fundAccountId=2097...&direction=OUT&pageNo=1&pageSize=20 +→ 200 {"records":[{"flowNo":"LS20260909...","direction":"OUT","amount":100.00,"balanceAfter":4900.00,"bizType":"PAYMENT",...}],"total":N} +``` +**详情(互转带对侧)** +``` +GET /admin/finance/fund-flows/{id} +→ 200 {..., "bizType":"TRANSFER","transferGroupId":"...","pairedFlowId":"...","remark":"银行取现"} +``` + +## 7. 注意事项 +- 流水只读,无新增/修改/删除端点(由业务动作产生)。 +- balanceAfter 为该笔记完后的结存快照,可用于逐笔勾稽。 +- 手写动作(互转/盘盈盘亏/期初)无关联业务单号,bizNo 为 null。 +- 长整型 ID 序列化为字符串。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7003 | remark 出参 #7133 +- Commit:https://git.1814.love:8443/wx/HL/commit/b46269a4d4 +- 负责人:腰苏图(yst) diff --git a/changelogs-v2/2026-09/09_7052_业务外收支分类-新增接口-管理后台.md b/changelogs-v2/2026-09/09_7052_业务外收支分类-新增接口-管理后台.md new file mode 100644 index 00000000..ae2f319c --- /dev/null +++ b/changelogs-v2/2026-09/09_7052_业务外收支分类-新增接口-管理后台.md @@ -0,0 +1,96 @@ +--- +schema: "hl-changelog/v2" +ticket: "7052" +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 并部署测试服。新增 code 留空后端自动生码(NONBIZ_ 前缀,#7052);按方向组各自一套含已停用;停用/启用幂等。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 业务外收支分类 + +## 1. 接口背景 +财务域「业务外收支分类」:与旅游主业无关的其他收入/支出归类(如房租、工资、理财收益等),按方向(IN 收入 / OUT 支出)各成一套。用于业务外流水(nonbiz)归集。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/nonbiz-categories` | 按方向查分类列表(含已停用) | +| 新增 | POST `/admin/finance/nonbiz-categories` | 新增分类(code 可留空自动生码) | +| 新增 | PUT `/admin/finance/nonbiz-categories/{code}` | 改名称/排序 | +| 新增 | POST `/admin/finance/nonbiz-categories/{code}/disable` | 停用(幂等) | +| 新增 | POST `/admin/finance/nonbiz-categories/{code}/enable` | 启用(幂等) | + +## 3. 接口详情 + +### 3.1 查询 GET / +入参(Query):`direction` 必填:`IN` 收入组 / `OUT` 支出组。返回该方向组全部分类(含已停用)。 + +出参 `List`: + +| 字段 | 类型 | 说明 | +|---|---|---| +| code | String | 类别码(如 AGENT_SALARY;业务主键) | +| name | String | 分类名 | +| direction | String | IN / OUT | +| status | String | NORMAL / DISABLED | +| sort | Integer | 排序 | + +### 3.2 新增 POST / +入参:`direction`(必填 IN/OUT)/ `code`(可选 ≤50;**留空后端自动生码** `NONBIZ_` 前缀全局唯一)/ `name`(必填 ≤50)/ `sort`(缺省 0)。 + +出参:`Result`,data=最终落库的类别码(自动生码时返回生成值)。 + +### 3.3 改 PUT /{code} +入参:`name`(必填 ≤50)/ `sort`。(code 建后不可改;历史单据快照不追溯。) + +### 3.4 / 3.5 停用 / 启用 +`POST /{code}/disable`、`POST /{code}/enable`,均幂等。 + +## 4. 枚举 / 数据字典 +- `direction`:IN 收入 / OUT 支出 +- `status`:NORMAL 正常 / DISABLED 停用 + +## 5. 错误码(段位 598200-598299) +| 码 | 含义 | +|---|---| +| 598201 | 类别码已存在(code 全局唯一,创建跨方向查重;自动生码序号耗尽同码) | +| 598202 | 类别不存在 | +| 598203 | 方向组非法,须为 IN 或 OUT | + +## 6. 示例 +**新增(自动生码)** +``` +POST /admin/finance/nonbiz-categories {"direction":"OUT","name":"办公室租金"} +→ 200 data="NONBIZ_7"(自动生成的类别码) +``` +**新增(指定 code 撞码,异常)** +``` +POST /admin/finance/nonbiz-categories {"direction":"IN","code":"RENT","name":"租金"} +→ 598201 类别码已存在(即使 RENT 在 OUT 组已存在也报) +``` +**查询支出组** +``` +GET /admin/finance/nonbiz-categories?direction=OUT +→ 200 [{"code":"RENT","name":"租金","direction":"OUT","status":"NORMAL","sort":0},...] +``` + +## 7. 注意事项 +- code 全局唯一(跨方向),创建时后端跨方向查重。 +- code 建后不可改;前端展示以 name 为准。 +- 推荐新增时留空 code 走自动生码。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7052(自动生码) +- Commit:https://git.1814.love:8443/wx/HL/commit/fc87029a68 +- 负责人:腰苏图(yst) diff --git a/changelogs-v2/2026-09/09_7129_费用分类-新增接口-管理后台.md b/changelogs-v2/2026-09/09_7129_费用分类-新增接口-管理后台.md new file mode 100644 index 00000000..c4794fcb --- /dev/null +++ b/changelogs-v2/2026-09/09_7129_费用分类-新增接口-管理后台.md @@ -0,0 +1,97 @@ +--- +schema: "hl-changelog/v2" +ticket: "7129" +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 并部署测试服。status 统一 DISABLED(#7129);重复停用/启用改幂等成功;停用大类级联停用末级、启用不级联。" +updated_at: "2026-09-09" +base: "dev-v3" +--- + +# 费用分类(业务内) + +## 1. 接口背景 +财务域「费用分类」(业务内支出分类):两级树(大类 level=1 → 末级 level=2),供费用报销等业务归集。本期统一状态枚举为 DISABLED,停用/启用幂等化。 + +## 2. 变更清单 +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | GET `/admin/finance/expense-categories/tree` | 分类树(status 筛选) | +| 新增 | POST `/admin/finance/expense-categories` | 新增分类(大类或末级) | +| 新增 | PUT `/admin/finance/expense-categories/{id}` | 改名称/排序 | +| 新增 | POST `/admin/finance/expense-categories/{id}/disable` | 停用(幂等,大类级联停用末级) | +| 新增 | POST `/admin/finance/expense-categories/{id}/enable` | 启用(幂等,不级联) | + +## 3. 接口详情 + +### 3.1 分类树 GET /tree +入参(Query):`status` 可选:`NORMAL`(默认,只出正常)/ `DISABLED` / `ALL`;其他值 → 598303。 + +出参 `List`(树形,大类嵌 children): + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | String | 分类ID | +| parentId | String | 父类ID(大类为 null) | +| level | Integer | 1 大类 / 2 末级 | +| name | String | 分类名 | +| sort | Integer | 排序 | +| status | String | NORMAL / DISABLED | +| children | Array | 末级列表(仅大类行有,空数组非 null) | + +### 3.2 新增 POST / +入参:`parentId`(可选;空=新增大类 level=1,填=新增末级 level=2)/ `name`(必填,≤50 字)/ `sort`(可选默认 0)。出参 `{id}`。 + +### 3.3 改 PUT /{id} +入参:`name`(必填 ≤50)/ `sort`。(历史单据名称快照不追溯。) + +### 3.4 停用 /{id}/disable +幂等(已 DISABLED 直接成功);**停用大类级联停用其全部末级**。 + +### 3.5 启用 /{id}/enable +幂等(DISABLED→NORMAL,已正常直接成功);**启用大类不级联启用末级**(末级需单独启用)。 + +## 4. 枚举 / 数据字典 +- `status`:NORMAL 正常 / DISABLED 停用(原 CANCELLED 已统一为 DISABLED) + +## 5. 错误码(段位 598300-598399) +| 码 | 含义 | +|---|---| +| 598301 | 分类不存在 | +| 598302 | 分类名已存在(大类名全局唯一;末级名大类内唯一) | +| 598303 | 分类当前状态不允许此操作(含非法 status 参数) | +| 598304 | 所属大类不存在或非法 | + +## 6. 示例 +**新增末级** +``` +POST /admin/finance/expense-categories {"parentId":"2097...","name":"市内交通","sort":1} +→ 200 {"id":"2098..."} +``` +**停用大类(级联停用末级)** +``` +POST /admin/finance/expense-categories/{id}/disable → 200 +``` +**重复停用(幂等)** +``` +POST /admin/finance/expense-categories/{id}/disable → 200(再次调用仍成功) +``` + +## 7. 注意事项 +- 停用大类会级联停用末级;启用大类**不**级联(末级单独启用)。 +- 重复停用/启用返回 200 幂等成功,不再报 598303。 +- 长整型 ID 序列化为字符串。 + +## 8. 关联 / 联系人 +- Issue:https://git.1814.love:8443/wx/HL/issues/7129(统一 DISABLED) +- Commit:https://git.1814.love:8443/wx/HL/commit/fc87029a68 +- 负责人:腰苏图(yst)