文件 Wiki（KmsFileWikiController）

提供 KMS 知识管理模块 文件 Wiki 域的能力：按文件 checksum 查看/重新生成 Wiki Markdown 正文、获取/列举 Wiki 网盘与目录、向 Wiki 添加/移除文件、按网盘清空、按文件名查询与热门列表。对应库表 KMS_FILE_WIKI。

• 接口类型：REST 资源（@RestController，方法级 produces 多为 application/json；/view 与 /regenerate 返回 text/markdown）
• 基址：${myapps.context-path.kms:}/api/kms/wiki 与 ${myapps.context-path.kms:}/kms/wiki（类级 @RequestMapping 同时声明两个前缀，同一端点可经任一前缀访问；下文示例统一采用 /api/kms/wiki）
• Tag：kms wiki 模块

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter，见 index.md「鉴权说明」）：本控制器路径 /api/kms/wiki/**、/kms/wiki/** 均不在 KmsSecurityFilter.isExcludeURI 的豁免名单内，过滤器调用 Security.getUserIdFromToken(request)，取不到用户则返回 HTTP 401。所有端点均需 accessToken，可通过以下任一方式传递：query 参数 accessToken、query 参数 access_token（移动端）、请求头 accessToken、Cookie accessToken、请求头 Authorization: Bearer <token>。
• 执行用户：控制器内 getUser()（继承自 AbstractBaseController）调用 Security.getUserIdFromToken(request) 还原当前用户 id，再经 Feign 装载 KmsUser。无 userCode 参数。
• 响应结构：除 /view、/regenerate 返回 text/markdown 外，统一返回 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。注意：KMS 的 Resource 为 AbstractBaseController 内部类，其构造器对 data 执行 ESAPI.encode(data) 做 XSS 编码，故 data 中的 HTML 特殊字符会被转义。
• HTTP 状态码与错误码：成功默认 HTTP 200 / errcode=0；InvalidRequestException → HTTP 400 / errcode=400；其他 Exception → HTTP 500 / errcode=500（详见 index.md「错误码补充」）。
• checksum：文件校验码（明文 sha 字符串），用作 KMS_FILE_WIKI 文件维度的唯一索引。

---

1. 查看 Wiki 正文

按文件 checksum 返回 Wiki Markdown。.wiki.md 不存在时依次尝试 kms/.raw2md 摘要、从源文档重新抽取后通过 LLM 生成并落盘。成功访问后会对该 checksum 对应的 KMS_FILE_WIKI 记录 VIEW_COUNT 自增 1（无记录则不受影响）。

• 接口类型：REST 资源（文本响应，非 JSON）
• 请求方式：GET
• 请求路径：/view（完整：{kms-context}/api/kms/wiki/view）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms wiki 模块

请求参数

参数名	位置	类型	必填	说明
checksum	query	string	是	文件校验码（去空格后长度需 ≥ 2，否则抛 InvalidRequestException HTTP 400）

请求示例

GET /api/kms/wiki/view?checksum=__CHECKSUM__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：纯文本 Markdown，非 Resource JSON。 Content-Type：text/markdown; charset=utf-8。 状态码：成功 200 OK。

成功示例（响应体为原始 Markdown 文本）：

# 文件标题

文件内容的 Wiki 摘要……

失败示例（checksum 无效）：HTTP 400，响应体为 Resource JSON

{ "errcode": 400, "errmsg": "checksum 无效（至少 2 个字符）", "data": null, "errors": null }

---

2. 重新生成 Wiki 正文

按 checksum 从 kms/.raw2md 摘要（或源文档重抽文本）调用 LLM 生成并覆盖写入 .wiki.md；AI 不可用则写入固定占位文案。若该 checksum 已登记 KMS_FILE_WIKI，则同步刷新 CREATE_DATE；并在落盘后更新 wiki 向量索引（不增加 view_count）。

• 接口类型：REST 资源（文本响应，非 JSON）
• 请求方式：POST
• 请求路径：/regenerate（完整：{kms-context}/api/kms/wiki/regenerate）
• 鉴权：是（需 accessToken，据源码）
• Tag：kms wiki 模块

请求参数

参数名	位置	类型	必填	说明
checksum	query	string	是	文件校验码（去空格后长度需 ≥ 2，否则抛 InvalidRequestException HTTP 400）

请求示例

POST /api/kms/wiki/regenerate?checksum=__CHECKSUM__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：纯文本 Markdown，非 Resource JSON。 Content-Type：text/markdown; charset=utf-8。 状态码：成功 200 OK。

成功示例（响应体为重新生成后的 Markdown 文本）：

# 文件标题（重新生成）

基于 RAG 与 LLM 重写的 Wiki 摘要……

失败示例（checksum 无效）：HTTP 400，响应体为 Resource JSON

{ "errcode": 400, "errmsg": "checksum 无效（至少 2 个字符）", "data": null, "errors": null }

---

3. 获取 WIKI 网盘

返回当前用户企业域下的 WIKI 网盘（ownerId = <domainid>_wiki），所有已登录用户可见；网盘不存在则自动创建。

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

请求参数

无。

请求示例

GET /api/kms/wiki/disk?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：单个 Disk 网盘对象（含 id、name、ownerId 等字段）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "id": "__WIKIDISKID__", "name": "Wiki 网盘", "ownerId": "__DOMAINID___wiki" },
  "errors": null
}

---

4. 根据 folderId 获取直接子目录集合

列出指定目录（或网盘根，根 id 同 diskId）下一级子文件夹。返回原始实体列表，不设置 operations 等扩展字段。

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

请求参数

参数名	位置	类型	必填	说明
folderId	path	string	是	文件夹Id（也支持网盘Id：当 folderService 未命中而 diskService 命中时，会先确保根目录再列出）

请求示例

GET /api/kms/wiki/folders/__FOLDERID__/path/list?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<FolderEntity>，仅含类型为文件夹的子项（isFolder=true）；folderId 为空或既非文件夹又非网盘时返回空数组。

---

5. 目录下的文件列表

分页查询指定网盘下指定文件夹内的文件列表。仅返回文件，不含子目录；直接返回服务层 DataPackage，未经 DataBuilder 包装，不设置 operations、收藏、AI 等扩展字段。

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

请求参数

参数名	位置	类型	必填	说明
diskId	path	string	是	网盘Id
folderId	path	string	是	文件夹Id
fileName	query	string	否	文件名过滤关键字
orderByfield	query	string	是	排序字段
orderMode	query	string	是	排序模式（ASC/DESC）
pageNo	query	int	是	页码，从 1 开始
linesPerPage	query	int	是	每页条数

请求示例

GET /api/kms/wiki/__DISKID__/folders/__FOLDERID__/files?pageNo=1&linesPerPage=20&orderByfield=LAST_MODIFY_DATE&orderMode=DESC&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：DataPackage<FileObject>，已过滤掉子目录，仅含文件。

---

6. 为 Wiki 添加文件

按 file_id 与/或 folder_id 批量添加文件到 Wiki 范围（均支持逗号分隔多个 Id）。同一 file_checksum 已存在则计为 skipped。

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

请求参数

参数名	位置	类型	必填	说明
file_id	query	string	否	文件Id（逗号分隔多个；与 folder_id 至少传其一，否则抛 InvalidRequestException HTTP 400）
folder_id	query	string	否	文件夹Id（逗号分隔多个；会递归收集其下文件）

请求示例

POST /api/kms/wiki/add?file_id=__FID1__,__FID2__&folder_id=__FOLDERID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：AddResult 对象 { "created": <int>, "skipped": <int> }，分别表示本次新建条数与因 checksum 重复跳过的条数。

---

7. 从 Wiki 移除文件

按 file_id 与/或 folder_id 批量从 Wiki 范围移除文件（均支持逗号分隔多个 Id）。

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

请求参数

参数名	位置	类型	必填	说明
file_id	query	string	否	文件Id（逗号分隔多个；与 folder_id 至少传其一）
folder_id	query	string	否	文件夹Id（逗号分隔多个）

请求示例

POST /api/kms/wiki/remove?file_id=__FID1__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：RemoveResult 对象 { "removed": <int>, "notFound": <int> }，分别表示本次成功移除条数与未在 Wiki 中找到的条数。

---

8. 按网盘清空 Wiki 范围

删除指定网盘下、与头版本文件（按 checksum 匹配）相关的全部 KMS_FILE_WIKI 记录。

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

请求参数

参数名	位置	类型	必填	说明
disk_id	query	string	是	网盘Id；为空抛 InvalidRequestException（HTTP 400）

请求示例

POST /api/kms/wiki/clear?disk_id=__DISKID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：ClearBody 对象 { "deleted": <long> }，表示本次删除的记录数。

---

9. 查询 Wiki 文件列表

按网盘 Id 必填查询该网盘下登记到 Wiki 的文件列表；可选 file_name 按头版本文件名模糊匹配（不区分大小写）。

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

请求参数

参数名	位置	类型	必填	说明
disk_id	query	string	是	网盘Id；为空抛 InvalidRequestException（HTTP 400）
file_name	query	string	否	文件名关键字（模糊、不区分大小写）

请求示例

GET /api/kms/wiki/list?disk_id=__DISKID__&file_name=报告&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<KmsFileWikiListItem>，每项结构：{ "id": <String>, "fileChecksum": <String>, "createDate": <Date>, "fileId": <String>, "fileName": <String> }。

---

10. 热门 Wiki 文件

返回当前企业域 Wiki 网盘（与 #3「获取 WIKI 网盘」一致；不存在则自动创建）下，按 KMS_FILE_WIKI.VIEW_COUNT 降序的前 N 条热门文件。响应项结构与 #9 /list 相同。

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

请求参数

参数名	位置	类型	必填	说明
limit	query	int	否	返回条数，默认 20，最大 500

请求示例

GET /api/kms/wiki/hot?limit=20&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<KmsFileWikiListItem>（结构同 #9）。

---