授权（AuthorizationController）

提供 KMS 知识管理模块「授权域」的能力：按资源查询授权列表、为资源创建/更新授权、按授权 Id 批量删除授权。所有端点均返回统一 Resource 封装。

• 接口类型：REST 资源（@RestController，类级与方法级 produces = MediaType.APPLICATION_JSON_VALUE）
• 基址：${myapps.context-path.kms:}/api/kms
• Tag：kms授权模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter）：KmsMvcConfig 注册全局 Servlet 过滤器 KmsSecurityFilter（URL 模式 /*，context-path 为 / 时为 /kms/*）。本控制器路径 /api/kms/resources/{resourceId}/authorizations、/api/kms/authorizations 均不在 KmsSecurityFilter.isExcludeURI 的豁免名单内（豁免仅覆盖 /login.*、/admin、/domain.*、/tray/service、/authtime、service/OfficeServer、.*outsideshare/.*/preview、静态资源后缀、actuator/health 等），亦不匹配 S3 数据面前缀。过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401（无响应体）。因此所有端点均需 accessToken，可通过以下任一方式传递：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。完整鉴权机制见 index.md「鉴权说明」。
• 执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign（UserAPI.getUserById）装载 KmsUser。无 userCode 参数。
• 响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故 data 中的 HTML 特殊字符会被转义。
• HTTP 状态码与错误码（据源码 AbstractBaseController 全局异常处理）：成功 HTTP 200；InvalidRequestException（如 authorization.resourceId 与路径 resourceId 不一致）→ HTTP 400 / errcode=400；UnauthorizedException → HTTP 403 / errcode=403；ForbiddenException → HTTP 403 / errcode=403；ResourceNotFoundException → HTTP 404 / errcode=404；其他 Exception → HTTP 500 / errcode=500。
• 路径变量：resourceId、authorizationId 均为 KMS 内部主键（明文 id），非 DES 加密密文。

---

1. 根据资源获取授权列表

按资源 Id 分页查询该资源下已有的授权记录。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/resources/{resourceId}/authorizations（完整：{kms-context}/api/kms/resources/{resourceId}/authorizations）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms授权模块

请求参数

参数名	位置	类型	必填	说明
resourceId	path	string	是	资源Id（文件/文件夹 Id）
pageNo	query	int	是	页码（无 defaultValue，必填）
linesPerPage	query	int	是	每页条数（无 defaultValue，必填）

请求示例

GET /api/kms/resources/__RESOURCEID__/authorizations?pageNo=1&linesPerPage=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<Authorization>，该资源下的授权分页数据。

---

2. 创建授权信息

为指定资源创建一条授权记录。服务端先校验 authorization.resourceId 与路径 resourceId 一致，不一致抛 InvalidRequestException（HTTP 400）；再将当前用户写入 creator/creatorId/domainId 与 createDate，调用 authorizationService.create 持久化。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/resources/{resourceId}/authorizations（完整：{kms-context}/api/kms/resources/{resourceId}/authorizations）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms授权模块

请求参数

参数名	位置	类型	必填	说明
resourceId	path	string	是	资源Id
body	body	object	是	Authorization 对象 JSON，body.resourceId 必须与路径 resourceId 一致

请求体

{
  "resourceId": "__RESOURCEID__",
  "operations": 1,
  "userId": "__TARGETUSERID__"
}

请求示例

POST /api/kms/resources/__RESOURCEID__/authorizations?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "resourceId": "__RESOURCEID__", "operations": 1, "userId": "__TARGETUSERID__" }

响应

结构：统一 Resource。 data：创建后的 Authorization 实体（IEntity）。

失败示例（resourceId 不一致）：

{ "errcode": 400, "errmsg": "请求参数有误", "data": null, "errors": null }

---

3. 更新授权信息

按资源 Id 与授权 Id 更新一条授权记录。服务端先按 authorization.id 查找既有记录，再调用 authorizationService.update 更新。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/resources/{resourceId}/authorizations/{authorizationId}（完整：{kms-context}/api/kms/resources/{resourceId}/authorizations/{authorizationId}）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms授权模块

请求参数

参数名	位置	类型	必填	说明
resourceId	path	string	是	资源Id
authorizationId	path	string	是	授权Id（路径占位；实际以 body 中的 authorization.id 为准）
body	body	object	是	Authorization 对象 JSON

请求体

{
  "id": "__AUTHORIZATIONID__",
  "resourceId": "__RESOURCEID__",
  "operations": 3
}

请求示例

PUT /api/kms/resources/__RESOURCEID__/authorizations/__AUTHORIZATIONID__?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "id": "__AUTHORIZATIONID__", "resourceId": "__RESOURCEID__", "operations": 3 }

响应

结构：统一 Resource。 data：更新后的 Authorization 实体（IEntity）。

---

4. 删除授权信息

按授权 Id 数组批量删除授权记录。服务端遍历数组逐个调用 authorizationService.delete。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/authorizations（完整：{kms-context}/api/kms/authorizations）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms授权模块

请求参数

参数名	位置	类型	必填	说明
body	body	array(string)	是	待删除授权Id数组

请求体

["__AUTHORIZATIONID1__", "__AUTHORIZATIONID2__"]

请求示例

DELETE /api/kms/authorizations?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

["__AUTHORIZATIONID1__", "__AUTHORIZATIONID2__"]

响应

结构：统一 Resource。 data：boolean，固定为 true。

---