186 lines
13 KiB
Plaintext
186 lines
13 KiB
Plaintext
================================================================================
|
||
EasyGoAdmin 后端开发者文档 · 14 核心模块实现详解
|
||
================================================================================
|
||
对高频改动/机制代表性最强的模块，给出实现级细节（其余标准 CRUD 模块遵循
|
||
04 章 ModuleSpec 模式，不再逐个展开）。代码位置均在 internal/logic/。
|
||
|
||
--------------------------------------------------------------------------------
|
||
1. index 个人中心（index.go）
|
||
--------------------------------------------------------------------------------
|
||
1.1 GetUser（GET /api/index/getUser）
|
||
数据来源与安全边界：
|
||
* 用户行经 dao.User.Ctx（自动过滤软删/租户）；password/salt 永不返回。
|
||
* Roles/Perms 优先取 JWT 中间件注入的 ctx（与鉴权同源），为空时回源
|
||
LoadIdentity；超管强制 perms=["*:*:*"]（前端据此放开全部按钮）。
|
||
* 头像经 upload.GetFileUrl 补域名；城市编码四列
|
||
（province/city/district/street_code）组装为 city[] 数组；city_info
|
||
为空时用 ResolveCityNames 按编码回填名称。
|
||
1.2 GetMenus / GetMenusById（两条路由共用 getMenuTree）
|
||
* 仅取 type=0（目录/菜单）且 status=0（启用）且 hide=0 的节点——
|
||
按钮权限节点不进菜单树，由 GetUser.permissions 下发。
|
||
* 超管全量；其余 user→user_role→role_role_menu→menu.id IN(...) 授权过滤；
|
||
无角色返回空树（[] 非 null）。
|
||
* 挂树规则：父节点不在授权集合内（未授权/顶级）一律挂根，避免菜单丢失；
|
||
排序 sort,id（根级再按 sort+id 兜底稳定排序）。
|
||
1.3 UpdatePassword
|
||
只取 id/password/salt 三列 → 旧密码 IsBcrypt+VerifyPassword 校验（1012）→
|
||
事务外 GenerateSalt+HashPassword → Update 覆盖 password/salt
|
||
（update_user/time 由 hooks 盖章）。改密后未强制下线（令牌仍有效至过期），
|
||
如需立即失效可配合在线用户强退。
|
||
1.4 UpdateProfile
|
||
头像 SaveFileField(avatar, "user") 临时转正；城市优先由编码数组经
|
||
ResolveCityNames 解析名称覆盖 city_info；四列编码经 cityCodeAt(req.City, i)
|
||
取值写入；不触达 username/password/tenant 等敏感列。
|
||
|
||
--------------------------------------------------------------------------------
|
||
2. role 角色（role.go）
|
||
--------------------------------------------------------------------------------
|
||
2.1 MenuList（GET /api/role/menu/list/:roleId）
|
||
返回全量菜单树（type 0/1 均含，供权限勾选界面展示目录+菜单+按钮三层），
|
||
每节点带 Checked=role_menu 是否含该 id（checkedSet 预构建）。
|
||
2.2 SavePermission（POST /api/role/menu/save）
|
||
语义为“全量重写”：先 Delete 该角色全部 role_menu（软删）→ 逐个 Insert
|
||
req.MenuIds → clearRoleIdentityCache(roleId)。
|
||
缓存清理链：按 roleId 查受影响 user_id 列表 → 逐个 Del
|
||
easygoadmin:user:identity:{uid}（见 15 章缓存清单）。
|
||
2.3 data_scope 字段链路（数据范围，机制总览见 03 章第 6 节）：
|
||
roleToData：Add/Update 均带 data_scope，入参 ≤0 归一为 1（全部）；
|
||
roleSpec.SerializeMaps = {"data_scope": "role_data_scope"} →
|
||
列表行 dataScopeText 由字典填充；
|
||
AfterUpdate（roleClearCache）在数据范围变更后失效该角色全部用户
|
||
身份缓存——下一次请求 LoadIdentity 重取 min(data_scope) 即生效。
|
||
2.4 其他：删除守卫（存在用户引用则拒绝，1014/1011 语义）。
|
||
已知偏差（如实记录）：role 的 spec 唯一预检当前声明为
|
||
UniqueFields{Field:"code"}（未带 Group），而索引 uk_tenant_code 是
|
||
“租户内唯一”——预检范围偏宽，超管为不同租户创建相同角色编码时会被
|
||
误报“已存在”（数据库层不会冲突）。修复方向：补 Group:"tenant_id"，
|
||
使预检范围等于索引范围（见 04 章 4.4 与 13 章 Q11）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
3. menu 菜单（menu.go）
|
||
--------------------------------------------------------------------------------
|
||
* List 树形（IsTree+ParentOf）；删除守卫 menuDeleteGuard：存在子菜单拒绝（1011）。
|
||
* 关联清理：删除菜单时同步清理 role_menu 引用（menuCleanRelations），
|
||
批量删除同理——防止悬挂授权。
|
||
* 父级校验 menuParentGuard：parentId 不得指向自身或后代（防环）。
|
||
* type 语义：0=菜单/目录（进菜单树），1=权限节点（进 Perms 校验）；
|
||
status 0=启用；hide 0=显示（hide=1 不进菜单树但权限仍生效需注意——
|
||
getMenuTree 过滤 hide=0，LoadIdentity 过滤 hide=0，故 hide=1 权限节点
|
||
不生效，配置时勿用）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
4. user 用户（user.go，机制最全的模块）
|
||
--------------------------------------------------------------------------------
|
||
4.1 唯一校验（手写，按行现租户）
|
||
usernameExists / mobileExists 按 (username|mobile, tenant_id, 排除自身) 查；
|
||
Update 时先读被改行的 tenant_id 再校验——校验范围必须等于
|
||
uk_tenant_username / uk_tenant_mobile 索引范围（含 del_flag 由 dao.Ctx
|
||
恒过滤保证）。历史教训：用 GetTenantID（超管=默认租户）会漏报 1062。
|
||
4.2 AssignRoles(userId, roleIds)
|
||
全量重写 user_role（先删后插）→ clearIdentityCache(userId)。
|
||
Add/Update 均经此方法同步角色。
|
||
4.3 checkTenantUserMax(tenantId)
|
||
统计租户现有用户数 vs tenant.max_user_num，超限返回 1007。
|
||
4.4 genUserCode(tenantId)
|
||
前缀=租户 code（平台/超管为 "SYS"），序号=该租户现有用户数+1，
|
||
格式 "{prefix}-%06d"（如 T0001-000001）。
|
||
4.5 Import（POST /api/user/import）
|
||
excel.ReadSheet → 表头映射 → 逐行：唯一校验/租户上限/默认密码 bcrypt
|
||
（预计算）/角色与城市解析 → 批量插入 → 返回导入成功/失败统计。
|
||
城市列经 ResolveCityCodes(名称串) 转编码入库。
|
||
4.6 Export：与列表同筛选（userFilter + DataScope，applyFilters 同链）
|
||
→ ChunkQuery 500/页 → excel.WriteSheet（导出可见集=列表可见集）。
|
||
4.7 userExpandNames：列表行批量补 dept/level/position/role 名称与城市文本
|
||
（namesById/dictName 批查防 N+1）。
|
||
4.8 DataScope 接线（数据权限，机制总览见 03 章第 6 节）：
|
||
userSpec 声明 DataScope: ApplyDataScope("dept_id")——user 是当前
|
||
唯一接线模块（全库仅 user 表有 dept_id 列）。Update 改 dept_id 后
|
||
AssignRoles 无条件 clearIdentityCache，部门变更即时生效（无需等 300s）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
5. tenant 租户（tenant.go）
|
||
--------------------------------------------------------------------------------
|
||
5.1 编码规则 T%04d（自增 ID 回填）
|
||
code 为 NOT NULL + 唯一键，插入时无法预知 ID → 先写临时占位编码
|
||
（T%010d(纳秒取模)），Insert 后按 LastInsertId 修正为 "T"+4位ID。
|
||
Add 与 Account 均遵循此模式；显式传 code 时查重后直接使用不回填。
|
||
5.2 Account（POST /api/tenant/account）开户事务
|
||
bcrypt 在事务外预计算（短事务纪律）→ WithTrans 内三段原子写：
|
||
① Insert 租户（status=1，hooks 填审计列）
|
||
② 修正 code=T%04d(tenantId)
|
||
③ 以 tenantCtx（WithTenantID(txCtx, tenantId)）Insert 初始管理员：
|
||
code="{code}-000001"（首用户序号），tenant_id 显式传入，password/salt
|
||
为预计算值
|
||
返回 {tenantId, code, userId}。角色分配未含在开户事务内（按需另行调用）。
|
||
5.3 tenantFilter / fillUserCount / clearCache
|
||
列表为平台专属视图（超管可见全部，带每租户用户数统计）；
|
||
状态/过期变更后 Del tenant:info:{id}（Tenant 中间件 60s 摘要缓存）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
6. dict / dict_item 字典（dict.go、dict_item.go）
|
||
--------------------------------------------------------------------------------
|
||
6.1 两级缓存
|
||
Redis 层：easygoadmin:dict:item:{code} = 字典项 JSON 数组，TTL 3600s
|
||
（setCache；getCache 命中直接返回，供前端下拉等高频读取）。
|
||
进程层：base.go dictTextCache（{code}:{value}→name），TTL 300s
|
||
（DictGetText 消费，供 {field}Text 填充）。
|
||
6.2 RefreshCache（GET /api/dict/refreshCache）
|
||
重建 Redis 层：可按 code 单字典或全量重查 dict_item → 按字典编码分组
|
||
→ 逐 code setCache。注意：只刷 Redis 层，进程内 dictTextCache 仍按 300s
|
||
自然过期（重启/多实例各自过期）。
|
||
6.3 别名路由（/api/dictionary/list|info，登录即可）供前端通用字典组件；
|
||
dict_item 快捷路由 getDictItemList/:code 走 Redis 缓存。
|
||
6.4 dict_item 无 list 标准接口（页面用 page）；删除字典项不主动清缓存
|
||
（最长 1 小时延迟），关键场景调 RefreshCache。
|
||
|
||
--------------------------------------------------------------------------------
|
||
7. city 城市（city.go）
|
||
--------------------------------------------------------------------------------
|
||
7.1 双向编解码（internal/logic 包级函数，user/index 模块复用）
|
||
ResolveCityNames(ctx, codes[]string, separator) string
|
||
area_code IN(...) 批查 → 按入参顺序拼名称串（空编码跳过）。
|
||
ResolveCityCodes(ctx, cityInfo string) [4]string
|
||
名称串按逗号拆 4 级，逐级 parent 约束消歧：
|
||
省：pid=0 AND name=? → 市：parent_code=省area_code AND name=?
|
||
→ 区 → 街道，逐级依赖上级结果；任一级失败后续留空。
|
||
例："江苏省,南京市,建邺区" → [320000000000, 320100000000, 320105000000, ""]
|
||
7.2 查询接口：ByParent(parent_code)/GetCityList(:parentCode) 级联懒加载、
|
||
AreaProvince（pid=0 省份列表），均登录即可（前端级联选择器高频调用）。
|
||
7.3 大表注意：勿全表 List；筛选走 area_code/parent_code/pid。
|
||
|
||
--------------------------------------------------------------------------------
|
||
8. config 配置（config.go）与 param 参数
|
||
--------------------------------------------------------------------------------
|
||
* config 为“配置分组”，config_item 为键值明细（config_id 关联，value/options/type）。
|
||
* 网站设置页专用：GET /api/config/web/index 聚合读取、POST /api/config/web/save
|
||
批量保存（perm sys:configWeb:*），save 为覆盖式写入。
|
||
* param 为全局键值参数（code 唯一），与 config_item 的区别：param 面向
|
||
运行参数快速读写，config 面向结构化表单配置。
|
||
|
||
--------------------------------------------------------------------------------
|
||
9. 模块机制代表速查
|
||
--------------------------------------------------------------------------------
|
||
树形模块 menu / dept / category（IsTree+ParentOf+删除子级守卫）
|
||
导入导出模块 user / level / example（excel + ChunkQuery）
|
||
文件/富文本模块 article（cover 单图、images 多图、content 富文本）、user（avatar）、
|
||
tenant（logo）、example
|
||
无表模块 auth / index / online_user / server_monitor / cache_monitor /
|
||
generator / upload
|
||
控制密集模块 job（调度挂载）、role（权限缓存）、tenant（开户事务）、
|
||
user（唯一/上限/角色）、dict（两级缓存）
|
||
|
||
--------------------------------------------------------------------------------
|
||
10. 唯一预检覆盖现状（已知偏差汇总）
|
||
--------------------------------------------------------------------------------
|
||
当前 spec 声明了 UniqueFields 的模块仅两处：
|
||
role {Field:"code"}（无 Group —— 预检范围偏宽，见第 2.3 节偏差说明）
|
||
param {Field:"code"}（与全局 uk_code 一致，无偏差）
|
||
user（username/mobile/code）为手写检查（按行现租户，与索引对齐）；
|
||
tenant.Add 手写 code 查重；config/dict/file_template 的 Add 走 CheckUnique
|
||
（code 全局，三处调用点在各自 Add）；三者的 Update 未做预检——改 code 撞
|
||
uk_code 时以数据库 1062 兜底。
|
||
未做预检、依赖数据库 uk_* 兜底的模块：dept / level / position / category
|
||
（uk_tenant_name）——重复名称提交会收到 1062 裸错误提示。
|
||
修复方向：为四个模块补 UniqueFields{Field:"name", Group:"tenant_id"}
|
||
（user 名称类除外，已手写），并按 04 章 4.4 保证预检范围=索引范围。
|