98 行
3.7 KiB
Markdown
98 行
3.7 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7129"
|
||
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 并部署测试服。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<ExpenseCategoryNodeRespVO>`（树形，大类嵌 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）
|