hyb-oa/.trellis/tasks/archive/2026-05/05-29-portal-task-first-redesign/prd.md

工作台任务优先重构

Goal

把 PC 工作台从“欢迎语 + 功能入口 + 折叠模块”改成“小团队今天要处理什么”的任务优先页面。首屏只回答：我今天要处理什么、我发起的事是否有状态变化、团队哪里卡住了；低频管理、普通通知、空壳统计和纯入口后置或不显示。

What I Already Know

• 目标用户是国内、小于 10 人的科技初创公司，使用者通常一人多岗，不是专职 OA 操作员。
• 工作台定位已确认：今天要我处理的事 优先，不是功能入口页。
• 当前页面截图显示：大欢迎卡片占用首屏、今日任务 中只有一个焦点事项、右侧按钮重复导航、下方 团队与通知 / 角色重点 / 试点观测摘要 是折叠空壳。
• 当前实现入口主要在 client/src/pages/PortalHomePage.tsx。
• 当前工作台数据接口是 client/src/api/portal.ts 的 fetchPortalHome()，后端路由为 server/src/routes/portal.js 的 /api/portal/home。
• 当前测试里大量断言旧文案：当前焦点、下一步、团队与通知、角色重点、试点观测摘要。
• 前端设计裁决以 frontend-design skill 为准；产品事实源要求首页只做工作台摘要，不重复完整待办列表、通知列表和进度列表。

Confirmed Decisions

• 待处理 = 所有需要当前用户行动的事项，不限审批。
• 待处理 包括待审批、待补材料、待付款 / 待复核、票据异常、管理员配置缺口、明确分配给我的团队动作。
• 待处理 不包括普通通知、已完成进度、只读动态、低频管理入口。
• 移除首屏欢迎大卡片，改成紧凑状态摘要。
• 报销进度 只在有进行中、待补材料、被驳回、待付款等状态时出现；不做固定按钮。
• 取消 团队与通知 折叠区，改成有真实阻塞才显示的 团队卡点。
• 取消 角色重点 折叠区，角色只影响事项来源和优先级，不单独占一个区域。
• 试点观测摘要 改成仅异常时出现的 管理提醒。
• 空状态只显示一句话和最多两个高频动作，不显示空壳模块。
• 本轮优先前端展示重构，尽量复用现有接口；不新增后端表，不重做审批、报销、通知接口。

Requirements

• R1: 工作台首屏必须从“欢迎入口页”改成“任务优先页”，默认不展示大欢迎卡片。
• R2: 顶部展示一行紧凑状态摘要，例如 今天有 1 件待处理，2 个进度更新。
• R3: 主区命名为 今日待处理，聚合所有需要当前用户行动的事项。
• R4: 每条待处理事项必须说明 什么事、为什么找我、状态/期限、下一步动作。
• R5: 不再固定展示 报销进度 按钮；只有存在可靠进度状态时才展示到 我的进度。
• R6: 没有状态级数据时，不用申请数量伪装成进度更新。
• R7: 普通通知不进入工作台主区，只保留顶部铃铛和通知中心职责。
• R8: 团队卡点 只在有真实阻塞时显示，最多展示 3 条，更多进入对应页面。
• R9: 管理提醒 只在管理员/负责人存在真实异常时显示，正常时不显示。
• R10: 删除 团队与通知、角色重点、试点观测摘要 这类折叠空壳区域。
• R11: 角色差异通过事项来源和优先级体现：审批人看到待审批，财务看到待付款/待核票，管理员看到配置/试运行异常，负责人看到团队阻塞。
• R12: 空状态只显示 今天没有需要你处理的事项。，最多提供 发起报销、查看我的进度，管理员可有轻量 管理设置 入口。
• R13: 页面文案使用自然中文业务动作，避免 当前焦点、角色重点、入口、管理员按需查看 等内部系统味文案。
• R14: 前端实现优先复用现有接口和权限能力；缺真实数据的区域直接不显示，不新增假数据。

Scope

• In scope:
  • client/src/pages/PortalHomePage.tsx 的结构、文案、事项聚合和空状态。
  • 现有 portal payload 的前端聚合逻辑。
  • 与工作台旧文案绑定的 E2E/视觉测试。
  • 必要时更新产品体验事实源或前端 Trellis spec，沉淀“工作台任务优先”规则。
• Out of scope:
  • 新增后端表或新建工作台聚合模型。
  • 重做审批、报销、通知、财务接口。
  • 重构移动工作台。
  • 重构侧边栏、顶部栏、个人设置页。
  • 公网部署和真实数据写入，除非后续单独批准。

Out Of Scope

• 新增后端表或新建工作台聚合模型。
• 重做审批、报销、通知、财务接口。
• 重构移动工作台主路径；本轮只同步待处理页移动列表的按钮层级和文案一致性。
• 重构侧边栏、顶部栏、个人设置页。
• 公网部署、生产配置、真实数据写入、企业微信写入或真实付款。

Proposed Implementation Plan

1. 重新定义工作台前端事项模型

   • 从 pendingTasks、todoSummary、warning/high cards、financeSummary、weeklySummary、teamPresence、adoptionSummary.hints 中生成待处理、团队卡点、管理提醒。
   • 只使用有真实数量或真实异常的来源。

2. 重构首屏结构

   • 移除 WorkbenchHero 大欢迎卡片或改为极简状态条。
   • 用 今日待处理 作为主区。
   • 主动作跟随最高优先级事项，不再另放重复按钮清单。

3. 删除折叠空壳

   • 移除 团队与通知、角色重点、固定 试点观测摘要。
   • 用条件渲染的 团队卡点、管理提醒、我的进度 替代。

4. 调整空状态

   • 无待处理、无进度、无卡点时只展示一句空状态和少量高频动作。

5. 更新测试

   • 修改 visual-portal.spec.ts、login-portal-ux.spec.ts、visual-shell.spec.ts 等旧断言。
   • 覆盖普通员工、审批人/负责人、财务/管理员视图。

Acceptance Criteria

• 工作台首屏不再出现大欢迎卡片。
• 工作台首屏不再出现 当前焦点、下一步、团队与通知、角色重点、试点观测摘要 旧文案。
• 有待处理事项时，今日待处理 直接展示可行动事项和明确下一步。
• 没有待处理事项时，页面显示极简空状态，不出现空壳模块。
• 报销进度 不作为固定按钮出现；只有可靠状态数据时才进入进度区域。
• 普通通知不在工作台主区重复展示。
• 团队卡点和管理提醒仅在真实异常/阻塞存在时出现。
• 普通员工、审批人/负责人、财务/管理员视图均符合任务优先规则。
• cd client && npm run typecheck 通过。
• cd client && npm run build 通过。
• 聚焦 Playwright/截图验证通过，并保存重构后截图证据。

Technical Notes

• client/src/pages/PortalHomePage.tsx 当前包含：
  • WorkbenchHero
  • TodayTaskPanel
  • SecondaryWorkspacePanel
  • AdoptionSummaryPanel
  • 多个 SummaryPanel / QuickActionsPanel / SecondaryCardsPanel
• 当前工作台 payload 已包含足够的基础字段，但“我的进度”缺少明确状态级数据时应谨慎显示。
• buildAdoptionHints() 当前会在无异常时返回正向提示；前端管理提醒应过滤这类“正常提示”，只显示异常提示。
• 旧视觉测试需要同步改为新产品语义，不能继续用旧折叠区作为健康判断。

Test Plan

• cd client && npm run typecheck
• cd client && npm run build
• 聚焦 E2E：
  • cd client && npx playwright test tests/e2e/visual-portal.spec.ts --workers=1 --reporter=list
  • cd client && npx playwright test tests/e2e/login-portal-ux.spec.ts --workers=1 --reporter=list
  • 必要时补跑 visual-shell.spec.ts
• 视觉证据：
  • 普通员工 PC 工作台
  • 审批人/负责人 PC 工作台
  • 财务/管理员 PC 工作台

Verification Record

2026-05-29 已完成本轮前端验证：

• cd client && npm run typecheck：通过。
• cd client && npm run build：通过。
• cd client && npx playwright test tests/e2e/visual-portal.spec.ts --workers=1 --reporter=list：3 passed。
• cd client && npx playwright test tests/e2e/visual-shell.spec.ts --workers=1 --reporter=list：5 passed。
• cd client && npx playwright test tests/e2e/login-portal-ux.spec.ts --workers=1 --reporter=list：12 passed。
• python3 ./.trellis/scripts/task.py validate 05-29-portal-task-first-redesign：通过。
• git diff --check：通过。
• 截图证据已保存到 output/playwright/portal-task-first-redesign/portal-employee.png、portal-admin.png、portal-finance.png；员工截图已复核并清除了欢迎弹窗遮罩污染。

2026-05-29 企微主办边界复核后完成补充验证：

• cd client && npm run typecheck：通过。
• cd client && npm run build：通过。
• cd client && npx playwright test tests/e2e/workflow-action-confirm-ui.spec.ts tests/e2e/workflow-quick-approve.spec.ts --workers=1 --reporter=list：3 passed。
• cd client && npx playwright test tests/e2e/login-portal-ux.spec.ts tests/e2e/visual-portal.spec.ts tests/e2e/visual-shell.spec.ts tests/e2e/r102-reimbursement-main-flow.spec.ts --workers=1 --reporter=list：23 passed。
• cd client && npx playwright test tests/e2e/pc-core-workflow-visual-wave2.spec.ts --workers=1 --reporter=list：1 passed。
• 补充自审后重跑 cd client && npx playwright test tests/e2e/login-portal-ux.spec.ts tests/e2e/visual-portal.spec.ts --workers=1 --reporter=list：15 passed。
• python3 ./.trellis/scripts/task.py validate 05-29-portal-task-first-redesign：通过。
• node scripts/qa/check-trellis-governance.mjs：通过。
• git diff --check：通过。

Approved Addendum: 待处理页面任务优先整改

2026-05-29 用户确认对 /workflow/tasks 做小范围页面整改，目标是让审批人逐单看详情后谨慎处理。后续业务边界复核确认：请假、补卡、外出、加班和打卡属于企业微信主办，OA 不提供列表页快捷审批。

• 默认目标：逐单看详情后处理；列表页默认不提供 通过 快捷动作。
• 按钮层级：查看处理 为主按钮；审批动作进入详情页后执行。
• 企微主办边界：请假、补卡、外出、加班、打卡相关事项只做镜像、历史、审计、异常或应急接管展示，正常审批不在 OA 列表页处理。
• 未来若恢复列表快捷通过，必须由后端显式提供 eligibility 字段和审计语义，不能由前端按实体类型、天数或行文案自行判断。
• 主体形态：保留 PC 表格密度，但改为任务列表式表格，第一列集中展示什么事、为什么找我、等待多久和编号。
• 历史入口：高级 / 历史 改为 已处理记录；点击后默认进入 已处理，历史筛选不混入 待处理。
• 时间表达：首屏优先显示 已等待多久，绝对接收时间作为次级信息；不再把任务创建时间叫 更新时间。
• 本轮不改后端接口、不改审批详情页、不做部署或真实数据写入。

Approved Addendum: PC 报销列表任务优先整改

2026-05-29 用户确认对 PC /reimbursements 列表页做小范围页面整改，目标是让 我的报销 默认服务普通员工/发起人，多角色用户仍先看自己的报销，审批、财务和台账能力按角色/权限降噪。

• 默认对象：普通员工/发起人优先；审批和财务能力作为二级入口，不抢默认视角。
• 首屏结构：新增 被驳回待补正、草稿待完善、审批中进度 三张任务卡，显示数量，点击只切换当前页状态筛选。
• 默认范围：多角色用户进入 我的报销 仍默认看自己的报销，不自动进入全范围台账。
• 记录筛选：状态 tabs 保留，但作为 报销记录 筛选放在任务面板下方。
• 空状态：按当前状态分别写清楚；草稿空态提供 新建报销 情境动作。
• 主按钮：顶部 新建报销 继续作为唯一主按钮，任务面板不放同权重 CTA。
• 台账工具：高级 / 台账 改为 台账工具，仅在至少有一个真实可用二级能力时显示；普通员工仅有 expense.create 不显示。
• 更多创建方式：按真实可用内容显隐；普通员工不因模板、差旅关联等低频能力看到噪音入口，相关加载/失败不默认暴露到页面顶部。
• 列表节点文案：按视角显示 待你处理 或 当前节点，不再对发起人统一叫 待办。
• 批量结果：默认隐藏 taskId 等内部排障字段。
• 本轮范围：只覆盖 PC ReimbursementsPage，不扩展到移动报销页或报销详情页，不改后端接口，不部署或写真实数据。

Definition Of Done

• PRD、实现、验证和截图证据在本 Trellis task 中可追溯。
• 没有新增假数据、无意义入口或折叠空壳。
• 代码提交使用中文 commit message，并引用 portal-task-first-redesign。
• 如后续要求公网可测，必须先部署并完成公网检查后再告知用户可以测试。