231 lines
8.6 KiB
Markdown
231 lines
8.6 KiB
Markdown
# wxchat 插件 · 使用与调用说明
|
||
|
||
> 仿微信风格的移动端 IM 社交后端（基于 GatewayWorker）。
|
||
> 本文档说明插件的安装、目录分层、接口调用方式与实时通信约定。
|
||
|
||
---
|
||
|
||
## 1. 功能简介
|
||
|
||
- **实时聊天**：单聊/群聊，文本/图片/语音/视频/文件，心跳、认证、撤回、已读回执、敏感词过滤。
|
||
- **用户体系**：短信验证码登录、一键登录、完善资料、邀请码，`TokenService` 鉴权。
|
||
- **社交关系**：好友、关注/粉丝/互关、亲密度等级。
|
||
- **动态（朋友圈）**：发布、评论、点赞、收藏、话题、浏览历史。
|
||
- **其它**：礼物、抽奖、未读计数、APP 版本管理（`AppVersionCheck` 中间件）、启动配置下发。
|
||
|
||
---
|
||
|
||
## 2. 安装与启用
|
||
|
||
1. 将插件整体放入 `addon/wxchat/`。
|
||
2. 后台「插件管理」启用；配置项在「插件管理 → 配置」（`/backend/addon/setting?addon=wxchat`）可视化维护，实际值存于数据库 `wxapp_addon_config`，运行时通过 `AddonService::config('wxchat')` 读取。
|
||
3. 启动常驻聊天进程（WebSocket 服务）：
|
||
|
||
```bash
|
||
php think wxchat:server
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 控制器分层（目录约定）
|
||
|
||
| 层 | 目录 | 继承基类 | 对外 URL 前缀 | 说明 |
|
||
|----|------|----------|---------------|------|
|
||
| 对外 API | `controller/api/` | `ywxapp\controller\Frontend` | `/wxchat/<ctrl>/<action>` | 客户端 REST 接口 |
|
||
| 用户中心 | `controller/member/` | `ywxapp\controller\Frontend` | `/wxchat/<ctrl>/<action>` | 会员中心业务（认证/任务/房间/家族）|
|
||
| 后台管理 | `controller/backend/` | `ywxapp\controller\AddonBackend` | `/wxchat/backend/<ctrl>` | 运营后台管理界面 |
|
||
|
||
> 路由统一在 `addon/wxchat/route/app.php` 中声明，对外 URL 保持不变，仅映射到对应分层命名空间。
|
||
|
||
---
|
||
|
||
## 4. 基础调用约定
|
||
|
||
- **Base URL**：`/wxchat`
|
||
- **请求方法**：每个接口均用 `Route::any` 注册，GET / POST 均可（推荐按语义使用 POST 提交数据）。
|
||
- **响应格式**（由 `Frontend` 提供）：
|
||
|
||
```jsonc
|
||
// 成功
|
||
{ "code": 0, "msg": "success", "data": { ... } }
|
||
// 失败
|
||
{ "code": 1, "msg": "错误信息", "data": null }
|
||
```
|
||
|
||
- **鉴权现状**：当前开发态下，所有 `controller/api/*` 控制器均声明
|
||
`protected $noNeedLogin = ['*']; protected $noNeedVerify = ['*'];`
|
||
即**接口全部开放**，便于联调。**上线前务必关闭开放态、开启登录与签名校验。**
|
||
- **Token**：登录成功后由会员体系 `TokenService` 下发，后续需鉴权的请求在请求头携带该 Token。
|
||
|
||
---
|
||
|
||
## 5. 对外 API 接口清单
|
||
|
||
> 以下 URL 均相对于 Base URL `/wxchat`。例如 `index/appConf` 实际请求 `/wxchat/index/appConf`。
|
||
|
||
### 5.1 启动配置（Index）
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `index/appConf` | GET | 启动配置：功能开关、业务限制、广告、服务器地址（`socketUrl`/`uploadUrl`/`cdnUrl`/`apiUrl`）、第三方 AppId、版本兼容等。 |
|
||
| `index/launchData` | GET | 冷启动数据（广告、弹窗等）。 |
|
||
| `index/baseData` | GET | 基础数据。 |
|
||
|
||
### 5.2 登录与账号（Login）
|
||
|
||
| 接口 | 方法 | 入参（POST） | 说明 |
|
||
|------|------|--------------|------|
|
||
| `login/sendSmsCode` | POST | `mobile`, `event`(默认 `login`) | 发送短信验证码。 |
|
||
| `login/smsLogin` | POST | `mobile`, `captcha`, `event` | 短信验证码登录；成功后返回用户信息（含 Token）。 |
|
||
| `login/oneClickLogin` | POST | 一键登录凭证 | 本地号码一键登录。 |
|
||
| `login/completeUserInfo` | POST | 昵称/头像/邀请码等 | 完善个人信息。 |
|
||
| `login/index` | GET | — | 登录态校验/入口。 |
|
||
|
||
### 5.3 用户（User）
|
||
|
||
`user/profile` · `user/updateProfile` · `user/nearby`(附近的人) · `user/local`(同城) · `user/online`(在线) · `user/heartbeat`(心跳) · `user/privacy`(隐私设置) · `user/updatePrivacy` · `user/cancelAccount`(注销)。
|
||
|
||
### 5.4 关注（Follow）
|
||
|
||
`follow/toggleFollow`(关注/取关) · `follow/getFollowingList`(关注列表) · `follow/getFollowerList`(粉丝列表) · `follow/getMutualList`(互关列表)。
|
||
|
||
### 5.5 好友（Friend，通用 CRUD）
|
||
|
||
`friend/index` · `friend/create` · `friend/save` · `friend/read` · `friend/edit` · `friend/update` · `friend/delete`。
|
||
|
||
### 5.6 动态 / 朋友圈（Moment）
|
||
|
||
`moment/create`(发布) · `moment/upload`(图片上传) · `moment/comment`(评论) · `moment/like`(点赞) · `moment/collect`(收藏) · `moment/follow`(关注动态) · `moment/red`(红包动态)。
|
||
|
||
### 5.7 消息（Message）
|
||
|
||
`message/send`(发送) · `message/history`(历史记录) · `message/unread`(未读) · `message/recall`(撤回)。
|
||
|
||
### 5.8 礼物（Gift）
|
||
|
||
`gift/index`(礼物列表) · `gift/send`(赠送) · `gift/received`(收到记录)。
|
||
|
||
### 5.9 抽奖（Lottery）
|
||
|
||
`lottery/config`(奖品配置) · `lottery/draw`(抽奖)。
|
||
|
||
### 5.10 推荐 / 搜索 / 未读
|
||
|
||
- 推荐：`recommend/index`
|
||
- 搜索：`search/index`
|
||
- 未读计数：`unread/count` · `unread/read`
|
||
|
||
### 5.11 测试（Test）
|
||
|
||
`test/index` 等通用 CRUD 接口，仅供联调/调试使用。
|
||
|
||
---
|
||
|
||
## 6. 用户中心接口（member）
|
||
|
||
| 业务 | 接口（前缀 `/wxchat`） |
|
||
|------|------------------------|
|
||
| 实名认证 | `auth/submit` · `auth/status` · `auth/review` |
|
||
| 任务 | `task/lists` · `task/progress` · `task/claim` · `task/invite` |
|
||
| 房间 | `room/lists` · `room/create` · `room/join` · `room/leave` · `room/micUp` · `room/micDown` · `room/micManage` · `room/danmaku` |
|
||
| 家族 | `family/create` · `family/join` · `family/quit` · `family/info` · `family/members` |
|
||
|
||
---
|
||
|
||
## 7. 后台管理（backend）
|
||
|
||
后台菜单由 `addon/wxchat/menu.json` 注入，入口位于后台「社交(wxchat)」：
|
||
|
||
| 菜单 | URL |
|
||
|------|-----|
|
||
| 任务管理 | `/wxchat/backend/task` |
|
||
| 实名认证 | `/wxchat/backend/auth` |
|
||
| 房间管理 | `/wxchat/backend/room` |
|
||
|
||
对应控制器：`controller/backend/WxchatTask.php`、`WxchatAuth.php`、`WxchatRoom.php`。
|
||
|
||
---
|
||
|
||
## 8. WebSocket 实时通信
|
||
|
||
- **启动**：`php think wxchat:server`（GatewayWorker 常驻进程）。
|
||
- **连接地址**：由 `index/appConf` 返回的 `socketUrl` 下发（默认 `wss://dev.xixingwl.cn:2346`）。
|
||
- **鉴权 / 心跳 / 消息**：由 `AppVersionCheck` 中间件与 `worker/` 下各 `handle` 类处理（认证、聊天、关系、状态、系统消息等）。
|
||
|
||
---
|
||
|
||
## 9. 主要配置项（appConf 返回）
|
||
|
||
| 分组 | 关键字段 |
|
||
|------|----------|
|
||
| 功能开关 | `chatEnabled` `videoCallEnabled` `voiceRoomEnabled` `giftShopEnabled` `rechargeEnabled` `vipEnabled` `matchEnabled` `momentEnabled` |
|
||
| 业务限制 | `dailyMatchLimit` `dailyMessageLimit` `maxFriends` `maxMomentImages` `maxChatImageSize` `maxVideoDuration` `maxVoiceDuration` |
|
||
| 广告 | `enableAd` `splashAdId` `bannerAdId` `interstitialAdId` `rewardAdId` `adFrequency` |
|
||
| 服务器 | `socketUrl` `uploadUrl` `cdnUrl` `apiUrl` `apiVersion` |
|
||
| 第三方 | `wechatAppId` `qqAppId` `appleServiceId` `pushService` `mapService` |
|
||
| 版本兼容 | `minIosVersion` `minAndroidVersion` `supportedPlatforms` |
|
||
|
||
> 配置值在后台「插件管理 → 配置」修改后即时覆盖代码默认值下发。
|
||
|
||
---
|
||
|
||
## 10. 注意事项
|
||
|
||
1. **开发态全开放**：当前所有 API 控制器 `$noNeedLogin = ['*']`，属调试状态，上线前需开启登录与签名校验。
|
||
2. **测试代码**：`Login` 控制器内含直接调用短信网关发短信的测试代码（含明文账号密码），上线前需删除。
|
||
3. **WebSocket 依赖**：实时聊天、心跳、撤回等功能依赖 `php think wxchat:server` 进程处于运行状态且客户端按 `socketUrl` 连接。
|
||
4. **数据表**：插件数据表以 `wxapp_wxchat_*` 命名（约 20 张），安装时由 `install.sql` 导入。
|
||
|
||
---
|
||
|
||
## 附录：消息协议结构（草稿）
|
||
|
||
> 以下为 WebSocket 消息包结构的设计草稿，供客户端对接参考。
|
||
|
||
```php
|
||
class ChatPacket
|
||
{
|
||
protected $header;
|
||
protected $payload;
|
||
protected $ext;
|
||
}
|
||
|
||
/**
|
||
* 消息头结构设计（示例）
|
||
*/
|
||
class Header
|
||
{
|
||
protected $version;
|
||
protected $packet_id;
|
||
protected $timestamp;
|
||
protected $from_uid;
|
||
protected $to_id;
|
||
protected $session_type;
|
||
protected $msg_type;
|
||
protected $need_ack;
|
||
protected $signature;
|
||
protected $server_time; // 服务端回填
|
||
protected $session_seq; // 服务端回填
|
||
}
|
||
|
||
/**
|
||
* 消息体结构设计（示例）
|
||
*/
|
||
class Payload
|
||
{
|
||
public $content;
|
||
public $mention_uids;
|
||
public $reply_to;
|
||
// 其他字段按需扩展
|
||
}
|
||
|
||
/**
|
||
* 扩展字段结构设计（示例）
|
||
*/
|
||
class Ext
|
||
{
|
||
public $client;
|
||
public $platform;
|
||
}
|
||
```
|