组织部门数据模型（core/repositories/models/departments）

本文说明 组织机构（部门） core/repositories/models/departments 包中的职责、与项目各层的对接方式，以及它的对应关系。

项目地址 https://github.com/openskeye/go-vss

---

1. 在项目中承担的作用

该模型描述系统 组织机构（部门） 核心业务实体：数据落在表 sk-departments，通过统一 ORM（orm.Model、orm.Foundation）及缓存策略接入 db 服务；backend HTTP 服务在系统管理下提供部门增删改查与树形列表；鉴权资源聚合会将全量部门与管理员、角色一并返回，供初始化与权限相关逻辑使用。

层级	作用
数据层	core/app/sev/db/internal/svc/init_database.go 对 departments.Departments 执行 AutoMigrate；ServiceContext 注入 DepartmentsModel。
RPC / db 服务	backendservice 中的部门列表、创建、更新、树形结构等逻辑操作 DepartmentsModel 与 departments.Item。
HTTP / backend	core/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.go	GORM 实体 Departments，实现 orm.Model（表名、主键、列集合、写入前 Correction、内存缓存、ConvToItem 等）。
data.go	对外/API 层 Item（内嵌 *Departments，处理 roleIds 在 API 与 DB 之间的形态转换）；MapToModel / CheckMap 用于 RPC 入参。
db.go	DB 封装 orm.Foundation[Departments]，NewDB 构造。
variables.go	列名常量、Columns 合法列列表、PrimaryId，供查询条件、更新校验、MaxId 等使用。

---

3. 表与字段：数据库列 ↔ Go ↔ JSON

实体 Departments 映射表 sk-departments（TableName() 返回值）。

字段	含义	说明
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）

便于查询与校验统一使用常量名，避免魔法字符串。

常量	数据库列
ColumnId	id
ColumnName	name
ColumnRemark	remark
ColumnParentId	parentId
ColumnCascadeDepUniqueId	cascadeDepUniqueId
ColumnRoleIds	roleIds
ColumnState	state
ColumnCreatedAt	createdAt
ColumnUpdatedAt	updatedAt

PrimaryId 为 "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_*.go
• HTTP 处理器：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.go（cascadeDepCode）