主题
关键流程
六条链路覆盖「人怎么进来、租户怎么开、权限怎么判、消息怎么发、代码怎么生、任务怎么跑」。代码位置写成
相对路径#L行号,只标已核实的位置;接口路径省略/admin-api前缀(该前缀由pmforge.web.admin-api配置决定)。
1. 登录认证
触发:用户在管理端输入账号密码,或 App 端用手机号 + 短信验证码登录。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 提交登录 | POST /system/auth/login → pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/auth/AuthController.java#L66 |
| 2 | 图形验证码校验(可开关) | AdminAuthServiceImpl#L105 → #L201-L210;pmforge.captcha.enable=false 时直接通过 #L203 |
| 3 | 查用户、比对密码 | AdminAuthServiceImpl#L81-L96:不存在/密码错 → BAD_CREDENTIALS 并写登录日志 #L86-L87;禁用则拒绝 #L94-L96 |
| 4 | 社交账号绑定(按需) | AdminAuthServiceImpl#L111-L113 |
| 5 | 签发令牌 | #L212-L220:写登录日志 #L214 → OAuth2TokenServiceImpl#L63(先建 refresh,再建 access) |
| 6 | 后续请求带 token | TokenAuthenticationFilter#L71-L73 解析并校验,把 LoginUser 放进上下文 #L58 |
| 7 | 刷新 / 登出 | POST /system/auth/refresh-token(AuthController#L85,OAuth2TokenServiceImpl#L73);POST /system/auth/logout(#L73,removeAccessToken#L144) |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 验证码 | AUTH_LOGIN_CAPTCHA_CODE_ERROR | 验证码过期、Redis 未连通、captcha.enable 与前端不一致 |
| 凭证 | BAD_CREDENTIALS | 用户不存在或密码错;注意两者返回一致,避免撞库探测 |
| 账号状态 | 登录被拒 | 用户 status 被禁用 AdminAuthServiceImpl#L94-L96 |
| 令牌 | 后续请求 401 | access token 过期未刷新;refresh 无效时 OAuth2TokenServiceImpl#L77 直接失败 |
2. 租户开通与套餐生效
触发:平台管理员新建一个租户,或在套餐里增删菜单。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 建套餐(选菜单) | POST /system/tenant-package/create(TenantPackageController#L35,system:tenant-package:create) |
| 2 | 建租户 | POST /system/tenant/create(TenantController#L78,system:tenant:create)→ TenantServiceImpl#L100,@DSTransactional + 关闭数据权限 |
| 3 | 唯一性与套餐校验 | TenantServiceImpl#L102、#L104、#L106(→ TenantPackageServiceImpl#L117) |
| 4 | 初始化管理员角色 | TenantServiceImpl#L131-L138:tenant_admin 角色 + 绑定套餐 menuIds |
| 5 | 初始化管理员账号 | TenantServiceImpl#L123-L127:建用户并 assignUserRole |
| 6 | 套餐变更同步 | PUT /system/tenant-package/update → TenantPackageServiceImpl#L63-L65 遍历在用租户 → TenantServiceImpl#L194 重算角色菜单 |
| 7 | 每次请求校验租户 | TenantSecurityWebFilter#L97 → TenantServiceImpl#L84(不存在 / 停用 / 过期三种错误) |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 套餐 | TENANT_PACKAGE_NOT_EXISTS / TENANT_PACKAGE_DISABLE | 套餐被删或停用 TenantPackageServiceImpl#L120、#L123 |
| 重复 | 名称/域名冲突 | 唯一性校验 TenantServiceImpl#L102、#L104 |
| 裁剪 | 自定义角色菜单变少 | #L194 起:管理员角色直接重设,其他角色取交集(CollUtil.intersectionDistinct) |
| 缓存 | 续期后仍提示过期 | TenantFrameworkServiceImpl#L43 用 LoadingCache 缓存了「无效租户」异常,需等缓存刷新 |
3. 角色授权与权限校验
触发:租户管理员建角色、勾菜单、分配用户;随后用户访问某个接口。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 维护菜单与权限点 | SYS-PERM-01;menu.permission 形如 system:role:create |
| 2 | 建角色并设数据权限 | POST /system/role/create(RoleController#L42,system:role:create) |
| 3 | 角色-菜单 | POST /system/permission/assign-role-menu(PermissionController#L41)→ PermissionServiceImpl#L141 |
| 4 | 用户-角色 | POST /system/permission/assign-user-role(#L70)→ PermissionServiceImpl#L208 |
| 5 | 接口鉴权 | @PreAuthorize("@ss.hasPermission('...')") → SecurityFrameworkServiceImpl#L30 → PermissionServiceImpl#L63 |
| 6 | 权限点判定 | PermissionServiceImpl#L93-L106:权限点 → 菜单 ID → 拥有该菜单的角色 → 与用户角色求交集 |
| 7 | 数据权限 | @DataPermission + role.dataScope → PermissionServiceImpl#L271、#L277 |
| 8 | 前端拿菜单 | GET /system/auth/get-permission-info(AuthController#L93),过滤禁用角色与菜单 #L109、#L114 |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 权限点写错 | 有菜单仍 403 | 菜单里的 permission 与注解字符串不一致,查不到菜单 ID 即判无权限 #L94-L106 |
| 缓存 | 改完菜单不生效 | permission_menu_ids 等缓存(application.yaml 的 tenant.ignore-caches 列出 9 项)未清 |
| 角色禁用 | 权限突然消失 | 只加载启用角色 #L70;前端菜单也过滤禁用角色 AuthController#L109 |
| 超管 | 测试环境「怎么都能过」 | PermissionServiceImpl#L83 对 super_admin 直接放行 |
4. 消息通知投递(站内信 / 邮件 / 短信)
触发:业务代码调用发送服务;或运维在模板页手工发一条。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 站内信入口 | NotifySendServiceImpl#L35(发给管理员)/ #L40(发给会员)/ #L57(落 system_notify_message) |
| 2 | 模板校验 | #L47 读缓存;模板被禁用时直接返回 null,不发也不报错 #L48-L51 |
| 3 | 参数校验 | #L53:缺参抛 NOTIFY_SEND_TEMPLATE_PARAM_MISS;渲染 #L56 |
| 4 | 邮件发送 | MailSendServiceImpl#L58:模板 #L146、账号 #L157、收件人过滤 #L74-L85、先落日志 #L94、投递 MQ #L98 |
| 5 | 邮件异步执行 | #L121 → MailUtil.send#L127 → 回写成功/失败 #L130、#L133 |
| 6 | 短信发送 | SmsSendServiceImpl#L81:模板/渠道/手机号校验 → 落日志 #L97 → 投递 #L101 → 通道发送 #L158、#L164 |
| 7 | 短信回执 | SmsSendServiceImpl#L177;回调入口 SmsCallbackController#L26(阿里云)、#L36(腾讯云)、#L47(华为云)、#L56(七牛) |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 静默失败 | 什么都没发生 | 模板 status 非启用,NotifySendServiceImpl#L48-L51 直接返回 |
| 邮件 | MAIL_SEND_MAIL_NOT_EXISTS | 收件人邮箱为空或格式非法 MailSendServiceImpl#L87 |
| 短信 | 渠道报错 | 余额、签名、模板未报备,属第三方;日志里有 EXCEPTION 占位 |
| 异步 | 接口成功但没收到 | MQ 未连通或消费失败。本仓 MQ 底座是 Redis:RedisMQTemplate 的 channel 模式(Pub/Sub,广播、不重试)与 stream 模式(消费组 + pending 重投);RabbitMQ 只有 Jackson2JsonMessageConverter 一个 Bean,没有队列声明;RocketMQ/Kafka 只提供租户相关 hook |
5. 代码生成闭环
触发:开发者要为新表生成一套 CRUD 骨架。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 选表 | GET /infra/codegen/db/table/list(CodegenController#L49,infra:codegen:query) |
| 2 | 导入表结构 | POST /infra/codegen/create-list(#L93)→ CodegenServiceImpl#L70、#L84 |
| 3 | 配字段与模板 | PUT /infra/codegen/update(#L100);模板类型含单表 / 树表 / 主子表 |
| 4 | 同步表变更 | PUT /infra/codegen/sync-from-db(#L108)→ CodegenServiceImpl#L157 |
| 5 | 预览 | GET /infra/codegen/preview(#L135)→ generationCodes#L261,主子表会额外加载子表并校验 subJoinColumnId #L275-L286 |
| 6 | 下载 | GET /infra/codegen/download(#L144)→ CodegenEngine#L374、#L411,模板表见 #L69(后端)与 #L108(前端) |
| 7 | 人工接管 | 拷入模块 → 改 Service/Controller → 建菜单权限点 → 补 SQL 与文档 |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 主子表 | 预览/下载报错 | 子表未绑定或 subJoinColumnId 未选 #L286 |
| 注释 | 生成的类没有注释 | 表与字段缺 comment,生成器无内容可填 |
| 路径 | 文件落到错误包 | pmforge.codegen.base-package 与模块实际包名不一致(application.yaml) |
| 前端 | 只有后端代码 | 前端模板在 CodegenEngine#L108,但仓库没有前端工程可落 |
6. 定时任务调度
触发:infra_job 里的任务按 cron 到点执行,或管理员手动触发。
| # | 动作 | 接口 / 代码 |
|---|---|---|
| 1 | 写处理器 | 实现 pmforge-framework/pmforge-spring-boot-starter-job/src/main/java/com/pmforge/framework/quartz/core/handler/JobHandler.java#L17 的 String execute(String param),@Component 的 Bean 名即 handlerName(示例 JobLogCleanJob) |
| 2 | 建任务 | POST /infra/job/create(JobController#L44,infra:job:create)→ JobServiceImpl#L47:cron 校验 #L48、handler 唯一 #L50、处理器存在性 #L54/#L94 |
| 3 | 注册到 Quartz | #L63 → SchedulerManager#L40;成功后置为 NORMAL #L66 |
| 4 | 执行 | JobHandlerInvoker#L54 先建日志 → 调用 execute → 异常捕获 #L57 → 回写耗时与结果 #L62、#L76-L87 |
| 5 | 管理动作 | 暂停/恢复 PUT /infra/job/update-status(#L61);手动触发 PUT /infra/job/trigger(#L94);同步 POST /infra/job/sync(#L103,先删再建 #L142-L159) |
| 6 | 本地禁用 | application-local.yaml#L10 排除 QuartzAutoConfiguration → SchedulerManager 以 null 构造 → 任何调度操作抛「定时任务 - 已禁用」SchedulerManager#L143-L147 |
| 失败点 | 现象 | 原因 |
|---|---|---|
| 处理器 | 建任务时报错 | handlerName 与 Spring Bean 名不一致,或 Bean 未实现 JobHandler #L94 |
| cron | 保存被拒 | 表达式非法 JobServiceImpl#L193 |
| 执行 | 任务不跑 | local profile 默认禁用;或任务状态是 STOP(暂停) |
| 日志 | 表越来越大 | 依赖 JobLogCleanJob 清理 14 天前日志(#L25、#L30),该任务本身也要被调度 |
7. 共性
- 所有链路都依赖租户上下文:不带租户的请求要么被
TenantSecurityWebFilter拒绝,要么落到全局表。 - 失败信息优先看日志表:登录失败看
SYS-LOG-01,接口异常看INF-LOG-02,任务失败看INF-JOB-02,消息看邮件/短信日志。 - 缓存是双刃剑:权限、租户、模板都在缓存里,改完不生效先怀疑缓存,而非代码。