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 映射 展示所属机构列。

---

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 登记备查。