主题
从功能到代码:跟着「新增用户」走一遍
这一页是一次完整示范:从产品能力出发,经功能卡 → 接口索引 → 数据字典,落到一个 Controller 方法、一个 Service、一张表,最后回到「怎么自己验证」。全程用真实文件与行号,读完可以照着再走一遍别的功能。
0. 路线图
| 步 | 你在哪一层 | 看什么 | 本次的落点 |
|---|---|---|---|
| 1 | 产品层 | 能力清单里有没有这个功能 | 能力地图 的 SYS-USER-01 |
| 2 | 功能卡 | 权限点、接口、表、坑,一页看完 | SYS-USER-01 |
| 3 | 接口索引 | 全量接口与权限点的机器清单 | system 接口清单 |
| 4 | 数据字典 | 表与实体字段 | system 数据字典 |
| 5 | 代码 | Controller → Service → Mapper → DO | 本文第 3–6 节 |
| 6 | 验证 | 权限、租户、日志是否都生效 | 本文第 7 节 |
1. 产品侧:这个功能叫什么
能力地图里它是 SYS-USER-01「用户管理」,状态 ✅(pmforge-module-system 参与构建)。功能卡上写着它的四件事:
- 权限点:
system:user:create、system:user:update、system:user:delete、system:user:query、system:user:export、system:user:import - 接口:
/system/user/create、/update、/delete、/get、/page、/export、/import - 表:
system_users、system_user_role、system_user_post - 坑:导入走
@ApiAccessLog(operateType = IMPORT);分页查询会二次装配部门信息
2. 接口索引与数据字典:机器生成的那一层
system 接口清单 由 script/docs/scan-knowledge.mjs 扫描 @RestController 生成,每一行是「方法 + 路径 + 权限点 + 源文件行号」。/system/user/create 这一行会把你送到 UserController.java 的对应行。
system 数据字典 则把 @TableName 与 sql/mysql/pmforge.sql 的 CREATE TABLE 对齐:system_users 的字段、类型、注释都在这里。两者都是生成物,代码改了没重新生成,npm run docs:check 会让 CI 失败。
3. 入口:Controller
pmforge-module-system/src/main/java/com/pmforge/module/system/controller/admin/user/UserController.java
| 行 | 内容 |
|---|---|
#L52 | @PostMapping("/create") —— 路径与类上的 /system/user 拼成 /system/user/create |
#L54 | @PreAuthorize("@ss.hasPermission('system:user:create')") —— 功能权限校验,ss 是 SecurityFrameworkService |
#L55 | public CommonResult<Long> createUser(@Valid @RequestBody UserSaveReqVO reqVO) —— 显式返回 CommonResult,不靠全局包装 |
参数对象 UserSaveReqVO 在 controller/admin/user/vo/user/UserSaveReqVO.java,字段校验注解(@NotBlank、@Email 等)在这一层生效。
4. 业务:Service
pmforge-module-system/src/main/java/com/pmforge/module/system/service/user/AdminUserServiceImpl.java
| 行 | 内容 |
|---|---|
#L99 | public Long createUser(UserSaveReqVO createReqVO) 实际业务入口 |
#L108 | validateUserForCreateOrUpdate(...) 查用户名/手机/邮箱唯一性(#L402 是该方法定义) |
#L114 | userMapper.insert(user) 写主表 |
#L117 | userPostMapper.insertBatch(...) 写用户-岗位关联表 |
user 是 UserConvert 从 VO 转换来的 DO,密码在此前用 BCryptPasswordEncoder 加密。方法上有 @Transactional(rollbackFor = Exception.class),主表与关联表同事务。
5. 持久化:Mapper 与 DO
| 位置 | 内容 |
|---|---|
pmforge-module-system/src/main/java/com/pmforge/module/system/dal/mysql/user/AdminUserMapper.java#L14 | public interface AdminUserMapper extends BaseMapperX<AdminUserDO>,继承 BaseMapperX 直接拿到 insert、selectPage、selectJoinPage 等 |
pmforge-module-system/src/main/java/com/pmforge/module/system/dal/dataobject/user/AdminUserDO.java#L22 | @TableName(value = "system_users", autoResultMap = true)(SQL Server 里 system_user 是关键字,所以表名带 s) |
同文件 #L29 | public class AdminUserDO extends TenantBaseDO —— 带 tenant_id,插入时由租户拦截器补值 |
6. 数据库:表与权限点
- 建表语句:
sql/mysql/pmforge.sql#L5021(CREATE TABLE system_users),字段与注释可在数据字典对照。 - 权限点种子:
sql/mysql/pmforge.sql#L1927的system_menu批量 INSERT 里有system:user:create—— 菜单表既是导航也是权限点来源,@PreAuthorize校验的就是这个字符串。 - 租户与数据权限:
system_users的tenant_id由TenantLineInnerInterceptor自动补条件;部门范围过滤走 数据权限。
7. 验证:怎么确认这条链真的通了
- 接口层:启动后打开
http://localhost:48080/doc.html,找「系统管理 → 用户」,调/system/user/create,返回{"code":0,"data":<id>}。 - 权限层:用一个没有
system:user:create的账号调同一接口,应返回 403 而不是 200;给角色补上该权限点后立刻生效(权限来自缓存,PermissionServiceImpl负责刷新)。 - 租户层:用租户 A 的账号创建用户,再查
system_users,tenant_id应为 A;切到租户 B 查不到这条记录。 - 日志层:调用后查
infra_api_access_log,应有一条request_url=/system/user/create的记录(@ApiAccessLog默认记录写操作)。 - 一致性:改动 Controller 后跑
npm run docs:gen,接口索引应出现新行;不重新生成就提交,npm run docs:check会失败。