openapi: 3.0.3
info:
  title: 工作手机SDK - 微信控制API
  description: |
    通过Frida无感控制微信的完整REST API服务。
    
    ## 认证
    所有接口需要在Header中携带 `X-API-Key: workphone-sdk-2026`
    
    ## 基础URL
    `http://192.168.110.80:8899`（手机IP）或 `http://localhost:8899`（本机）
    
    ## 功能模块
    - 系统管理（连接/重连/截图/事件）
    - 账号信息
    - 联系人管理（4991人）
    - 消息发送/群发/读取
    - 朋友圈（读取/发布/评论）
    - 视频号（Finder）
    - 收藏
    - 红包/钱包/账单
    - 文件/图片/视频/语音
    - 群组管理（公告/名称/备注/踢人/解散）
    - 标签管理（36个）
    - 小程序
    - 高级SQL查询
  version: "5.0.0"
  contact:
    name: 工作手机SDK
    
servers:
  - url: http://192.168.110.80:8899
    description: 手机本地服务
  - url: http://localhost:8899
    description: 本机调试

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    Success:
      type: object
      properties:
        success:
          type: boolean
        timestamp:
          type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
        timestamp:
          type: string

paths:
  # ==================== 系统 ====================
  /health:
    get:
      tags: [系统]
      summary: 健康检查
      security: []
      responses:
        '200':
          description: 服务状态
          
  /docs:
    get:
      tags: [系统]
      summary: API文档（JSON格式）
      security: []
      responses:
        '200':
          description: 所有接口列表

  /api/v1/system/info:
    get:
      tags: [系统]
      summary: 获取系统信息
      description: 返回Frida连接状态、DB路径、DB数量等
      responses:
        '200':
          description: 系统信息

  /api/v1/system/connect:
    post:
      tags: [系统]
      summary: 连接Frida
      responses:
        '200':
          description: 连接结果

  /api/v1/system/reconnect:
    post:
      tags: [系统]
      summary: 重新连接Frida（微信重启后使用）
      responses:
        '200':
          description: 重连结果

  /api/v1/system/events:
    get:
      tags: [系统]
      summary: 获取实时事件流
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 事件列表

  /api/v1/system/screenshot:
    post:
      tags: [系统]
      summary: 截取手机屏幕
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  example: /sdcard/screenshot.png
      responses:
        '200':
          description: 截图结果

  # ==================== 账号 ====================
  /api/v1/account/info:
    get:
      tags: [账号]
      summary: 获取微信账号信息
      description: 返回昵称、微信号、手机号、头像等
      responses:
        '200':
          description: 账号信息
          content:
            application/json:
              example:
                success: true
                account:
                  nickname: "游条姐-游戏教学辅助看我朋友圈"
                  wxid: "wxid_5g37snchpv8e22"
                  mobile: "Lytiao1"
                  alias: ""

  # ==================== 联系人 ====================
  /api/v1/contacts:
    get:
      tags: [联系人]
      summary: 获取联系人列表
      description: 支持分页，总计4991人
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 200
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: keyword
          in: query
          schema:
            type: string
          description: 搜索关键词（昵称/备注）
      responses:
        '200':
          description: 联系人列表
          content:
            application/json:
              example:
                success: true
                count: 200
                contacts:
                  - username: "wxid_abc123"
                    nickname: "张三"
                    conRemark: "客户-张三"
                    type: "3"

  /api/v1/contacts/count:
    get:
      tags: [联系人]
      summary: 获取联系人总数
      responses:
        '200':
          description: 数量统计
          content:
            application/json:
              example:
                success: true
                type3_friends: 4991
                total_rcontact: 8076
                groups: 50

  /api/v1/contacts/{wxid}:
    get:
      tags: [联系人]
      summary: 获取联系人详情
      parameters:
        - name: wxid
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 联系人详情

  /api/v1/contacts/{wxid}/remark:
    put:
      tags: [联系人]
      summary: 设置好友备注
      parameters:
        - name: wxid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                remark:
                  type: string
                  example: "客户-李四"
      responses:
        '200':
          description: 设置结果

  /api/v1/contacts/add:
    post:
      tags: [联系人]
      summary: 添加好友（打开搜索界面）
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                wxid:
                  type: string
                  example: "wxid_abc123"
      responses:
        '200':
          description: 操作结果

  /api/v1/contacts/search:
    get:
      tags: [联系人]
      summary: 搜索联系人
      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 搜索结果

  # ==================== 消息 ====================
  /api/v1/messages/send:
    post:
      tags: [消息]
      summary: 发送消息
      description: 通过WCDB直接写入，无感发送
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to_id, content]
              properties:
                to_id:
                  type: string
                  description: 接收方wxid或群ID
                  example: "filehelper"
                content:
                  type: string
                  example: "你好！"
                type:
                  type: integer
                  default: 1
                  description: 消息类型（1=文字）
      responses:
        '200':
          description: 发送结果
          content:
            application/json:
              example:
                success: true
                message_id: "1779108141283"
                method: "wcdb_insert"
                to_id: "filehelper"

  /api/v1/messages/mass:
    post:
      tags: [消息]
      summary: 群发消息
      description: 向多个联系人批量发送消息
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [targets, content]
              properties:
                targets:
                  type: array
                  items:
                    type: string
                  example: ["wxid_abc", "wxid_def", "wxid_ghi"]
                content:
                  type: string
                  example: "群发消息内容"
      responses:
        '200':
          description: 群发结果
          content:
            application/json:
              example:
                success: true
                total: 3
                success_count: 3

  /api/v1/messages:
    get:
      tags: [消息]
      summary: 获取消息记录
      parameters:
        - name: talker
          in: query
          schema:
            type: string
          description: 联系人wxid（不传则返回所有）
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 消息列表

  /api/v1/messages/search:
    get:
      tags: [消息]
      summary: 搜索消息内容
      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 搜索结果

  /api/v1/conversations:
    get:
      tags: [消息]
      summary: 获取最近会话列表
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 会话列表

  # ==================== 朋友圈 ====================
  /api/v1/moments:
    get:
      tags: [朋友圈]
      summary: 获取朋友圈列表
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: 朋友圈列表

  /api/v1/moments/post:
    post:
      tags: [朋友圈]
      summary: 发布朋友圈
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: "今天天气很好！"
      responses:
        '200':
          description: 发布结果

  /api/v1/moments/{sns_id}:
    get:
      tags: [朋友圈]
      summary: 获取朋友圈详情
      parameters:
        - name: sns_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 朋友圈详情

  /api/v1/moments/{sns_id}/comments:
    get:
      tags: [朋友圈]
      summary: 获取朋友圈评论
      parameters:
        - name: sns_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 评论列表

  # ==================== 视频号 ====================
  /api/v1/finder/contacts:
    get:
      tags: [视频号]
      summary: 获取视频号关注列表
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 视频号联系人

  /api/v1/finder/videos:
    get:
      tags: [视频号]
      summary: 获取视频号内容缓存
      responses:
        '200':
          description: 视频号内容

  /api/v1/finder/open:
    post:
      tags: [视频号]
      summary: 打开视频号界面
      responses:
        '200':
          description: 操作结果

  # ==================== 收藏 ====================
  /api/v1/favorites:
    get:
      tags: [收藏]
      summary: 获取收藏列表
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 收藏列表

  # ==================== 红包/钱包 ====================
  /api/v1/wallet/redpackets:
    get:
      tags: [红包/钱包]
      summary: 获取红包记录
      description: 包含已收红包、钱包流水、AA支付记录
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 红包记录

  /api/v1/wallet/info:
    get:
      tags: [红包/钱包]
      summary: 获取钱包信息
      description: 包含用户信息、钱包类型、绑定银行卡
      responses:
        '200':
          description: 钱包信息

  /api/v1/wallet/ledger:
    get:
      tags: [红包/钱包]
      summary: 获取钱包流水账单
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: 账单记录
          content:
            application/json:
              example:
                success: true
                records:
                  - transferId: "xxx"
                    tradeAmount: "100.00"
                    tradeDirection: "1"
                    tradeType: "红包"
                    talker: "wxid_abc"

  # ==================== 文件/媒体 ====================
  /api/v1/media/files:
    get:
      tags: [文件/媒体]
      summary: 获取文件消息记录
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 文件列表

  /api/v1/media/images:
    get:
      tags: [文件/媒体]
      summary: 获取图片记录（83069张）
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 图片列表

  /api/v1/media/videos:
    get:
      tags: [文件/媒体]
      summary: 获取视频记录（792条）
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: 视频列表

  /api/v1/media/voices:
    get:
      tags: [文件/媒体]
      summary: 获取语音记录
      responses:
        '200':
          description: 语音列表

  # ==================== 群组 ====================
  /api/v1/groups:
    get:
      tags: [群组管理]
      summary: 获取群组列表（50个）
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: 群组列表

  /api/v1/groups/{group_id}:
    get:
      tags: [群组管理]
      summary: 获取群组详情
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
          example: "7615610559@chatroom"
      responses:
        '200':
          description: 群组详情

  /api/v1/groups/{group_id}/members:
    get:
      tags: [群组管理]
      summary: 获取群成员列表
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成员列表

  /api/v1/groups/{group_id}/notice:
    put:
      tags: [群组管理]
      summary: 设置群公告
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notice:
                  type: string
                  example: "群公告内容"
      responses:
        '200':
          description: 设置结果

  /api/v1/groups/{group_id}/name:
    put:
      tags: [群组管理]
      summary: 修改群名称
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "新群名称"
      responses:
        '200':
          description: 修改结果

  /api/v1/groups/{group_id}/nickname:
    put:
      tags: [群组管理]
      summary: 设置我在群内的昵称
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                nickname:
                  type: string
      responses:
        '200':
          description: 设置结果

  /api/v1/groups/{group_id}/kick:
    post:
      tags: [群组管理]
      summary: 踢出群成员
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                member_id:
                  type: string
                  example: "wxid_abc123"
      responses:
        '200':
          description: 操作结果

  /api/v1/groups/{group_id}/message:
    post:
      tags: [群组管理]
      summary: 发送群消息
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: "群消息内容"
      responses:
        '200':
          description: 发送结果

  # ==================== 标签 ====================
  /api/v1/labels:
    get:
      tags: [标签]
      summary: 获取标签列表（36个）
      responses:
        '200':
          description: 标签列表

  /api/v1/labels/{label_id}/members:
    get:
      tags: [标签]
      summary: 获取标签下的联系人
      parameters:
        - name: label_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 标签成员

  # ==================== 小程序 ====================
  /api/v1/miniapps:
    get:
      tags: [小程序]
      summary: 获取小程序使用记录
      responses:
        '200':
          description: 小程序列表

  /api/v1/miniapps/open:
    post:
      tags: [小程序]
      summary: 打开小程序
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                app_id:
                  type: string
      responses:
        '200':
          description: 操作结果

  # ==================== 导航 ====================
  /api/v1/navigate/chat:
    post:
      tags: [导航]
      summary: 导航到聊天界面
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                wxid:
                  type: string
      responses:
        '200':
          description: 操作结果

  /api/v1/navigate/moments:
    post:
      tags: [导航]
      summary: 导航到朋友圈
      responses:
        '200':
          description: 操作结果

  /api/v1/navigate/contacts:
    post:
      tags: [导航]
      summary: 导航到通讯录
      responses:
        '200':
          description: 操作结果

  # ==================== 高级SQL ====================
  /api/v1/db/query:
    post:
      tags: [高级SQL]
      summary: 执行原始SQL查询
      description: 直接查询微信DB，支持所有23个数据库
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sql]
              properties:
                sql:
                  type: string
                  example: "SELECT COUNT(*) as cnt FROM rcontact WHERE type=3"
                db:
                  type: string
                  description: 数据库名称（不填则用EnMicroMsg）
                  example: "WalletCoreDB-2"
      responses:
        '200':
          description: 查询结果

  /api/v1/db/info:
    get:
      tags: [高级SQL]
      summary: 获取所有DB实例信息
      responses:
        '200':
          description: DB列表

  /api/v1/db/tables:
    get:
      tags: [高级SQL]
      summary: 枚举所有DB的表
      responses:
        '200':
          description: 所有表结构

tags:
  - name: 系统
    description: 系统管理、连接、截图
  - name: 账号
    description: 微信账号信息
  - name: 联系人
    description: 联系人管理（4991人）
  - name: 消息
    description: 消息发送、群发、读取
  - name: 朋友圈
    description: 朋友圈读取、发布、评论
  - name: 视频号
    description: 视频号（Finder）
  - name: 收藏
    description: 微信收藏
  - name: 红包/钱包
    description: 红包记录、钱包流水、银行卡
  - name: 文件/媒体
    description: 文件、图片（83069张）、视频（792条）、语音
  - name: 群组管理
    description: 群组列表、成员、公告、名称、踢人
  - name: 标签
    description: 联系人标签（36个）
  - name: 小程序
    description: 小程序使用记录
  - name: 导航
    description: 界面导航控制
  - name: 高级SQL
    description: 原始SQL查询，支持23个数据库