qiwei-subscription-flow.md 2.9 KB
企微登录两步流程与订阅套餐页规范
流程页服务（默认模式）
qiwei_login_start 默认在本地端口（QIWEI_FLOW_PORT，默认 4310）启动
流程页服务（mcp/src/core/login-flow-server.js）并自动打开浏览器：
- 页面加载时请求
/flow/state自动判断当前所处步骤 （已登录→完成页；已订阅→直接出码；未订阅→套餐页）； - 套餐页点「开通服务」→
/flow/subscribe使用一次性付款确认码提交； - 本地服务一次调用正式
POST /subscribe，由 Future Server 按席位与月数完成整笔扣费和续期； - 出码后每 3 秒自动轮询
/flow/check，无需手动刷新； - 状态 10 自动切到验证码输入页，提交
/flow/verify后继续轮询； - 状态 2 显示登录成功页。
鉴权 token 仅保存在流程页服务进程内存中，不写入 HTML。HTML 只携带当前本地页面使用的 一次性付款确认码，开通成功后立即失效。
flowUi=false 回退模式
- 已开通订阅时，可以使用扫码回退服务：
qiwei_login_start生成二维码（outputs/login/qiwei-login-qrcode.png+ 预览页）；- 手机企业微信扫码确认后，
qiwei_login_check轮询状态； - 状态 10 时用
qiwei_login_verify提交 6 位验证码。
- 未开通/已到期时返回
needs_subscription，提示重新使用默认动态流程页或调用qiwei_subscribe；不再生成会把鉴权信息写入 HTML 的静态付费页。
价格
- 单价：每个账号（席位）¥500/月（以服务端
/subscribe/status返回的price为准，本地默认值为 500）。 - 页面套餐：1 号 ¥500/月、3 号 ¥1500/月、10 号 ¥5000/月（推荐）、 20 号 ¥10000/月、50 号 ¥25000/月；时长 1/6/12 个月。
错误码设计
| 错误码 | HTTP | 含义 | 用户提示 |
|---|---|---|---|
| QW-AUTH-401 | 401 | 鉴权失败 | token 无效或过期，检查 QIWEI_AUTH_TOKEN 后重试 |
| QW-PAY-402 | 402 | 飞马余额不足 | 余额不足以完成扣费，请先充值飞马余额 |
| QW-SUB-402 | 402 | 订阅未开通或已到期 | 在套餐页选择席位并点击开通 |
| QW-PAY-403 | 403 | 本地付款确认无效或已使用 | 刷新本地流程页后重新选择套餐 |
| QW-SEAT-403 | 403 | 席位已满 | 增购席位或停用闲置设备 |
| QW-UP-502 | 502/503 | 网关或企微服务不可用 | 稍后重试 |
对应模块：mcp/src/core/subscribe-page.js（套餐、价格、ERROR_CODES、
classifySubscribeError）与 mcp/src/core/login-flow-server.js（动态页面和一次性付款确认）。
MCP 工具侧状态
needs_subscription：qiwei_login_start检测到未订阅时返回， 默认动态流程页直接展示套餐；flowUi=false时提示改用动态流程；needs_seat：席位不足；needs_auth：鉴权失败；needs_verify_code：扫码后需要 6 位验证码。