获取动态详情

1. 接口定位

• 接口名称: 获取动态详情
• 所属域: chat/moments
• 业务目标: 按动态 ID 获取单条动态详情

2. 请求定义

• Method: POST
• Path: /chatx/moments/post/detail
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，请通过 Header token 传入有效登录令牌
• 幂等性: 幂等（只读接口）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	用户登录 token

Body 参数

字段	必填	类型	说明
postID	是	string	动态 ID

字段说明

• API 层会在转发前把当前登录用户的 callerUserID 注入请求体，客户端无需传入。
• 当前实现按 postID + delete_time=nil 取单条动态。
• 服务端会先按审核状态与调用者身份做鉴权：作者可查看自己的任意审核状态动态；非作者仅可查看 approved 动态。
• 对非作者动态，服务端会再基于 callerUserID 与发帖人关系校验可见性；无权限时返回无权限错误。
• 当前实现会在返回前补齐点赞数、评论数、是否点赞、作者资料和评论预览。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
post	object	动态详情

post 对象

字段	类型	说明
postID	string	动态 ID
userID	string	发布者用户 ID
content	string	文本内容
mediaURLs	array<string>	媒体 URL 列表
visibility	int32	动态可见性原始值
createTime	int64	创建时间，毫秒时间戳
likeCount	int64	点赞数
commentCount	int64	评论总数
isLiked	bool	当前调用者是否已点赞
author	object	发布者公开资料
commentPreview	array<object>	最新评论预览，最多 3 条，按新到旧返回
commentPreviewCursor	string	评论预览继续向后翻页的游标

author 或 commenter 对象

字段	类型	说明
userID	string	用户 ID
nickname	string	昵称
faceURL	string	头像 URL

commentPreview 对象

字段	类型	说明
commentID	string	评论 ID
postID	string	所属动态 ID
userID	string	评论人用户 ID
replyToCommentID	string	回复目标评论 ID
content	string	评论内容
createTime	int64	创建时间，毫秒时间戳
commenter	object	评论人公开资料

5. 业务规则

• 路由统一要求 token。
• API 层会把当前登录用户写入 callerUserID，用于计算 isLiked。
• 数据库按 postID 查询未删除动态。
• 查询到动态后会执行鉴权：作者可见全部审核状态；非作者仅可见 approved。
• 对非作者 approved 动态，再执行 visibility 鉴权：好友可见 friends/public，非好友仅可见 public。
• 评论预览最多返回 3 条，顺序为新到旧。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	Header 缺少 token	token is empty
1001	postID 为空	postID is required
-	动态不存在或已删除	由数据库层返回
-	查询用户公开资料失败	由用户资料查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/moments/post/detail", {
  method: "POST",
  headers: {
    operationID: "moments-post-detail-001",
    token: "user-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    postID: "p_10001",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "postID": "p_10001"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "post": {
      "postID": "p_10001",
      "userID": "u_1001",
      "content": "第一条动态",
      "mediaURLs": [],
      "visibility": 1,
      "createTime": 1774920300000,
      "likeCount": 1,
      "commentCount": 2,
      "isLiked": true,
      "author": {
        "userID": "u_1001",
        "nickname": "Alice",
        "faceURL": "https://cdn.example.com/avatar/a.png"
      },
      "commentPreview": [],
      "commentPreviewCursor": ""
    }
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "postID is required"
}

8. 时序流程

1. 校验 operationID 和 token。
2. API 层解析 token，并把当前用户写入 callerUserID。
3. 服务端 校验 postID。
4. 数据库取回动态主体。
5. 服务端 先校验审核状态与调用者身份（作者放行，非作者仅 approved）。
6. 服务端 再校验调用者是否可见该动态。
7. 服务端 聚合点赞、评论、作者资料和评论预览。
8. 返回 post 详情。

9. 变更记录

• 2026-03-31: 首版发布，基于 chatx moments API、协议定义和 服务端、数据库实现整理。
• 2026-06-01: 补充审核态规则：作者可查看任意审核状态，非作者仅可查看审核通过动态。