组织管理模块接入快速说明

面向读者：第三方系统开发者、Codex/Claude Code/Cursor Agent 等 AI 开发工具。

目的：让第三方系统快速接入玄道智控（Cyber Hub）的组织管理模块。

接入前提

组织管理接口统一挂在 /account/api/v1 下。
读取组织数据通常需要登录用户权限。
新增、更新、删除、排序这类写操作通常需要管理员权限。
调用受保护接口时，使用 Authorization: Bearer <accessToken>。

请求头示例：

http

Authorization: Bearer <accessToken>
Content-Type: application/json

用户管理

常用接口

操作	方法与路径	说明
查询用户列表	`GET /account/api/v1/user`	管理员使用
查询用户详情	`GET /account/api/v1/user/info?id=<userId>`	登录用户可用
创建用户	`POST /account/api/v1/user/info`	管理员使用
更新用户	`PUT /account/api/v1/user/info`	管理员使用
启用/停用用户	`PUT /account/api/v1/user/info/enable`	管理员使用
删除用户	`DELETE /account/api/v1/user/info?id=<userId>`	管理员使用

关键字段

字段	含义
`id` / `userId`	用户 ID
`username`	登录账号
`name`	用户名称
`roles`	角色集合
`departmentId`	所属部门 ID
`departmentName`	所属部门名称
`mobile` / `email`	手机号、邮箱
`enable`	是否启用
`expireTime`	过期时间，`0` 表示不过期

最小示例

查询用户详情：

http

GET /account/api/v1/user/info?id=user-123
Authorization: Bearer <accessToken>

创建用户：

http

POST /account/api/v1/user/info
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "username": "alice",
  "name": "Alice",
  "password": "<base64-or-plain-password>",
  "roles": ["cyberhub:admin"],
  "departmentId": "dept-root",
  "departmentName": "总部",
  "enable": true,
  "expireTime": 0
}

必须知道的规则

创建和更新用户时，后端会校验角色是否合法。
用户角色会自动补上 cyberhub:user，别指望创建“零基础角色”用户。
不能删除自己，也不能操作比自己权限更高的用户。

部门管理

常用接口

操作	方法与路径	说明
查询部门树	`GET /account/api/v1/department/tree`	主数据源，返回整棵树
创建部门	`POST /account/api/v1/department/new`	`name` 必填
更新部门	`PUT /account/api/v1/department/<deptId>`	可更新名称、父级、角色、`custom`
移动部门	`POST /account/api/v1/department/move`	支持批量移动
排序部门	`PUT /account/api/v1/department/sort`	请求体是 `deptId -> sort`
删除部门	`DELETE /account/api/v1/department/<deptId>`	递归删除
批量删除部门	`POST /account/api/v1/department/batchDelete`	批量递归删除

查询部门树返回结构重点

字段	含义
`id`	部门 ID
`name`	部门名称
`parentId`	父部门 ID
`sort`	排序值
`roles`	绑定角色字符串
`custom`	自定义字段，字符串类型
`memberCount`	当前部门及所有子部门下的用户总数
`children`	子部门数组

最小示例

查询部门树：

http

GET /account/api/v1/department/tree
Authorization: Bearer <accessToken>

创建部门：

http

POST /account/api/v1/department/new
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "name": "研发部",
  "parentId": "dept-root",
  "roles": ["cyberhub:user"],
  "custom": "{\"owner\":\"alice\"}"
}

更新部门：

http

PUT /account/api/v1/department/dept-123
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "name": "研发一部",
  "parentId": "dept-root",
  "roles": ["cyberhub:user"],
  "custom": "{\"owner\":\"bob\"}"
}

批量移动部门：

http

POST /account/api/v1/department/move
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "deptIds": ["dept-1", "dept-2"],
  "parentId": "dept-root"
}

`custom` 规则

类型是 string。
可存普通字符串，也可存 JSON 字符串。
后端不校验是不是合法 JSON，只按字符串原样存。
查询部门树会返回 custom。
更新部门时：
- 传非空字符串：覆盖原值。
- 缺失或空串：保持原值。
- 当前不能通过空串清空部门 custom。

必须知道的规则

parentId 为空表示根部门。
后端会防止把部门父级设成自己或自己的子孙，避免成环。
删除部门是递归删除，别把它当“只删当前节点”。

角色管理

常用接口

操作	方法与路径	说明
查询角色列表	`GET /account/api/v1/role`	可按 `applicationType` 过滤
查询角色详情	`GET /account/api/v1/role/info?roleId=<roleId>`	返回权限、菜单、`custom`
创建角色	`POST /account/api/v1/role/info`	`roleId` 必须带应用前缀
更新角色	`PUT /account/api/v1/role/info`	可更新名称、权限、菜单、`custom`
删除角色	`DELETE /account/api/v1/role/info?roleId=<roleId>`	内置角色不能删
角色排序	`PUT /account/api/v1/role/sort?applicationType=<appType>`	请求体是角色 ID 数组
查询所有角色权限	`GET /account/api/v1/permission/role`	返回全部角色及权限
设置角色权限	`POST /account/api/v1/permission/role?roleId=<roleId>`	请求体是权限 ID 数组
清空角色权限	`DELETE /account/api/v1/permission/role?roleId=<roleId>`	清空角色权限

角色字段重点

字段	含义
`roleId`	角色 ID，例如 `cyberhub:admin`
`roleName`	角色名称
`applicationType`	应用类型，例如 `cyberhub`、`ccs_pro`
`code`	角色编码
`permissions`	权限列表
`menuList`	顶部菜单列表
`custom`	自定义字段，字符串类型

最小示例

查询角色列表：

http

GET /account/api/v1/role?applicationType=cyberhub
Authorization: Bearer <accessToken>

创建角色：

http

POST /account/api/v1/role/info
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "roleId": "cyberhub:operator",
  "roleName": "运维角色",
  "applicationType": "cyberhub",
  "code": "operator",
  "permissionIds": ["dashboard:view", "service:view"],
  "menuList": ["ProjectManagement", "ServiceManagement"],
  "custom": "{\"owner\":\"alice\"}"
}

更新角色：

http

PUT /account/api/v1/role/info
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "roleId": "cyberhub:operator",
  "roleName": "运维角色-更新",
  "permissionIds": ["dashboard:view"],
  "menuList": ["ApplicationManagement"],
  "custom": "{\"owner\":\"bob\"}"
}

设置角色权限：

http

POST /account/api/v1/permission/role?roleId=cyberhub:operator
Authorization: Bearer <accessToken>
Content-Type: application/json

["dashboard:view", "service:view"]

`custom` 规则

类型是 string。
可存普通字符串，也可存 JSON 字符串。
后端不校验是不是合法 JSON。
角色列表、角色详情、角色权限列表都会返回 custom。
更新角色时如果请求里带了非空 custom，就按传入值覆盖。
角色更新传空串或缺失 custom，都会保持原值。

必须知道的规则

roleId 必须包含 ${applicationType}: 前缀，不符合直接报错。
permissionIds 里的权限必须都存在。
内置角色不能删除。
已分配给用户的角色不能删除。
cyberhub 角色的 menuList 会参与顶部菜单聚合，其他应用角色通常没有这层意义。

常见坑

部门 custom 和角色 custom 现在都属于保守更新：
- 传非空字符串才覆盖。
- 空串或缺失都不改。
部门列表返回树结构，角色列表返回按应用分组结构，用户列表则是平铺列表。别把三套响应格式混着写解析器。
角色 ID 不是纯编码，必须包含应用前缀，例如 cyberhub:admin。
删除部门是递归删，删除角色要检查是否已分配给用户。

建议的最小接入能力

如果第三方系统只想“用玄道智控做组织主数据源”，建议最少接这几组接口：

用户：
- GET /account/api/v1/user
- GET /account/api/v1/user/info?id=...
部门：
- GET /account/api/v1/department/tree
角色：
- GET /account/api/v1/role
- GET /account/api/v1/role/info?roleId=...

如果第三方系统还需要反向维护组织结构，再补写接口：

用户写操作：创建、更新、启停、删除
部门写操作：创建、更新、移动、排序、删除
角色写操作：创建、更新、排序、删角色、设权限

参考文档

完整规则说明：常见坑

组织管理模块接入快速说明 ​

接入前提 ​

推荐接入顺序 ​

用户管理 ​

常用接口 ​

关键字段 ​

最小示例 ​

必须知道的规则 ​

部门管理 ​

常用接口 ​

查询部门树返回结构重点 ​

最小示例 ​

custom 规则 ​

必须知道的规则 ​

角色管理 ​

常用接口 ​

角色字段重点 ​

最小示例 ​

custom 规则 ​

必须知道的规则 ​

常见坑 ​

建议的最小接入能力 ​

参考文档 ​

组织管理模块接入快速说明

接入前提

推荐接入顺序

用户管理

常用接口

关键字段

最小示例

必须知道的规则

部门管理

常用接口

查询部门树返回结构重点

最小示例

`custom` 规则

必须知道的规则

角色管理

常用接口

角色字段重点

最小示例

`custom` 规则

必须知道的规则

常见坑

建议的最小接入能力

参考文档