标签（CategoryController）¶

提供 KMS 知识管理模块「分类/标签域」的管理能力：标签的批量新建、删除、更新、获取父级标签集合、获取标签树、按 Id 获取标签、获取标签集合、获取各标签下文件数量。所有端点均返回 JSON 资源。

接口类型：REST 资源（@RestController，类级与所有方法级 produces = MediaType.APPLICATION_JSON_VALUE）
基址：${myapps.context-path.kms:}/api/kms 与 ${myapps.context-path.kms:}/kms（类级 @RequestMapping 同时声明两个前缀，同一端点可经任一前缀访问；与 FileController 一致；下文示例统一采用 /api/kms）
Tag：kms标签模块

公共说明¶

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

1. 批量新建标签¶

按传入的标签名列表批量新建标签。请求体为 JSON 对象，name 字段为字符串数组（标签名列表）；逐个创建，单个失败时收集错误信息后整体抛出 InvalidRequestException（HTTP 400）。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	object	是	JSON 对象，含 `name` 字段（字符串数组）

请求体¶

{ "name": ["标签1", "标签2", "标签3"] }

请求示例¶

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

{ "name": ["标签1", "标签2"] }

响应¶

结构：统一 Resource。 data：List<Category>，已成功创建的标签数组。

失败示例（名称列表为空）：

{ "errcode": 400, "errmsg": "标签数据为空", "data": null, "errors": null }

失败示例（部分创建失败）：

{ "errcode": 400, "errmsg": "<异常消息>,无法创建,其他标签已经创建", "data": null, "errors": null }

2. 删除标签¶

按标签 Id 数组批量删除标签。

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

请求参数¶

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

请求体¶

["__CATID1__", "__CATID2__"]

请求示例¶

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

["__CATID1__", "__CATID2__"]

响应¶

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

3. 更新标签¶

更新指定标签的名称与父级 Id（仅更新 name、parentId 两个字段）。先按请求体 id 取出既有标签，再覆盖这两个字段后落库。

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

请求参数¶

参数名	位置	类型	必填	说明
body	body	object	是	`Category` 对象 JSON，需含 `id`、`name`、`parentId`

请求体¶

{ "id": "__CATID__", "name": "新标签名", "parentId": "__PARENTID__" }

请求示例¶

PUT /api/kms/categorys?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "id": "__CATID__", "name": "新标签名", "parentId": "__PARENTID__" }

响应¶

结构：统一 Resource。 data：更新后的 Category。

4. 获取父级标签集合¶

返回当前用户企业域下可作为父级的标签集合。

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

请求参数¶

无。

请求示例¶

GET /api/kms/categorys/parent?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：List<Category>，父级标签集合。

5. 获取标签树¶

返回当前用户企业域下的标签树结构。

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

请求参数¶

无。

请求示例¶

GET /api/kms/categorys/tree?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：List<Map<String, Object>>，标签树节点数组（由 service.getCaregorysTree 构造）。

6. 获取标签¶

按标签 Id 获取单个标签详情，含父标签名称。

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

请求参数¶

参数名	位置	类型	必填	说明
id	path	string	是	标签Id

请求示例¶

GET /api/kms/categorys/__CATID__?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：Map<String, String>，字段为 id/name/parentId/domainId/parentName（父标签不存在时 parentName 为空串 ""）。

7. 获取标签集合¶

返回当前用户企业域下的全部标签集合。

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

请求参数¶

无。

请求示例¶

GET /api/kms/categorys?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：List<Category>，标签集合。

8. 获取标签的文件数量¶

按当前用户企业域统计每个标签下关联的文件数量。

接口类型：REST 资源
请求方式：GET
请求路径：/categorys/files/count（完整：{kms-context}/api/kms/categorys/files/count）
鉴权：是（需 accessToken，据源码）
Tag：kms标签模块

请求参数¶

无。

请求示例¶

GET /api/kms/categorys/files/count?accessToken=__TOKEN__ HTTP/1.1

响应¶

结构：统一 Resource。 data：List<CategoryFileCount>，每项含标签信息及其关联文件数量（据源码，由 service.listFileCategoryCountByDomainid(domainid) 提供）。