SFT/缺失的后端接口.md

缺失的后端接口 / 真实接口契约说明

更新说明:阶段1(工程基础设施+登录+系统管理)与阶段2(基础配置:核心企业/客户经理)原先按前端自 行设计的契约用 mock-server/ 模拟开发。现后端已提供首版真实接口(swagger_project_scfs_2026-07- 09_14-15-23.json),前端已完成对接改造,不再使用 mock 契约。本文档改为:Part 1 速查已对接的 真实接口契约(便于前后端联调核对);Part 2 列出联调/开发中发现的、后端文档未覆盖或建议后续 补充的事项。mock-server/ 保留作无后端环境下的应急本地演示兜底,契约与下文不一致,不作为参考。

通用约定(均已通过真实 swagger 核实):

• 所有接口返回统一包裹结构 { code: number, message: string, data: any },code === 200 表示业务成功, 前端统一按 code !== 200 判断失败并展示 message,不再做具体错误码分支处理。
• 除登录、刷新令牌、发送短信外,其余接口均需在请求头携带 Authorization: Bearer {token}。
• 日期时间字段格式统一为 yyyy-MM-dd HH:mm:ss。
• 分页查询接口(.../page)请求 Body 均含 page(从1开始)、pageSize;响应 data 统一为 { total, page, pageSize, records: [...] }(字段名为 records,不是 list)。
• 除个别接口(见下文标注)外,增删改接口均为单条操作,不提供批量接口。

Part 1:已提供接口契约速查

1.1 通用鉴权

接口	说明
POST /api/auth/login-password	账号密码登录,Body {username, password},响应 LoginVo
POST /api/auth/login-phone	手机验证码登录,Body {phone, smsCode},响应 LoginVo
POST /api/auth/send-sms-code	发送短信验证码,Body {phone, businessType},登录场景前端暂传 businessType: 'LOGIN'(见 Part 2-1)
POST /api/auth/refresh-token	刷新令牌,无 Body,依赖 httpOnly Cookie 中的 refresh_token(不携带 Authorization 头),响应 LoginVo
POST /api/auth/logout	登出,无 Body
POST /api/auth/user-info	获取当前用户信息,无 Body(基于当前 JWT),响应 UserDetailVo
GET /api/auth/user/permission-detail?userId=	获取用户扁平权限列表 UserPermissionDetailVo[],前端自行 buildTreeFromFlat/extractMenuTree/extractButtonCodes
POST /api/auth/change-password	修改密码,Body {oldPassword, newPassword}(首次登录强制改密场景复用)
POST /api/user/reset-password	管理员重置用户密码,Body {userId}
POST /api/auth/reset-password	找回密码场景(未接入前端,登记备查),Body {phone, smsCode, newPassword}

LoginVo 字段:{ token, username, realName, userId, phone, userType, organizationId, forceChangePwd }。

1.2 系统管理 —— 用户

接口	Body/Query	说明
POST /api/auth/user/page	{organizationId, usernameLike, phone, status(ACTIVE|LOCKED), roleId, page, pageSize}	响应 records: UserPageVo[](含 organizationName/roleNameList,不含 roleIds/createdAt)
POST /api/auth/user/create	{username, phone, realName, organizationId, status, email, userRoleBtoList:[{roleId}]}	响应 CreateUserVo{id,status},不返回初始密码
POST /api/user/update	{id, username, phone, realName, organizationId, email, userRoleBtoList:[{userId,roleId}]}
POST /api/user/delete	{userId}	单条
POST /api/user/lock / POST /api/user/unlock	{userId}
GET /api/auth/user-role/list-by-user?userId=	—	响应 UserRoleVo[]{id(即roleId), roleName, organizationId, isBuiltIn},用于编辑用户时回填已选角色
POST /api/auth/user-role/bind / unbind	{userId, roleIdList}	独立接口,当前未使用(create/update 已内嵌 userRoleBtoList)

1.3 系统管理 —— 角色

接口	Body	说明
POST /api/role/page	{roleName, page, pageSize}	不支持按机构/状态过滤,响应 records: RoleVo[]
POST /api/role/detail	{roleId}	响应 RoleDetailVo{roleName,id,organizationId,isBuiltIn,permissionIdList}
POST /api/role/create	{roleName, organizationId, isBuiltIn}	不含权限,不返回新建 id(见 Part 2-2)
POST /api/role/update	{id, roleName, organizationId}	不含权限
POST /api/role/delete	{roleId}	单条
GET /api/auth/role-permission/list-by-role?roleId=	—	响应 RolePermissionVo[]
POST /api/auth/role-permission/bind / unbind	{roleId, permissionIdList}	前端采用"查旧集合→diff→分别 bind/unbind"策略

角色模型不含数据权限范围(dataScope)字段。

1.4 系统管理 —— 权限字典

接口	Body	说明
GET /api/permission/tree	—	响应嵌套树 PermissionTreeVo[],顶级 level=0
POST /api/permission/create	{permissionType(PAGE|BUTTON), permissionName, permissionCode, parentId, level, sortOrder, icon, routePath, pageResourcePaths[], apiResourcePaths[]}	响应 {id, permissionCode}
POST /api/permission/update	同上,不含 permissionType
POST /api/permission/delete	{id}

1.5 系统管理 —— 机构

接口	Body/Query	说明
GET /api/organization/query-tree	{organizationName?, organizationId?}	响应嵌套树 OrganizationTreeNodeVo[],不传筛选参数时返回全树
GET /api/organization/list-all	{organizationName?}	响应扁平 OrganizationSimpleVo[],用于表单"所属机构"下拉
POST /api/organization/create	{organizationName, parentId, remark}	parentId 为数字(引用上级机构的数字 id),响应完整 OrganizationDetailVo
POST /api/organization/update	{organizationId(字符串), organizationName, parentId, remark}	注意:定位字段是字符串业务码 organizationId,不是数字 id
POST /api/organization/delete	{organizationId(字符串)}	同上,响应 data 为 boolean

机构模型关键点:id(数字主键,供 parentId/用户/角色/核心企业/客户经理的 organizationId 外键引用)与 organizationId(字符串业务码,仅用于机构自身 update/delete 定位及 query-tree 筛选参数)是两个不同字段, 同时存在于同一条机构记录上。/api/organization/tree(POST,无筛选参数的全量树)与 query-tree 功能重叠, 前端统一只使用 query-tree。

1.6 基础配置 —— 核心企业 / 客户经理

接口	Body	说明
POST /api/core-enterprise/page	{page, pageSize, enterpriseName}	仅支持企业名称模糊搜索,响应 records: CoreEnterpriseVo[]
POST /api/core-enterprise/create / update / delete	见 CreateCoreEnterpriseBto/UpdateCoreEnterpriseBto(字段:enterpriseCode/enterpriseName/businessLicense/organizationId/contactPerson/contactPhone/status(ACTIVE|INACTIVE)/remark);delete Body {id}
POST /api/customer-manager/page	{page, pageSize, managerName}	仅支持姓名模糊搜索,响应 records: CustomerManagerVo[]
POST /api/customer-manager/create / update / delete	字段:managerCode/managerName/mobilePhone/organizationId/department/status(ACTIVE|INACTIVE)/remark;delete Body {id}

核心企业、客户经理模型均不含 organizationName,前端本地通过 organization/list-all 建 id→name 映射 展示所属机构列。

1.7 客户管理 —— 个人客户

接口	说明
POST /api/customer-info/personal/list	{organizationIdEq,customerCodeEq,customerNameLike,certificateNumberEq,page,pageSize},响应 records: IndividualCustomerListVo[](仅 id,organizationId,customerName,certificateType,certificateNumber,mobilePhone,ocrStatus,customerCode,不含性别/创建人/创建时间)
POST /api/customer-info/personal/detail	{id} 或 {customerCode},响应 IndividualCustomerDetailVo
POST /api/customer-info/personal/create	CreateIndividualCustomerBto,响应 data=新建id
POST /api/customer-info/personal/update	UpdateIndividualCustomerBto
POST /api/customer-info/personal/ocr-idcard	{fileBase64,channelNo,fileType('01'|'02')},响应 OcrIdCardResultVo
POST /api/customer-info/personal/upload-file	{fileBase64,channelNo},响应 {fileNo},个人身份证与企业营业执照图片均调用此通用接口

1.8 客户管理 —— 企业客户

接口	说明
POST /api/enterprise-customer/page	{page,pageSize,enterpriseName,businessLicense,mobilePhone},响应 records: EnterpriseCustomerVo[]
POST /api/enterprise-customer/detail	{id},响应 EnterpriseCustomerDetailVo
POST /api/enterprise-customer/create	{createEnterpriseCustomerBto,enableOcr}
POST /api/enterprise-customer/update	UpdateEnterpriseCustomerBto

---

Part 2:待后端确认 / 建议补充事项

1. send-sms-code 的 businessType 取值无 enum 文档:swagger 仅标注为普通 string,登录场景前端暂定 传 'LOGIN',需后端确认合法取值枚举(找回密码场景描述提到 FIND_PASSWORD,登录场景取值待确认)。
2. POST /api/role/create 不返回新建记录 id:前端已改为"创建成功后按 roleName+organizationId 反查 role/page 取得 id 再绑定权限"规避,建议后端补充直接返回新建 id(core-enterprise/create、 customer-manager/create 同样不返回新建 id,当前无需立即二次操作故不阻塞,但建议一并补充以保持接口 一致性)。
3. 批量删除接口缺失:用户、角色、机构、核心企业、客户经理的删除接口均为单条,前端已改为循环调用 单条删除接口模拟批量交互(src/utils/loopDelete.js),建议后端评估是否补充原子性 batch 接口。
4. 管理员直接为其他用户指定新密码(无需旧密码)的接口不存在:原型图中的"密码修改"入口暂保留但 置灰禁用,提示改用"密码重置"。
5. user/create、user/reset-password 是否已实际发送短信通知用户,新密码规则(固定值/随机)未文档化: 前端仅按约定展示"已通过短信通知用户"提示文案,不做实际校验。
6. role-permission/bind/unbind 的语义(全量替换 vs 增量追加)未在 swagger 说明:前端已按"先查旧 集合、计算 diff、分别调用 bind(新增项)/unbind(移除项)"的保守策略实现,不受该语义影响,但建议 后端在文档中明确。
7. 角色列表(role/page)不支持按所属机构过滤;核心企业、客户经理列表只支持单一名称模糊搜索: 相比原前端自行设计的契约,过滤能力收窄,搜索表单已同步精简,若后续产品侧需要更多筛选维度,需后端 评估补充查询参数。
8. 角色数据权限范围(本机构/本机构及下级/全部)字段在真实模型中不存在:若产品侧仍需要该能力,需 后端评估补充。
9. 用户列表/详情不返回 roleIds:编辑用户角色时需额外调用 user-role/list-by-user,建议后端在 UserPageVo/UserDetailVo 中直接补充 roleIdList 以减少一次请求。
10. 权限字典种子数据需部署后手动初始化:用户/角色/机构/权限/核心企业/客户经理各页面与按钮节点, 需部署后通过新的"系统管理 > 权限管理"页面手动创建,并授予内置管理员角色,否则登录后看不到任何 菜单。当前 MainLayout.vue 菜单渲染只支持两级,初始化菜单节点时层级需控制在 2 级以内。
11. /api/auth/reset-password(找回密码)与登录页暂未接入:当前登录页仅实现"账号密码"与"手机验证码" 两种登录方式,找回密码入口未在本次范围内开发,契约已在 Part 1-1 登记备查。
12. 个人客户/企业客户均无删除接口:列表页暂不提供删除入口。
13. 营业执照无同步OCR识别接口:enterprise-customer/create 的 enableOcr 参数用途/时序未文档化, 前端按"手动填写+提交时告知后端可异步识别"实现。
14. 企业客户股东高管信息(enterpriseRelatedPersonBtoList)只能在新增时一次性提交:update/detail 接口均不支持读取或修改,编辑模式下该区块前端替换为提示文案,不可编辑。
15. 企业客户 businessLicenseFileNo 编辑/详情接口读取不到:编辑模式无法回显已上传的营业执照图片。
16. 企业客户分页查询不支持按所属机构/企业编号过滤:仅支持企业名称/营业执照号/手机号三项。
17. 个人客户 customerCode(客户编号)生成机制未文档化:前端创建时不传该字段,交由后端生成。
18. 身份证/营业执照 OCR 结果字段命名未在 swagger 明确标注(OcrIdCardResultVo 具体字段以实测为准), 前端 mapOcrIdCardResult 按常见字段名(name/sex/nation/idcard/address/authority/birth/validDate) 做防御性映射,识别失败或字段缺失时不阻断提交,允许手动填写。
19. 移动端确认页(个人开户 mobile/*、企业开户 confirm、贷款申请确认扫码后续)不属于本项目范围: 相关接口已在后端提供但本次前端管理后台不实现对应移动端页面,登记备查。