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

## 流程页服务（默认模式）

`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 位验证码。