txagent-y/docs/dev/api/API-10-搜索通知举报.md

API-10 搜索·通知·举报·反馈（SEARCH + NOTI + REPORT + FEEDBACK + HISTORY）

共 10 个接口：SEARCH-01~02 + NOTI-01~03 + REPORT-01~02 + FEEDBACK-01 + HISTORY-01~02

注： 搜索历史由客户端本地存储，后端不提供读写接口（原 SEARCH-03/04 已下线）。

---

搜索系统（search）

SEARCH-01 综合搜索

项目	说明
接口路径	GET /client/api/v1/search
接口用途	按关键词搜索用户 / 帖子 / 标签（对应搜索页 4 个 tab）
权限要求	需登录
涉及表	user, user_profile, post, post_media, tag, user_follow, search_trending

接口逻辑：

1. 接收搜索关键词（前端 300ms 防抖），后端会 trim 前后空格；校验 type 合法后，将关键词记录到服务内存聚合器，后台默认每 2 分钟批量写入 search_trending 并累加 search_count；若待写入搜索 hit 达到 1000 次或不同关键词达到 1000 个，会提前异步 flush（统计写入失败或瞬时超出 4096 个不同关键词聚合上限不影响搜索结果返回）
2. 按 type 分流：
   • type=users：在 user（普通用户 + 创作者）+ user_profile 中模糊匹配 username / display_name / user_no；分页，仅返回 active 且未删除用户
   • type=posts：在 post（status=published, deleted_at IS NULL）中模糊匹配 title；排序：匹配度 > 点赞数 > 发布时间；关联 post_media 取封面/时长、user 取创作者；分页
   • type=tags：在 tag 中模糊匹配 name，附带 post_count 冗余字段；按 post_count 倒序；分页
   • type=all（默认）：并行执行上述三段，每段固定 limit（users=3, posts=10, tags=10），忽略 page/pageSize
3. 用户段返回 isCreator；创作者用户会补充当前用户视角的 isFollowing、followerCount、postCount，普通用户这些创作者指标返回零值 / false
4. 搜索历史不写后端，由客户端本地保存；后端只异步沉淀聚合后的搜索词和次数，不提供个人搜索历史读写

请求参数（Query）：

字段	类型	必选	说明
keyword	string	是	搜索关键词
type	string	否	all（默认）/ users / posts / tags
page	number	否	页码，默认 1（type=all 时忽略）
pageSize	number	否	每页条数，默认 20（type=all 时忽略）

响应数据：

顶层结构按 type 决定返回哪些段；type=all 时三段齐全，其他 type 仅返回对应段。

字段	类型	说明
users	object/null	用户段（type=users 或 all 时存在）
users.list	array	用户列表，包含普通用户和创作者
users.list[].userId	string	用户 ID
users.list[].userNo	string	9 位用户编号
users.list[].nickname	string	昵称
users.list[].avatar	url	头像
users.list[].description	string	简介；创作者优先返回创作者简介，普通用户返回用户简介
users.list[].isCreator	boolean	是否创作者
users.list[].followerCount	number	粉丝数；普通用户为 0
users.list[].postCount	number	内容数；普通用户为 0
users.list[].isFollowing	boolean	当前用户是否已关注；普通用户为 false
users.pagination	object	分页信息
posts	object/null	帖子段（type=posts 或 all 时存在）
posts.list	array	帖子列表，字段与 CONTENT-02 列表项一致
posts.list[].postId	string	帖子 ID
posts.list[].title	string	标题
posts.list[].type	string	post / video
posts.list[].coverUrl	url	封面图
posts.list[].blurCoverUrl	url	模糊封面（锁定态使用）
posts.list[].duration	number	时长（秒，视频类）
posts.list[].isLocked	boolean	是否锁定（需订阅/付费）
posts.list[].visibility	number	0=免费 1~4=付费档位
posts.list[].visibilityTierName	string	档位名称
posts.list[].likeCount	number	点赞数
posts.list[].creator	object	创作者简要信息（userId/nickname/avatar）
posts.pagination	object	分页信息
tags	object/null	标签段（type=tags 或 all 时存在）
tags.list	array	标签列表
tags.list[].tagName	string	标签名（不带 #）
tags.list[].postCount	number	关联内容数
tags.pagination	object	分页信息

---

SEARCH-02 获取热门搜索词

项目	说明
接口路径	GET /client/api/v1/search/trending
接口用途	获取热门搜索词列表（搜索历史页底部「热门搜索」chips）
权限要求	公开
涉及表	search_trending

接口逻辑：

1. 客户端接口读取服务内存缓存，不每次直查数据库
2. 服务启动时从 search_trending 加载热搜词，之后每 2 分钟自动刷新一次；刷新失败保留旧缓存
3. 缓存数据来源：search_trending 表中 is_hot=1 AND is_active=1 AND deleted_at IS NULL 的词
4. 排序：运营手动词 is_manual=1 优先，按 sort_order ASC；自动热词按 search_count DESC；再按 updated_at DESC, id ASC 兜底，取前 10
5. search_count 由搜索接口异步聚合写入，默认每 2 分钟批量落库，待写入搜索 hit 达到 1000 次或不同关键词达到 1000 个时提前 flush；接口缓存仍按 2 分钟刷新节奏展示，搜索量很低时展示延迟可能接近 4 分钟

请求参数： 无

响应数据：

字段	类型	说明
keywords	string[]	热门搜索词列表（最多 10 个）

---

通知系统（notification）

relatedId 语义说明

type	relatedType	relatedId 含义
like	post	被点赞的内容 ID（post._id）
comment	post	被评论的内容 ID（post._id）
mention	post	@ 提及所在的内容 ID（post._id）
creator_publish	post	创作者新发布内容 ID（post._id）
publish_success	post	UP 主自己发布成功的内容 ID（post._id）
publish_success	media	视频上传处理完成并进入待审核的媒体 ID（media.id）
system	media	分片视频异步处理失败的媒体 ID（media.id）
follow	user	关注者的用户 ID（user._id）
subscription	user	订阅者的用户 ID（user._id）
purchase	order	订阅订单 ID（subscription_order._id）
ppv_unlock	order	PPV 消息 ID（ppv_message._id）
system	—	null（系统通知无关联对象）

NOTI-01 获取通知列表

项目	说明
接口路径	GET /client/api/v1/notification/list
接口用途	获取通知中心消息
权限要求	需登录
涉及表	notification, user

接口逻辑：

1. 查询 notification 表（user_id 匹配，按 created_at 倒序）
2. 支持按 category 筛选（interaction/subscription/system）
3. 相同类型聚合（如"XXX等3人点赞了你的内容"）
4. 关联 user 表 获取触发者信息

请求参数（Query）：

字段	类型	必选	说明
category	string	否	分类：all/interaction/subscription/system，默认all
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	通知列表
list[].notificationId	string	通知ID
list[].category	string	分类
list[].type	string	具体类型：like/comment/mention/creator_publish/publish_success/subscription/follow/purchase/ppv_unlock/system
list[].title	string	通知标题
list[].content	string	通知内容
list[].sender	object/null	触发者信息
list[].sender.userId	string	触发者ID
list[].sender.nickname	string	昵称
list[].sender.avatar	url	头像
list[].coverUrl	url	关联内容封面；当 relatedType=post 且可解析到内容封面时返回
list[].relatedId	string	关联对象ID（含义见下表）
list[].relatedType	string	关联类型：post/user/order/media
list[].isRead	boolean	是否已读
list[].createdAt	timestamp	创建时间
pagination	object	分页信息

---

NOTI-02 标记已读

项目	说明
接口路径	PUT /client/api/v1/notification/read
接口用途	标记通知为已读（单条/全部）
权限要求	需登录
涉及表	notification

接口逻辑：

1. 如果传了 notificationIds，更新指定通知的 is_read=1
2. 如果传了 category，更新该分类所有通知的 is_read=1
3. 如果都不传，更新该用户所有通知的 is_read=1

请求参数（Body）：

字段	类型	必选	说明
notificationIds	string[]	否	通知ID数组（不传表示全部标记）
category	string	否	按分类标记全部已读

响应数据：

字段	类型	说明
readCount	number	本次标记已读的数量

---

NOTI-03 获取未读数

项目	说明
接口路径	GET /client/api/v1/notification/unread-count
接口用途	获取各分类的未读通知数
权限要求	需登录
涉及表	notification

接口逻辑：

1. 聚合查询 notification 表（user_id 匹配，is_read=0），按 category 分组 count

请求参数： 无

响应数据：

字段	类型	说明
total	number	总未读数
interaction	number	互动未读数
subscription	number	订阅未读数
system	number	系统未读数

---

浏览历史（history）

HISTORY-01 获取浏览历史

项目	说明
接口路径	GET /client/api/v1/history/views
接口用途	获取用户的内容浏览历史
权限要求	需登录
涉及表	view_history, post, user, media

接口逻辑：

1. 查询 view_history 表 WHERE user_id=当前用户，按 last_viewed_at 倒序，分页（读）
2. 关联查询 post 表 获取帖子信息（读）
3. 关联查询 user 表 获取创作者信息（读）
4. 关联查询 media 表 获取封面/缩略图（读）
5. 返回浏览历史列表

请求参数（Query）：

字段	类型	必选	说明
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	浏览记录列表
list[].postId	string	帖子ID
list[].title	string	帖子标题
list[].coverUrl	url	封面图URL
list[].type	string	内容类型：post/video
list[].creator	object	创作者信息
list[].creator.userId	string	创作者ID
list[].creator.nickname	string	昵称
list[].creator.avatar	url	头像
list[].lastViewedAt	timestamp	最后浏览时间
pagination	object	分页信息

---

HISTORY-02 清除浏览历史

项目	说明
接口路径	DELETE /client/api/v1/history/views
接口用途	清除用户的浏览历史
权限要求	需登录
涉及表	view_history

接口逻辑：

1. 软删除 view_history 表 中该用户的所有记录（批量更新 deleted_at=当前时间）

请求参数： 无

响应数据：

字段	类型	说明
success	number	1=成功

---

举报系统（report）

REPORT-01 举报内容

项目	说明
接口路径	POST /client/api/v1/report/content
接口用途	用户举报不当内容（苹果审核要求）
权限要求	需登录
涉及表	report

接口逻辑：

1. 校验被举报内容存在（读 post 表）
2. 检查是否重复举报（同一用户对同一内容）
3. 优先读取 imageMediaIds，查询 media 表校验媒体存在、归属当前用户、已处理完成且为图片（读）
4. 若未传 imageMediaIds，兼容读取旧字段 images
5. 写入 report 表（type=content/user，status=1待处理，images 保存举报截图 URL 列表）；同一用户对同一对象已有待处理举报时，返回原举报记录并更新最新原因、说明和截图

请求参数（Body）：

字段	类型	必选	说明
targetId	string	是	被举报对象ID
targetType	string	是	举报对象类型：content/user
reason	string	是	举报类型：porn/violence/harassment/fraud/other
description	string	否	补充说明
imageMediaIds	string[]	否	新字段，举报截图媒体 ID 列表；优先于 images 生效
images	string[]	否	旧字段，举报截图 URL 列表（兼容保留，deprecated）

响应数据：

字段	类型	说明
reportId	string	举报记录ID
message	string	"举报已提交，平台将通过机器审核+人工审核处理"

---

REPORT-02 举报IM消息

项目	说明
接口路径	POST /client/api/v1/report/message
接口用途	用户举报私信中的不当消息（苹果审核要求）
权限要求	需登录
涉及表	report, message

接口逻辑：

1. 校验被举报消息存在且用户是该会话参与者（读 message + conversation）
2. 检查是否重复举报
3. 写入 report 表（type=message，status=1待处理）；同一用户对同一消息已有待处理举报时，返回原举报记录并更新最新原因、说明

请求参数（Body）：

字段	类型	必选	说明
messageId	string	是	被举报消息ID
reason	string	是	举报类型：porn/violence/harassment/fraud/other
description	string	否	补充说明

响应数据：

字段	类型	说明
reportId	string	举报记录ID
message	string	"举报已提交"

---

反馈系统（feedback）

FEEDBACK-01 提交帮助与反馈

项目	说明
接口路径	POST /client/api/v1/feedback
接口用途	用户在“我的 > 帮助与反馈”页提交问题描述和截图
权限要求	需登录
涉及表	user_feedback

接口逻辑：

1. 从登录 token 解析当前用户 userId
2. 校验 description 非空，去掉首尾空白
3. 优先读取 imageMediaIds，查询 media 表校验媒体存在、归属当前用户、已处理完成且为图片（读）
4. 若未传 imageMediaIds，兼容读取旧字段 images
5. 对最终图片列表做空串过滤
6. 写入 user_feedback 表，保存 user_id / description / images

请求参数（Body）：

字段	类型	必选	说明
description	string	是	反馈描述
imageMediaIds	string[]	否	新字段，反馈截图媒体 ID 列表；优先于 images 生效
images	string[]	否	旧字段，反馈截图 URL 列表（兼容保留，deprecated）

响应数据：

字段	类型	说明
feedbackId	string	反馈记录 ID

---

异常日志（error-log）

ERRORLOG-01 上报客户端异常日志

项目	说明
接口路径	POST /client/api/v1/uploadlogs
接口用途	客户端在出现白屏、崩溃、接口异常等问题时，上报错误内容和运行环境，供后台排查
权限要求	公开（可未登录调用）；若请求头带有效 Bearer Token，则自动关联当前用户
涉及表	client_error_log

接口逻辑：

1. 对 deviceId、contents、appVersion、osType、stack 做首尾空白裁剪
2. 校验 deviceId、contents 必填；deviceId 最大 128 字符，appVersion/osType 最大 32 字符
3. 不做服务端去重；每次调用都单独写入一条 client_error_log
4. 若请求头带有效 Bearer Token，则从 token 解析 userId 并写入；否则 user_id 为空
5. 返回新写入的日志 ID

说明：

1. 请求体不接受 userId、username 等显式用户字段，用户关联只信登录态 token。
2. stack 为可选字段，若客户端有堆栈信息应尽量完整上传。

请求参数（Body）：

字段	类型	必选	说明
deviceId	string	是	设备号，用于后台按设备维度排查
contents	string	是	异常摘要/错误内容
appVersion	string	否	App 版本号
osType	string	否	系统类型，如 ios / android / h5
stack	string	否	异常堆栈或补充诊断信息

请求示例：

{
  "deviceId": "qa-uploadlogs-dev-20260420-001",
  "contents": "App launch blank screen on boot",
  "appVersion": "9.9.1-test",
  "osType": "ios",
  "stack": "Error: bootstrap failed\n    at App.start (app.js:42)\n    at main (index.js:7)"
}

响应数据：

字段	类型	说明
logId	string	异常日志记录 ID

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "logId": "48faa79e-ca02-4030-a002-c953dabdeea2"
  }
}