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