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

## 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 需要本地提交后另行确认。