hyb-oa/.trellis/tasks/archive/2026-05/05-26-oa-email-code-login/implement.md

邮箱验证码登录实施记录

Implementation Scope

• 新增 EmailLoginCode Prisma 模型和迁移，用于登录验证码，不复用 PasswordResetCode。
• 新增后端接口：
  • POST /api/auth/email-login/code
  • POST /api/auth/email-login/verify
• 邮箱验证码使用 HMAC-SHA256 保存 hash，验证码明文只进入邮件正文，不写库。
• 验证成功后复用现有 refresh cookie、has_session、access token、设备指纹和 session 数量上限逻辑。
• 前端登录页新增“密码登录 / 邮箱验证码”切换。
• 使用 frontend-design 作为前端视觉主准则，将认证页升级为 refined industrial minimal：细网格背景、顶部品牌轨道、单一认证面板。

Safety Boundaries

• 不复用密码找回验证码表和语义。
• 不新增短信登录。
• 不修改企业微信 OAuth/绑定逻辑。
• 不修改企业邮箱/企业微信后台配置。
• 不写真实账号密码、验证码、token、Secret 或真实 payload。
• 不部署公网，不写真实业务数据。

Migration Notes

• 新增表：email_login_codes。
• 外键：email_login_codes.employee_id -> employees.id，ON DELETE RESTRICT。
• 索引：
  • email_login_codes_employee_id_created_at_idx
  • email_login_codes_expires_at_idx
• 回滚路径：若需回滚本功能，先停用新增前端入口和接口，再执行 DROP TABLE "email_login_codes";。该表只保存登录验证码 hash 和请求上下文，不承载业务事实源。

Validation Log

• cd server && node --check src/routes/auth.js && node --check src/config.js：已通过。
• cd server && npm run prisma:validate：已通过。
• cd server && npm test -- --run tests/unit/routes/auth.login.test.js：已通过，9 passed。
• cd client && npm run typecheck：已通过。
• cd client && npm run build：已通过，production build 和 PWA precache 正常生成。
• 登录 focused E2E：已通过，3 passed。
• 企业微信入口 E2E：已通过，2 passed。
• node scripts/qa/check-ui-design-rules.mjs --strict：已通过。
• python3 ./.trellis/scripts/task.py validate 05-26-oa-email-code-login：已通过。
• git diff --check：已通过。
• 视觉截图已生成：
  • output/playwright/oa-email-code-login/desktop-password-login.png
  • output/playwright/oa-email-code-login/desktop-email-code-login.png
  • output/playwright/oa-email-code-login/mobile-wecom-login.png

Design Governance Update

• 已同步 AGENTS.md、.trellis/spec/hyb-oa/frontend-react-vite-design.md 和 docs/产品设计规则.md：前端视觉与交互设计以 frontend-design skill 为准。
• docs/产品设计规则.md 继续保留业务事实、品牌识别、历史页面治理和验收参考，不作为视觉裁决优先级。

Known Notes

• Trellis governance 对历史任务 05-26-oa-auth-layout-wecom-login-ux 的 jsonl 仍保留 docs/产品设计规则.md context warning；这是已提交历史任务的上下文提醒，不影响本任务通过。
• 公网部署和 live smoke 需要本地提交后另行确认。

Deployment And Public Smoke Log

• 用户已批准执行部署与公网验证。
• 部署前已完成远端备份：
  • DB 备份：hyb-oa-db-20260527_075800.dump
  • 文件存储备份：hyb-oa-storage-20260527_075801.tar.gz
  • 远端环境配置副本：hyb-oa-env-20260527_075800.env
• 部署命令采用 SYNC_ENV=0，未覆盖远端 .env。
• 部署脚本已通过：
  • 部署环境契约校验。
  • Docker 前端 production build。
  • Prisma migration deploy，已应用 20260526211500_email_code_login。
  • Prisma migration status：schema up to date。
  • /ready、external deps smoke、runtime smoke。
  • 公网 live smoke：3 passed。
  • 公网前端资源文案扫描：findings=0。
• 补充公网验证已通过：
  • check-live-smoke-env.mjs --strict：public ready、企微 ready、live smoke 与 OCR 条件均 ready。
  • 邮箱验证码公网后端探测：不存在账号请求验证码返回通用成功；伪造验证码校验被拒绝，未暴露账号存在性。
  • 公网前端 focused E2E：登录页找回密码/PWA 输入保护、邮箱验证码登录、找回密码流程，3 passed。
  • 公网企业微信入口 E2E：普通浏览器次级入口、企业微信场景主 CTA，2 passed。
  • 公网登录页截图与溢出检查：PC 密码登录、PC 邮箱验证码、移动企微入口均通过。
• 视觉截图：
  • output/playwright/oa-email-code-login-live/desktop-password-login.png
  • output/playwright/oa-email-code-login-live/desktop-email-code-login.png
  • output/playwright/oa-email-code-login-live/mobile-wecom-login.png
• 远端近期 server 日志摘要：近 5 分钟 error-like 行数为 0。