openclaw-voc-skill/claude-code/claude-code-qiwe-assistant/docs/specs/qiwe-subscription-flow.md

企微登录两步流程与订阅套餐页规范

流程页服务（默认模式）

qiwe_login_start 默认在本地端口（QIWE_FLOW_PORT，默认 4310）启动 流程页服务（mcp/src/core/login-flow-server.js）并自动打开浏览器：

• 页面加载时请求 /flow/state 自动判断当前所处步骤 （已登录→完成页；已订阅→直接出码；未订阅→套餐页）；
• 套餐页点「开通服务」→ /flow/subscribe 扣费成功后自动进入出码步骤；
• 出码后每 3 秒自动轮询 /flow/check，无需手动刷新；
• 状态 10 自动切到验证码输入页，提交 /flow/verify 后继续轮询；
• 状态 2 显示登录成功页。

鉴权 token 仅保存在流程页服务进程内存中，不写入 HTML。 传 flowUi=false 回退到静态文件模式（下述两步流程）。

流程总览（静态模式）

1. 第 1 步：开通订阅（付费）

   • qiwe_login_start 会先查询 GET /subscribe/status；
   • 未开通/已到期时，不直接报错，而是生成套餐选择页 outputs/subscription/qiwe-subscribe.html 并自动打开浏览器；
   • 页面上选择席位（1/3/10/20/50 个号）与时长（1/6/12 个月）， 点击「开通服务」后调用 POST /subscribe，按 席位数 × ¥200/月 × 月数 从飞马余额一次性扣费；
   • 开通成功后重新调用 qiwe_login_start 进入第 2 步。

2. 第 2 步：扫码登录

   • qiwe_login_start 生成二维码（outputs/login/qiwe-login-qrcode.png + 预览页）；
   • 手机企业微信扫码确认后，qiwe_login_check 轮询状态；
   • 状态 10 时用 qiwe_login_verify 提交 6 位验证码。

价格

• 单价：每个账号（席位）¥200/月（QIWE_MONTHLY_PRICE）。
• 页面套餐：1 号 ¥200/月、3 号 ¥600/月、10 号 ¥2000/月（推荐）、 20 号 ¥4000/月、50 号 ¥10000/月；时长 1/6/12 个月。

错误码设计

错误码	HTTP	含义	用户提示
QW-AUTH-401	401	鉴权失败	token 无效或过期，检查 QIWE_AUTH_TOKEN 后重试
QW-PAY-402	402	飞马余额不足	余额不足以完成扣费，请先充值飞马余额
QW-SUB-402	402	订阅未开通或已到期	在套餐页选择席位并点击开通
QW-SEAT-403	403	席位已满	增购席位或停用闲置设备
QW-UP-502	502/503	网关或企微服务不可用	稍后重试

对应模块：mcp/src/core/subscribe-page.js（ERROR_CODES / classifySubscribeError / saveSubscribePage）。

MCP 工具侧状态

• needs_subscription：qiwe_login_start 检测到未订阅时返回， summary.subscribePage 指向套餐页路径；
• needs_seat：席位不足；
• needs_auth：鉴权失败；
• needs_verify_code：扫码后需要 6 位验证码。