docs: 新增基础配置接口章节(核心企业/客户经理)

缺失的后端接口.md

@@ -1,6 +1,6 @@
 # 缺失的后端接口
 
-> 说明:本项目前端已按下述接口契约完成开发,并使用 `mock-server/`(开发期专用、不作为交付物)完整模拟了 8.1 通用鉴权 与 8.3 系统管理 共 18 个接口用于本地验证;8.2 基础通用能力共 5 个接口在阶段 1 暂无实际消费页面(将在后续"授信管理""钱包管理"等阶段接入),此处先登记契约供后端团队提前评估。
+> 说明:本项目前端已按下述接口契约完成开发,并使用 `mock-server/`(开发期专用、不作为交付物)完整模拟了 8.1 通用鉴权、8.3 系统管理、8.4 基础配置 共 26 个接口用于本地验证;8.2 基础通用能力共 5 个接口在阶段 1 暂无实际消费页面(将在后续"授信管理""钱包管理"等阶段接入),此处先登记契约供后端团队提前评估。
 >
 > 通用约定:
 > - 所有接口返回统一包裹结构 `{ "code": number, "msg": string, "data": any }`,`code === 200` 表示业务成功,其余为业务错误码(本文档中列出的错误码均为 mock-server 已实现的示例编码,后端可自行编排,前端仅依赖 `code !== 200` 判断失败并展示 `msg`)。
@@ -374,3 +374,146 @@
 - **已知限制**:业务需求文档中"存在已关联核心企业时禁止删除机构"的规则,阶段2引入核心企业(渠道)模块后仍**暂未实现**该项校验(设计阶段已与产品侧确认本阶段不做,待后续阶段评估是否补充)。
 
 可能的业务错误码:机构名称为空(40004)、上级机构无效(40004)、同上级下机构名重复(40005)、上级机构选择了自身或下级(40006)、一级机构不可删除(40007,现体现为批量删除响应中的 failed 项)、存在下级机构不可删除(40008,现体现为批量删除响应中的 failed 项)、已关联用户不可删除(40009,现体现为批量删除响应中的 failed 项)。
+
+---
+
+## 8.4 基础配置接口
+
+### 24. 核心企业列表查询
+
+`GET /base-config/channel/list`
+
+查询参数:
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| orgId | string | 否 | 所属机构 ID,精确匹配 |
+| channelCode | string | 否 | 渠道编号,模糊匹配 |
+| channelName | string | 否 | 渠道名称,模糊匹配 |
+| page | number | 否 | 页码,默认 1 |
+| pageSize | number | 否 | 每页条数,默认 10 |
+
+响应 `data`:`{ list: ChannelItem[], total: number }`,`ChannelItem` 字段:
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | string | 核心企业 ID |
+| name | string | 渠道名称 |
+| channelCode | string | 渠道编号(不做唯一性校验) |
+| appCode | string | 应用编号 |
+| motherAccountBank | string | 母户开户行 |
+| orgId | string | 所属机构 ID |
+| orgName | string | 所属机构名称 |
+| createdAt | string | 创建时间 |
+
+### 25. 新增核心企业
+
+`POST /base-config/channel`
+
+请求参数(Body):
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| name | string | 是 | 渠道名称 |
+| channelCode | string | 是 | 渠道编号,不做唯一性强制校验 |
+| appCode | string | 是 | 应用编号 |
+| motherAccountBank | string | 是 | 母户开户行 |
+| orgId | string | 是 | 所属机构 ID,需为有效机构 |
+
+响应 `data`:新增后的 `ChannelItem`。
+
+可能的业务错误码:渠道名称为空(40025)、渠道编号为空(40026)、应用编号为空(40027)、母户开户行为空(40028)、所属机构无效(40029)。
+
+### 26. 修改核心企业
+
+`PUT /base-config/channel/{id}`
+
+请求参数(Body):同新增,`{ name, channelCode, appCode, motherAccountBank, orgId }`。
+
+响应 `data`:修改后的 `ChannelItem`;校验规则同新增。目标核心企业不存在时返回 `40404`。
+
+### 27. 批量删除核心企业
+
+`DELETE /base-config/channel/batch`
+
+请求参数(Body):`{ ids: string[] }`(至少 1 项)
+
+响应 `data`:
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| successIds | string[] | 删除成功的核心企业 ID 列表 |
+| failed | array | 删除失败项,元素结构 `{ id, name, reason }` |
+
+`code` 始终为 200,部分/全部业务失败通过 `data.failed` 体现。可能的失败原因(`failed[].reason`):核心企业不存在。`ids` 为空数组时返回业务错误码 40024。
+
+业务规则:本阶段核心企业删除不校验其他模块(如授信、支付)对该核心企业的引用(设计阶段已确认本阶段不做,待后续阶段评估是否补充)。
+
+### 28. 客户经理列表查询
+
+`GET /base-config/manager/list`
+
+查询参数:
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| orgCode | string | 否 | 机构号,模糊匹配 |
+| orgName | string | 否 | 机构名称,模糊匹配 |
+| name | string | 否 | 客户经理姓名,模糊匹配 |
+| jobNumber | string | 否 | 工号,模糊匹配 |
+| page | number | 否 | 页码,默认 1 |
+| pageSize | number | 否 | 每页条数,默认 10 |
+
+响应 `data`:`{ list: ManagerItem[], total: number }`,`ManagerItem` 字段:
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | string | 客户经理 ID |
+| orgCode | string | 机构号(自由文本,不关联机构树) |
+| orgName | string | 机构名称(自由文本,不关联机构树) |
+| jobNumber | string | 工号,全局唯一 |
+| name | string | 客户经理姓名 |
+
+> 前端列表查询无结果时(仅在用户主动点击"查询"触发,页面初次加载不触发)提示"客户经理不存在"。
+
+### 29. 新增客户经理
+
+`POST /base-config/manager`
+
+请求参数(Body):
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| orgCode | string | 是 | 机构号,自由文本 |
+| orgName | string | 是 | 机构名称,自由文本 |
+| jobNumber | string | 是 | 工号,全局唯一 |
+| name | string | 是 | 客户经理姓名 |
+
+响应 `data`:新增后的 `ManagerItem`。
+
+可能的业务错误码:机构号为空(40030)、机构名称为空(40031)、工号为空(40032)、客户经理姓名为空(40033)、工号已存在(40034)。
+
+### 30. 修改客户经理
+
+`PUT /base-config/manager/{id}`
+
+请求参数(Body):同新增,`{ orgCode, orgName, jobNumber, name }`。
+
+响应 `data`:修改后的 `ManagerItem`;校验规则同新增(工号唯一性校验排除自身)。目标客户经理不存在时返回 `40404`。
+
+### 31. 批量删除客户经理
+
+`DELETE /base-config/manager/batch`
+
+请求参数(Body):`{ ids: string[] }`(至少 1 项)
+
+响应 `data`:
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| successIds | string[] | 删除成功的客户经理 ID 列表 |
+| failed | array | 删除失败项,元素结构 `{ id, name, reason }` |
+
+`code` 始终为 200,部分/全部业务失败通过 `data.failed` 体现。可能的失败原因(`failed[].reason`):客户经理不存在。`ids` 为空数组时返回业务错误码 40024。
+
+业务规则:本阶段客户经理删除不做引用检查。