QIWEI-skill/docs/specs/qiwei-account-login-seat-flow.md

企微账号登录与席位决策流程

计数模型

• 客户订阅席位按唯一企微账号 corpId + userId 计数。
• 多台电脑使用同一 Fmode 凭据连接同一企微账号时，共享服务端账号会话，不重复占客户席位。
• 上游登录实例容量与客户订阅席位分开管理。
• 临时二维码、待验证码和待席位决策的登录尝试不计客户席位，并设置过期清理时间。

完整流程

flowchart TD
  A["启动客户端或打开登录页"] --> B{"Fmode Token 有效"}
  B -- "否" --> B1["配置或刷新 Token"] --> B
  B -- "是" --> C["查询订阅状态"]
  C --> D{"订阅有效"}
  D -- "否" --> D1["开通或续费"] --> C
  D -- "是" --> E["查询已绑定账号"]
  E --> F{"选择登录方式"}
  F -- "已有账号在线" --> S["绑定当前电脑并共享会话"]
  F -- "已有账号离线" --> G["复用账号 guid 生成二维码"]
  F -- "登录其他账号" --> H["创建临时 uid 和上游实例"]
  G --> Q["扫码与验证码状态轮询"]
  H --> Q
  Q --> I{"登录成功并获得 corpId + userId"}
  I -- "身份已绑定" --> R["复用席位并更新 canonical guid"] --> S
  I -- "新身份" --> J{"客户席位有空余"}
  J -- "是" --> K["正式绑定新账号"] --> S
  J -- "否" --> L{"购买、替换或取消"}
  L -- "新增购买席位" --> M["实时询价并幂等扣费"]
  M --> N["重新查询席位并提交登录"] --> K
  L -- "替换已有账号" --> O["确认目标账号并停止旧 guid"] --> K
  L -- "取消" --> P["停止临时实例并清理"]
  S --> T["登录完成并启动监听或 Relay"]

接口约定

接口	用途
GET /login/accounts	返回当前租户已绑定账号、在线状态和席位摘要
POST /login/select	将当前电脑 uid 绑定到已有账号
POST /login/start	创建或复用上游登录会话；newAccount=true 时创建临时 uid
POST /login/check	轮询二维码；成功后按账号身份去重并返回席位决策
POST /login/resolve	执行购买后提交、替换或取消
GET /subscribe/status?seats=N&months=1	获取增购实时补差报价
POST /subscribe	使用报价金额和幂等键完成增购

席位已满决策

扫码身份为新账号且席位已满时，/login/check 返回：

{
  "status": 2,
  "decisionRequired": true,
  "loginState": "decision_required",
  "actions": ["purchase", "replace", "cancel"]
}

• purchase：按当前席位数加一询价并购买；购买成功后再次加锁校验，随后自动绑定当前扫码账号。
• replace：客户选择一个已绑定账号，二次确认后停止旧会话并绑定新账号。
• cancel：停止临时会话并清理登录尝试。

支付和账号绑定使用相同租户锁串行化。支付成功但绑定请求中断时，客户端复用原幂等订单并再次执行 purchase 提交，避免重复扣费。

兼容规则

• 旧 QiweiDevice 记录存在 guid + lastLoginAt 时，懒迁移为一个 legacy 账号席位。
• 只有二维码但从未成功登录的旧记录不占客户席位。
• 业务接口继续使用 uid，服务端通过 uid 找到共享 guid，现有 MCP 工具调用保持兼容。