部门管理模块

概述

部门模块用于管理组织架构中的部门信息，支持树形层级结构、部门领导、用户归属等功能。

模块路径：backend-fastapi/core/dept/

API 前缀：/api/core/depts

数据模型

class Dept(BaseModel):
    __tablename__ = "core_dept"

    name: str           # 部门名称
    code: str           # 部门编码（唯一）
    dept_type: str      # 部门类型
    phone: str          # 部门电话
    email: str          # 部门邮箱
    status: bool        # 部门状态（启用/禁用）
    description: str    # 部门描述
    parent_id: str      # 父部门 ID（逻辑外键）
    lead_id: str        # 部门领导 ID（逻辑外键）
    level: int          # 部门层级（0 为顶层）
    path: str           # 部门路径（格式：/id1/id2/）

部门类型 (dept_type)

值	说明
company	公司
department	部门
team	小组
other	其他

路径字段 (path)

path 字段用于快速查询部门的所有后代，格式为 /祖先ID1/祖先ID2/.../父ID/。

例如：

• 顶级部门：/
• 一级部门：/顶级ID/
• 二级部门：/顶级ID/一级ID/

服务层

DeptService 继承 BaseService，提供以下方法：

树形结构

方法	说明
get_tree(db, parent_id)	获取部门树形结构
get_children(db, parent_id)	获取直接子部门
get_descendants(db, dept_id)	获取所有后代部门（通过 path 查询）
get_ancestors(db, dept_id)	获取所有祖先部门
get_by_parent(db, parent_id)	根据父部门获取子部门列表

部门操作

方法	说明
create(db, data)	创建部门（自动计算 level 和 path）
update(db, record_id, data)	更新部门（父部门变化时重新计算）
move(db, dept_id, new_parent_id)	移动部门到新父部门下
can_delete(db, dept_id)	检查部门是否可删除
batch_update_status(db, ids, status)	批量更新状态
batch_delete(db, ids, hard)	批量删除

用户管理

方法	说明
get_dept_users(db, dept_id, include_children)	获取部门用户
add_users_to_dept(db, dept_id, user_ids)	添加用户到部门
remove_users_from_dept(db, dept_id, user_ids)	从部门移除用户
get_user_count(db, dept_id)	获取部门用户数量

统计与搜索

方法	说明
get_stats(db)	获取部门统计信息
search(db, keyword)	搜索部门（返回匹配部门及其层级路径）
get_by_ids(db, ids)	批量获取部门（含层级路径）
get_child_count(db, dept_id)	获取子部门数量

API 接口

基础 CRUD

方法	路径	说明
POST	/	创建部门
GET	/	获取部门列表
GET	/{record_id}	获取部门详情
PUT	/{record_id}	更新部门
DELETE	/{record_id}	删除部门

树形结构

方法	路径	说明
GET	/tree	获取部门树
GET	/children/{parent_id}	获取子部门
POST	/{dept_id}/move	移动部门

用户管理

方法	路径	说明
GET	/{dept_id}/users	获取部门用户
POST	/{dept_id}/users	添加用户到部门
DELETE	/{dept_id}/users	从部门移除用户

统计与搜索

方法	路径	说明
GET	/stats	获取统计信息
GET	/search	搜索部门

请求/响应示例

获取部门树

响应：

[
  {
    "id": "dept001",
    "name": "总公司",
    "code": "HQ",
    "dept_type": "company",
    "status": true,
    "level": 0,
    "children": [
      {
        "id": "dept002",
        "name": "技术部",
        "code": "TECH",
        "dept_type": "department",
        "status": true,
        "level": 1,
        "children": []
      }
    ]
  }
]

获取统计信息

响应：

{
  "total_count": 15,
  "active_count": 12,
  "inactive_count": 3,
  "root_count": 2,
  "type_stats": {
    "公司": 2,
    "部门": 8,
    "小组": 4,
    "其他": 1
  },
  "max_level": 3
}

与其他模块的关系

• 用户模块：用户通过 dept_id 关联部门
• 工作流模块：审批人解析支持按部门分配
• 数据权限：支持按部门及其子部门过滤数据