Skip to content

关键流程 ​

六条链路覆盖「人怎么进来、租户怎么开、权限怎么判、消息怎么发、代码怎么生、任务怎么跑」。代码位置写成 相对路径#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后续请求带 tokenTokenAuthenticationFilter#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
令牌后续请求 401access 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,消息看邮件/短信日志。
  • 缓存是双刃剑:权限、租户、模板都在缓存里,改完不生效先怀疑缓存,而非代码。