Wiki 概念词条（KmsWikiConceptEntryController）

提供 KMS 知识管理模块 Wiki 概念词条 域的能力：词条及其 Markdown 正文的增删改查、热门/置顶列表、置顶/取消置顶、基于 RAG 的 AI 正文生成。对应库表 KMS_WIKI_CONCEPT_ENTRY。

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

公共说明

• 鉴权（据源码 KmsMvcConfig + KmsSecurityFilter，见 index.md「鉴权说明」）：本控制器路径 /api/kms/wiki/concept/entries/**、/kms/wiki/concept/entries/** 均不在 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 参数。
• 响应结构：除显式标注 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；ResourceNotFoundException → HTTP 404 / errcode=404；其他 Exception → HTTP 500 / errcode=500（详见 index.md「错误码补充」）。
• 路径变量：id 为 KMS_WIKI_CONCEPT_ENTRY.ID（明文主键，非 DES 加密密文）。
• 正文存储位置：词条 Markdown 正文落盘于 storage/kms/.wiki/conceptentry/{id}.md。

---

1. 词条列表

返回当前用户可见的全部词条列表。先按 IS_TOP 降序、TOP_SORT 降序，再按 entryName 升序。可按分类与状态过滤，均不填则返回全量。

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

请求参数

参数名	位置	类型	必填	说明
categoryId	query	string	否	分类 Id，过滤指定分类下的词条
status	query	int	否	状态过滤：0 草稿、1 正常、2 废弃；不填返回全部状态

请求示例

GET /api/kms/wiki/concept/entries?categoryId=__CATID__&status=1&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：List<KmsWikiConceptEntry>，元素结构见下方「词条对象结构」。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__ENTRYID__",
      "categoryId": "__CATID__",
      "entryName": "概念A",
      "entryAlias": "别名A",
      "description": "概念A 的简述",
      "owner": "张三",
      "viewCount": 12,
      "status": 1,
      "createDate": "2026-08-01T10:00:00.000+08:00",
      "updateDate": "2026-08-02T11:00:00.000+08:00",
      "isTop": true,
      "topSort": 5
    }
  ],
  "errors": null
}

词条对象结构（KmsWikiConceptEntry）：id（主键）、categoryId（分类Id）、entryName（全局唯一名称）、entryAlias（别名）、description（描述）、owner（所有者名称）、viewCount（浏览量）、status（0草稿/1正常/2废弃）、createDate/updateDate（服务端维护，入参忽略）、isTop（是否置顶）、topSort（置顶排序值，越大越靠前）。

---

2. 热门词条

按浏览量 viewCount 降序返回前 N 条热门词条。

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

请求参数

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

请求示例

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

响应

结构：统一 Resource。 data：List<KmsWikiConceptEntry>（结构同 #1）。

---

3. 置顶词条

仅返回 IS_TOP=1 的词条，按 topSort 降序、entryName 升序。

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

请求参数

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

请求示例

GET /api/kms/wiki/concept/entries/pinned?limit=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：List<KmsWikiConceptEntry>（结构同 #1）。

---

4. 词条详情

根据词条 Id 获取单个词条对象。词条不存在抛 ResourceNotFoundException（HTTP 404）。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id

请求示例

GET /api/kms/wiki/concept/entries/__ENTRYID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：KmsWikiConceptEntry（结构同 #1）。

---

5. 获取词条正文（Markdown）

读取词条 Markdown 正文文件（storage/kms/.wiki/conceptentry/{id}.md），文件不存在时返回空字符串。每次成功访问，库表对应记录的 VIEW_COUNT 自增 1。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id

请求示例

GET /api/kms/wiki/concept/entries/__ENTRYID__/body?accessToken=__TOKEN__ HTTP/1.1

响应

结构：纯文本 Markdown，非 Resource JSON。 Content-Type：text/markdown; charset=utf-8。 状态码：成功 200 OK；词条不存在抛 ResourceNotFoundException（HTTP 404，由全局异常处理器统一映射为 Resource JSON）。

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

# 概念A

概念A 的详细说明正文……

---

6. 新建词条正文

首次写入词条 Markdown 正文。若 {id}.md 已存在则失败（请改用更新接口 #7）。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id
body	body	object	否	JSON 对象，见下方请求体；不传时按 null 处理

请求体

{ "content": "# 概念A\n\n概念A 的正文……" }

请求示例

POST /api/kms/wiki/concept/entries/__ENTRYID__/body?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "content": "# 概念A\n\n概念A 的正文……" }

响应

结构：统一 Resource。 data：boolean，true 表示写入成功。

---

7. 更新词条正文

覆盖写入词条 Markdown 正文；若文件不存在则创建。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id
body	body	object	否	JSON 对象，见下方请求体；不传时按 null 处理

请求体

{ "content": "# 概念A（更新后）\n\n新的正文……" }

请求示例

PUT /api/kms/wiki/concept/entries/__ENTRYID__/body?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "content": "# 概念A（更新后）\n\n新的正文……" }

响应

结构：统一 Resource。 data：boolean，true 表示更新成功。

---

8. AI 生成词条正文

读取词条标题与描述，按 diskIds 调用 RagService 检索片段，经本机 llm-proxy 生成 Markdown，并覆盖写入 storage/kms/.wiki/conceptentry/{id}.md。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id
body	body	object	否	JSON 对象，见下方请求体

请求体

{ "diskIds": "__DISKID1__,__DISKID2__", "topK": 10 }

字段	类型	必填	说明
diskIds	string	是	网盘 Id 逗号分隔串，用于 RAG 检索范围；为空抛 InvalidRequestException（HTTP 400）
topK	int	否	向量检索条数，默认 10，最大 50

请求示例

POST /api/kms/wiki/concept/entries/__ENTRYID__/body/ai-generate?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "diskIds": "__DISKID1__,__DISKID2__", "topK": 10 }

响应

结构：统一 Resource。 data：String，AI 生成并落盘后的 Markdown 正文。

失败示例（diskIds 为空）：

{ "errcode": 400, "errmsg": "diskIds 不能为空（逗号分隔网盘 ID）", "data": null, "errors": null }

---

9. 新建词条

创建一条新词条。必填 categoryId、entryName；entryName 全局唯一。owner 可空，默认当前用户名称；viewCount 由服务端置 0。

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

请求参数

参数名	位置	类型	必填	说明
body	body	object	是	JSON 对象，见下方请求体

请求体

{
  "id": "__ENTRYID__",
  "categoryId": "__CATID__",
  "entryName": "概念A",
  "entryAlias": "别名A",
  "description": "概念A 的简述",
  "owner": "张三",
  "status": 1,
  "isTop": false,
  "topSort": 0
}

createDate/updateDate 为服务端只读字段（@JsonProperty(Access.READ_ONLY)），传不入库；viewCount 由服务端置 0。

请求示例

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

{ "categoryId": "__CATID__", "entryName": "概念A", "description": "概念A 的简述", "status": 1 }

响应

结构：统一 Resource。 data：新建后的 KmsWikiConceptEntry（结构同 #1）。

---

10. 更新词条

更新指定词条对象。浏览量 viewCount 不由此接口修改，保留原值。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id
body	body	object	是	JSON 对象（字段同 #9 请求体）

请求示例

PUT /api/kms/wiki/concept/entries/__ENTRYID__?accessToken=__TOKEN__ HTTP/1.1
Content-Type: application/json

{ "categoryId": "__CATID__", "entryName": "概念A-改名", "description": "更新后描述", "status": 1 }

响应

结构：统一 Resource。 data：更新后的 KmsWikiConceptEntry（结构同 #1）。

---

11. 删除词条（Query 形式）

通过 query 参数 id 删除词条（含其正文文件）。

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

请求参数

参数名	位置	类型	必填	说明
id	query	string	是	待删除词条主键Id

请求示例

DELETE /api/kms/wiki/concept/entries?id=__ENTRYID__&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示删除成功。

---

12. 删除词条（Path 形式）

通过路径变量 id 删除词条（含其正文文件）。语义与 #11 相同，仅参数位置不同。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	待删除词条主键Id

请求示例

DELETE /api/kms/wiki/concept/entries/__ENTRYID__?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：boolean，true 表示删除成功。

---

13. 置顶词条

将指定词条设置为置顶（IS_TOP=1），可同时指定 topSort；置顶条目中数字越大越靠前。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id
topSort	query	int	否	置顶排序值，不传默认为 1

请求示例

PUT /api/kms/wiki/concept/entries/__ENTRYID__/top?topSort=10&accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：更新后的 KmsWikiConceptEntry（结构同 #1，isTop=true、topSort 已写入）。

---

14. 取消置顶

将指定词条取消置顶（IS_TOP=0）。

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

请求参数

参数名	位置	类型	必填	说明
id	path	string	是	词条主键Id

请求示例

DELETE /api/kms/wiki/concept/entries/__ENTRYID__/top?accessToken=__TOKEN__ HTTP/1.1

响应

结构：统一 Resource。 data：更新后的 KmsWikiConceptEntry（结构同 #1，isTop=false）。

---