组织、员工与知识库授权

本页面向渠道租户初始化与组织同步，使用租户管理员契约 Token。指定用户调用时仍需具备对应业务权限。只需外部访客标识时，请使用访客注册。

组织与部门

方法	路径	说明
POST	`/kb/department/add`	新建组织或部门，JSON 请求
GET	`/kb/department/queryByCode`	Query 参数 `code`，按组织编码查询
DELETE	`/kb/department/delete`	Query 参数 `code`，删除组织或部门

创建请求：

{
  "code": "partner_org_001",
  "name": "合作客户",
  "aliasName": "客户组织",
  "pid": "0",
  "type": "ORGANIZATION",
  "description": "渠道同步组织"
}

字段	必填	说明
`code`	否	外部稳定组织编码；省略或空字符串时生成；最长 50，只允许字母、数字、下划线、短横线，至少含一个字母或数字，须全局唯一
`name`	是	非空名称
`pid`	否	父组织 code，默认 `"0"` 表示顶级；子部门使用已创建父节点的 code
`type`	是	`ORGANIZATION` 组织，`DEPARTMENT` 部门
`aliasName`、`description`	否	别名、说明

创建与查询响应字段

两个接口都返回普通响应，data 为同一组织对象。保存 data.code 供员工部门关系和知识授权使用；列表场景的统计/权限扩展在单对象接口中可空。

字段	JSON 类型	说明
`id`	integer	/主/键/i/d/
`creator`	string	/创/建/人/
`creatorAvatar`	string	/创/建/人/头/像/
`creatorName`	string	/创/建/人/名/称/
`createTime`	string	/创/建/时/间/；日期时间字符串，可无时区偏移
`modifier`	string	/修/改/人/
`modifierTime`	string	/修/改/时/间/；日期时间字符串，可无时区偏移
`sort`	integer	/排/序/
`tenantId`	string	/所/属/租/户/业/务/编/码/
`code`	string	/组/织/编/码/
`name`	string	/组/织/名/称/
`aliasName`	string	/组/织/的/别/名/
`pid`	string	/组/织/的/父/编/码/,/默/认/为/0/
`grade`	integer	/组/织/层/级/，/用/于/加/速/查/询/组/织/的/层/级/关/系/（/例/如/，/可/以/快/速/查/询/某/个/组/织/是/第/几/层/）/。/
`fullPath`	string	/内/部/层/级/路/径/字/符/串/，/按/不/透/明/值/读/取/，/不/从/中/提/取/业/务/编/码/
`description`	string	/描/述/
`userCount`	integer	/人/员/数/量/，/未/统/计/可/空/
`relationUserCount`	integer	/关/联/人/员/数/量/，/未/统/计/可/空/
`type`	string	/O/R/G/A/N/I/Z/A/T/I/O/N/ /组/织/、/D/E/P/A/R/T/M/E/N/T/ /部/门/
`children`	array[object]	/子/部/门/数/组/，/递/归/使/用/同/一/对/象/；/单/节/点/查/询/可/能/不/填/充/
`deprecateTag`	string	/废/弃/标/签/，/0/-/正/常/，/1/-/废/弃/
`inSpace`	boolean	/场/景/性/空/间/成/员/标/记/，/可/空/
`inPerm`	boolean	/场/景/性/权/限/成/员/标/记/，/可/空/
`limitType`	string	/场/景/性/权/限/类/型/，/可/空/

创建请求示例

curl --request POST "${BASE_URL}/kb/department/add" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"code":"partner_org_001","name":"合作客户","pid":"0","type":"ORGANIZATION"}'

创建或按编码查询的响应示例（省略未填充扩展）：

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "id": 11,
    "code": "partner_org_001",
    "name": "合作客户",
    "aliasName": null,
    "pid": "0",
    "type": "ORGANIZATION",
    "grade": 1,
    "description": null,
    "tenantId": "partner_tenant_001",
    "children": []
  }
}

按编码查询

Query 参数 code 为必填 string。

curl --get "${BASE_URL}/kb/department/queryByCode" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --data-urlencode "code=partner_org_001"

删除组织或部门

Query 参数 code 为必填 string，不使用数字 id：

curl --get --request DELETE "${BASE_URL}/kb/department/delete" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --data-urlencode "code=partner_org_001"

响应字段	JSON 类型	说明
`code`	integer	8200 表示操作成功
`message`	string	删除结果提示
`data`	string	结果字符串，可为空，不是被删除组织对象

{"code":8200,"message":"SUCCESS","data":""}

删除顶级组织时不能存在子组织；删除普通部门会连同子部门处理，并调整相关人员和空间部门关系。请先核实节点范围，删除超时后先查询结果再决定是否重试。

创建员工

POST /user/api/sysUser/userAdd，JSON 请求。

员工创建会建立正式用户、组织关系和登录认证信息，与访客注册行为不同。

{
  "code": "partner_employee_001",
  "name": "示例员工",
  "nickName": "示例员工",
  "tel": "13800000001",
  "departmentNo": ["partner_org_001"],
  "uniqueName": "partner_employee_login_001",
  "pwd": "REPLACE_WITH_PASSWORD",
  "validDays": "365"
}

字段	类型	说明
`code`	string	可选，规则同组织编码；省略时生成，全局唯一
`name`、`nickName`	string	建议同时提供；昵称最长 20，当前人员展示姓名使用昵称
`tel`	string	登录联系电话，提供时租户内唯一；按项目的员工登录方式填写
`departmentNo`	array[string]	组织/部门 code 列表，使用当前租户有效组织，建议至少一个
`uniqueName`	string	提供稳定的唯一登录名称，全局唯一
`pwd`	string	员工初始登录密码，使用符合部署密码策略的真实值
`validDays`	string	有效天数，使用正整数字符串；与 `expirationTime` 不同时传
`expirationTime`	string	到期日期，`yyyy-MM-dd`；与 `validDays` 不同时传
`logoImage`、`email`	string	可选头像、邮箱；非空邮箱在租户内唯一
`sex`	string	可选，`male`、`female`、`unknown`
`birthday`、`joinTime`	string	可选，`yyyy-MM-dd`
`jobNo`、`jobTitle`、`country`、`city`	string	可选工号、职务、国家、城市
`sign`、`industry`、`relationCode`	string	可选签名、行业、外包企业关联编码

当前成功响应的 data 已是用户对象，不再是旧版的空字符串。 主要字段示例：

{
  "code": 8200,
  "message": "新增成功",
  "data": {
    "id": 1001,
    "code": "partner_employee_001",
    "name": "示例员工",
    "nickName": "示例员工",
    "tel": "13800000001",
    "departmentNo": ["partner_org_001"],
    "uniqueName": "partner_employee_login_001",
    "type": "OFFICIAL",
    "state": 1,
    "tenantId": "partner_tenant_001"
  }
}

创建响应字段

字段	JSON 类型	说明
`data.id`	integer	/用/户/主/键/
`data.code`	string	/用/户/编/码/
`data.name`	string	/用/户/名/称/
`data.nickName`	string	/昵/称/
`data.tel`	string	/联/系/电/话/
`data.departmentNo`	array[string]	/创/建/结/果/关/联/的/部/门/编/码/数/组/
`data.logoImage`	string	/用/户/头/像/
`data.sex`	string	/性/别/
`data.birthday`	string	/生/日/；yyyy-MM-dd
`data.email`	string	/邮/箱/地/址/
`data.sign`	string	/个/性/签/名/
`data.industry`	string	/所/属/领/域/
`data.relationCode`	string	/关/联/外/包/企/业/编/码/
`data.jobNo`	string	/工/号/
`data.joinTime`	string	/加/入/公/司/时/间/；yyyy-MM-dd
`data.jobTitle`	string	/职/务/
`data.country`	string	/国/家/
`data.city`	string	/工/作/城/市/
`data.uniqueName`	string	/唯/一/登/录/名/称/，/提/供/时/用/于/账/号/登/录/
`data.type`	string	/人/员/类/型/，/当/前/员/工/创/建/为/ /O/F/F/I/C/I/A/L/
`data.state`	integer	/1/ /正/常/，/0/ /停/用/
`data.tenantId`	string	/所/属/租/户/编/号/
`data.createTime`	string	/创/建/时/间/；日期时间字符串，可无时区偏移
`data.expirationTime`	string	/账/号/过/期/时/间/，/未/限/制/时/可/能/为/空/；日期时间字符串，可无时区偏移

保存 data.code 用于用户契约和授权，保存 data.id 用于员工更新。响应不包含初始密码。未输入的联系、个人资料字段可空，不应向非必要人员暴露。

创建调用示例

curl --request POST "${BASE_URL}/user/api/sysUser/userAdd" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"code":"partner_employee_001","name":"示例员工","nickName":"示例员工","departmentNo":["partner_org_001"],"uniqueName":"partner_employee_login_001","pwd":"REPLACE_PASSWORD","validDays":"365"}'

创建成功只说明用户及相关初始化完成；具体资源访问仍取决于角色与知识授权。

查询和更新员工

GET /user/api/sysUser/userList 返回分页用户列表，使用 pageNo（默认 1）、pageSize（默认 10），并可使用 nickName 搜索昵称、联系电话、工号或唯一登录名称，或按 departmentCode、state、type 等条件回查；对候选记录检查返回的 code。已知用户编码时也可使用按 code 查询用户。

PUT /user/api/sysUser/userUpdate 使用与创建相同的请求模型，必须提供已有用户的数字主键 id。按当前资料组织完整更新请求，尤其保留登录信息和 departmentNo；不要将其视为仅传一个字段的 PATCH。服务端保留原用户 code，已有唯一登录名称也不会按一般资料修改流程直接替换。成功返回更新提示对象，不是员工详情。

员工列表请求字段

Query 字段	类型	必填	说明
`pageNo`	integer	否	默认 1
`pageSize`	integer	否	默认 10
`nickName`	string	否	名称/电话/工号/唯一登录名称搜索
`departmentCode`	string	否	所属部门 code
`state`	integer	否	1 正常，0 停用
`type`	string	否	人员类型，使用已知的员工类型

curl --get "${BASE_URL}/user/api/sysUser/userList" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --data-urlencode "nickName=partner_employee_login_001" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

员工列表响应

顶层为标准分页，data[] 完整字段见 EmployeeListItem。

关键字段	JSON 类型	说明
`data[].id`	integer	员工数字主键，更新使用
`data[].code`	string	员工 code，契约与角色关联使用
`data[].departmentNo`	string / null	部门编码的字符串表示，注意不是创建接口的数组
`data[].state`	integer	当前状态，用于状态切换前后确认
`data[].uniqueName`	string / null	唯一登录名称
`data[].expirationTime`	string / null	账号到期日期时间

{
  "code": 8200,
  "message": "SUCCESS",
  "pageNo": 1,
  "pageSize": 10,
  "total": 1,
  "totalPage": 1,
  "data": [{
    "id": 1001,
    "code": "partner_employee_001",
    "name": "示例员工",
    "nickName": "示例员工",
    "departmentNo": "partner_org_001",
    "uniqueName": "partner_employee_login_001",
    "state": 1,
    "type": "OFFICIAL"
  }]
}

员工更新请求与响应

请求字段继承上方员工创建表，额外必填 integer 型 id。不要通过本接口更换用户 code 或已有唯一登录名称，也不要将初始密码字段当成密码重置接口。

curl --request PUT "${BASE_URL}/user/api/sysUser/userUpdate" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"id":1001,"name":"示例员工","nickName":"更新后的昵称","departmentNo":["partner_org_001"],"uniqueName":"partner_employee_login_001"}'

示例是字段结构；实际调用先读取员工现有资料，补齐需要保留的联系信息、部门和有效期。

字段	JSON 类型	说明
`data.msg`	string	/更/新/结/果/提/示/，/随/语/言/变/化/，/不/是/更/新/后/的/用/户/资/料/
`data.refreshSession`	boolean	/是/否/提/示/刷/新/当/前/会/话/；/更/新/对/象/为/当/前/用/户/时/为/ /t/r/u/e/

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {"msg": "修改成功", "refreshSession": false}
}

refreshSession 不是“是否修改成功”；按外层状态处理请求，并重新查询验证业务资料。msg 不作为固定文案判断条件。

用户角色与停用

POST /user/api/sysUserRole/addUserRoleS，JSON：

{
  "userCode": "partner_employee_001",
  "roleId": ["REPLACE_WITH_ROLE_CODE"]
}

字段	类型	必填	说明
`userCode`	string	是	目标用户 code
`roleId`	array[string]	是	非空角色编码数组，使用目标租户的真实角色

curl --request POST "${BASE_URL}/user/api/sysUserRole/addUserRoleS" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"userCode":"partner_employee_001","roleId":["REPLACE_WITH_ROLE_CODE"]}'

角色保存响应：

字段	JSON 类型	说明
`code`	integer	8200 表示操作成功
`message`	string	状态提示
`data`	string	结果字符串，不返回角色列表

{"code":8200,"message":"SUCCESS","data":""}

roleId 为角色编码数组。该操作全量替换用户角色，需提交期望保留的全部角色；不是追加一项。

PUT /user/api/sysUser/fire，JSON：

{
  "code": "partner_employee_001"
}

请求 code 为必填 string。示例：

curl --request PUT "${BASE_URL}/user/api/sysUser/fire" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"code":"partner_employee_001"}'

响应字段	JSON 类型	说明
`code`	integer	普通业务状态
`message`	string	状态提示
`data`	boolean	操作结果；不是切换后的用户启用状态

{"code":8200,"message":"SUCCESS","data":true}

该接口是状态切换：正常变停用，停用变正常。成功返回 data 为布尔值。它没有目标状态参数，不具备重复执行幂等性；超时后先查询用户状态，不能盲目重试。

创建知识库并保留外部编码

POST /kl/api/saas/container/add，JSON：

{
  "code": "partner_kb_001",
  "name": "合作客户知识库",
  "category": "COMMON",
  "type": "KNOWLEDGE",
  "parentCode": "0",
  "classifyCode": "0",
  "visibilityRange": "MEMBERS_ONLY",
  "sharingPermission": "NON_SHAREABLE",
  "tag": ["产品"]
}

name、category、type 为必填；parentCode 默认 "0"。code 可透传，规则同组织编码；description、tag、classifyCode 可选。成功 data 返回知识库对象，保存 data.code。

初始化请求字段

字段	JSON 类型	必填	说明
`code`	string	否	外部编码，全局唯一，最长 50，规则同组织编码
`name`	string	是	知识库名称
`category`	string	是	通用文档使用 COMMON；其他类别按开通能力
`type`	string	是	KNOWLEDGE 知识库，DIRECTORY 目录
`parentCode`	string	否	父编码，默认 0
`description`	string	否	描述
`classifyCode`	string	否	分类 code
`tag`	array[string]	否	标签集合
`visibilityRange`	string	否	可见范围，值见下方权限说明
`sharingPermission`	string	否	SHAREABLE / NON_SHAREABLE
`kbKnowledgeBasePermissionReqList`	array[object]	否	权限条目；结构见下方权限说明

curl --request POST "${BASE_URL}/kl/api/saas/container/add" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"code":"partner_kb_001","name":"合作客户知识库","category":"COMMON","type":"KNOWLEDGE","parentCode":"0","visibilityRange":"MEMBERS_ONLY","sharingPermission":"NON_SHAREABLE"}'

初始化响应字段

字段	JSON 类型	说明
`data`	object	完整字段见 KnowledgeContainer
`data.id`	integer	知识库数字主键
`data.code`	string	稳定知识库编码，用于文件请求和权限配置
`data.name`	string	知识库名称
`data.kbKnowledgeBasePermissionReqList`	array[object] / null	当前权限扩展；配置前从权限查询接口读取完整值

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {"id":101,"code":"partner_kb_001","name":"合作客户知识库","category":"COMMON","type":"KNOWLEDGE"}
}

此渠道初始化入口支持外部 code。/openapi/paas/v1/knowledge/container/add 的简化请求字段不同，不能假定同一路径也支持本页所有字段。

知识库权限

先通过 GET /kb/space/permission/queryByCode?code={知识库code} 读取当前权限，再用 PUT /kb/space/permission/update 提交完整配置。更新要求当前用户具有知识库管理权限。

{
  "containerId": "partner_kb_001",
  "visibilityRange": "MEMBERS_ONLY",
  "sharingPermission": "NON_SHAREABLE",
  "kbKnowledgeBasePermissionReqList": [
    {
      "permissionType": "MANAGE",
      "membershipType": "USER",
      "membershipCode": "REPLACE_WITH_OWNER_USER_CODE",
      "membershipName": "知识库所有者",
      "owner": true
    },
    {
      "permissionType": "VIEW_ONLY",
      "membershipType": "USER",
      "membershipCode": "partner_employee_001",
      "membershipName": "示例员工",
      "owner": false
    }
  ]
}

字段	说明
`containerId`	知识库 code
`visibilityRange`	`MEMBERS_ONLY`、`ENTERPRISE_PUBLIC`、`ENTERPRISE_PUBLIC_ASK_ONLY`、`INTERNET_PUBLIC`
`sharingPermission`	`SHAREABLE` 或 `NON_SHAREABLE`
`permissionType`	典型值：`MANAGE`、`EDIT`、`VIEW_ONLY`、`ASK_ONLY`
`membershipType`	用户用 `USER`，组织/部门用 `ORGANIZATION`
`membershipCode`	对应用户或组织 code，不使用数据库 id
`membershipName`	展示名称
`owner`	是否所有者，显式传布尔值

权限更新为全量替换：遗漏成员会移除该成员权限。保留真实所有者的 MANAGE + USER + owner=true 记录；示例所有者编码必须替换为查询到的实际值。只有问答权限的用户不因此获得原文读取权限。

推荐顺序：开户 → 管理员契约认证 → 创建组织 → 创建员工 → 创建知识库 → 查询并设置完整权限 → 用指定用户契约验证访问。

权限查询请求与响应

Query 参数 code 为必填 string，取知识库 code。返回 data 是一份可用于构造完整更新请求的权限配置，不是平铺权限列表。

curl --get "${BASE_URL}/kb/space/permission/queryByCode" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --data-urlencode "code=partner_kb_001"

响应字段	JSON 类型	说明
`data.containerId`	string	知识库 code
`data.visibilityRange`	string	可见范围
`data.sharingPermission`	string	分享权限
`data.kbKnowledgeBasePermissionReqList`	array[object]	完整成员权限，保留未改动条目
`data.kbKnowledgeBasePermissionReqList[].id`	integer / null	已有权限记录主键
`data.kbKnowledgeBasePermissionReqList[].permissionType`	string	成员权限类型
`data.kbKnowledgeBasePermissionReqList[].membershipType`	string	成员类别
`data.kbKnowledgeBasePermissionReqList[].membershipCode`	string	成员业务编码
`data.kbKnowledgeBasePermissionReqList[].membershipName`	string	展示名称
`data.kbKnowledgeBasePermissionReqList[].owner`	boolean	是否真实所有者

{
  "code": 8200,
  "message": "SUCCESS",
  "data": {
    "containerId": "partner_kb_001",
    "visibilityRange": "MEMBERS_ONLY",
    "sharingPermission": "NON_SHAREABLE",
    "kbKnowledgeBasePermissionReqList": [{
      "id": 1,
      "permissionType": "MANAGE",
      "membershipType": "USER",
      "membershipCode": "REPLACE_WITH_OWNER_USER_CODE",
      "membershipName": "知识库所有者",
      "owner": true
    }]
  }
}

权限更新请求与响应

将查询结果中的 data 作为配置基线，保留所有需要继续拥有权限的成员，再提交上方 JSON 结构。以下变量 PERMISSION_JSON 表示已在服务端校验的完整配置：

curl --request PUT "${BASE_URL}/kb/space/permission/update" \
  --header "Authorization: Bearer ${CHANNEL_USER_TOKEN}" \
  --header "Content-Type: application/json" \
  --data "${PERMISSION_JSON}"

响应字段	JSON 类型	说明
`code`	integer	8200 表示更新请求成功
`message`	string	状态提示
`data`	string	结果字符串，不返回新权限快照

{"code":8200,"message":"SUCCESS","data":""}

更新前后都查询权限：确认真实所有者保留、目标成员权限符合预期；再用指定用户契约验证允许访问和禁止访问两种情况。若存在多个管理系统并发写入，应由集成方串行协调全量更新，避免较旧配置覆盖较新成员授权。

故障与重试边界

操作	结果未知时
创建组织/员工/知识库	按预设稳定编码回查，确认不存在后再决定重试
更新资料	查询实际字段后再决定是否重新提交
替换角色/权限	重新查询最新状态并合并，不重放过期快照
员工启停	查询当前 state，不重复切换
删除组织	核对目标及子级是否仍存在，不盲目重新级联

错误体按统一错误处理解析。所有接口受租户、角色和资源权限约束，管理员契约也不绕过合同和用户状态校验。

组织与部门​

创建与查询响应字段​

创建请求示例​

按编码查询​

删除组织或部门​

创建员工​

创建响应字段​

创建调用示例​

查询和更新员工​

员工列表请求字段​

员工列表响应​

员工更新请求与响应​

用户角色与停用​

创建知识库并保留外部编码​

初始化请求字段​

初始化响应字段​

知识库权限​

权限查询请求与响应​

权限更新请求与响应​

故障与重试边界​