03-接口设计

项目：ERP-CRM ｜ 版本：v1.1 ｜ 生成日期：2026-10-05 ｜ 依据：源码分析（v1.1：2026-10-06 一致性回刷，与 16-20 篇对齐）

1. API 总体风格与约定

后端共 45 个 @RestController（含登录/注册/公共上传两个无前缀 Controller），接口为 RuoYi 风格的 REST-ish 设计：路径按"业务域/资源/动作"三层组织，列表 GET /xxx/list、详情 GET /xxx/{id}、新增 POST /xxx、修改 PUT /xxx、删除 DELETE /xxx/{ids}、导出 POST /xxx/export、特殊动作用动词子路径（如 PUT /erp/stock/stock-in/{id}、PUT /erp/transfer/execute/{id}、POST /crm/approval/submit/{contractId}）。接口文档由 springdoc 自动生成，开发期访问 http://localhost:9090/swagger-ui/index.html（application.yml springdoc 段；prod 激活时 EcProdConfigVerifier 强制 springdoc.api-docs.enabled=false）。

全局约定（前后端共同遵守的"隐形协议"，代码依据标注在括号内）：

1. 每个请求必须携带 tenant 请求头——TenantInterceptor 对一切路径生效，缺失即抛"请求缺少租户信息"。前端 utils/request.js 从 cookie 自动注入。
2. 认证走 Authorization: Bearer <JWT>——JwtAuthenticationTokenFilter 解析后从 Redis login_tokens:{uuid} 取 LoginUser。
3. 响应包裹统一为 {code, msg, ...}——成功 code=200；列表额外带 rows/total（TableDataInfo）；单体数据在 data 键（AjaxResult.success(data)）。
4. 401 是"HTTP 200 + body code 401"——AuthenticationEntryPointImpl + ServletUtils.renderString（response.setStatus(200) 硬编码）；403 才是真 HTTP 语义之外的 body code（GlobalExceptionHandler 返回 AjaxResult.error(403, "没有权限，请联系管理员授权")，HTTP 仍 200）。
5. 分页参数 pageNum/pageSize（query）——PageUtils.startPage() 从请求参数取，pageSize 被钳制 ≤500；响应 total 为 PageHelper 统计的全量行数。
6. 错误消息可直接展示——业务校验失败一律抛 ServiceException，GlobalExceptionHandler 将其 message 原样放入 msg（如"仅待入库状态的采购单可执行入库"）。
7. 写接口默认带操作日志与防重——@Log(title, businessType) 异步落 sys_oper_log；@RepeatSubmit + 前端 1 秒窗口防重复提交。
8. 上传下载——POST /common/upload（multipart，单文件 10MB/请求 20MB 上限，扩展名白名单 MimeTypeUtils）与 GET /common/download、GET /common/download/resource；上传产物经 /profile/** 匿名直出（SecurityConfig GET 放行）。

2. API 端点总表

以下按 Controller 归组列出全部主要端点（"库"列标注该接口数据落在主库 MASTER 还是当前租户库 TENANT；通用 CRUD 五件套以 "CRUD" 缩写表示 list/get/POST/PUT/DELETE）。

2.1 认证与平台

2.2 系统管理（租户库，RuoYi 标准）

2.3 监控审计

2.4 CRM（租户库）

2.5 ERP（租户库）

2.6 AI 知识库（租户库）

3. 认证鉴权机制

认证时序（SysLoginService.login，erp-crm/src/main/java/com/ec/auth/web/service/SysLoginService.java）：

1. 查主库校验租户存在/未停用/未过期（finally 中恢复当前租户数据源键）；
2. 检查 Redis 锁定键 pwd_lock_time:{tenant}:{username}——命中则报"密码错误次数过多，账号已锁定，请约 N 分钟后再试"；
3. AuthenticationManager.authenticate → UserDetailsServiceImpl.loadUserByUsername 查当前租户库 sys_user（BCrypt 比对）；
4. 密码错（BadCredentialsException）则计数 pwd_err_cnt:{tenant}:{username}（10 分钟窗口），累计 5 次写锁定键并清计数；
5. 成功后清计数、异步记录登录日志（AsyncManager + AsyncFactory.recordLogininfor）、更新登录 IP/时间，TokenService.createToken 签发 JWT。

令牌结构：JWT（HS512，密钥 EC_TOKEN_SECRET ≥64 字节）payload 仅含 login_user_key（随机 UUID）与 login_tenant_key（租户名）；真实会话对象 LoginUser 存 Redis login_tokens:{uuid}，TTL=token.expireTime（120 分钟）。JwtAuthenticationTokenFilter 每请求解析 JWT→取 Redis→verifyToken 判断剩余有效期 ≤20 分钟则滑动续期（TokenService.MILLIS_MINUTE_TEN）。JWT 被盗用无法单独作废，但 Redis 键删除即可强制下线（监控-在线用户页即此原理）。

鉴权模型：接口级 @PreAuthorize("@ss.hasPermi('crm:customer:add')")（PermissionService 比对 LoginUser.permissions）；数据级 @DataScope（按角色配置拼 dept_id in (...) SQL 片段）；行级归属校验在 service 显式编码（客户转移/公海/删除均含 owner 判定）。菜单权限的"源头"是租户库 sys_menu.perms 列，角色-菜单经 sys_role_menu 关联。

4. 错误处理与响应码约定

GlobalExceptionHandler（auth/web/exception/GlobalExceptionHandler.java）统一兜底，全部返回 HTTP 200 + 业务码：

前端 utils/errorHandler.js 的 resolveApiMessage/notifyApiError/promptRelogin 按同一套业务码映射提示行为；utils/errorCode.js 保有 code→默认文案表。

5. 核心接口示例

5.1 登录 POST /login

请求（tenant 头必须；body 字段与 LoginBody 一一对应）：

POST /login HTTP/1.1
Content-Type: application/json;charset=utf-8
tenant: tenant1

{ "username": "admin", "password": "admin123" }

成功响应（SysLoginController.login：ajax.put(Constants.TOKEN, token)）：

{ "msg": "操作成功", "code": 200, "token": "eyJhbGciOiJIUzUxMiJ9..." }

失败响应示例（密码错误 3 次时，SysLoginService 第 148 行）：

{ "msg": "用户名或密码错误，还可尝试 2 次", "code": 500 }

内置逻辑：IP 限流（30 次/分，@RateLimiter(limitType = LimitType.IP, time = 60, count = 30)）→ 租户状态校验 → 锁定检查 → AuthenticationManager 认证（租户库 sys_user）→ 计数/锁定 → 签发 JWT + Redis 会话；成功与失败均打点 erp.login.total{tenant,result}（ErpMetrics.login）。

5.2 采购入库 PUT /erp/stock/stock-in/{id}

请求：

PUT /erp/stock/stock-in/13 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
tenant: tenant1

处理链（ErpStockOrderServiceImpl.stockIn，erp-crm/src/main/java/com/ec/erp/service/impl/ErpStockOrderServiceImpl.java 第 105-135 行）：① 采购单存在性校验；② warehouseId 非空校验（"采购单未指定入库仓库，请先补充仓库信息"）；③ 明细非空校验；④ CAS 认领 claimForStockIn(id)（UPDATE erp_stock_order SET status='1' WHERE id=? AND status='0'，返回 0 即抛"仅待入库状态的采购单可执行入库"）；⑤ 按明细逐条写 erp_storage_flow（type=1 入库、带 warehouse_id 与订单号备注）。整个方法 @Transactional，任一步失败全部回滚。响应：

{ "msg": "操作成功", "code": 200 }

5.3 列表查询 GET /crm/customer/list（分页契约）

请求：GET /crm/customer/list?pageNum=1&pageSize=10&name=华&customerRank=1。处理：startPage() → PageHelper 拦截 SQL 拼 LIMIT → TableDataInfo：

{ "total": 42, "rows": [ { "id": 1, "name": "华信集团", "linkman": "王总", "phone": "13800000000", "region": "华东", "customerRank": "1", "customerStatus": "1", "owner": "admin", "lastFollowupTime": "2026-09-30 10:12:00" } ], "code": 200, "msg": "查询成功" }

前端 useTable 直接消费 rows/total；导出则将同样查询条件 POST 到 /crm/customer/export 返回 xlsx blob（ExcelUtil 按 @Excel 注解列头）。

6. 接口一致性清单（维护提示）

• 新增模块时按 gen_business_modules.py 的 controller 模板补齐五件套端点，并同步在租户模板库 sys_menu 加菜单与按钮权限（参照 db-backup/upgrade_business_modules.sql 末段的 INSERT INTO sys_menu/sys_role_menu 写法），否则前端页面拿不到菜单与 v-hasPermi 权限串。
• 所有新接口必须显式声明 @PreAuthorize；未声明则仅要求登录（authenticated），任何租户内用户均可调用。
• 主库类接口（租户管理、套餐）注意 @DataSource(MASTER) 已封装在 saas service 层，web 层不要自行切换数据源。
• Flowable 相关接口的入参 taskId 是引擎任务 ID（UUID 字符串）而非 crm_approval.id，两者不可混用（CrmApprovalController.getInfo 的 {id} 传任务 ID）。