oa-email-code-login 实现邮箱验证码登录

2026-05-27 06:49:58 +08:00
@@ -0,0 +1,57 @@
+# 邮箱验证码登录实施记录
+
+## 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 需要本地提交后另行确认。