---
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）