From 2c11b45e319d6194aca67867ca5a0f0d31f317b1 Mon Sep 17 00:00:00 2001
From: xiangning <xiangning@buildflow.local>
Date: Fri, 17 Jul 2026 15:18:45 +0800
Subject: [PATCH] docs(monitoring): define uhaozu captcha login flow

---
 .../2026-07-17-uhaozu-captcha-login-design.md | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-17-uhaozu-captcha-login-design.md

diff --git a/docs/superpowers/specs/2026-07-17-uhaozu-captcha-login-design.md b/docs/superpowers/specs/2026-07-17-uhaozu-captcha-login-design.md
new file mode 100644
index 0000000..c137dff
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-17-uhaozu-captcha-login-design.md
@@ -0,0 +1,65 @@
+# u号租验证码登录设计
+
+## 目标
+
+在 BuildFlow 外部系统凭证弹窗中输入 u号租账号和密码后，展示 u号租使用的腾讯验证码。验证码由用户本人完成，验证通过后系统继续调用 u号租登录接口，获取并保存登录 Cookie。
+
+本功能只负责展示验证码和承接用户操作，不实现验证码识别、自动点击或绕过。
+
+## 固定流程
+
+1. 用户在外部系统凭证弹窗输入 u号租账号和密码。
+2. 前端使用 u号租对应的腾讯验证码应用 ID `192192826` 调起腾讯验证码 SDK。
+3. 腾讯 SDK 自行完成 `cap_union_prehandle`、`tdc.js`、验证码图片和 `blob:` 资源的加载，前端不手工拼装这些内部请求。
+4. 用户在腾讯验证码弹窗内手动完成安全验证。
+5. 腾讯 SDK 回调成功结果，前端取得 `ticket` 和 `randstr`。
+6. 前端把账号、密码、`ticket`、`randstr` 提交给 BuildFlow API。
+7. BuildFlow API 按 u号租真实登录请求契约提交登录，不猜测字段名或加密方式。
+8. 登录成功后，API 从响应会话中提取 `b.uhaozu.com` 和 `mapi.uhaozu.com` 所需 Cookie。
+9. API 用新 Cookie 覆盖该外部系统原有 Cookie 凭证，保留非 Cookie 类型凭证。
+10. 前端提示登录成功并刷新凭证状态。
+
+## 前端设计
+
+- 落点：`build-flow.web/apps/web-antdv-next/src/views/monitoring/systems/modules/credential-form.vue`。
+- 账号和密码为空时不调起验证码。
+- 验证码脚本按需加载，避免全站页面无条件加载第三方脚本。
+- 点击“登录”后直接展示腾讯原生验证码弹窗，不复制验证码图片，不自行绘制验证内容。
+- 用户关闭或验证失败时保持凭证弹窗打开，不调用登录 API。
+- 验证通过后锁定登录按钮，调用后端登录接口，完成后恢复按钮状态。
+- 页面不保存账号、密码、验证码票据或 Cookie 到本地存储。
+
+## 后端设计
+
+- HTTP 入口保留在 `BuildFlow.Host/Endpoints/Monitoring`，权限沿用外部系统管理权限。
+- Endpoint 只转换请求并发送 Monitoring 模块的 MediatR Command。
+- Monitoring Application Handler 校验外部系统存在且类型为 `UHaoZu`。
+- Monitoring Infrastructure 负责按真实 u号租登录契约发起请求并维护 CookieContainer。
+- 登录请求字段、密码处理方式、必要请求头和成功判断必须来自实际 u号租登录请求，不使用当前草稿中的猜测字段。
+- 成功后只返回凭证数量和状态，不向前端返回 Cookie 明文。
+- 密码、`ticket`、`randstr`、Cookie 和完整登录响应不得写入日志。
+- 本次复用现有 `SystemData.Credentials`，不新增数据库表或迁移。
+
+## 错误处理
+
+- 腾讯验证码脚本加载失败：前端提示刷新重试。
+- 用户取消验证码：仅结束本次操作，不显示登录失败。
+- 验证票据失效或被拒绝：后端返回业务错误，用户重新调起验证码。
+- u号租账号或密码错误：展示 u号租返回的可读业务信息，不保存 Cookie。
+- u号租请求超时或不可用：返回统一业务错误，不泄露上游响应、请求头或凭证。
+- 登录响应成功但没有有效 Cookie：视为失败，不覆盖旧凭证。
+
+## 测试与验收
+
+- 前端测试：账号密码为空时不弹验证码；取消验证不调用登录 API；成功回调只调用一次登录 API；失败后按钮恢复。
+- 后端测试：非 u号租系统被拒绝；上游失败不修改凭证；无 Cookie 不覆盖旧凭证；成功时覆盖 Cookie 并保留 Header/Token。
+- 构建验证：前端 typecheck/build，后端解决方案 build/test。
+- 人工验收：在真实环境输入测试账号，确认腾讯原生验证弹出；用户手动完成后登录继续；数据库凭证中出现有效 Cookie；随后 u号租 Connector 能使用该 Cookie 请求数据。
+
+## 明确不做
+
+- 不识别验证码图片。
+- 不自动点击验证码。
+- 不下载验证码图片后自行实现验证 UI。
+- 不使用 Playwright、远程桌面、Sidecar 或反向代理替换用户指定流程。
+- 不把账号、密码或 Cookie 暴露给浏览器日志、服务日志或接口响应。