chore(task): 归档 pc-detail-responsive-approval-polish

2026-08-03 22:00:48 +08:00
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. 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."}
@@ -0,0 +1,94 @@
+# PC 详情响应式断点与审批展示回归设计
+
+## 1. 设计边界
+
+本任务只协调现有 PC 壳层与详情工作区的断点，并修复审批详情已经暴露的只读展示问题。不改变导航条目、权限、移动路由、审批状态机、动作 API、服务端 DTO 或数据库。
+
+视觉与交互继续使用仓库现有企业详情页模式。当前项目声明的 `frontend-design` skill 不可用；规划阶段使用可用的 `ui-ux-pro-max` 核对了响应式无横向滚动、真实长度 fixture 和长内容适配原则，最终以生产实图、现有共享组件和项目规约为依据。
+
+## 2. 响应式断点合同
+
+### 2.1 壳层三处同源切换
+
+固定侧栏、主内容左边距和顶部抽屉入口必须在同一个 `xl=1280px` 断点切换：
+
+- `Sidebar`：`hidden xl:flex xl:flex-col`；
+- `AppShellLayout` 主区：`xl:ml-72`；
+- `Topbar` 菜单按钮：`xl:hidden`。
+
+三者仍分属各自组件，无法通过运行时常量安全生成 Tailwind class；用结构测试锁定它们统一为 `xl`，并断言不再残留对应的 `lg` class。这样避免只改左边距而留下固定侧栏或菜单重复。
+
+详情工作区与动作面板继续在 `lg=1024px` 进入双栏和 sticky：
+
+- 小于 1024：单栏详情，现有移动/窄屏表达不变；
+- 1024–1279：全局侧栏收起，顶部菜单可用，详情双栏和 sticky 生效；
+- 1280 及以上：固定侧栏展开，详情双栏和 sticky 生效。
+
+### 2.2 1280px 最坏内容预算
+
+1280px 是固定侧栏首次出现后的最窄点。按当前结构估算：
+
+```text
+1280 视口
+- 288 固定侧栏
+- 约 64 页面左右 padding
+- 约 16 layout-container padding
+- 20 详情列 gap
+= 约 892px 可分配给两列
+```
+
+现有 `1.45fr : 0.72fr` 在该宽度下约得到 596px 主栏和 296px 右栏，满足本任务阈值：
+
+- 主栏计算宽度不少于 560px；
+- 右栏计算宽度不少于 280px；
+- 页面文档宽度不超过视口 2px；
+- 常规业务编号和公司时区日期时间保持单行。
+
+因此首选保留现有列比例，只修复壳层断点冲突。若浏览器实测未达到阈值，再在同一共享 `.detail-workspace-grid` 中调整比例；不得用页面私有列宽覆盖制造第二事实源。
+
+## 3. 可测量布局回归
+
+1280px 的审批详情和资产详情使用真实长度 fixture。测试读取 DOM 几何而不是只看截图：
+
+- `BusinessDetailMain` 与 `BusinessDetailAside` 的 `getBoundingClientRect().width`；
+- `.detail-workspace-grid` 的实际列数；
+- `.detail-action-panel` 的 `position`、`top` 和宽度；
+- `documentElement.scrollWidth <= window.innerWidth + 2`；
+- 对报销编号、日期时间和代表性资产字段创建 `Range`，断言 `getClientRects()` 只有一行，避免 `break-words` 让普通 `scrollWidth` 断言产生假阴性。
+
+截图只保留为人工辅助证据。结构测试单独锁定三处壳层 class，移动端使用已有回归，不新增五档视口矩阵。
+
+## 4. 共享操作面板与审批动作
+
+### 4.1 共享空面板
+
+`BusinessDetailActionPanel` 先归一化 children，再判断 `status / primaryAction / secondaryActions / moreActions / summary / children` 是否存在。全部为空时直接返回 `null`；只含 summary 或 status 时仍正常渲染只读面板。
+
+调用方传入的空 Fragment 在 React 层仍可能是真值，因此 Workflow 页面必须先派生动作布尔值，只在至少一个动作允许时构造对应 slot。
+
+### 4.2 Workflow 动作模型
+
+从 `allowedActions` 派生：
+
+- `canApprove`：决定 `primaryAction` 是否渲染“通过”；
+- `canReturn / canReject`：决定次动作是否渲染；
+- `canTransfer`：决定“更多 → 转审”是否渲染；
+- mutation 期间只禁用已经可见的动作，不用禁用按钮表示“没有权限/任务已完成”。
+
+已完成任务不生成任何动作 slot，但保留处理 summary，右栏成为只读状态面板。待处理任务继续保持现有确认、理由、mutation 和刷新合同。
+
+审批概况中的“可执行动作” `MetricCard` 仅在动作集合非空时渲染；无动作时不显示 `-` 空卡片。
+
+## 5. 审批显示收敛
+
+- 在现有 `client/src/lib/approvalDisplay.ts` 增加审批语境的 `approvalRoleLabel`，至少覆盖 `manager / ceo / finance / finance_mgr / hr`，未知值回退为“审批人”而不是回显技术码。
+- Workflow 处理摘要使用该 helper，不新增页面内角色映射。
+- 处理历史时间改用现有 `formatDisplayDateTime`，保持 `Asia/Shanghai` 合同；不修改 API ISO 值。
+- 返回按钮统一为“返回审批列表”，继续回到现有 `/workflow/tasks`，不新增 tab 状态持久化。
+
+## 6. 兼容、发布与回滚
+
+- 这是纯前端变化，无迁移、服务端 DTO 或权限变化。
+- 壳层断点影响所有 PC 路由，必须回归普通列表、管理页和核心详情；1024–1279px 导航从固定侧栏变为顶部菜单属于有意行为。
+- 回滚可恢复三处 `lg` class 和 Workflow 展示改动；不涉及数据回滚。
+- 自动化、本地构建、标准部署、公网 `/ready` 和发布后体检全部通过后，才可通知用户线上复核。
@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. 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."}
@@ -0,0 +1,52 @@
+# PC 详情响应式断点与审批展示回归实施计划
+
+## 1. 开发前
+
+- [x] 用户审查并明确批准最新 PRD、设计和实施清单后，运行 `task.py start`；本轮规划批准不等于实施批准。
+- [x] 使用 `trellis-before-dev` 重新读取 frontend、hyb-oa、审批与部署相关规约。
+- [x] 记录 1280px 基线几何：固定侧栏、详情主/侧栏宽度、编号/时间行数和页面横向溢出。
+
+## 2. 壳层与详情断点
+
+- [x] 将 `Sidebar` 固定侧栏、`AppShellLayout` 主区左边距和 `Topbar` 菜单入口同步从 `lg` 调整为 `xl`，不改变移动路由。
+- [x] 保持详情工作区和动作面板 `lg` 双栏/sticky；在 1280px 实测主栏 ≥560px、右栏 ≥280px。只有未达阈值时才调整共享列比例，不添加页面私有覆盖。
+- [x] 补结构测试，断言三处壳层使用同一个 `xl` 断点且无对应 `lg` 残留。
+
+## 3. 共享操作面板与审批只读态
+
+- [x] `BusinessDetailActionPanel` 无 status/action/summary/children 时返回 null，有只读 summary 时继续渲染。
+- [x] Workflow 按 `allowedActions` 派生 primary/secondary/more slots：已完成任务不渲染动作条，待处理任务保持通过、退回、驳回、转审及 loading/确认合同。
+- [x] 无允许动作时移除审批概况中的“可执行动作”空事实卡。
+
+## 4. 审批展示
+
+- [x] 在共享 `approvalDisplay` 增加审批角色中文 helper，Workflow 摘要不再回显 `finance` 等技术码。
+- [x] 处理历史时间使用 `formatDisplayDateTime`；返回入口改为“返回审批列表”。
+- [x] 使用合成 completed 与 pending 任务分别回归只读态和动作态。
+
+## 5. 自动化验证
+
+- [x] 1280×代表高度的审批详情 fixture 使用真实长度编号、日期时间、动作和转审候选；断言主/侧栏宽度、两列、sticky、无横向溢出及关键文本单行。
+- [x] 1280px 资产详情使用真实长度字段并执行同样几何断言，打开长选项/操作区确认 z-index 和内容不被正文覆盖。
+- [x] 用结构合同证明 1024–1279px 顶部菜单可用、固定侧栏不出现；浏览器布局硬门禁只测 1280px，并复用现有移动回归证明移动端不变。
+- [x] 审批 pending 动作分别覆盖通过、退回、驳回、转审可见性和既有确认；completed 断言动作按钮为 0、summary 存在、空动作事实卡为 0。
+- [x] 角色显示中文、历史时间为上海时区格式、返回文案正确；共享空面板 guard 有结构或可观察消费者回归。
+
+## 6. 质量门禁与发布
+
+- [x] `cd client && npm run typecheck && npm run build`
+- [x] 运行聚焦 Playwright：审批详情、资产详情、壳层导航、普通列表/管理页与移动基础回归。
+- [x] `bash scripts/check-minimal.sh`
+- [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] `node scripts/qa/check-sensitive-content.mjs`
+- [x] `git diff --check`
+- [x] 按 `trellis-check` 复核范围、共享断点、动作权限与测试强度；本任务不改变审批状态机，因此无需服务端状态机 reviewer。
+- [ ] 使用中文 commit message 并引用 `pc-detail-responsive-approval-polish`，完成后按 Trellis 流程归档。
+- [ ] 用户已批准实施后，代码验证完成仍需单独确认部署权限；部署通过标准 13 项体检、自动合同刷新、公网 `/ready` 与发布后体检后再通知。
+
+## 回滚点
+
+- 壳层三处断点必须同批回滚，禁止只恢复其中一处。
+- Workflow 动作呈现和共享面板 guard 可与壳层同提交回滚；无数据或服务端回滚步骤。
@@ -0,0 +1,84 @@
+# PC 详情响应式断点与审批展示回归
+
+## Goal
+
+修复 PC 详情页在窄笔记本宽度下因全局侧栏与详情双栏同时展开而导致的正文挤压，并把真实内容宽度、空操作区和已完成审批展示纳入可测量的自动化合同，避免再次以 `sticky` 存在代替视觉可用性验收。
+
+## Background
+
+- 已归档任务 `detail-page-structure-progress-actions` 将 `.detail-workspace-grid` 和 `BusinessDetailActionPanel` 从 `xl` 前移到 `lg`，目标是在笔记本宽度保持右侧操作持续可见。
+- `client/src/layouts/AppShellLayout.tsx:69`、`client/src/components/navigation/Sidebar.tsx:6` 与 `client/src/components/navigation/Topbar.tsx:146` 也在 `lg=1024px` 同时展开 288px 全局侧栏、增加主区左边距并隐藏抽屉菜单。
+- 生产 1024px 实图证明两个断点叠加后，审批详情正文被压窄，报销单号拆成多行、时间强制换行。右栏 `position: sticky`、`top` 和 `z-index` 虽然符合现有测试，但整体布局不可接受，说明原验收是假阳性。
+- 若全局侧栏改为 `xl=1280px` 展开，新的最坏点是 1280px：视口扣除 288px 侧栏后再分配详情主/侧栏。验收必须覆盖断点前后和实际最窄内容区，而不是只测 1024px。
+- `BusinessDetailActionPanel` 已计算 `hasActionContent`，但当前只用于分隔线；没有任何 action、summary 或 children 时仍渲染空面板。
+- 已完成审批仍渲染蓝色主按钮外观的禁用“通过”以及禁用“退回/驳回”，同时摘要显示原始角色码 `finance`，处理历史显示原始 ISO 时间。
+
+## Scope
+
+- 协调现有 PC 全局侧栏、主内容左边距、顶部菜单与详情双栏的响应式断点。
+- 补强共享详情操作面板的空内容行为，以及 Workflow 审批详情的已完成只读态、角色、时间和返回文案。
+- 用 1280px 常规 PC 最坏点建立数值布局回归，复用现有移动回归确认移动端不变。
+- 不修改服务端、数据库、权限、审批动作合同或生产业务数据。
+
+## Requirements
+
+### R1 常规移动与 PC 的断点协调
+
+- 全局固定侧栏、主内容左边距和顶部抽屉入口必须由同一个响应式断点控制，不能在同一视口出现固定侧栏与抽屉入口重复或主内容偏移漂移。
+- 常规移动端继续使用现有移动路由、移动壳层和固定底部动作合同；本任务不新增设备分类或逐设备支持声明。
+- 1024–1279px 作为 PC 窄窗口自然兼容区间：固定侧栏收起、顶部菜单可用、详情双栏保持足够正文空间；不为该区间建立独立视觉承诺或完整视口矩阵。
+- 不得通过隐藏操作、恢复页面底部孤立操作卡或制造第二套动作区解决正文宽度问题。
+- 1280px 及以上展开固定侧栏后，详情工作区列宽比例必须按扣除侧栏后的内容区重新评估；主栏不得因右栏最小宽度而出现业务编号、常规日期时间的非必要破碎换行。
+- 修改全局壳层断点时，必须回归普通列表、管理页、审批详情、报销详情、付款详情和资产详情，确保导航、抽屉、内容偏移与横向滚动无回退。
+
+### R2 可测量的响应式验收
+
+- 自动化以 1280px 作为常规 PC 最窄硬门禁，验证固定侧栏、详情双栏、sticky、计算列宽和内容适配；现有移动回归继续证明常规移动端不受影响。
+- 通过结构断言锁定固定侧栏、主内容左边距和顶部抽屉入口使用同一个 `xl` 断点，防止其中一处以后单独漂移；不为 1024–1279px 增加重复的全页面视觉矩阵。
+- 使用真实长度的中文动作、业务编号、日期时间和下拉选项，不以短合成文案代替生产内容。
+- 断言必须包含计算宽度或溢出指标，例如主栏/右栏最小宽度、关键业务编号 `scrollWidth <= clientWidth`、页面无横向滚动；截图仅作辅助证据，不作为唯一门禁。
+- 审批详情与资产详情必须分别覆盖最坏内容宽度；已有只检查 `position/top/z-index` 的断言应补强，不能继续单独作为布局通过证据。
+
+### R3 空操作面板与已完成审批
+
+- `BusinessDetailActionPanel` 在 action、summary、children 和 status 均无可见内容时不渲染整个面板；调用方不需要各自重复空值判断。
+- 审批概况中的“可执行动作”事实卡在没有任何允许动作时不渲染，不再显示一个值为 `-` 的空卡片。
+- 已完成或无可执行动作的审批详情不渲染看似可点击的“通过/退回/驳回/更多”动作条；保留必要的只读处理摘要，并明确当前任务已完成或仅供查看。
+- 待处理审批继续保留一个主动作“通过”、次动作“退回/驳回”和“更多 → 转审”，权限、确认、原因与 mutation 合同不改变。
+
+### R4 审批展示缺陷
+
+- 审批详情不得显示 `finance`、`manager` 等原始角色码；使用审批语境下的自然中文标签，并从共享审批显示 helper 取得，避免页面内新增第二份映射。
+- 处理历史时间复用 `formatDisplayDateTime`，按 `Asia/Shanghai` 展示；API 与数据库 ISO 时间保持不变。
+- 返回入口统一使用中性“返回审批列表”，不为区分待处理/已处理新增 tab 状态持久化。
+
+## Acceptance Criteria
+
+- [x] 1024–1279px 不展开 288px 固定侧栏，顶部菜单仍可打开导航，详情操作持续可达且无横向滚动。
+- [x] 1280px 最坏点下主栏和右栏均达到设计阈值，常规报销编号、日期时间不发生截图中所示的破碎换行。
+- [x] 结构测试锁定侧栏、主区左边距与抽屉入口统一使用 `xl`；1280px 浏览器回归锁定详情列数、sticky、计算宽度和无横向溢出。
+- [x] 审批详情和资产详情均使用真实长度 fixture 在 1280px 通过数值断言；截图不再是唯一视觉证据。
+- [x] 完全无内容的共享操作面板不渲染；有 summary 但无 action 的面板仍保留只读摘要。
+- [x] 已完成审批不显示蓝色“通过”或其他禁用动作条，待处理审批动作和确认行为不回退。
+- [x] 审批角色显示自然中文，处理历史时间显示公司时区格式，不再出现技术码或原始 ISO；返回入口显示“返回审批列表”。
+- [x] 前端 typecheck/build、相关 Playwright、流程/Trellis/敏感内容和 `git diff --check` 门禁通过。
+- [x] 部署与公网检查完成后才能通知用户线上复核；生产真实审批详情确认报销单号与创建时间保持单行，主侧栏布局无塌陷。
+
+## Out of Scope
+
+- 重做全局导航信息架构、改变导航条目或权限。
+- 重设计全部详情页视觉体系、移动端详情或业务状态机。
+- 修改审批权限、动作 API、确认规则、工作流历史数据或服务端时间格式。
+- 为视觉验证制造生产审批、资产或付款数据。
+
+## Test Plan
+
+- 结构测试锁定 Sidebar、AppShell 主区与 Topbar 菜单统一使用 `xl` 断点，详情双栏/sticky 继续使用 `lg`。
+- 1280px Playwright 使用真实长度合成数据覆盖审批详情和资产详情，断言主栏 ≥560px、右栏 ≥280px、两列、sticky、关键文本单行且页面无横向滚动。
+- 审批 completed fixture 断言无动作按钮、无“可执行动作”空事实卡、中文角色、上海时间和中性返回文案；pending fixture 回归通过、退回、驳回、转审及确认行为。
+- 运行现有移动基础回归、前端 typecheck/build、全量最小门禁、Trellis/流程/敏感内容与 `git diff --check`。
+
+## Notes
+
+- 生产部署已完成，部署前聚合体检 13/13、运行时与公网构建检查通过。
+- 生产真实审批详情已在常规 PC 宽度完成只读复核：报销单号与创建时间均保持单行，右侧处理栏未下沉或塌陷。
@@ -0,0 +1,26 @@
+{
+  "id": "pc-detail-responsive-approval-polish",
+  "name": "pc-detail-responsive-approval-polish",
+  "title": "PC详情响应式断点与审批展示回归",
+  "description": "协调 PC 壳层与详情双栏断点，并补强审批只读态和可测量的 1280px 布局回归。",
+  "status": "completed",
+  "dev_type": null,
+  "scope": "client",
+  "package": null,
+  "priority": "P2",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-08-03",
+  "completedAt": "2026-08-03",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "实现、提交与生产部署完成：壳层三处断点统一为 xl，详情双栏与 sticky 保持 lg；审批只读态、中文角色、公司时区和 1280px 数值回归通过；部署前聚合体检 13/13 与公网检查通过；生产真实审批详情确认报销单号和创建时间保持单行，右栏无塌陷。",
+  "meta": {}
+}
				`@@ -0,0 +1 @@`
				{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. 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."}