im_server/docs/IM-测试环境接口审核报告-2026-08-20.md

IM 测试环境接口审核报告（2026-08-20）

1. 审核范围

• 对照文档：docs/IM-前后端对接文档.md
• 测试环境：https://api.118im.com
• WebSocket：wss://api.118im.com/v0/channels
• API Key：已使用测试环境普通 Key，报告中不展开。
• 租户：default
• 测试账号：本轮通过短信验证码固定码 123456 和 WebSocket {acc} 临时注册，用户 ID usrIPhpZJeJDMI。
• 本轮只新增本报告，不修改原前后端对接文档。

2. 总体结论

测试环境已能跑通基础启动、注册、登录、bootstrap、通讯录空列表、建群、工作台、日报/月报草稿、个人资料、隐私、反馈、设备推送 Token 等主链路。整体方向和产品需求基本匹配：Tinode WebSocket 承担消息与 Topic，/v1/im/* 承担产品化业务接口。

但当前仍不建议直接按整份对接文档全量联调。主要风险是：部分文档接口没有路由或路由兜底错误，部分配置类接口在测试库空数据时返回 500/502，部分通用响应约定没有统一落到所有列表接口，办公协同和转发/群文件相关接口还存在明显缺口。

3. P0/P1 问题

处理备注（2026-08-20）：

• 已在提交 6c6d2f6 fix: stabilize im audit endpoints 中处理本节前 6 项，以及 bootstrap.limits 缺失问题。
• 已用本地 Docker 启动服务并调用本地 API 验证通过；测试环境需发布该提交后再复测公网结果。
• 当前短信供应商未接入时，注册、找回密码和敏感操作验证码均按测试码 123456 验证；生产接入短信供应商后应切回真实短信策略。

优先级	问题	测试结果	影响	建议
P0	密码重置发码 scene=reset_password 返回 502	POST /v1/im/auth/verification-codes，Body {"scene":"reset_password","phone":"15509271990"}，带 Idempotency-Key，返回 Cloudflare 502	忘记密码无法联调，且不是统一 JSON 错误	已处理：短信未接入时保留 challenge，并用测试码 123456 验证；本地 API 验证返回 200
P0	登录后二次身份验证挑战返回 502	POST /v1/im/security/challenges，Body {"scene":"close_youth_mode","channel":"sms"}，带 Idempotency-Key，返回 Cloudflare 502	关闭青少年模式、敏感操作二次验证不可用	已处理：短信发送失败不再使 challenge 失败；带 Idempotency-Key 创建和 123456 verify 本地均返回 200
P0	总经理信箱配置和提交返回 500	GET /v1/im/executive-mailbox/config 返回 INTERNAL_ERROR；按文档提交也返回 500	工作台入口开启但页面不可用	已处理：修复 im_mailbox_config、im_mailbox_submissions 的 SELECT * 映射问题；本地 config/submit 均返回 200
P1	举报原因返回 500	GET /v1/im/reports/abuse/reasons?target_type=user 返回 INTERNAL_ERROR	举报页无法打开	已处理：补齐 AbuseReason 数据库字段映射；本地返回 200 和 items
P1	转发目标接口不存在	GET /v1/im/forward-targets?query= 返回 404	4.17～4.20 转发目标页无法联调	已处理：新增 /v1/im/forward-targets，返回文件助手和可转发的 P2P/群会话；本地返回 200
P1	群文件接口被群详情兜底吞掉	GET /v1/im/groups/{topic}/files 返回群详情 JSON，而不是文件列表或 404	前端会误判接口成功，群文件页数据结构错误	已处理：未知一级 tail 不再落到群详情；/files 未实现时本地返回 404

4. 章节审核

0. 公共对接约定

通过项：

• POST /v1/im/tenants/resolve 可未登录调用，返回统一 code/data/request_id/server_time。
• endpoints 已返回正确公网地址：https://api.118im.com/v1/im、wss://api.118im.com/v0/channels、https://api.118im.com/v0/file。
• 缺 token 访问 GET /v1/im/bootstrap 返回统一 JSON：401 AUTH_REQUIRED。

问题：

• 公共约定写分页统一返回 items,next_cursor,has_more，但很多接口只返回 items,next_cursor，例如 friends、friend-requests、system-notifications、favorites、calls。
• 写请求确实依赖 Idempotency-Key，但部分章节没有重复强调；前端实现时必须按公共约定统一加。

1. 账号注册、登录与身份安全

通过项：

• 企业解析通过，且不泄漏 tenant_id。
• 注册短信发码通过：返回 challenge_id/expires_in_seconds/resend_after_seconds/phone_mask。
• 固定验证码 123456 验证通过：返回 verification_token。
• WebSocket hi(tenant=default) 返回 201，acc user:new login:true 注册成功，返回 user/token/expires/username。
• GET /v1/im/security/realname 返回 status=unverified, can_submit=true。

问题：

• 已处理待发版复测：reset_password 发码不再因短信供应商未接入返回 502，本地返回 200。
• 已处理待发版复测：POST /v1/im/security/challenges 不再因短信供应商未接入返回 502，本地创建和校验均返回 200。
• 文档目标错误 reason 很完整，但 WS 登录/注册仍主要是 Tinode ctrl.text/code；稳定 params.reason 是否全链路返回还需要继续核。

2. 消息首页、全局导航与系统通知

通过项：

• GET /v1/im/bootstrap 已返回 features/permissions/message_policy/security/modules/system_topic。
• 最新测试环境已补 entries 和 entry_badges，包括 new_friends/groups/file_assistant/system_messages 入口与未读数字段，能支撑通讯录和首页入口显示。
• GET /v1/im/system-notifications?limit=5 返回 items,next_cursor。
• GET /v1/im/search/conversations?q=a 可返回已创建群会话，包含 seq/read/unread/public/private。

问题：

• 已处理待发版复测：bootstrap 已补 limits.max_file_size/max_text_length/max_forward_targets，本地返回 200。
• 系统通知没有聚合未读接口，当前依赖 bootstrap.entry_badges.system_unread_count，需要确认其真实计算来源和实时更新事件。

3. 单聊会话、会话建立与消息状态

通过项：

• 路由存在 GET /v1/im/conversations/{topic}/context。
• 好友申请接口存在：POST/GET /v1/im/friend-requests，列表空数据返回正常。
• 好友列表 GET /v1/im/friends 返回正常空列表。

问题：

• 文档出现 POST /v1/im/conversations/p2p、GET /v1/im/conversations/{topic}/messages、PATCH /v1/im/conversations/{topic}/settings，路由清单未看到对应明确 handler，需要进一步实测或补实现。
• 单聊发送约束最终仍要靠 WebSocket pub 校验，HTTP 文档里的关系状态和 WS 发布路径需要做端到端用例。

4. 消息输入、媒体内容与消息操作

通过项：

• 收藏基础接口存在，GET /v1/im/favorites?limit=5 正常返回空列表。
• 消息撤回/编辑/回执类路由挂在 /v1/im/topics/ 下，代码有统一 handler。

问题：

• 已处理待发版复测：GET /v1/im/forward-targets?query= 已新增，本地返回 200。
• 文档里的 POST /v1/im/messages/forward、GET /v1/im/forward-bundles/{bundle_id} 未在路由表看到。
• 文件上传仍主要使用 /v0/file，但业务 purpose、附件 ACL、群文件登记接口还没有从测试结果证明可用。
• 已处理待发版复测：bootstrap.limits.max_forward_targets/max_file_size/max_text_length 本地已返回。

5. 通讯录、好友关系与黑名单

通过项：

• GET /v1/im/friends、GET /v1/im/friend-requests、GET /v1/im/blocks 均返回统一成功空列表。
• GET /v1/im/users/search 可调用，空结果返回 items:[]。
• bootstrap.entries.new_friends 和 entry_badges.new_friends_pending_count 已能控制入口和未处理数。

问题：

• 本轮新注册用户搜索自己的 username 返回空列表，可能是“排除自己”的合理策略，也可能是搜索索引/隐私导致，需要用第二个用户互搜确认。
• 新朋友未处理数现在在 bootstrap.entry_badges 返回，但需要确认好友申请创建/处理后是否实时准确更新。

6. 群聊创建、资料维护与成员治理

通过项：

• POST /v1/im/groups 已支持截图里的 name + description 创建群聊，返回 topic/name/description/owner/member_count/version/permissions。
• GET /v1/im/groups、GET /v1/im/groups/{topic}、GET /summary、GET /members、POST /qrcodes、GET /governance、GET /role-limits、GET /mutes 均可用。
• 群二维码返回 qr_token/qr_payload/expires_at/group_snapshot，符合需求。

问题：

• GET /v1/im/groups/{topic}/members 返回的 owner 成员 user_id 为空字符串，这不适合前端成员列表和后续管理员/转让操作，应返回 usr...。
• 已处理待发版复测：GET /v1/im/groups/{topic}/files 不再返回群详情，本地返回 404。
• 已处理待发版复测：GET /v1/im/groups/{topic}/announcements 不再返回群详情，未知一级 tail 统一返回 404。
• 文档里的 POST /v1/im/group-invitations/{invitation_id}/accept 未在路由表看到；当前更像是走群内 /invitations 和扫码 join-request。

7. 文件下载、收藏管理与聊天记录检索

通过项：

• GET /v1/im/favorites 可用。
• 收藏批量、删除、转发相关 handler 在 /favorites 和 /favorites/ 下存在。

问题：

• 群文件接口不可用，且被错误兜底。
• 文档中的聊天记录搜索、媒体筛选、上下文接口挂在 /v1/im/topics/{topic}/...，需要有真实消息后再端到端验证；本轮未创建聊天消息。
• 文件下载鉴权复用 /v0/file，本轮未上传真实附件，ACL 未验证。

8. 实时语音与视频通话

通过项：

• GET /v1/im/calls?limit=5 返回正常空列表。
• 文档对通话主体设计合理：WebSocket 信令为主，HTTP 只做记录查询。

问题：

• 需要真机或至少两个 WS 用户做 call started/ringing/accept/hang-up 端到端；本轮只验证 HTTP 通话记录列表。
• Push、好友关系、拉黑、并发通话校验没有通过测试环境验证。

9. 企业工作台与办公协同

通过项：

• GET /v1/im/workbench 返回模块列表和 layout_version。
• GET /v1/im/organization/departments 返回正常空列表。
• 日报列表、日报统计、日报草稿创建通过。
• 月报列表、月报统计、月报草稿创建通过。
• 会议创建按文档 Body 通过。

问题：

• GET /v1/im/meetings?limit=5 返回 405；文档没明确会议列表接口，但会议通知页面通常需要列表，设计上应补 GET /v1/im/meetings。
• GET /v1/im/organization/search?q= 空关键词返回 400；文档示例写 q=，需明确前端空关键词应不请求还是后端返回空列表。
• GET /v1/im/executive-mailbox/config 和提交均返回 500，总经理信箱不可联调。
• modules[].unread_count 当前全 0，需要确认是否真实 badge，还是静态占位。

10. 个人资料、通用设置、隐私与青少年模式

通过项：

• GET /v1/im/me、GET /v1/im/me/profile、GET /v1/im/me/privacy、GET /v1/im/settings/youth-mode 均可用。
• POST /v1/im/me/qrcodes 可用，返回 qr_token/qr_payload/display_profile/expires_at。
• PUT /v1/im/devices/{device_id}/push-token 可用，能登记 APNs 测试 token。
• GET /v1/im/app/releases/latest?platform=ios&version=1.0.0 可用。

问题：

• 文档写应用更新参数为 current_version，测试使用 version 也能返回；实现似乎不消费当前版本参数，建议统一字段名，避免客户端多套逻辑。
• 青少年模式关闭依赖二次验证，而二次验证挑战当前 502。
• Android 系统权限说明多为客户端能力，本轮无法通过服务端验证。

11. 反诈安全、举报与意见反馈

通过项：

• POST /v1/im/security/urls/check 可用，安全 URL 返回 decision=allow/risk_level=low。
• GET /v1/im/feedback/config 可用。
• POST /v1/im/feedback 可用，返回 feedback_id/status=received。

问题：

• GET /v1/im/reports/abuse/reasons?target_type=user 返回 500，举报页阻塞。
• 风控 challenge confirm 路由存在，但需要先有业务接口返回 RISK_CONFIRMATION_REQUIRED 后才能完整验证。
• 举报提交需要真实目标对象和原因数据，本轮因原因接口 500 未继续提交。

12. 联调实施清单

建议把当前验收顺序调整为：

1. 已处理待发版复测：密码重置 502、二次验证 502、总经理信箱 500、举报原因 500。
2. 部分已处理待发版复测：转发目标已补、群文件路径错误兜底已修；消息转发/Forward Bundle 缺路由、群成员 user_id 为空仍待处理。
3. 统一公共协议：所有列表是否必须返回 has_more；所有写接口是否都必须 Idempotency-Key；bootstrap.limits 是否需要补。
4. 两用户端到端：好友申请、同意、P2P context、普通消息、已读、拉黑、删除好友。
5. 群端到端：邀请成员、入群审批、公告、群文件、管理员、禁言、群主转让。
6. 真机端到端：文件上传下载、APNs/FCM 推送、WebRTC 通话。

5. 代表性实测结果

接口	方法	状态	结论
/v1/im/tenants/resolve	POST	200	企业解析正常，endpoint host 正确
/v1/im/auth/verification-codes register	POST	200	注册发码正常
/v1/im/auth/verification-codes/{id}/verify	POST	200	固定验证码 123456 正常
WebSocket hi + acc	WS	201/200	注册并登录成功
/v1/im/auth/verification-codes reset_password	POST	502	已处理待发版复测；本地返回 200
/v1/im/security/challenges	POST	502	已处理待发版复测；本地创建和 123456 校验返回 200
/v1/im/bootstrap	GET	200	已包含 entries/entry_badges；已补 limits 待发版复测
/v1/im/groups	POST	200	创建群聊含 description 正常
/v1/im/groups/{topic}/members	GET	200	可用，但成员 user_id 为空
/v1/im/groups/{topic}/files	GET	200	已处理待发版复测；未实现时本地返回 404，不再误返回群详情
/v1/im/forward-targets	GET	404	已处理待发版复测；本地返回 200
/v1/im/executive-mailbox/config	GET	500	已处理待发版复测；本地 config/submit 返回 200
/v1/im/reports/abuse/reasons	GET	500	已处理待发版复测；本地返回 200
/v1/im/feedback	POST	200	意见反馈提交正常
/v1/im/devices/{device_id}/push-token	PUT	200	推送 token 登记正常

6. 本轮测试产生的数据

• 创建临时用户：usrIPhpZJeJDMI
• 创建群：grpcNdeRoa_VO0
• 创建会议：mtg_vN4182ncLyi5wp4A
• 创建日报草稿：dr_MdAFCj2fYTkBjiq8
• 创建月报草稿：mr_eWjm2hpuzSsqcIcH
• 创建反馈：fb_TEJYaStZn9i0JSun
• 登记设备：audit-device

这些数据均在测试租户 default 下，可按需要由测试库清理。