wangsli/hyb-oa
1
0
派生 0
代码 工单 合并请求 工作流 8 软件包 项目 发布 百科 活动
文件
73e78f21b4d9d41fa12850e422c7ff7facb710e5
hyb-oa/.trellis/tasks/archive/2026-07/07-16-legacy-portal-navigation-compat-cleanup/prd.md
T

8.5 KiB
原始文件 Blame 文件历史

清理旧 Portal 导航兼容

Goal

移除已经失效的 Portal 导航双文案兼容和重复报告字段，使公网 smoke、视觉审计与当前产品文案统一以 工作台 为准，同时保留 /portal 路由、内部技术标识、对用户可见英文 Portal 的负向检测以及历史审计材料。

Scope

  • 最小推荐范围：更新部署规约中的 工作台 | Portal 双接受合同为仅接受 工作台。
  • 删除只读视觉报告中与 englishFound 重复、无现行消费者的 navPortalCopy 字段。
  • 保留 ENGLISH_PRIMARY_TERMS 中的 Portal，继续把用户可见英文旧词视为视觉 finding。
  • 现行用户/运维手册中的 Portal 术语不在本批迁移范围。

What I Already Know

  • 当前前端导航、后端 workspace 默认导航和所有现行 mock fixture 都使用 工作台。
  • client/tests/e2e/helpers/smokeAssertions.ts 自 2026-05-29 起只接受精确中文 工作台，没有运行时代码仍执行双文案兼容。
  • .trellis/spec/hyb-oa/deployment-trialrun.md 仍声称旧 mock 可输出 Portal，并给出 .or(...Portal) 示例；该规约已与实际 helper 漂移。
  • 当前 mock/fixture 中未发现 label: "Portal" 或等价单引号写法。
  • client/tests/e2e/oafront3-pc-readonly-visual.spec.ts 把 Portal 纳入禁止英文主展示词，这是应保留的负向检测。
  • 同一视觉报告另行输出 navPortalCopy: text.includes("Portal")，但 englishFound 已包含相同信号；现行代码没有消费者。
  • 归档视觉报告包含旧 navPortalCopy 字段，属于历史证据，不改写。
  • /portal 路由、assertPortalLoaded、PortalHomePage、Portal API/数据库标识和测试标题是仍在使用的内部技术标识，不等同于用户可见旧导航兼容。
  • 多份当前手册和业务规约仍用 Portal 指代工作台；一次性迁移会显著扩大审阅范围。

Confirmed Scope

  • 用户于 2026-07-16 选择方案 1，采用最小兼容清理，不把文档术语迁移和内部符号重命名混入同一批。
  • 移除重复报告字段不会影响历史报告读取，因为未发现现行聚合器或门禁消费该字段。
  • 本任务不改变路由、导航结构、页面视觉、角色权限或部署行为。

Open Questions

  • 无。

Requirements

  • 规约必须准确反映现行 smoke helper：导航仅接受 工作台。
  • 删除重复的 navPortalCopy 新报告字段，但保留 Portal 英文负向检测。
  • 保留 /portal 路由和所有仍有消费者的内部 Portal 技术标识。
  • 不改写历史 Issue、归档 task 或归档视觉报告。
  • 验证 TypeScript、Playwright spec 加载、前端构建和 Trellis 治理。
  • 验证产生的 client/dist/、Playwright report 和 test-results 在取证后清理。

Acceptance Criteria

  • 部署规约不再声明或示范 工作台 | Portal 导航双接受。
  • smokeAssertions.ts 继续精确断言 工作台，不新增其他旧词 fallback。
  • 新生成的只读视觉报告不再包含重复字段 navPortalCopy。
  • ENGLISH_PRIMARY_TERMS 仍包含 Portal，用户可见旧英文文案仍产生 finding。
  • 当前 mock/fixture 不含 Portal 导航 label。
  • /portal 路由与内部 Portal 标识保持不变。
  • TypeScript、Playwright spec --list、前端 build、task/governance/diff 门禁通过。
  • 最终工作树不包含验证生成物，修改范围与用户选择一致。

Feasible Approaches

方案 1：最小兼容清理（推荐）

  • 更新部署规约为中文单一合同。
  • 删除重复 navPortalCopy 报告字段。
  • 保留负向英文检测、内部标识和所有现行/历史文档原状。
  • 优点：两处小改、风险最低，直接解决实际兼容漂移。
  • 缺点：部分现行手册仍使用 Portal 作为工作台术语。

方案 2：兼容清理 + 现行手册术语迁移

  • 在方案 1 基础上，把 CURRENT 用户/运维文档中面向人的 Portal 改为 工作台。
  • 优点：用户和运维文案更一致。
  • 缺点：涉及多份事实源，需要逐条判断历史描述、路由名与当前体验，回归面明显扩大。

方案 3：连内部 Portal 标识一起重命名

  • 同时重命名路由、组件、API、测试标题或数据库技术标识。
  • 不推荐：没有用户价值，会制造跨前后端、数据与历史兼容风险。

Definition of Done

  • 用户选择的范围完成并记录，未顺带重命名内部技术标识。
  • 兼容删除有静态引用、历史、报告消费者和回滚证据。
  • 前端与治理门禁通过，生成物清理完成。
  • 形成中文本地提交计划并另行取得提交确认；不自动 push 或部署。

Technical Approach

  1. 区分用户可见旧词、负向检测、内部标识、现行手册与历史证据。
  2. 以现行 helper 和导航源为事实，删除规约中的虚假双接受描述。
  3. 删除只读视觉报告中的重复字段，保留 englishFound 的 Portal 负向信号。
  4. 运行静态引用、TypeScript、Playwright 加载、build 和治理门禁。

详细引用矩阵、验证边界与回滚见 design.md 和 research/portal-compat-audit.md。

Decision (ADR-lite)

Context：运行时已经中文单一化，但部署规约仍保留旧 fallback，视觉报告又重复输出相同旧词信号；同时内部 /portal 技术标识和历史证据仍有合法用途。

Decision：用户已选择方案 1；只删失效兼容和重复报告字段，不做大范围术语或内部符号迁移。

Consequences：当前导航合同与代码重新一致，未来报告更精简；现行手册术语一致性留待独立文档治理批次。

Test Plan

cd client && npm run typecheck
cd client && npx playwright test tests/e2e/oafront3-pc-readonly-visual.spec.ts --list
cd client && npx playwright test tests/e2e/visual-shell.spec.ts --list
cd client && npm run build
python3 ./.trellis/scripts/task.py validate 07-16-legacy-portal-navigation-compat-cleanup
node scripts/qa/check-trellis-governance.mjs
git diff --check
  • 不运行带凭据公网视觉审计或 live smoke；若需要真实公网复核，必须另行批准并提供前置条件。
  • 不执行部署、生产配置修改、数据库写入或企业微信写入。

Verification Results

  • smokeAssertions.ts 仍有两处精确 工作台 导航断言；当前前后端及 fixture 搜索未发现 Portal 导航 label。
  • 活跃测试、规约、脚本和部署范围中 navPortalCopy 引用为 0；受保护归档报告仍保留旧字段。
  • ENGLISH_PRIMARY_TERMS 继续包含 Portal，englishFound 仍是用户可见英文旧词的单一 finding 信号。
  • cd client && npm run typecheck 退出码为 0。
  • 两个相关 Playwright spec 使用 --list 成功加载，共列出 2 个文件、6 个测试；未启动浏览器或访问公网。
  • cd client && npm run build 退出码为 0：Vite 转换 2381 个模块，PWA 生成 102 个预缓存条目；仅有既有 Browserslist 数据陈旧提示。
  • task validate、Trellis governance 和 git diff --check 严格模式通过；治理无 warning/error。
  • client/dist、client/playwright-report 和 client/test-results 已清理。
  • 独立只读复核无阻断：确认精确中文导航合同、englishFound 检测能力、内部标识与历史证据边界均保持完整，工作树未超出方案 1。
  • 未执行 live smoke、带凭据视觉审计、部署、push 或任何数据写入。

Out of Scope

  • 未经选择的现行手册术语批量迁移。
  • /portal 路由、Portal API、数据库字段、组件名和内部 helper 名重命名。
  • 改写历史 Issue CSV、归档 task、归档视觉报告或旧截图。
  • 页面布局、视觉、交互、权限、导航分组或业务能力调整。
  • push、部署、公网检查或真实数据写入。

Technical Notes

  • 当前中文导航源：client/src/components/navigation/NavLinks.tsx、client/src/features/navigation/schema.ts、server/src/services/workspaceSettings.js。
  • 当前 smoke helper：client/tests/e2e/helpers/smokeAssertions.ts。
  • 待清理规约：.trellis/spec/hyb-oa/deployment-trialrun.md。
  • 待精简报告：client/tests/e2e/oafront3-pc-readonly-visual.spec.ts。
  • 上一批候选：.trellis/tasks/archive/2026-07/07-15-production-trust-closeout-cleanup/research/cleanup-candidate-inventory.md。

Research References

  • research/portal-compat-audit.md：导航源、fixture、规约、视觉报告、历史证据和内部标识分类结果。
在新工单中引用 查看 Git Blame 复制永久链接