hyb-oa/.trellis/tasks/archive/2026-07/05-31-unified-page-header-actions/prd.md

统一页面右上角操作区规划

Goal

统一 PC 页面标题右上角按钮规划，解决当前业务页右上角按钮数量、优先级和位置不一致的问题。页面应采用成熟企业后台/Ant Design Pro 常见模式：页面标题区只承载页面级主操作，列表筛选、导出、刷新、测试数据、分类管理等低频或列表级工具进入列表工具栏、筛选区或 更多。

Scope

• 前端 PC 页面标题右侧操作区、业务列表工具栏和相关 E2E/视觉断言。
• 首轮覆盖报销、采购、合同、项目、资产、付款、应付账款和票据等业务页。
• 只调整操作入口位置、按钮优先级、列表工具收纳和设计规范，不改变业务权限、接口、状态机或数据结构。

What I Already Know

• 用户反馈：现在页面右上角按钮规划不统一。
• 产品背景：面向国内小于 10 人科技初创公司，系统应低认知负担、成熟常规、不创新。
• 既有规范要求：页面标题默认为 route 名称；Header primary action 只保留真实页面级主操作；低频工具不要堆在右上角。
• 当前代码审计发现：
  • 报销：标题右侧主要是 新建报销，列表工具在下方，相对接近目标。
  • 采购：标题右侧同时放 新建采购 和 筛选，筛选应进入列表工具区。
  • 合同：标题右侧同时放 新增合同、到期列表、导出、筛选，过载最明显。
  • 项目：标题右侧放 合同、显示测试数据、新建项目，页面级动作与排障开关混用。
  • 资产：标题右侧放 新增资产、移动扫码查找、资产分类，管理工具和主操作混用。
  • 付款：标题右侧放 刷新、新建批次，刷新不应占据标题主操作区。
  • 应付账款：标题右侧放 刷新、导出，只读列表页不应强制占用标题主按钮区。
  • 票据：标题右侧放 上传票据、绑定、导出，主操作与后续处理工具混用。

Requirements

• 标题右上角只允许：
  • 一个页面级主操作按钮，例如 新建报销、新建采购、新增合同、新建项目、新增资产、新建批次、上传票据。
  • 最多一个 更多，用于页面级低频操作；当低频操作只有列表级含义时，放到列表工具栏，不放标题区。
  • 详情/编辑模式可用一个 返回列表，但不与创建按钮并列。
• 筛选 不放标题右上角；统一放在列表工具栏/筛选区右侧。
• 导出 不作为标题区常驻按钮；统一进入列表工具栏右侧或 更多。
• 刷新 不作为标题区常驻按钮；需要保留时进入列表工具栏，或作为低频工具。
• 显示测试数据 属于排障/试运行开关，不放标题右上角，进入筛选/更多/排障区。
• 分类管理、扫码查找、到期列表、绑定 等非创建动作，不与主创建按钮并列；按场景进入 更多、筛选区、管理入口或下方操作面板。
• 尽量通过共享组件或模板约束新页面，避免继续逐页漂移。

Additional Consistency Rules To Review

• 页面标题：菜单名、页面主标题和浏览路径用词要一致；例如菜单 合同，页面标题也用 合同，不要在不同位置混用 合同台账、合同管理、合同列表。
• 说明文案：默认页面不展示解释性副标题；只在空状态、错误、权限、企业微信边界、不可逆操作和试运行边界中解释。
• 筛选布局：业务列表统一为“状态/范围 tabs 或 chips + 一行高频筛选 + 高级筛选入口”；不允许有的页面两行筛选、有的页面无筛选、有的页面把筛选放标题右上角。
• 列表列结构：业务列表统一按“对象身份、相对方/人员、金额/日期、状态、操作”组织；右侧固定操作列默认 查看详情 / 处理 / 继续编辑。
• 空状态：统一使用短标题 + 一句当前筛选结果 + 一个真实下一步；不要写流程说明。
• 更多菜单：所有 更多 都右对齐、浮层不被遮挡、只放低频动作；危险动作必须二次确认。
• 详情页：PC 统一为“顶部摘要 + 主事实/证据 + 右侧状态/操作区 + 历史”；列表页不默认在下方展开详情。
• 编辑页/面板：创建和编辑统一使用同一编辑模板；主按钮固定为 保存 / 提交，取消/返回在左或次级位置。
• 权限显隐：无权限动作直接隐藏；不要显示不可用按钮再解释一堆原因，除非是权限申请或配置缺失边界。
• 移动端对应：移动端不照搬 PC 右上角；统一为顶部标题 + 卡片列表/详情 + 底部主操作，次级动作进入 更多。

Proposed Page-Level Changes

页面	标题右上角目标	迁移动作
报销	新建报销	保持；检查导出/统计是否仍在列表工具栏。
采购	新建采购	筛选 移到列表工具栏。
合同	新增合同 + 更多（如需要）	筛选 移到筛选区；导出 移到列表工具栏/更多；到期列表 改为列表状态/筛选入口。
项目	新建项目	合同 移为列表/详情关联入口；显示测试数据 移到筛选/排障入口。
资产	新增资产 + 更多	移动扫码查找、资产分类 放入 更多 或管理面板，不与新增并列。
付款	新建批次	刷新 移到列表工具栏。
应付账款	无主按钮，必要时 更多	刷新、导出 移到列表工具栏/更多。
票据	上传票据 + 更多	绑定、导出 放入 更多 或列表工具栏。

Out of Scope

• 不改变业务权限、审批规则、数据结构或接口。
• 不新增真实业务写入。
• 不重新设计移动端底部主操作；本任务先收敛 PC 页面标题右上角。
• 不部署公网；实现完成后先本地验证，部署另行获得批准。

Acceptance Criteria

• 业务列表页标题右上角符合“一主操作 + 最多一个更多”的规则。
• 筛选、导出、刷新、显示测试数据 不再作为标题右上角常驻按钮。
• 采购、合同、项目、资产、付款、应付账款、票据至少完成首轮统一。
• 规则写入前端设计规范，后续页面可复用。
• 标题、筛选、列表列、空状态、详情/编辑操作区至少完成一致性审计，形成后续改造清单。
• 前端 typecheck/build 通过。
• 聚焦 Playwright/视觉复检覆盖主要业务页。

Test Plan

cd client && npm run typecheck
cd client && npm run build
E2E_BASE_URL=http://127.0.0.1:5173 npx playwright test tests/e2e/r103-cross-page-ui-consistency.spec.ts --workers=1 --reporter=list
git diff --check
python3 ./.trellis/scripts/task.py validate 05-31-unified-page-header-actions
node scripts/qa/check-trellis-governance.mjs

Technical Notes

• 设计裁决使用 frontend-design skill，并按成熟企业后台/Ant Design Pro 的页面区分：标题区负责页面级主操作，表格工具栏负责列表级工具。
• 相关规范：.trellis/spec/hyb-oa/frontend-react-vite-design.md
• 相关组件：client/src/components/patterns/ListWorkspace.tsx、client/src/components/common/PageHeader.tsx、client/src/components/patterns/BusinessListTemplate.tsx

Closeout Verification (2026-07-16)

• 实现提交 dcf34d7 后，七个页面、HeaderActionGroup 和相关聚焦测试没有发生实现漂移。
• cd client && npm run typecheck 通过；cd client && npm run build 通过，Vite 转换 2381 个模块，PWA 生成 102 个预缓存条目，仅有既有 Browserslist 数据陈旧提示。
• 在 Vite dev 模式下运行 r103-cross-page-ui-consistency.spec.ts 为 3 passed；production preview 首次运行的 1 个失败是 PWA Service Worker 绕过 page.route mock 并回到登录页的验证环境问题，未作为产品 finding。
• 当前标题动作迁移本身通过静态复核，但任务不能归档：聚焦视觉覆盖仍缺项目/资产列表，且一致性审计发现权限显隐和旧测试漂移。

Follow-up Findings

• PaymentBatchesPage 对只有复核权限、没有付款创建权限的用户仍显示 新建批次，点击后才出现无权限面板。
• ContractsRegistryPage 对只读合同用户仍显示新增、编辑、续约和归档入口，写接口最终会返回 403。
• InvoicePoolPage 已计算上传权限，但标题区 上传票据 没有按该权限隐藏。
• assets-flow.spec.ts 与 manual/asset1d-public-trial.spec.ts 仍把已迁入 更多 的 资产分类 当作直接按钮点击。
• HeaderActionGroup 目前只统一布局，不约束动作数量；缺少七页面统一标题动作合同测试，现有截图缺项目和资产列表。

上述 finding 需要独立修复 task；在修复并补齐视觉/回归覆盖前，本任务保持 in_progress，不得虚报完成或归档。

Final Closeout Verification (2026-07-18)

• 承接任务 07-18-small-team-internal-readiness 已闭合上述 follow-up：付款复核角色看不到新建批次，应付账款导出按权限隐藏，合同只读角色看不到新增/编辑/续约/归档，票据无上传权限时 fail-closed；对应合成 Playwright 5/5 纳入最终候选门禁。
• assets-flow.spec.ts 和历史 manual 资产用例已改为通过标题区 更多 -> 资产分类；资产流程 spec 可解析，当前菜单行为由实际浏览器回归覆盖。
• r103-cross-page-ui-consistency.spec.ts 扩展为 8 项：七个页面标题区严格执行“一主操作 + 最多一个更多”，并覆盖项目/资产代表视觉、资产“更多 -> 资产分类”及核心页面动作合同。
• 当前 checkout 的 bash scripts/qa/run-local-candidate.sh full 最终为 44/44 passed、0 skipped/failed/unexpected；项目、资产、合同、付款、报销双断点截图及权限显隐 spec 均包含在候选 acceptance 集合。
• 本任务仅完成本地前端验收并归档；未部署、未公网复检，不能据此宣称线上可测。