yunzhu-im-mobile

yunzhu-im-mobile

基于 uni-app (Vue 3) 的移动端 IM 客户端，包含登录、会话列表、聊天收发（文字/图片/视频/文件）、通讯录、应用中心（SSO 打开应用）、搜索中心等功能。

项目特性

• 支持密码登录、短信验证码登录
• 会话列表与联系人列表
• 聊天功能：
  • 拉取历史消息
  • 上拉加载更多
  • 发送文本消息
  • 发送图片/视频/文件消息
  • 发送失败重试
• WebSocket 实时消息推送（30s 心跳）
• 本地未读计数与 Tab 角标更新
• 通知类消息卡片展示，支持回调链接打开
• 应用中心：
  • 拉取快捷应用列表
  • 最近使用应用本地缓存
  • SSO 登录后内嵌 web-view 打开应用
• 搜索中心：
  • 搜索联系人
  • 搜索应用（本地过滤）
• 自定义头像组件（按名称/ID 稳定渐变）

---

技术栈

• uni-app
• Vue 3
• JavaScript (CommonJS + ESM)
• uni.request / uni.uploadFile / uni.connectSocket
• sharp（仅用于 SVG 转 PNG 脚本）

---

目录结构

.
├─ App.vue                         # 应用入口，启动时鉴权并连接 WebSocket
├─ pages.json                      # 页面路由与 tabBar 配置
├─ manifest.json                   # uni-app 平台配置（App/小程序）
├─ uni.scss                        # 全局主题变量
├─ uni.promisify.adaptor.js        # uni API Promise 适配
├─ package.json
│
├─ pages/
│  ├─ login/index.vue              # 登录页（密码/验证码）
│  ├─ index/index.vue              # 消息会话列表页（tab: 消息）
│  ├─ chat/index.vue               # 聊天页
│  ├─ contacts/index.vue           # 通讯录页（tab: 通讯录）
│  ├─ contact-detail/index.vue     # 联系人详情页
│  ├─ app-center/index.vue         # 应用中心页（tab: 应用中心）
│  ├─ search-center/index.vue      # 全局搜索页
│  ├─ profile/index.vue            # 个人信息页
│  └─ webview/index.vue            # 通用内嵌网页页
│
├─ components/
│  ├─ UserAvatar.vue               # 用户头像（图像/文字渐变占位）
│  ├─ SystemAvatar.vue             # 系统/应用头像
│  └─ chat/
│     ├─ PrivateMessageBubble.vue  # 私信消息气泡
│     └─ NotificationBubble.vue    # 通知消息卡片
│
├─ composables/
│  ├─ useContacts.js               # 会话列表数据拉取
│  ├─ useMessages.js               # 历史消息、发送、重试、上传发送
│  └─ useWebSocket.js              # WS 连接、推送处理、未读更新
│
├─ store/
│  └─ chat.js                      # 全局聊天状态（contacts/messages/unread）
│
├─ utils/
│  └─ api.js                       # HTTP API 封装与认证工具
│
├─ scripts/
│  └─ svg-to-png.js                # tab SVG 批量转 81x81 PNG
│
├─ static/icons/                   # 图标资源（含 tab 图标）
└─ document/
   └─ Message_Integration_Guide.md # 消息中心接口与接入说明

---

环境要求

• Node.js 16+（建议 18+）
• HBuilderX（推荐）或支持 uni-app 的开发环境
• 具备可访问 https://api.hnyunzhu.com 的网络环境

---

安装与运行

npm install

该仓库主要通过 HBuilderX 运行/打包（package.json 未配置完整的 uni CLI 脚本）。

在 HBuilderX 中运行

1. 使用 HBuilderX 打开项目根目录
2. 运行到目标平台（如：Android 真机 / 模拟器 / H5）
3. 首次进入若无 token 会跳转登录页

---

构建与发布

按 uni-app 常规流程在 HBuilderX 中：

• 发行 -> 原生 App-云打包 / 本地打包
• 或发行到对应小程序平台（需在 manifest.json 配置 appid）

---

配置说明

1) 后端 API 地址

当前在 utils/api.js 中固定为：

• BASE_URL = https://api.hnyunzhu.com/api/v1
• WS_BASE = wss://api.hnyunzhu.com/api/v1/ws/messages（位于 composables/useWebSocket.js）

如需切换环境（测试/预发），请统一修改上述常量。

2) Token 与用户信息本地存储

• token key：token
• 当前用户 key：current_user

3) tabBar 图标

pages.json 中 tabBar 使用的是 PNG：

• static/icons/tab-message(.png)
• static/icons/tab-contacts(.png)
• static/icons/tab-app(.png)

若你修改了对应 SVG，可执行脚本重新生成 PNG。

---

图标转换脚本（可选）

用于把 static/icons 下 tab SVG 统一转成 81x81 PNG：

node scripts/svg-to-png.js

依赖：

• sharp（已在 devDependencies 中）

---

主要业务流程

启动流程

1. App.vue 启动时读取 token
2. 无 token -> 跳转登录页
3. 有 token -> 调用 getCurrentUserInfo
4. 鉴权通过后建立 WebSocket 长连接

消息流程

1. 进入聊天页调用 getMessages
2. 发送文本调用 sendMessage
3. 发送附件先 uploadFile，后 sendMessage
4. 收到 WS 推送后：
   • 追加到对应会话消息
   • 更新会话预览
   • 非当前会话时未读数 +1
   • 更新底部 Tab 未读角标

应用中心流程

1. 拉取 getLaunchpadApps
2. 点击应用后调用 ssoLogin
3. 获取 redirect_url 并跳转到 pages/webview/index

---

接口概览（客户端实际使用）

• 认证：
  • POST /auth/login/json
  • POST /auth/sms/login
  • POST /auth/sms/send-code
• 用户：
  • GET /users/me（及 fallback 路径）
  • GET /users/search
  • GET /users/
• 消息：
  • GET /messages/conversations
  • GET /messages/history/{otherUserId}
  • POST /messages/
  • POST /messages/upload
  • GET /messages/{messageId}/callback-url
• 应用中心：
  • GET /simple/me/launchpad-apps
  • POST /simple/sso-login
• WebSocket：
  • wss://.../ws/messages?token=...

详细协议可参考 document/Message_Integration_Guide.md。

---

已知说明

• 当前仓库已包含 unpackage/ 构建产物，协作时建议确认是否纳入版本管理策略
• package.json 的 scripts 目前仅保留默认 test 占位脚本
• 一些页面按钮（如“更多”“语音/视频”等）当前为占位交互（toast）

---

后续建议

• 增加多环境配置（dev/staging/prod）并统一 API/WS 地址管理
• 完善 npm scripts（lint、build、dev）
• 补充错误监控与 WS 断线重连策略
• 增加 README 截图、接口示例与发布流程图