主题
系统管理模块(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. 规模与口径
| 指标 | 数值 | 统计方法 |
|---|---|---|
| Controller | 35 | @RestController 类数(与 接口索引 一致) |
| 接口 | 199 | @GetMapping/@PostMapping/@PutMapping/@DeleteMapping 方法注解数 |
| 唯一权限点 | 89 | 生成物中 @PreAuthorize 权限标识去重 |
| 表 | 32 | 数据索引 的 system_* 表 |
| Java 文件 | 462 | 模块目录 Get-ChildItem -Recurse -Filter *.java |
| 跨模块 API | 14 | api/**/*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/captcha | system_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_bind | SYS-AUTH-01、02、03、04、05、SYS-APP-01 |
| 用户 user(2) | 管理员 CRUD、导入导出、改密/改状态、个人中心 | GET /system/user/page、POST /system/user/create、GET /system/user/profile/get | system_users、system_user_role、system_user_post | SYS-USER-01、02 |
| 角色权限 permission(3) | 角色 CRUD、菜单树、角色-菜单/数据范围分配、用户-角色分配 | GET /system/role/page、GET /system/menu/list、POST /system/permission/assign-role-menu | system_role、system_menu、system_role_menu | SYS-ROLE-01、SYS-PERM-01、02 |
| 组织 dept/post(2) | 部门树、岗位;部门负责人与用户归属 | GET /system/dept/list、GET /system/post/page | system_dept、system_post、system_user_post | SYS-DEPT-01、SYS-POST-01 |
| 租户 tenant(3) | 租户、套餐、按域名/名称查租户(含 app 端) | GET /system/tenant/page、GET /system/tenant-package/page、GET /system/tenant/get-by-website | system_tenant、system_tenant_package | SYS-TENANT-01、02 |
| 字典与地区 dict/area(5) | 字典类型/数据、app 字典、地区树与 IP 定位 | GET /system/dict-data/page、GET /system/dict-data/type、GET /system/area/tree | system_dict_type、system_dict_data | SYS-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-sms | system_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_code | SYS-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/page | system_login_log、system_operate_log | SYS-LOG-01、02 |
3.1 三条主链路
- 登录:
AuthController#login→AdminAuthService#authenticate(校验验证码/密码/状态,失败写登录日志)→createTokenAfterLoginSuccess→OAuth2TokenService#createAccessToken写system_oauth2_access_token与 refresh token。 - 刷新令牌:
POST /system/auth/refresh-token→OAuth2TokenService#refreshAccessToken(校验 refresh token 有效期与客户端)→ 生成新 access token。 - 权限信息:
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.java | 6 个 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()) 取代理再调 |
未启用会员模块时,部分登录/发信报 NoSuchBeanDefinitionException | MemberServiceImpl 延迟反射获取 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 步即可与现有子域同构:
- 建表:
system_notice_category(含creator/create_time/updater/update_time/deleted/tenant_id公共列),同步菜单与按钮权限 SQL。 - DO + Mapper:
dal/dataobject/notice/NoticeCategoryDO.java、dal/mysql/notice/NoticeCategoryMapper.java。 - Service:
service/notice/NoticeCategoryService(+Impl),实现validateExists、名称唯一性、删除前引用检查。 - Controller + VO:
controller/admin/notice/NoticeCategoryController,VO 放同包vo/,复用PageParam/PageResult。 - 权限点:查询/新增/修改/删除分别用
system:notice-category:query|create|update|delete,并在菜单 SQL 的permission列登记。 - 跨模块出口(可选):需要被其他模块调用时,加
api/notice/NoticeCategoryApi(+Impl)与 DTO,不要直接暴露 DO。 - 文档:补一张功能卡,更新本页规模数字,执行
npm run docs:gen重新生成接口/数据索引。
8. 相关页面
- 接口清单:system 接口索引(自动生成,勿手改)
- 数据字典:system 数据索引
- 功能卡:SYS-USER-01、SYS-AUTH-01、SYS-PERM-02
- 相邻模块:基础设施、模块全景