Skip to content

系统管理模块(pmforge-module-system) ​

规模:35 个 Controller、212 个接口、89 个唯一权限点、32 张表、462 个 Java 文件(模块目录全量,含 src/test)、27 张功能卡。

1. 职责与边界 ​

系统管理回答两个问题:你是谁(认证)、你能做什么(授权),并把多租户、组织、字典、消息、日志这些「平台底座」一起收在这一模块。

负责不负责
登录/登出/刷新令牌、图形与短信验证码、社交登录、OAuth2 客户端业务数据的增删改查(会员、订单、流程)
管理员、角色、菜单、按钮权限标识、数据权限范围前端页面与交互(pmforge-ui)
部门/岗位、租户/租户套餐、字典、地区文件存储、代码生成、定时任务(在 infra)
站内信/公告/邮件/短信的模板、发送、日志具体业务通知的触发时机(由各业务模块调用)
登录日志、操作日志链路追踪、指标监控(framework monitor starter)

模块对外有三类入口:/admin-api/system/**(管理后台)、/app-api/system/**(App 端基础数据)、/system/sms/callback/{渠道}(短信回调,免登录)。

2. 规模与口径 ​

指标数值统计方法
Controller35@RestController 类数(与 接口索引 一致)
接口199@GetMapping/@PostMapping/@PutMapping/@DeleteMapping 方法注解数
唯一权限点89生成物中 @PreAuthorize 权限标识去重
表32数据索引 的 system_* 表
Java 文件462模块目录 Get-ChildItem -Recurse -Filter *.java
跨模块 API14api/**/*Api.java:AdminUserApi、DeptApi、DictDataApi、SmsCodeApi 等

子域控制器分布:认证授权 8、用户 2、角色权限 3、组织 2、租户 3、字典与地区 5、消息通知 10、日志审计 2,合计 35。

3. 八个业务子域 ​

子域(控制器)职责代表接口(真实路径)关联表功能卡 ID
认证授权 auth(8)账号/短信/社交登录、登出、刷新令牌、OAuth2 客户端与授权码、验证码POST /system/auth/login、POST /system/auth/refresh-token、POST /system/oauth2/token、POST /system/captchasystem_oauth2_client、system_oauth2_access_token、system_oauth2_refresh_token、system_oauth2_code、system_oauth2_approve、system_social_client、system_social_user、system_social_user_bindSYS-AUTH-01、02、03、04、05、SYS-APP-01
用户 user(2)管理员 CRUD、导入导出、改密/改状态、个人中心GET /system/user/page、POST /system/user/create、GET /system/user/profile/getsystem_users、system_user_role、system_user_postSYS-USER-01、02
角色权限 permission(3)角色 CRUD、菜单树、角色-菜单/数据范围分配、用户-角色分配GET /system/role/page、GET /system/menu/list、POST /system/permission/assign-role-menusystem_role、system_menu、system_role_menuSYS-ROLE-01、SYS-PERM-01、02
组织 dept/post(2)部门树、岗位;部门负责人与用户归属GET /system/dept/list、GET /system/post/pagesystem_dept、system_post、system_user_postSYS-DEPT-01、SYS-POST-01
租户 tenant(3)租户、套餐、按域名/名称查租户(含 app 端)GET /system/tenant/page、GET /system/tenant-package/page、GET /system/tenant/get-by-websitesystem_tenant、system_tenant_packageSYS-TENANT-01、02
字典与地区 dict/area(5)字典类型/数据、app 字典、地区树与 IP 定位GET /system/dict-data/page、GET /system/dict-data/type、GET /system/area/treesystem_dict_type、system_dict_dataSYS-DICT-01、02、SYS-AREA-01
消息通知 notify/mail/sms(10)公告、站内信/模板、邮件账号/模板/日志、短信渠道/模板/日志/回调POST /system/notice/push、GET /system/notify-message/my-page、POST /system/mail-template/send-mail、POST /system/sms-template/send-smssystem_notice、system_notify_message、system_notify_template、system_mail_account、system_mail_template、system_mail_log、system_sms_channel、system_sms_template、system_sms_log、system_sms_codeSYS-NOTICE-01、SYS-NOTIFY-01、02、SYS-MAIL-01、02、SYS-SMS-01、02
日志审计 logger(2)登录日志(成功/失败/类型)、操作日志(方法、参数、耗时)GET /system/login-log/page、GET /system/operate-log/pagesystem_login_log、system_operate_logSYS-LOG-01、02

3.1 三条主链路 ​

  1. 登录:AuthController#login → AdminAuthService#authenticate(校验验证码/密码/状态,失败写登录日志)→ createTokenAfterLoginSuccess → OAuth2TokenService#createAccessToken 写 system_oauth2_access_token 与 refresh token。
  2. 刷新令牌:POST /system/auth/refresh-token → OAuth2TokenService#refreshAccessToken(校验 refresh token 有效期与客户端)→ 生成新 access token。
  3. 权限信息:GET /system/auth/get-permission-info → 用户 + 角色 + 菜单树 + 权限标识;菜单/角色缓存由 PermissionServiceImpl 的 @Cacheable 提供。

3.2 数据模型分组 ​

32 张表可按「身份、授权、组织、租户、消息、日志」六组记忆,排查问题时先定位组,再看关联:

分组表读法
身份system_users、system_social_user、system_social_user_bind、system_social_client账号主体与第三方绑定;system_users 是 SQL Server 关键字规避后的表名
令牌system_oauth2_client、system_oauth2_access_token、system_oauth2_refresh_token、system_oauth2_code、system_oauth2_approve客户端 → 授权码 → 令牌三级;过期清理靠 TokenCleanJob
授权system_role、system_menu、system_role_menu、system_user_role角色-菜单决定「能看什么」,按钮权限标识存在 system_menu.permission
组织system_dept、system_post、system_user_post部门树 + 岗位;数据权限按部门列过滤
租户system_tenant、system_tenant_package套餐决定菜单/功能上限,租户表带 tenant_id 隔离
消息与日志system_notice、system_notify_*、system_mail_*、system_sms_*、system_login_log、system_operate_log、system_dict_*模板-渠道-日志三段式;字典单独一组便于缓存

4. 包结构约定 ​

text
com.pmforge.module.system
├── api/            # 跨模块 RPC:AdminUserApi、DeptApi、SmsCodeApi…(14 个)
├── controller/     # admin/** 与 app/**,VO 跟控制器同包
├── convert/        # MapStruct:DO ↔ VO、DO ↔ DTO
├── dal/dataobject/ # 32 个 DO,与表一一对应
├── dal/mysql/      # Mapper,继承 BaseMapperX
├── enums/          # 业务枚举 + ErrorCodeConstants(错误码分段见速查)
├── framework/      # 与 framework 对接:captcha/datapermission/justauth/operatelog/sms/web/weixin
├── job/            # TokenCleanJob、DemoJob
├── mq/             # 消息生产者/消费者
├── service/        # 按子域再分包:auth user permission dept tenant dict notify mail sms social oauth2 logger member
└── util/           # 模块内工具
包放什么约定
controller/admin/**后台 REST + VO路径以 /system/ 开头,权限注解 @PreAuthorize("@ss.hasPermission('system:xxx:yyy')")
controller/app/**App 端只读接口路径同样 /system/,但走 app-api 前缀与会员/租户上下文
service/**接口 + Impl 同包校验「存在性/唯一性」放在 service,Controller 只做参数与转换
dal/mysql/**Mapper复杂查询写 LambdaQueryWrapperX,不拼 XML(除非联表)
api/**给别的模块调用的接口必须成对出现 XxxApi + XxxApiImpl,DTO 放 dto/
framework/**本模块对框架能力的实现只放配置与适配,不放业务逻辑

5. 对框架能力的实现 ​

能力实现落点要点
短信客户端framework/sms/core/client/impl/SmsClientFactoryImpl.java渠道枚举 5 种:DEBUG_DING_TALK、ALIYUN、TENCENT、HUAWEI、QINIU;工厂维护 channelIdClients 与 channelCodeClients 两个 Map,首次 init()、后续 refresh(),客户端继承 AbstractSmsClient
验证码framework/captcha/core/RedisCaptchaServiceImpl.java、PictureWordCaptchaServiceImpl.java实现 anji-plus 的 CaptchaCacheService,type()="redis",用 StringRedisTemplate 按秒级 TTL 存;图片/文字点选由 PmforgeCaptchaConfiguration 装配
社交登录framework/justauth/core/AuthRequestFactory.java基于 JustAuth(me.zhyd.oauth)与 AuthDefaultSource,按 system_social_client 配置反射创建 AuthRequest;PmforgeJustAuthConfiguration 注册
数据权限framework/datapermission/config/DataPermissionConfiguration.java注册 DeptDataPermissionRuleCustomizer:AdminUserDO 按部门列、DeptDO 按 id、AdminUserDO 按用户列;规则由 framework 拼接进 SQL
操作日志解析framework/operatelog/core/*ParseFunction.java6 个 IParseFunction:getAdminUserById(返回「昵称(手机号)」)、部门、岗位、地区、性别、布尔;模板里写 {{getAdminUserById{#userId}}}
会员适配service/member/MemberServiceImpl.java用 pmforge.info.base-package + ClassUtil.loadClass + SpringUtil.getBean 反射调用 MemberUserApi,让 system 不编译依赖 member

6. 已知坑 ​

现象原因规避
加了 @Cacheable 却每次都查库同类内部 this.xxx() 自调用绕过 Spring 代理照 PermissionServiceImpl#getSelf() 的写法,用 SpringUtil.getBean(getClass()) 取代理再调
未启用会员模块时,部分登录/发信报 NoSuchBeanDefinitionExceptionMemberServiceImpl 延迟反射获取 MemberUserApi,member 未启用时容器里没有该 Bean只在会员场景调用;启用 member 后自动可用,不要改成编译期依赖
换库后 system_users 相关 SQL 报错表名本就是规避 SQL Server 关键字 system_user 而加 s,且 DO 上有 autoResultMap = true改表名必须同步 DO、SQL、迁移脚本三处
单测里 Service 注入全为 null模块有 181 处 @Resource 字段注入,不是构造器注入用 @Import/Spring 容器跑测试,或手动反射注入;不要 new XxxServiceImpl()
新表不生效数据权限数据权限规则只对显式注册的 DO/列生效在 DataPermissionConfiguration 里补 addDeptColumn/addUserColumn,否则查全表

7. 扩展点:新增一个业务子域 ​

以「公告分类」为例,走完这 7 步即可与现有子域同构:

  1. 建表:system_notice_category(含 creator/create_time/updater/update_time/deleted/tenant_id 公共列),同步菜单与按钮权限 SQL。
  2. DO + Mapper:dal/dataobject/notice/NoticeCategoryDO.java、dal/mysql/notice/NoticeCategoryMapper.java。
  3. Service:service/notice/NoticeCategoryService(+Impl),实现 validateExists、名称唯一性、删除前引用检查。
  4. Controller + VO:controller/admin/notice/NoticeCategoryController,VO 放同包 vo/,复用 PageParam/PageResult。
  5. 权限点:查询/新增/修改/删除分别用 system:notice-category:query|create|update|delete,并在菜单 SQL 的 permission 列登记。
  6. 跨模块出口(可选):需要被其他模块调用时,加 api/notice/NoticeCategoryApi(+Impl) 与 DTO,不要直接暴露 DO。
  7. 文档:补一张功能卡,更新本页规模数字,执行 npm run docs:gen 重新生成接口/数据索引。

8. 相关页面 ​