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

## 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

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

## Test Plan

```bash
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 集合。
- 本任务仅完成本地前端验收并归档；未部署、未公网复检，不能据此宣称线上可测。