# 邮箱验证码登录实施记录

## 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。