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

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

`qiwei_login_start` 默认在本地端口（`QIWEI_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 步：开通订阅（付费）**
   - `qiwei_login_start` 会先查询 `GET /subscribe/status`；
   - 未开通/已到期时，不直接报错，而是生成套餐选择页
     `outputs/subscription/qiwei-subscribe.html` 并自动打开浏览器；
   - 页面上选择席位（1/3/10/20/50 个号）与时长（1/6/12 个月），
     点击「开通服务」后调用 `POST /subscribe`，按
     `席位数 × ¥200/月 × 月数` 从飞马余额一次性扣费；
   - 开通成功后重新调用 `qiwei_login_start` 进入第 2 步。

2. **第 2 步：扫码登录**
   - `qiwei_login_start` 生成二维码（`outputs/login/qiwei-login-qrcode.png` + 预览页）；
   - 手机企业微信扫码确认后，`qiwei_login_check` 轮询状态；
   - 状态 10 时用 `qiwei_login_verify` 提交 6 位验证码。

## 价格

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

## 错误码设计

| 错误码 | HTTP | 含义 | 用户提示 |
| --- | --- | --- | --- |
| QW-AUTH-401 | 401 | 鉴权失败 | token 无效或过期，检查 QIWEI_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`：`qiwei_login_start` 检测到未订阅时返回，
  `summary.subscribePage` 指向套餐页路径；
- `needs_seat`：席位不足；
- `needs_auth`：鉴权失败；
- `needs_verify_code`：扫码后需要 6 位验证码。