评论（CommentController）¶

提供文档评论/意见的能力：获取评论统计与列表、查看回复、新增评论、点赞/踩、删除评论等。本控制器所有端点均返回 JSON 资源。

接口类型：REST 资源（@RestController，基类 AbstractRuntimeController）
基址：${myapps.context-path.runtime:}/api/runtime/{applicationId}
Tag：评论模块

公共说明¶

鉴权（据源码 RuntimeMvcConfig + RestSecurityHandlerInterceptor）：拦截器注册到 /api/runtime/** 与 /api/rest/bpm/**，本控制器路径位于 /api/runtime/{applicationId}/...，不在豁免名单（豁免名单仅覆盖 /api/runtime/login.*、/api/runtime/dingding/authlogin、/api/runtime/synchronization.*、/runtime/sync/.* 等，详见 login.md「公共说明 · 鉴权」）。拦截器对非 /rest/ 路径走 Security.getUserIdFromToken(request)，未取到再尝试 Security.getDebugUserIdFromToken(request)，两者皆无则拒绝访问。因此所有端点均需 accessToken（或 debugToken），可通过 Cookie / 请求头 / query 参数任一方式传递。
路径变量 {applicationId}：必填，经 DES 加密（按当前执行用户密钥），服务端在方法入口处 DesUtil.decryptTextByUserId(applicationId, getUser().getId()) 解密。
明文 id：与 document.md 不同，本控制器下 {flag}、{commentId} 路径变量以及 formId、docId query 参数均为**明文**，不参与 DES 解密。
Comment 请求体：POST /flags/{flag}/comments 的 @RequestBody 为 CommentVO JSON 对象，主要字段：
```
{
  "comment": "<评论内容>",
  "parentId": "<父评论Id，回复时传入；顶层评论可空>"
}
```
服务端会自动补齐 applicationid、flag、domainid、userId、userName、avatar、createDate，调用方无需传这些字段。
响应结构：统一 Resource（见 ../index.md「统一响应结构」），字段为 errcode/errmsg/data/errors。errmsg 成功统一为 "ok"。
HTTP 状态码：所有端点均标注 @ResponseStatus(HttpStatus.OK)，成功返回 HTTP 200；业务结果由响应体 errcode 体现（错误码表见 ../index.md）。

1. 获取评论统计¶

根据评论标识（flag）获取评论数与点赞数。若该 flag 的统计记录不存在，会先创建一条空白统计记录。

接口类型：REST 资源
请求方式：GET
请求路径：/flags/{flag}/comments/count（完整：{runtime-context}/api/runtime/{applicationId}/flags/{flag}/comments/count）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
flag	path	string	是	评论标识（业务自定义，明文）

请求示例¶

GET /api/runtime/__APPID__/flags/doc-001/comments/count HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应¶

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：JSONObject，字段： - commentNum（int）：评论总数（按 flag + parentId="" 统计的顶层评论数）。 - likeNum（int）：点赞数。 - id（string）：统计记录（CommentVO）的主键。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": { "commentNum": 12, "likeNum": 3, "id": "__COMMENT_STAT_ID__" },
  "errors": null
}

2. 获取评论列表¶

根据评论标识（flag）查询该主题下的全部评论，并补齐评论者的头像。

接口类型：REST 资源
请求方式：GET
请求路径：/flags/{flag}/comments（完整：{runtime-context}/api/runtime/{applicationId}/flags/{flag}/comments）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
flag	path	string	是	评论标识（明文）

请求示例¶

GET /api/runtime/__APPID__/flags/doc-001/comments HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应¶

结构：统一 Resource。 data：Collection<CommentVO>（JSON 数组），元素含：id、comment（评论内容）、userId、userName、avatar（头像 URI）、likeNum、unlikeNum、parentId、flag、createDate 等。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__CID1__",
      "comment": "内容很赞",
      "userId": "__UID1__",
      "userName": "李伟",
      "avatar": "/uploads/avatar/u001.png",
      "likeNum": 3,
      "unlikeNum": 0,
      "parentId": "doc-001",
      "flag": "doc-001",
      "createDate": "2026-08-01 10:23:45"
    }
  ],
  "errors": null
}

3. 获取回复列表¶

根据评论 Id 查询其下所有回复（子评论），并补齐回复者头像。

接口类型：REST 资源
请求方式：GET
请求路径：/comments/{commentId}/answers（完整：{runtime-context}/api/runtime/{applicationId}/comments/{commentId}/answers）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
commentId	path	string	是	父评论Id（明文）

请求示例¶

GET /api/runtime/__APPID__/comments/__CID1__/answers HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应¶

结构：统一 Resource。 data：Collection<CommentVO>（JSON 数组），元素结构同「获取评论列表」。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": [
    {
      "id": "__CID2__",
      "comment": "同意",
      "userId": "__UID2__",
      "userName": "张敏",
      "avatar": "",
      "likeNum": 0,
      "unlikeNum": 0,
      "parentId": "__CID1__",
      "flag": "doc-001",
      "createDate": "2026-08-01 11:00:02"
    }
  ],
  "errors": null
}

4. 新增评论¶

在指定 flag 下创建评论或回复。评论落库后，若所在表单配置了「评论执行脚本」（commentExecuteScript），会以当前文档为上下文执行该脚本（脚本异常被吞，不影响评论创建结果）。

接口类型：REST 资源
请求方式：POST
请求路径：/flags/{flag}/comments（完整：{runtime-context}/api/runtime/{applicationId}/flags/{flag}/comments）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
flag	path	string	是	评论标识（明文）
formId	query	string	是	关联表单Id（明文，用于加载表单与执行评论脚本）
docId	query	string	是	关联文档Id（明文，作为脚本执行上下文）
comment	body	object(CommentVO)	是	评论对象（字段见下）

请求体¶

字段	类型	必填	说明
comment	string	是	评论内容
parentId	string	否	父评论Id；回复场景传入，顶层评论可空（缺省时服务端以 flag 作为 parentId）

{
  "comment": "回复：内容很赞",
  "parentId": "__CID1__"
}

请求示例¶

POST /api/runtime/__APPID__/flags/doc-001/comments?formId=__FORMID__&docId=__DOCID__ HTTP/1.1
Content-Type: application/json
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

{
  "comment": "回复：内容很赞",
  "parentId": "__CID1__"
}

响应¶

结构：统一 Resource。 data：CommentVO，创建后的评论对象（含服务端补齐的 id、userId、userName、avatar、createDate 等）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "id": "__NEWCID__",
    "comment": "回复：内容很赞",
    "userId": "__UID2__",
    "userName": "张敏",
    "avatar": "",
    "parentId": "__CID1__",
    "flag": "doc-001",
    "applicationid": "app-001",
    "createDate": "2026-08-04 09:12:30"
  },
  "errors": null
}

5. 点赞¶

对指定评论点赞（likeNum +1）。

接口类型：REST 资源
请求方式：PUT
请求路径：/comments/{commentId}/like（完整：{runtime-context}/api/runtime/{applicationId}/comments/{commentId}/like）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
commentId	path	string	是	评论Id（明文）

请求示例¶

PUT /api/runtime/__APPID__/comments/__CID1__/like HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应¶

结构：统一 Resource。 data：int，点赞后的最新点赞数。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": 4, "errors": null }

6. 觉得不行（踩）¶

对指定评论点踩（unlikeNum +1）。

接口类型：REST 资源
请求方式：PUT
请求路径：/comments/{commentId}/unlike（完整：{runtime-context}/api/runtime/{applicationId}/comments/{commentId}/unlike）
鉴权：是（需 accessToken，据源码）
Tag：评论模块

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
commentId	path	string	是	评论Id（明文）

请求示例¶

PUT /api/runtime/__APPID__/comments/__CID1__/unlike HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应¶

结构：统一 Resource。 data：int，点踩后的最新踩数。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": 1, "errors": null }

7. 删除评论¶

按评论 Id 数组批量删除评论。

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

请求参数¶

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id（DES 加密密文）
content	body	string	是	评论 Id 的 JSON 数组字符串

请求体¶

["__CID1__", "__CID2__"]

请求示例¶

DELETE /api/runtime/__APPID__/comments HTTP/1.1
Content-Type: application/json
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

["__CID1__", "__CID2__"]

响应¶

结构：统一 Resource。 data：null。

成功示例：

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }