SkeyeVSS开发笔记-组织部门数据模型

组织部门数据模型core/repositories/models/departments本文说明组织机构部门core/repositories/models/departments包中的职责、与项目各层的对接方式以及它的对应关系。项目地址https://github.com/openskeye/go-vss1. 在项目中承担的作用该模型描述系统组织机构部门核心业务实体数据落在表sk-departments通过统一 ORMorm.Model、orm.Foundation及缓存策略接入db 服务backend HTTP 服务在系统管理下提供部门增删改查与树形列表鉴权资源聚合会将全量部门与管理员、角色一并返回供初始化与权限相关逻辑使用。层级作用数据层core/app/sev/db/internal/svc/init_database.go对departments.Departments执行AutoMigrateServiceContext注入DepartmentsModel。RPC / db 服务backendservice中的部门列表、创建、更新、树形结构等逻辑操作DepartmentsModel与departments.Item。HTTP / backendcore/app/sev/backend/internal/handler/system/departments与路由中的/departments等接口逻辑层通过 RPC 调用 db 服务。鉴权AuthResLogic查询全部部门并ConvToItem()封装进core/common/types.AuthRes的departments字段。配置 / 编号MaxIdLogic在type cascadeDepCode时基于cascadeDepUniqueId生成下一级联编号与频道等类似逻辑对齐。与其它模型管理员admins、通道channels、设备devices等模型中的depIds部门 ID 集合引用本表id设备列表等场景会按depIds反查部门明细。部门是组织树 角色绑定的枢纽表——层级由parentId及业务上的cascadeDepUniqueId表达角色由roleIds绑定其它业务表用depIds挂到部门主键上。关联数据模型文档go-vss仓库引用本表id的通道 / 设备depIds字段说明见 7.2 通道数据模型、7.1 设备数据模型。2. 包内文件职责通用类型后期将不再赘述文件职责model.goGORM 实体Departments实现orm.Model表名、主键、列集合、写入前Correction、内存缓存、ConvToItem等。data.go对外/API 层Item内嵌*Departments处理roleIds在 API 与 DB 之间的形态转换MapToModel/CheckMap用于 RPC 入参。db.goDB封装orm.Foundation[Departments]NewDB构造。variables.go列名常量、Columns合法列列表、PrimaryId供查询条件、更新校验、MaxId等使用。3. 表与字段数据库列 ↔ Go ↔ JSON实体Departments映射表sk-departmentsTableName()返回值。字段含义说明id主键自增其它表depIds存此 ID。name名称部门名称树节点名在department_trees_logic中使用item.Name。remark备注文本说明。parentId父部门上级部门id构建树时Pid对应ParentId。cascadeDepUniqueId级联编号唯一索引MaxId的cascadeDepCode用于生成CheckMap中空串可规范为nil。roleIds角色 ID 集合存储形态库内为字符串如 JSON 文本详见下文Item的[]uint64映射。state启用状态0未启用1启用与注释约定一致。createdAt创建时间毫秒时间戳。updatedAt更新时间毫秒时间戳Correction/CorrectionMap在写入时刷新。Departments另内嵌*orm.DefaultModel由 ORM 通用逻辑使用通用类型后期将不再赘述。4.Item与Departments的字段对应Item在data.go中定义内嵌*Departments除下列字段外序列化字段与Departments的json标签一致。RoleIds []uint64仅挂载在Item上API 侧通常为数字数组持久化时通过ConvToModel写入Departments.RoleIds字符串ConvToItem从字符串解析回切片空列表落库可为[]。UseDBCache来自内嵌模型相关逻辑json:-。更新场景下CheckMap会校验 key 必须属于variables.Columns对roleIds会将入参转为[]uint64再序列化为字符串写入 map保证与库类型一致。5. 列名常量variables.go便于查询与校验统一使用常量名避免魔法字符串。常量数据库列ColumnIdidColumnNamenameColumnRemarkremarkColumnParentIdparentIdColumnCascadeDepUniqueIdcascadeDepUniqueIdColumnRoleIdsroleIdsColumnStatestateColumnCreatedAtcreatedAtColumnUpdatedAtupdatedAtPrimaryId为id。6. 行为与联调注意点缓存Departments.UseCache()对增删改查等启用内存缓存CacheKeyPrefix为表名过期时间约 60 秒。排查数据不一致时需考虑缓存窗口。树形接口扁平列表通过parentId与categories包组装为树DepartmentTreesLogic。与角色、设备、管理员部门通过roleIds绑定角色admins/channels/devices的depIds与部门id建立关联。7. 相关代码路径模型包core/repositories/models/departments/DB 迁移与模型注入core/app/sev/db/internal/svc/init_database.go、service_context.go部门 RPC 逻辑core/app/sev/db/internal/logic/backendservice/department_*.goHTTP 处理器core/app/sev/backend/internal/handler/system/departments/鉴权聚合core/app/sev/db/internal/logic/backendservice/auth_res_logic.go、core/common/types/auth.go级联编号core/app/sev/db/internal/logic/configservice/max_id_logic.gocascadeDepCode