From 3a866393c82229f54c83409a1812a896010c72fe Mon Sep 17 00:00:00 2001 From: halo Date: Thu, 9 Jul 2026 15:54:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=9F=BA=E7=A1=80?= =?UTF-8?q?=E9=85=8D=E7=BD=AE=E6=8E=A5=E5=8F=A3=E7=AB=A0=E8=8A=82(?= =?UTF-8?q?=E6=A0=B8=E5=BF=83=E4=BC=81=E4=B8=9A/=E5=AE=A2=E6=88=B7?= =?UTF-8?q?=E7=BB=8F=E7=90=86)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 缺失的后端接口.md | 145 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 144 insertions(+), 1 deletion(-) diff --git a/缺失的后端接口.md b/缺失的后端接口.md index 17e94ed..b1bd396 100644 --- a/缺失的后端接口.md +++ b/缺失的后端接口.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。 + +业务规则:本阶段客户经理删除不做引用检查。