From de65a07a5113244202989e4542ee321174a0ffdd Mon Sep 17 00:00:00 2001 From: shunli Date: Fri, 31 Jul 2026 08:29:30 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=20PC=20=E7=99=BB=E5=BD=95?= =?UTF-8?q?=E9=A1=B5=E6=A1=8C=E9=9D=A2=E5=B8=83=E5=B1=80=EF=BC=8807-30-pc-?= =?UTF-8?q?login-desktop-layout=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../spec/hyb-oa/frontend-react-vite-design.md | 31 ++- .../07-30-pc-login-desktop-layout/check.jsonl | 1 + .../07-30-pc-login-desktop-layout/design.md | 81 +++++++ .../implement.jsonl | 1 + .../implement.md | 52 +++++ .../07-30-pc-login-desktop-layout/prd.md | 84 +++++++ .../07-30-pc-login-desktop-layout/task.json | 33 +++ client/src/layouts/AuthLayout.tsx | 27 ++- client/src/pages/LoginPage.tsx | 209 +++++++++++------- client/src/router/index.tsx | 2 +- client/tests/e2e/login-portal-ux.spec.ts | 4 + client/tests/e2e/wecom-entry.spec.ts | 110 ++++++++- 12 files changed, 541 insertions(+), 94 deletions(-) create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/check.jsonl create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/design.md create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/implement.jsonl create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/implement.md create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/prd.md create mode 100644 .trellis/tasks/07-30-pc-login-desktop-layout/task.json diff --git a/.trellis/spec/hyb-oa/frontend-react-vite-design.md b/.trellis/spec/hyb-oa/frontend-react-vite-design.md index 46cdc6f6..b5d19737 100644 --- a/.trellis/spec/hyb-oa/frontend-react-vite-design.md +++ b/.trellis/spec/hyb-oa/frontend-react-vite-design.md @@ -1664,7 +1664,10 @@ onNeedRefresh() { - Auth routes should use one shared auth panel for brand, page title, subtitle, content and optional footer links. - `AuthLayout` owns only the auth page shell: background, width constraint, - centering, PWA update prompt and route outlet. + centering, PWA update prompt and route outlet. Its default variant remains a + 460px auth form; `/login` may explicitly select the `login` variant to allow + the approved desktop entry layout without widening password recovery or + forced password change pages. - Page implementations own only their form fields, submit actions, validation messages and route-specific login-entry choices. @@ -1673,8 +1676,12 @@ onNeedRefresh() { - Do not nest a form card inside another login card. - Put the brand block inside the auth panel so logo, system name, title and form share one visual axis. -- Keep the panel width stable around the current auth-shell width; auth pages - should feel like an OA workstation entry, not a marketing split hero. +- Keep password recovery, forced password change and login fallback-only panels + stable around the 460px auth-shell width. When PC Enterprise WeChat login is + enabled, `/login` may expand to a functional desktop split up to roughly + 920px: Enterprise WeChat entry on the left and a form column capped around + 404px on the right. This remains one shared auth panel, not a marketing split + hero or nested form-card layout. - Place `忘记密码？` beside the password label or directly below the password input on the right; do not bury it in help text or page footer. - Keep the DOM/tab order aligned with the main form flow even when CSS places @@ -1686,10 +1693,15 @@ onNeedRefresh() { ### 4. Login Entry Hierarchy -- Normal browser: account/password or email-code login is primary. Enterprise - WeChat is shown as a boundary notice or secondary entry that tells users to - open OA from the Enterprise WeChat workbench; do not require a clickable OAuth - button in ordinary browsers. +- Normal browser with `pcWebLoginEnabled=true` and a non-null `pcLoginUrl`: + Enterprise WeChat is the preferred desktop entry. At 1024px and above, show + it in the left functional column and keep account/password plus email-code in + the right fallback column. Below 1024px, preserve the existing single-column + form-first order and show the PC Enterprise WeChat entry afterward. +- Normal browser without an available PC login URL: keep the existing 460px + single-column form and show only the workbench boundary notice or other + configured secondary provider; never render an empty desktop column or a + disabled PC login button. - Enterprise WeChat WebView: Enterprise WeChat one-click entry is primary; account/password login remains available as the fallback path. - Enterprise WeChat entry changes must remain frontend entry hierarchy changes @@ -1706,7 +1718,10 @@ onNeedRefresh() { - keyboard Tab from the username/email field lands on the password input, not the forgot-password link; - password recovery request-code and reset flow on `/forgot-password`; - - normal-browser Enterprise WeChat boundary notice or secondary entry; + - 1024px and 1440px normal-browser PC Enterprise WeChat functional split, + including column position and controlled form width; + - 375px and 768px single-column form-first order without horizontal overflow; + - PC login configuration unavailable falling back to the 460px single column; - WeCom WebView Enterprise WeChat entry as primary CTA with password fallback. - UI design rules check and Playwright screenshot evidence when the auth layout changes visibly. diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/check.jsonl b/.trellis/tasks/07-30-pc-login-desktop-layout/check.jsonl new file mode 100644 index 00000000..9dd3234a --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/check.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/design.md b/.trellis/tasks/07-30-pc-login-desktop-layout/design.md new file mode 100644 index 00000000..a11f9d9f --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/design.md @@ -0,0 +1,81 @@ +# PC 登录页桌面布局优化设计 + +## 1. Design Goal + +只调整普通 PC 浏览器登录页的响应式布局和视觉层级：桌面端通过功能双栏突出企业微信扫码主入口，同时保留完整的密码与邮箱验证码回退；所有认证请求、跳转和错误合同保持不变。 + +## 2. Current Structure + +```text +AuthLayout + max-width: 460px（所有认证页共享） + └─ LoginPage + └─ AuthPanel + ├─ 品牌与标题 + ├─ 登录方式说明 + ├─ 密码 / 邮箱验证码切换与表单 + └─ 企业微信扫码入口 +``` + +问题根因是共享 `AuthLayout` 在所有视口统一限制为 460px，`LoginPage` 内部也只有单列内容流。直接扩大共享宽度会连带影响找回密码和修改密码；直接拉伸表单则会造成过长输入框。 + +## 3. Target Structure + +```text +普通浏览器，桌面 >= 1024px，PC 扫码可用 +AuthLayout(login variant, wider container) + └─ AuthPanel + ├─ 共享品牌、标题、全局状态 + └─ desktop grid + ├─ 左：企业微信扫码主入口 + └─ 右：密码 / 邮箱验证码切换与表单 + +普通浏览器，PC 扫码不可用 + └─ 宽容器内的受控单列表单，不渲染空白左栏 + +窄屏 / 企业微信 WebView + └─ 保持现有单列顺序与一键进入/密码回退行为 +``` + +## 4. Component Boundaries + +### 4.1 `AuthLayout` + +- 增加显式页面级布局 variant，由路由仅为 `/login` 选择宽版桌面容器。 +- 默认 variant 继续保持 460px，因此 `/forgot-password` 和 `/change-password` 不受影响。 +- PWA 更新提示与页面内容共享同一受控容器，不改变更新行为。 + +### 4.2 `LoginPage` + +- 复用现有查询、状态、事件处理函数和 `data-testid`。 +- 将“企业入口”和“备用登录”整理为可响应式排序的语义分区；桌面扫码可用时启用双栏。 +- 企业微信扫码按钮在桌面双栏中使用主入口视觉；窄屏沿用现有顺序与按钮行为。 +- 顶部绑定/登录结果提示属于全局状态，跨双栏显示，避免只附着在某一种登录方式上。 + +### 4.3 Shared styles + +- 优先使用现有 Tailwind 断点、主题 token、`AuthPanel`、`Button`、`Input` 和状态提示。 +- 仅在重复或难以表达的布局规则出现时增加少量 `auth-*` CSS 类，不新增 token 文件或依赖。 + +## 5. Responsive Contract + +| 场景 | 布局 | +| --- | --- | +| 375px | 单列，无横向滚动；保持现有普通浏览器内容顺序 | +| 768px | 单列或受控过渡宽度，不提前挤成双栏 | +| 1024px | PC 扫码可用时进入功能双栏 | +| 1440px | 双栏居中，外层和列宽均有上限，不把表单拉满 | +| 企业微信 WebView | 单列，一键进入优先；不展示 PC 扫码栏 | +| PC 扫码关闭/配置缺失 | 单列回退，不显示空栏或失效按钮 | + +## 6. Compatibility and Risk Controls + +- 不修改 `fetchWecomConfig`、`buildWecomLoginUrl`、redirect、设备指纹或任何服务端代码。 +- 不改现有输入、按钮和提示的测试标识；布局测试只增加容器级标识。 +- 主要风险是 JSX 重排导致条件渲染遗漏、移动端顺序回退或共享认证页被扩宽。通过场景化 Playwright、边界尺寸断言和截图复核控制。 +- 不引入新的持久化状态、迁移或生产配置，因此应用回滚只需回滚本任务前端提交。 + +## 7. Rollout Boundary + +- 本地验证不等于线上可测。 +- 若后续需要部署，必须另行获得明确批准，并完成公网登录页、扫码跳转、密码/邮箱入口和构建标识检查后才能通知用户测试。 diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/implement.jsonl b/.trellis/tasks/07-30-pc-login-desktop-layout/implement.jsonl new file mode 100644 index 00000000..9dd3234a --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/implement.jsonl @@ -0,0 +1 @@ +{"_example": "Fill with {\"file\": \"\", \"reason\": \"\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."} diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/implement.md b/.trellis/tasks/07-30-pc-login-desktop-layout/implement.md new file mode 100644 index 00000000..a7fe857b --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/implement.md @@ -0,0 +1,52 @@ +# PC 登录页桌面布局优化实施计划 + +## 1. Preconditions + +- [x] 用户确认创建独立 Trellis task。 +- [x] 用户确认桌面端采用“左侧企业微信主入口、右侧备用登录表单”的功能双栏。 +- [x] 用户已批准本 PRD、设计和实施计划，可以运行 `task.py start` 并修改产品代码。 + +## 2. Implementation + +- [x] 为 `AuthLayout` 增加显式登录页宽版 variant，并在路由中只对 `/login` 启用；默认认证页宽度保持不变。 +- [x] 重组 `LoginPage` 的展示层，把全局提示、企业微信主入口和备用登录表单整理为响应式分区。 +- [x] 在普通 PC 浏览器且扫码可用时启用桌面功能双栏；扫码不可用、窄屏和企微 WebView 使用受控单栏。 +- [x] 保留现有认证查询、跳转、回跳、设备指纹、表单状态、错误处理和全部既有控件测试标识。 +- [x] 未增加依赖、平行设计系统或新的 CSS token，仅复用现有 Tailwind、主题 token 和共享组件。 + +## 3. Focused Validation + +- [x] 扩充登录页 Playwright 覆盖：1440px 双栏、1024px 双栏、768px 单栏、375px 单栏、扫码关闭单栏、企业微信 WebView 单栏。 +- [x] 断言桌面双栏的实际边界、相对位置和合理表单宽度，而不只断言元素存在。 +- [x] 回归企业微信扫码跳转的 `entrySource`、`returnTo` 和设备指纹，以及密码/邮箱切换、找回密码和 PWA 输入保持。 +- [x] 生成代表性桌面与移动截图并人工复核信息层级、留白、对比度、焦点和无横向滚动。 + +建议命令： + +```bash +cd client && npx playwright test tests/e2e/wecom-entry.spec.ts tests/e2e/login-portal-ux.spec.ts --workers=1 --reporter=list +cd client && npm run typecheck +cd client && npm run build +``` + +## 4. Project Gates + +- [x] `python3 ./.trellis/scripts/task.py validate 07-30-pc-login-desktop-layout` +- [x] `node scripts/qa/check-process-contract.mjs --baseline --json` +- [x] `node scripts/qa/audit-docs.mjs --check-registry` +- [x] `node scripts/qa/check-trellis-governance.mjs` +- [x] `git diff --check` + +## 5. Review and Rollback + +- [x] 对最终 diff 做认证零变更复核，确认没有服务端、接口、配置、回调或生产文件变化。 +- [x] 已通过 1024px 首轮测试发现备用列过宽并收敛到约 404px；未通过改认证逻辑绕过视觉问题。 +- [x] 已确认生产部署不属于当前规划批准；如需部署，另行申请并按项目公网检查边界执行。 + +## 6. Local Evidence (2026-07-31) + +- `E2E_BASE_URL=http://127.0.0.1:5173 npx playwright test tests/e2e/wecom-entry.spec.ts tests/e2e/login-portal-ux.spec.ts --workers=1 --reporter=list`：19 passed。 +- `npm run build`：通过；Vite 2383 modules transformed，PWA 102 entries。 +- 代表性截图保存在本地忽略目录 `output/playwright/pc-login-{375,768,1024,1440}.png`，人工复核通过。 +- 项目门禁全部通过；`audit-docs` 只有既有 22 个未注册 docs 文件 warning。 +- 本地开发完成，尚未部署，不能告知用户线上可测。 diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/prd.md b/.trellis/tasks/07-30-pc-login-desktop-layout/prd.md new file mode 100644 index 00000000..472ee582 --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/prd.md @@ -0,0 +1,84 @@ +# PC 登录页桌面布局优化 + +## Goal + +让普通 PC 浏览器中的 OA 登录页呈现明确的桌面端信息层级和合理空间利用，不再像放大后的手机卡片；同时保持已经完成真实验收的企业微信扫码登录、账号密码、邮箱验证码、找回密码、回跳和错误提示行为不变。 + +## Background + +- 当前普通浏览器登录页由共享 `AuthLayout` 约束为最大宽度 460px，桌面视口仍使用单列卡片，因此用户明确反馈“过窄、像手机页面”。 +- 登录页同时承载企业微信扫码入口、账号密码和邮箱验证码；现有企业微信扫码链路已经完成生产真实验收。 +- `AuthLayout` 也被找回密码和修改密码页面复用，不能为了登录页变宽而无意改变全部认证页面。 +- 现有移动端和企业微信 WebView 登录路径已有独立行为，本任务只处理普通 PC 浏览器的桌面布局表达。 + +## Scope + +- 普通 PC 浏览器 `/login` 的页面级宽版容器和响应式功能双栏。 +- 企业微信扫码主入口、密码/邮箱验证码备用登录区的视觉层级与布局重组。 +- 375px、768px、1024px、1440px 代表性视口和企业微信 WebView 的布局回归。 +- 登录页聚焦 Playwright、截图复核和前端/项目治理门禁。 + +## Requirements + +### R1 桌面布局 + +- 普通 PC 浏览器在桌面断点采用“左侧企业微信主入口、右侧备用登录表单”的功能双栏，使用更符合桌面操作的宽度、分区和留白，不能只把现有 460px 单列卡片机械拉宽。 +- 登录方式的优先级必须清晰：企业微信扫码为日常首选，账号密码和邮箱验证码为可见、可用的回退方式。 +- 表单控件保持适合阅读和输入的宽度，不因外层加宽而出现过长输入框。 +- PC 扫码入口不可用时，页面应自然退回受控的单栏表单表达，不保留空白主入口栏。 + +### R2 响应式与共享页面边界 + +- 手机和窄屏继续使用现有单列登录体验，不出现横向滚动、截断或双栏挤压。 +- 企业微信 WebView 继续优先展示一键进入及必要的密码回退，不套用普通 PC 扫码布局。 +- 找回密码、修改密码等共享 `AuthLayout` 页面默认保持现状；如需调整共享容器，只能通过页面级布局能力显式启用。 + +### R3 认证行为零变更 + +- 不修改企业微信配置接口、扫码跳转、OAuth/state/cookie、回调、账号映射、会话、审计和生产开关。 +- 不修改账号密码、邮箱验证码、找回密码、PWA 更新提示、安全 redirect 或设备指纹行为。 +- 保留现有自动化依赖的登录控件语义和 `data-testid`；仅在视觉验收确有需要时增加布局测试标识。 + +### R4 视觉与可访问性 + +- 复用现有品牌、主题 token、`AuthPanel`、按钮、输入框和状态提示，不新建平行设计系统，不引入额外 UI 依赖。 +- 保持可见标签、键盘焦点、足够对比度、状态提示语义和 `prefers-reduced-motion` 边界。 +- 桌面布局至少覆盖 1024px 和 1440px；响应式回归至少覆盖 375px 和 768px。 + +## Acceptance Criteria + +- [x] 1024px 与 1440px 普通浏览器中，登录页形成明确的桌面端布局，不再呈现居中的 460px 手机式窄卡片。 +- [x] 企业微信扫码入口在桌面首屏具有清晰主入口地位，账号密码和邮箱验证码仍可直接找到并正常切换。 +- [x] 375px 与 768px 视口保持单列、无横向滚动，现有输入、提示和按钮完整可用。 +- [x] 企业微信 WebView 的一键进入、失败提示和账号密码回退布局及行为不回退。 +- [x] 找回密码和修改密码页面未被登录页的桌面专属布局意外扩宽或改版。 +- [x] 现有登录方式、returnTo、设备指纹、PWA 输入保持和扫码入口自动化回归通过。 +- [x] 前端 typecheck、build、聚焦 Playwright、代表性视口截图、Trellis 治理检查和 `git diff --check` 通过。 +- [x] 未经另行批准未修改生产配置或部署；当前仅能说明本地验证通过，尚未线上可测。 + +## Local Verification Evidence (2026-07-31) + +- 1024px 与 1440px 截图确认桌面功能双栏、企业微信主入口和约 404px 备用表单列；375px 与 768px 截图确认单列、表单先于企业入口且无横向滚动。 +- 聚焦 Playwright 共 19 项通过，覆盖扫码跳转参数、企微 WebView、密码/邮箱验证码、找回密码、PWA 输入保持、扫码关闭回退及四档视口布局。 +- `npm run build` 通过，Vite 转换 2383 个模块，PWA 生成 102 个预缓存条目。 +- task validate、流程合同、文档注册审计、Trellis 治理和 `git diff --check` 通过；文档审计保留 22 个未注册 docs 文件的既有 warning，本任务未新增文档。 +- 未修改服务端、认证接口、企微配置、生产配置或业务数据，未执行部署和公网检查。 + +## Out of Scope + +- 认证协议、服务端接口、企业微信后台配置、生产功能开关和账号映射规则。 +- 在 OA 页面内嵌企业微信二维码、引入企微 SDK/script/iframe 或重做扫码流程。 +- 找回密码、验证码失效提示、首次改密和全员账号回退体验收口。 +- 移动端或企业微信 WebView 的视觉重构。 +- 新增营销式欢迎页、功能宣传、轮播、客户背书或无实际作用的装饰内容。 + +## Key Decision + +- 用户已确认：普通 PC 浏览器在桌面断点采用功能双栏，左侧突出企业微信扫码入口，右侧承载账号密码与邮箱验证码回退；窄屏和企业微信 WebView 不采用该双栏。 + +## Test Plan + +- Playwright 覆盖 1024px/1440px 双栏，375px/768px 单栏，扫码关闭单栏和企业微信 WebView 单栏，并断言实际布局边界与无横向滚动。 +- 回归企业微信扫码入口的 `entrySource`、`returnTo` 和设备指纹，密码/邮箱验证码切换、找回密码入口及 PWA 输入保持。 +- 生成桌面与移动代表性截图，人工复核信息层级、表单宽度、间距、对比度和焦点状态。 +- 执行 `cd client && npm run typecheck && npm run build`、聚焦 Playwright、Trellis task validate、流程/文档/治理检查及 `git diff --check`。 diff --git a/.trellis/tasks/07-30-pc-login-desktop-layout/task.json b/.trellis/tasks/07-30-pc-login-desktop-layout/task.json new file mode 100644 index 00000000..9a59e832 --- /dev/null +++ b/.trellis/tasks/07-30-pc-login-desktop-layout/task.json @@ -0,0 +1,33 @@ +{ + "id": "pc-login-desktop-layout", + "name": "pc-login-desktop-layout", + "title": "PC 登录页桌面布局优化", + "description": "优化普通 PC 浏览器登录页的桌面布局，保持既有认证与回调链路不变。", + "status": "in_progress", + "dev_type": null, + "scope": "client 登录页桌面响应式布局、共享认证布局的页面级 variant、聚焦前端回归测试", + "package": null, + "priority": "P2", + "creator": "shunli", + "assignee": "shunli", + "createdAt": "2026-07-30", + "completedAt": null, + "branch": null, + "base_branch": "main", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [ + "client/src/layouts/AuthLayout.tsx", + "client/src/router/index.tsx", + "client/src/pages/LoginPage.tsx", + "client/src/index.css", + "client/tests/e2e/wecom-entry.spec.ts", + "client/tests/e2e/login-portal-ux.spec.ts" + ], + "notes": "本地实现与验证完成：PC 登录页桌面双栏、窄屏/企微单栏、扫码关闭回退均通过；未部署，尚未线上可测。", + "meta": {} +} diff --git a/client/src/layouts/AuthLayout.tsx b/client/src/layouts/AuthLayout.tsx index 2b63068c..3f3e0ef5 100644 --- a/client/src/layouts/AuthLayout.tsx +++ b/client/src/layouts/AuthLayout.tsx @@ -1,9 +1,15 @@ import { Outlet } from "react-router-dom"; import { Button } from "../components/ui/button"; import { usePwaUpdatePrompt } from "../hooks/usePwaUpdatePrompt"; +import { cn } from "../lib/utils"; -export function AuthLayout() { +type AuthLayoutProps = { + variant?: "default" | "login"; +}; + +export function AuthLayout({ variant = "default" }: AuthLayoutProps) { const { updateReady, applyUpdate, dismissUpdate } = usePwaUpdatePrompt(); + const isLoginLayout = variant === "login"; return (
@@ -11,8 +17,23 @@ export function AuthLayout() { aria-hidden="true" className="auth-shell__grid pointer-events-none absolute inset-0" /> -