224 lines
15 KiB
Markdown
224 lines
15 KiB
Markdown
# 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` 下，可按需要由测试库清理。
|