# 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 脚本）

---

## 目录结构

```text
.
├─ 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` 的网络环境

---

## 安装与运行

```bash
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：

```bash
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 截图、接口示例与发布流程图