# 内部公文前端拆分实施清单 ## 1. 文档目的 本文档只解决一个问题： - 在不改变“内部公文”业务语义的前提下，如何把当前前端实现拆成一套与“交叉评查”同级的独立页面架构 本文档关注的是： - 页面编排边界 - 组件职责边界 - `govdoc` 与 `reviews / cross-checking` 的复用边界 - 分阶段实施顺序 本文档不做以下事情： - 不改后端业务语义 - 不要求照搬旧项目代码 - 不把 `Collabora` 当成整个中栏预览架构 --- ## 2. 结论先行 内部公文前端应按以下原则重构： > **像交叉评查一样独立成页，但复用 reviews 的定位型预览能力。** 准确解释如下： - 内部公文应有自己独立的页面 orchestrator - 内部公文应有自己独立的业务组件层 - 内部公文应有自己独立的 TS service / adapter 层 - 中栏 PDF / DOCX 预览不应重新发明一套，而应优先复用 `reviews` 已有能力 - `Collabora` 只应作为 DOCX viewer，不应承担“问题定位主架构” 因此，目标不是： - 把当前 `govdoc-audit` 页面继续补丁式扩写 而是： - 把内部公文前端收敛为“独立页面编排 + 统一预览协议 + 独立业务壳”的平台化实现 --- ## 3. 当前实现现状 ## 3.1 当前内部公文前端入口 当前内部公文详情页主入口为： - [components/govdoc-audit/audit.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/govdoc-audit/audit.tsx:1) 当前内部公文列表页主入口为： - [components/govdoc-audit/audits.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/govdoc-audit/audits.tsx:1) 当前路由入口为： - [app/(audit)/govdoc/audits/page.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/govdoc/audits/page.tsx:1) - [app/(audit)/govdoc/detail/[documentId]/page.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/govdoc/detail/[documentId]/page.tsx:1) 当前详情页已经具备： - 顶部摘要与报告下载操作 - 评查 / 结构 / 大纲 / 实体 tab - 中栏文档视图 - 右栏 findings / checked rules 展示 问题不在于“没有功能”，而在于“页面职责混装”。 --- ## 3.2 当前详情页耦合点 当前 [audit.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/govdoc-audit/audit.tsx:1) 同时承担了以下职责： - 页面数据加载 - 顶部操作区渲染 - tab 状态切换 - 结果统计条渲染 - 中栏文档视图调度 - 右栏问题面板调度 - 规则弹窗调度 这会带来三个问题： - 页面 orchestrator 和业务组件未分层 - 中栏预览协议没有向平台现有 `reviews` 能力对齐 - 右栏问题区与 `reviews / cross-checking` 的定位交互无法复用 --- ## 3.3 当前中栏预览为什么不应继续沿现状扩写 当前内部公文中栏主要使用： - [components/govdoc-audit/doc-view.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/govdoc-audit/doc-view.tsx:1) 而平台现有成熟的“定位型预览”能力在： - [components/reviews/previewComponents/PdfPreviewTest.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/reviews/previewComponents/PdfPreviewTest.tsx:1) - [components/reviews/previewComponents/DocxPreviewTest.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/reviews/previewComponents/DocxPreviewTest.tsx:1) - [app/(audit)/reviews-test/ReviewsTestClient.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/reviews-test/ReviewsTestClient.tsx:1) - [app/(audit)/cross-checking/result/CrossCheckingResultClient.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/cross-checking/result/CrossCheckingResultClient.tsx:1) 必须明确： - PDF 中栏定位主能力不是 `Collabora` - DOCX 中栏当前虽然使用 `CollaboraViewer`，但它承担的是文档渲染，不是完整的问题定位架构 如果内部公文要做到： - 点击问题点后定位到对应页 - 对问题字段/段落做高亮 - 为后续“问题行定位”保留升级空间 则中栏必须对齐现有平台预览输入协议，而不是继续把 `DocView` 做成一套孤岛实现。 --- ## 4. 目标架构 ## 4.1 总体原则 前端目标架构应满足以下四条： - 内部公文页面独立编排 - 中栏预览能力平台复用 - 业务面板 govdoc 自治 - 数据适配集中在 adapter 层 可以概括为： > **govdoc 自己负责业务壳，platform 负责通用预览能力。** --- ## 4.2 目标目录结构 建议拆分为以下结构： ```text legal-platform-frontend/ app/(audit)/govdoc/ audits/page.tsx detail/[documentId]/page.tsx components/govdoc-audit/ GovdocAuditListPage.tsx GovdocAuditResultPage.tsx GovdocSummaryHeader.tsx GovdocFindingPanel.tsx GovdocStructurePanel.tsx GovdocOutlinePanel.tsx GovdocEntityPanel.tsx GovdocReportActions.tsx lib/api/govdoc-audit/ api.ts types.ts adapters.ts govdoc-routes.ts ``` 说明如下： - `page.tsx` 只保留路由入口职责 - `GovdocAuditResultPage.tsx` 负责详情页 orchestrator - `GovdocAuditListPage.tsx` 负责列表页 orchestrator - `Govdoc*Panel` 负责内部公文独有业务视图 - `adapters.ts` 负责把 govdoc 后端返回结果转成前端视图模型 --- ## 4.3 页面编排职责 ### 详情页 orchestrator 建议新增： - `components/govdoc-audit/GovdocAuditResultPage.tsx` 该组件只负责： - 读取 `documentId / runId` - 调用 govdoc API - 维护 tab 状态 - 维护当前激活问题点 - 维护当前预览定位目标 - 组装中栏与右栏 它不应承担： - 具体 finding 卡片渲染细节 - 实体/结构/大纲具体 UI 细节 - 预览底层渲染逻辑 这部分应当参照： - [CrossCheckingResultClient.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/cross-checking/result/CrossCheckingResultClient.tsx:1) --- ### 列表页 orchestrator 建议新增： - `components/govdoc-audit/GovdocAuditListPage.tsx` 该组件负责： - 列表数据加载 - 筛选状态 - 批量操作状态 - 导出与删除 - 跳转详情页 它应继续保持内部公文自己的筛选语义，但 UI 节奏应向平台文档列表页靠拢。 列表页设计参照： - [DocumentsListClient.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/app/(audit)/documents/list/DocumentsListClient.tsx:1) --- ## 5. 与 reviews / cross-checking 的复用边界 ## 5.1 应复用的能力 内部公文应复用以下能力： - PDF 中栏预览组件 - DOCX 中栏预览组件 - 问题点点击后的预览定位协议 - 页码跳转、高亮、bbox / charPositions 定位能力 优先复用对象： - [PdfPreviewTest.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/reviews/previewComponents/PdfPreviewTest.tsx:1) - [DocxPreviewTest.tsx](/home/wren-dev/Porject/leaudit-platform/legal-platform-frontend/components/reviews/previewComponents/DocxPreviewTest.tsx:1) 复用的是： - 预览能力 - 定位协议 - 用户交互模型 不是： - 合同业务语义 - 卷宗业务命名 - 旧页面外壳 --- ## 5.2 不应复用的部分 以下部分不应直接复用： - `reviews-test` 自身的业务标题、业务字段命名 - 合同/卷宗专有的右栏业务解释 - `cross-checking` 的评分协同、提议投票、交叉意见面板 原因是： - 这些属于业务壳，而不是平台通用能力 内部公文应保留自己的： - findings 口径 - checked rules 口径 - 结构 / 大纲 / 实体口径 - 报告下载口径 --- ## 5.3 Collabora 的正确定位 `CollaboraViewer` 的边界必须明确： - 它是 DOCX viewer - 它可以承担跳页、文本高亮、编辑/只读查看 - 它不是内部公文详情页的业务 orchestrator - 它也不是“问题行精确定位”的完整方案 因此： - `Collabora` 只能留在 `DocxPreviewTest` 这一层 - 不应让 govdoc 页面继续直接围绕 `Collabora` 自己长出一套完整详情页体系 --- ## 6. 必须新增的 adapter 层 ## 6.1 为什么必须有 adapters.ts 当前 `lib/api/govdoc-audit` 下已有： - `api.ts` - `types.ts` - `govdoc-routes.ts` 但还缺一层： - `adapters.ts` 这层必须存在，因为它承担的是“业务结果语义 -> 预览与页面视图语义”的转换。 如果没有这层，后果会是： - govdoc 页面自己维护一套 findings 展示模型 - reviews 页面自己维护一套 preview target 模型 - 同类定位交互会出现两套不兼容实现 --- ## 6.2 adapters.ts 建议职责 `adapters.ts` 建议至少提供以下能力： - 将 `govdoc` 结果对象转换为结果页 view model - 将 `finding / checked_rule` 转换为右栏展示项 - 将 `finding / paragraph / entity` 转换为中栏跳转目标 - 根据文件类型产出统一 preview target - 将后端报告产物状态转换为按钮展示状态 建议输出的数据语义包括： - `previewKind` - `previewPath` - `activeTarget` - `findingItems` - `summaryCards` - `reportActions` - `structureItems` - `outlineItems` - `entityItems` 这样后续页面层只编排，不解释后端字段细节。 --- ## 7. 分阶段实施顺序 ## 7.1 第一阶段：补 adapter，不改页面语义 目标： - 先把数据适配层补齐 动作： - 新增 `lib/api/govdoc-audit/adapters.ts` - 收敛 `audit.tsx` 里对原始接口字段的直接解释 - 把 preview target 语义统一为： - `page` - `highlightValue` - `bboxHighlight` - `charPositions` 本阶段收益： - 不改用户可见业务逻辑 - 为后续替换中栏和右栏做稳定基础 --- ## 7.2 第二阶段：拆详情页 orchestrator 目标： - 让 govdoc 详情页像 `cross-checking` 一样拥有独立 orchestrator 动作： - 新增 `GovdocAuditResultPage.tsx` - 将现有 `audit.tsx` 逻辑迁入新组件 - 路由入口改为挂载新组件 - 顶部摘要、下载操作、tab 切换拆成子组件 本阶段收益： - 页面职责清晰 - 后续中栏和右栏可以独立演进 --- ## 7.3 第三阶段：切换中栏到定位型预览 目标： - 内部公文详情页中栏不再以 `DocView` 为核心 动作： - 根据文件类型切换到 `PdfPreviewTest / DocxPreviewTest` - 从 govdoc adapter 输出统一 preview target - 让右栏点击直接驱动中栏定位 本阶段注意： - PDF 定位优先支持 `bboxHighlight / charPositions` - DOCX 优先支持 `targetPage + highlightValue` - 不承诺此阶段立即做到“DOCX 行级精确定位” --- ## 7.4 第四阶段：重构右栏与 tab 业务壳 目标： - 保留 govdoc 自己的业务面板，但交互模型对齐平台 动作： - 将当前 `RightPanel` 重构为 `GovdocFindingPanel` - 将结构、大纲、实体分面板组件化 - 收敛旧的孤立交互状态 本阶段收益： - govdoc 保持业务独立 - 同时具备平台统一的交互体验 --- ## 7.5 第五阶段：样式与布局收口 目标： - govdoc 页面在视觉上向平台现有绿色主题和通用 panel 节奏靠齐 动作： - 减少 `.govdoc-audit-scope` 中重复定义 - 优先复用 `layout-primitives.css` - 保留必要的 govdoc 业务样式命名空间 本阶段原则： - 先统一布局和交互节奏 - 再减少样式重复 - 不先做“大改视觉” --- ## 8. 风险点与前置条件 ## 8.1 最大风险不在前端组件，而在定位数据颗粒度 内部公文要实现“定位到哪一行有问题”，前端只是承载层，真正决定上限的是后端给的数据。 前端能稳定消费的数据类型分为两类： - PDF： - `page` - `bbox` - `page_box` - `char_positions` - DOCX： - `targetPage` - `highlightValue` - 未来如果需要更高精度，还需要更细粒度锚点 如果后端只给： - 问题描述 - 规则结果 而不给定位数据，那么前端最多只能做到： - 页级定位 - 文本关键字高亮 不能承诺做到稳定的“行级定位”。 --- ## 8.2 不应在这一阶段做的事情 以下动作不建议和本次拆分同时进行： - 重写 govdoc 全部视觉设计 - 把 govdoc 规则语义改造成合同/卷宗语义 - 试图把所有 `reviews` 业务组件直接搬进 govdoc - 在没有 adapter 的情况下直接大规模替换页面 原因很简单： - 这些动作会把“前端分层重构”和“业务改动”混在一起，增加回归风险 --- ## 9. 最终边界结论 内部公文前端的正确实现边界应锁定为： - **像交叉评查一样，独立成页** - **像 reviews 一样，复用定位型预览能力** - **像平台模块一样，数据解释集中在 adapter 层** - **像内部公文自己一样，保留 findings / checked rules / structure / outline / entities 的业务语义** 更直白地说： - `Govdoc 页面` 负责业务编排 - `reviews 预览组件` 负责中栏定位能力 - `Collabora` 只负责 DOCX 渲染 - `adapters.ts` 负责把 govdoc 后端结果翻译成前端可复用语义 这就是内部公文前端后续实施的固定边界。