# 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;
}
```