leaudit-platform-backend/docs/内部公文模块/内部公文前端拆分实施清单.md

# 内部公文前端拆分实施清单

## 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 后端结果翻译成前端可复用语义

这就是内部公文前端后续实施的固定边界。