YwxApp/YwxAppThink

Fork 0

Files

T

ywxapp 6c1a106bc1 chore: 重写初始提交(清空历史,整理后全量提交)

2026-08-16 16:54:14 +08:00

8.6 KiB

Raw Blame History

wxchat 插件 · 使用与调用说明

仿微信风格的移动端 IM 社交后端（基于 GatewayWorker）。本文档说明插件的安装、目录分层、接口调用方式与实时通信约定。

1. 功能简介

实时聊天：单聊/群聊，文本/图片/语音/视频/文件，心跳、认证、撤回、已读回执、敏感词过滤。
用户体系：短信验证码登录、一键登录、完善资料、邀请码，TokenService 鉴权。
社交关系：好友、关注/粉丝/互关、亲密度等级。
动态（朋友圈）：发布、评论、点赞、收藏、话题、浏览历史。
其它：礼物、抽奖、未读计数、APP 版本管理（AppVersionCheck 中间件）、启动配置下发。

2. 安装与启用

将插件整体放入 addon/wxchat/。
后台「插件管理」启用；配置项在「插件管理 → 配置」（/backend/addon/setting?addon=wxchat）可视化维护，实际值存于数据库 wxapp_addon_config，运行时通过 AddonService::config('wxchat') 读取。
启动常驻聊天进程（WebSocket 服务）：
```
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 提供）：

// 成功
{ "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. 注意事项

开发态全开放：当前所有 API 控制器 $noNeedLogin = ['*']，属调试状态，上线前需开启登录与签名校验。
测试代码：Login 控制器内含直接调用短信网关发短信的测试代码（含明文账号密码），上线前需删除。
WebSocket 依赖：实时聊天、心跳、撤回等功能依赖 php think wxchat:server 进程处于运行状态且客户端按 socketUrl 连接。
数据表：插件数据表以 wxapp_wxchat_* 命名（约 20 张），安装时由 install.sql 导入。

附录：消息协议结构（草稿）

以下为 WebSocket 消息包结构的设计草稿，供客户端对接参考。

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

8.6 KiB Raw Blame History Unescape Escape