merge-kix-login-to-upstream

把 KiX fork 的登录方案合并进上游

这个 skill 是干什么的

KiX 下游 fork 团队做了一套三端登录（邮箱验证码 / Google / Apple，接入 KiX/Lobah 身份平台）， 以及一批 bug 修复。上游（mozatyin/kix-platform）更新频繁、且自己长出了另一套原生登录 （邮箱+密码 / SMTP / WhatsApp OTP），但没有接入 KiX 平台。

你的任务：把 fork 的登录方案移植/替换进当前最新上游，并按需采纳 bug 修复。

核心原则：这是"讲意图 + 给参考代码"，不是"照搬补丁"。 上游结构一直在变，reference/ 里的代码是从 fork 抠出来的蓝本，依赖你自适应地落到 上游当前真实结构上。先读代码、先核对，再改。

开始前先读

1. reference/00-upstream-baseline-and-mapping.md —— 上游基线快照 + 前端/后端逐项落点映射 + 依赖核对清单。必读。
2. reference/frontend/kix-login-addon.reference.js —— 登录前端逻辑（从 fork 单体 addon 抠出，已去掉模板库等无关部分）。文件头有出处与照抄风险。
3. reference/backend/ —— 后端登录源码（3 个新建服务 + portal_auth 端点增量 + schemas/config/main 片段）。
4. reference/bugfixes/bugfixes.md —— 7 条 bug 的"症状/根因/我方修法/是否适用你上游"，建议型。

---

执行步骤

步骤 0 · 摸清你自己的上游现状（不要跳过）

在动手前，用搜索确认这些事实（结构可能和快照不同）：

• 登录页在哪？搜 signin、login、#login-section、/auth/token、portal/auth/login。
• 后台页登录后读哪个 token？搜 localStorage、kix_portal_token、KIX_API。
• app/routers/portal_auth.py 现有哪些端点、有没有 _create_portal_access_token / _create_portal_refresh_token。
• app/schemas.py、app/config.py、app/models.py（BrandConfig）、app/database.py、app/redis_client.py 是否具备映射文档里列的依赖。
• 把发现记下来，作为后续落点依据。

步骤 1 · 后端：加三端登录端点（注册登录合一）

按 reference/00-...md §五 的落点映射操作：

1. 新建 app/services/email_login_client.py、third_party_login_client.py、operator_provisioner.py（直接用 reference 同名文件，按你的 models/database 调整 import）。
2. 把 portal_auth.endpoints.py 里的 3 个端点 + _store_refresh_token + 新 import/常量 合进你已有的 app/routers/portal_auth.py。复用其中已存在的 token 助手；名字对不上就适配。
3. 把 schemas.login.py 的模型追加进 app/schemas.py；把 config.snippet.py 的字段加进 Settings；把 main.snippet.py 的 _seed_dev_brand 接 startup、close_client 接 shutdown。
4. 合一：不要保留独立注册端点作为登录前置；首次登录由 operator_provisioner 自动建 brand。上游 merchant-signup/Stripe 是否下线由你按实际判断。

最终端点路径（取决于 router prefix，通常）：

• POST /api/v1/portal/auth/email/send-code
• POST /api/v1/portal/auth/email/login
• POST /api/v1/portal/auth/third-party/login

步骤 2 · 前端：用三端登录替换上游登录

按 §四 落点映射，把 kix-login-addon.reference.js 的登录逻辑重写进你当前的登录页（如 signin.html），而不是把文件原样塞进 portal.html：

• 把登录表单区替换为三通道 UI（邮箱验证码含 60s 倒计时 / Google / Apple）。
• 三个提交流程打步骤 1 的后端端点。
• 登录成功：写你 portal 实际读取的 token key，再跳转后台页。
• 主题适配（思路型）：配色跟随你现有浅色主题，用 CSS 变量/继承，不要照搬 fork 的 #111/#fff/#00FC00 深色值。
• OAuth 配置（Firebase / Apple clientId）在 reference 文件顶部；共用同一 KiX/Lobah 后端就保留，否则换你自己的。

步骤 3 · Bug 修复（逐条判断，按需采纳）

打开 reference/bugfixes/bugfixes.md，逐条判断是否适用你上游：

• 与登录强相关的 #1 黑屏（仅当你页面有 #tut-overlay）、#2 API_BASE 写死（确认你登录页/前端没写死 host）、#3 错误提示不显示（若复用 fork 登录 JS）——重点看。
• #4–#7（QR/配方/券/模板目录）依赖 fork 特有后端模块，你上游没有对应代码就直接跳过，不要硬塞。
• 采纳与否你定；采纳的，说明你改了哪、为什么。

步骤 4 · 起后端做自检（docker 优先，可回退）

依赖优先 docker 化、线上 k8s。自检只做端点级烟雾测试（不做真实 OAuth 弹窗 / 真收验证码）。

先确定怎么起后端，按以下顺序回退：

1. 首选 docker：检测 docker / docker compose 是否可用（docker --version）。可用就用 docker / docker-compose 起整套依赖（FastAPI + Redis + DB）——这与线上 k8s 最接近，最可信。
2. 没有 docker → 尝试安装：若环境无 docker，尝试按其操作系统安装（如官方脚本 curl -fsSL https://get.docker.com | sh、或包管理器、或 Docker Desktop），装好后回到第 1 步。
3. 实在装不上 → 用他原来的部署方式：若无法安装 docker（权限/网络/平台限制），回退到该项目原有的本地启动方式（如 uvicorn app.main:app + 本地/已有的 Redis、DB，或仓库现成的启动脚本/Makefile）。在报告里写明退到了非 docker 方式及原因。

无论用哪种方式起起来后：

1. 确认服务健康（/health 或等价）。
2. 对三个登录端点做烟雾测试（在容器网络内或映射端口上 curl）：
   • 路由已注册：缺参/错误请求不是 404（404 = 没接上路由）。
   • 参数校验生效：
     • send-code 非法邮箱 → 422
     • send-code 60s 内重复 → 429
     • email/login 缺 verify_code → 422；错误验证码 → 401（外部服务不可达时可能 502，属预期）
     • third-party/login 非法 tp_platform → 422
   • 返回码合理即可，不要求真的登录成功。
3. 静态检查：Python 能 import（无语法/导入错误，如 python -c "import app.main" 或起服务不报错）；前端 JS 无语法错误；路由确实注册（/openapi.json 或 docs 里能看到三个端点）；关键字符串核对（端点路径、token key 一致）。
4. 把自检命令与结果如实写进最终报告（哪些过、哪些因外部依赖跳过）。

---

完成后给出

• 改了哪些文件、每处意图。
• bug 修复逐条：采纳/跳过 + 原因。
• 主题适配怎么处理的。
• docker 自检命令 + 实际返回码（含因外部服务跳过的项）。
• 仍需人工验证的：浏览器点 Google/Apple 弹窗、真实收邮件验证码、UI 在浅色主题下不发暗。

不要做

• 不要把 reference 代码当补丁照抄——务必自适应到上游当前结构。
• 不要照搬 fork 的深色主题色值。
• 不要为"对齐"把上游没有对应代码的 bug 修复硬塞进去。
• 不要在后端根本没起起来的情况下声称自检通过（docker 优先；装不上可回退原部署方式，但要在报告里写明）。
• 不要尝试真实 OAuth / 真实收码的端到端测试（环境做不了，烟雾测试即可）。