97 行
3.6 KiB
Markdown
97 行
3.6 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7052"
|
||
title: "业务外收支分类（查询 + 增改 + 停用/启用）"
|
||
consumer: "admin"
|
||
author: "yst"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "21540997"
|
||
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<NonbizCategoryRespVO>`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| 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<String>`，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）
|