oa-frontend-pretrial-cleanup 建档PC前端清障方案

2026-05-26 16:13:36 +08:00
@@ -0,0 +1,5 @@
+{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "检查前端改动是否遵守共享组件、PC 高密度工作台和 typecheck/build 要求。"}
+{"file": ".trellis/spec/hyb-oa/security-privacy.md", "reason": "检查截图、报告和页面文案没有敏感信息、完整账号或内部 payload 泄露。"}
+{"file": ".trellis/spec/hyb-oa/docs-and-evidence.md", "reason": "检查视觉证据和报告引用是否脱敏、可追溯且不替代 docs 事实源。"}
+{"file": ".trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-frontend-scope.md", "reason": "核对实际改动没有越过试运行前清障边界，不做业务状态机或全站重设计。"}
+{"file": ".trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-reference-systems.md", "reason": "核对页面统一遵守分层参考体系，不照抄竞品视觉或专有交互。"}
@@ -0,0 +1,5 @@
+{"file": ".trellis/spec/hyb-oa/frontend-react-vite-design.md", "reason": "前端 React/Vite 设计事实源、共享组件优先和 typecheck/build 验证要求。"}
+{"file": ".trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-frontend-scope.md", "reason": "父任务已确认的试运行前前端清障范围、边界和验收建议。"}
+{"file": ".trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-reference-systems.md", "reason": "父任务已确认的 PC 参考体系：Hyinda、飞书、Ant Design、业务覆盖参考。"}
+{"file": ".trellis/spec/hyb-oa/wecom-boundary.md", "reason": "HR/考勤与企业微信主办边界，避免 PC 清障误启用 OA 日常入口。"}
+{"file": ".trellis/spec/hyb-oa/security-privacy.md", "reason": "前端页面和证据截图不得泄露敏感信息、内部账号和原始 payload。"}
@@ -0,0 +1,110 @@
+# 实施方案
+
+## 执行原则
+
+- 先统一高频 PC 页面观感，再处理低频边界页。
+- 优先复用现有 `client/src/components/patterns/*` 和 `components/ui/*`，不引入新 UI 依赖。
+- 改展示、默认筛选、折叠和文案，不改业务语义。
+- 每一批改动后跑局部检查，避免大批量视觉改动难以定位问题。
+
+## 页面批次
+
+### Batch 1：共享样板和高频 A 类页面
+
+目标：把用户每天最先接触的页面统一成同一套 PC 工作台语言。
+
+候选文件：
+
+- `client/src/pages/PortalHomePage.tsx`
+- `client/src/pages/ReimbursementsPage.tsx`
+- `client/src/pages/ReimbursementDetailPage.tsx`
+- `client/src/pages/WorkflowTasksPage.tsx`
+- `client/src/pages/WorkflowTaskDetailPage.tsx`
+- `client/src/components/patterns/ListWorkspace.tsx`
+- `client/src/components/patterns/SectionPanel.tsx`
+
+改动方向：
+
+- Portal 保留工作台定位，但压缩说明文案，首屏突出待处理、我的申请、异常和常用入口。
+- 报销/审批列表保持 `ListWorkspace + WorkspaceHeader + FilterBar + PrimaryTable`，统一副标题、指标条、状态页签和空状态。
+- 报销/审批详情保持事实源结构，摘要、材料、审批流、日志和操作区层级一致。
+- 如发现 `SectionPanel` 与 `WorkspaceSection` 密度冲突，优先用局部 class 或轻量补充组件统一密度，不做组件体系大重构。
+
+### Batch 2：B 类业务运营页面
+
+目标：降低财务、合同、项目、资产页面的默认噪音，避免试运行用户被历史测试数据和高级配置分散。
+
+候选文件：
+
+- `client/src/pages/ApOperationsPage.tsx`
+- `client/src/pages/PaymentBatchesPage.tsx`
+- `client/src/pages/ContractsRegistryPage.tsx`
+- `client/src/pages/ProjectsPage.tsx`
+- `client/src/pages/ProjectDetailPage.tsx`
+- `client/src/pages/AssetRegistryPage.tsx`
+
+改动方向：
+
+- AP/付款默认突出待付款、异常、待补资料；历史全量、导出、复核日志保留但次级化。
+- 合同/项目弱化 TEST/SMOKE 噪音，首屏突出正式合同、到期、负责人、归档位置。
+- 资产台账默认看资产列表和当前详情，分类维护、ERP 同步、元数据 JSON 后置或折叠。
+- 操作按钮按主/次/危险分层，高风险动作保留确认。
+
+### Batch 3：C 类冻结/后置和边界页
+
+目标：让普通管理员一眼知道哪些页面不是试运行主路径，减少误启用和误操作。
+
+候选文件：
+
+- `client/src/pages/AttendancePage.tsx`
+- `client/src/pages/BudgetsPage.tsx`
+- `client/src/pages/TravelRequestsPage.tsx`
+- `client/src/pages/ErpIntegrationPage.tsx`
+- `client/src/pages/FeatureFlagsPage.tsx`
+- `client/src/pages/CutoverConsolePage.tsx`
+- `client/src/components/navigation/NavLinks.tsx`
+- `client/src/features/navigation/schema.ts`
+
+改动方向：
+
+- HR/考勤强调企业微信主办，OA 是留存/审计或应急边界。
+- 预算、差旅、ERP、切换控制台保留可达性，但页面标题、说明或状态标签明确“未启用/只读/仅管理/后置”。
+- 功能开关、通知渠道、切换控制台默认展示安全摘要，高级配置和危险动作后置。
+- 导航不新增入口；如已有入口容易误导，只调整标签或说明。
+
+## 验证流程
+
+### 本地前端验证
+
+```bash
+cd client && npm run typecheck
+cd client && npm run build
+```
+
+### UI 规则与视觉证据
+
+```bash
+node scripts/qa/check-ui-design-rules.mjs --strict
+bash scripts/qa/run-oafront3-pc-readonly-visual.sh
+```
+
+如涉及移动联动：
+
+```bash
+QA_ISSUE_ID=oa-frontend-pretrial VISUAL_MATRIX_SCOPE=mobile bash scripts/qa/run-visual-matrix.sh live
+```
+
+### Trellis 与仓库检查
+
+```bash
+python3 ./.trellis/scripts/task.py validate 05-26-oa-frontend-pretrial-cleanup
+node scripts/qa/check-trellis-governance.mjs
+git diff --check
+```
+
+## 风险控制
+
+- 若某个页面需要改 API、权限或状态机才能达成理想交互，停止在本任务内推进，只记录后续成熟化项。
+- 若视觉矩阵需要公网环境或登录态，先跑能本地完成的 typecheck/build/design rules；公网检查需另按已有脚本和环境执行。
+- 若修改范围超过 1-2 天，优先保 A 类核心页和 AP/付款，合同/项目/资产/C 类页降级为边界文案和默认折叠。
+- 不把截图、报告或 Trellis 文件写入真实票据、合同正文、银行材料、完整账号或 raw payload。
@@ -0,0 +1,107 @@
+# OA 前端试运行前 PC 清障
+
+## Goal
+
+在不推迟 OAOPS1 7 天真实试运行、不改业务状态机的前提下，收敛 PC 高频页面的视觉风格、信息密度、文案层级、默认视图和冻结模块边界，让真实用户进入试运行时看到的是一致、克制、可操作的 OA 工作台，而不是多套风格混杂的页面集合。
+
+## Scope
+
+- 建立并执行试运行前 PC 前端清障合同。
+- 覆盖 PC 高频页的样板收敛、文案减噪、默认视图降噪和冻结/后置边界表达。
+- 优先覆盖 Portal/首页、报销、审批、AP/付款、合同/项目、资产台账。
+- 低频 C 类配置页只做边界提示、安全摘要和高级配置后置。
+- 补齐本任务必要的本地验证和视觉证据。
+- 不进入正式 7 天试运行计数，不部署、不改公网配置、不写真实业务数据。
+
+## What I Already Know
+
+- 用户已确认 PC 页面仍存在风格不统一、页面啰嗦、操作复杂、设计不够统一的问题，尤其影响试运行前信心。
+- 父任务已记录试运行前前端可改范围：只做“PC 样板收敛 + 文案减噪 + 默认视图降噪 + 视觉证据补齐”，不做全站重设计。
+- 父任务已记录参考体系：
+  - 品牌看 Hyinda 官网。
+  - 主体验看飞书工作台/飞书审批。
+  - PC 样板看 Ant Design 中后台模式。
+  - 业务覆盖只参考钉钉、泛微、合思/每刻。
+- 现有设计事实源 `docs/产品设计规则.md` 已规定 DG9 页面分层、PC 列表页骨架、详情页事实源骨架、文案规则和移动边界。
+- 代码中已经有可复用 PC 样板组件：`ListWorkspace`、`WorkspaceHeader`、`FilterBar`、`PrimaryTable`、`StatStrip`、`WorkspaceSection`、`SectionPanel`、`MetricCard`。
+- 当前抽样页面已部分使用统一样板，但仍存在多套组合方式和密度差异：Portal 使用 `PageScaffold + WorkbenchHero + SectionPanel`，报销/审批列表较接近 `ListWorkspace`，AP 页面存在较多页面内自定义卡片和表格区块。
+
+## Assumptions
+
+- 本任务只处理 PC 端试运行前清障；移动端只在明显影响 PC 改动联动时做轻微验证，不做移动体系重构。
+- 页面可读性和一致性优先于新增功能；不新增业务能力、不恢复冻结模块、不改变权限。
+- 不引入新的 UI 组件库，不把 Ant Design 作为依赖引入，只参考其 PC 中后台模式。
+- 若某个页面需要后端数据或状态机配合才能彻底简化，本任务只做前端展示收敛，并把剩余项记入后续成熟化。
+
+## Requirements
+
+- 统一 PC 高频页样板：
+  - 列表页采用“页头 -> 关键筛选/状态页签 -> 表格/列表 -> 分页/批量动作”结构。
+  - 详情页采用“摘要 -> 关键字段 -> 附件/发票/审批流/日志 -> 主操作”结构。
+  - 页面标题、副标题、卡片标题、按钮层级和空/错/加载状态保持同一语气和密度。
+- 优先改动页面：
+  - A 类核心：Portal/首页、报销列表、报销详情、审批列表、审批详情。
+  - B 类业务运营：AP/付款、合同台账、项目列表/详情、资产台账。
+  - C 类边界页：HR/考勤、预算、差旅、ERP、功能开关/切换控制台，只做冻结/后置/企微主办边界表达和默认折叠。
+- 文案减噪：
+  - 删除或压缩解释设计意图、流程科普和重复状态文案。
+  - 保留状态、下一步动作、异常原因、必要风险说明。
+  - 高风险操作确认弹窗仍保留后果说明。
+- 默认视图降噪：
+  - AP/付款优先显示待付款、异常、待补资料。
+  - 合同/项目弱化或默认隐藏 TEST/SMOKE 噪音，突出正式数据、负责人、到期和归档。
+  - 资产台账优先资产列表和当前详情，分类维护、ERP 同步、高级字段后置。
+  - C 类配置页默认“安全摘要 + 高级配置”。
+- 冻结/后置模块边界：
+  - 预算、差旅、ERP、切换控制台等不得被误认为试运行主路径。
+  - HR/考勤必须表达企业微信主办、OA 留存/审计或应急边界。
+- 视觉证据：
+  - 至少补 PC 关键页面截图或视觉矩阵证据，覆盖首页、报销、审批、AP/付款、合同/项目/资产。
+  - 不在证据中保存密码、token、Secret、完整账号、真实票据原文、合同正文、银行材料或 raw payload。
+
+## Acceptance Criteria
+
+- [ ] PRD 和实施方案明确“试运行前清障”边界，不把本任务扩大成全站重设计。
+- [ ] A 类核心 PC 页面在标题、卡片密度、按钮层级、表格/筛选和空/错/加载状态上保持统一。
+- [ ] AP/付款、合同/项目、资产台账默认视图明显降低测试数据、高级配置和历史全量噪音。
+- [ ] 冻结/后置模块和 HR/考勤边界在页面上可被普通管理员理解，不误导真实员工。
+- [ ] 不改变 API、权限、审批、OCR、付款、AP、数据模型或状态机语义。
+- [ ] 前端验证通过：`cd client && npm run typecheck && npm run build`。
+- [ ] UI 设计规则通过：`node scripts/qa/check-ui-design-rules.mjs --strict`。
+- [ ] Trellis 检查通过：`python3 ./.trellis/scripts/task.py validate 05-26-oa-frontend-pretrial-cleanup`、`node scripts/qa/check-trellis-governance.mjs`、`git diff --check`。
+
+## Definition Of Done
+
+- 试运行前 PC 清障代码完成并通过本 PRD 的验证命令。
+- 视觉证据或视觉矩阵输出能证明关键 PC 页面没有明显遮挡、溢出、误导性入口或内部编号主展示。
+- 所有改动可回滚，且没有引入生产部署、真实数据写入、企业微信写入或付款动作。
+- 如发现超出 1-2 天的小型清障范围，记录为后续 `oa-frontend-experience-maturity`，不在本任务内扩大。
+
+## Out Of Scope
+
+- 不做全站视觉重设计、品牌重塑或新的设计系统。
+- 不引入 Ant Design 组件库或其他 UI 依赖。
+- 不修改后端接口、数据库、权限模型、审批规则、OCR、付款批次、AP 状态机。
+- 不启用预算硬控、差旅主线、ERP 写入、HR 深镜像、应急接管常态化、银企直连、真实支付接口。
+- 不启动真实 7 天试运行计数，不执行部署、公网配置变更、真实业务写入或企业微信写入。
+
+## Test Plan
+
+- `cd client && npm run typecheck`
+- `cd client && npm run build`
+- `node scripts/qa/check-ui-design-rules.mjs --strict`
+- `bash scripts/qa/run-oafront3-pc-readonly-visual.sh`
+- 需要移动联动时再运行：`QA_ISSUE_ID=oa-frontend-pretrial VISUAL_MATRIX_SCOPE=mobile bash scripts/qa/run-visual-matrix.sh live`
+- `python3 ./.trellis/scripts/task.py validate 05-26-oa-frontend-pretrial-cleanup`
+- `node scripts/qa/check-trellis-governance.mjs`
+- `git diff --check`
+
+## Technical Notes
+
+- 父任务：`.trellis/tasks/05-26-oaops1-seven-day-trial-prep/`
+- 前端清障范围：`.trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-frontend-scope.md`
+- PC 参考体系：`.trellis/tasks/05-26-oaops1-seven-day-trial-prep/research/pretrial-reference-systems.md`
+- 设计事实源：`docs/产品设计规则.md`
+- 前端 spec：`.trellis/spec/hyb-oa/frontend-react-vite-design.md`
+- 企微边界：`.trellis/spec/hyb-oa/wecom-boundary.md`
+- 隐私边界：`.trellis/spec/hyb-oa/security-privacy.md`
@@ -0,0 +1,26 @@
+{
+  "id": "oa-frontend-pretrial-cleanup",
+  "name": "oa-frontend-pretrial-cleanup",
+  "title": "OA 前端试运行前 PC 清障",
+  "description": "试运行前收敛 PC 高频页面风格、文案、默认视图和冻结模块边界，补齐视觉证据，不改业务状态机。",
+  "status": "planning",
+  "dev_type": null,
+  "scope": "frontend-pretrial-cleanup",
+  "package": null,
+  "priority": "P1",
+  "creator": "shunli",
+  "assignee": "shunli",
+  "createdAt": "2026-05-26",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "05-26-oaops1-seven-day-trial-prep",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
@@ -18,7 +18,9 @@
  "commit": null,
  "pr_url": null,
  "subtasks": [],
-  "children": [],
+  "children": [
+    "05-26-oa-frontend-pretrial-cleanup"
+  ],
  "parent": null,
  "relatedFiles": [
    "scripts/qa/run-oa-real-use-daily.sh",