TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08123b3b5aecc3547fad962d710ec2227523b8ed
leaudit-platform-backend/docs/内部公文模块/内部公文前端拆分实施清单.md
T
wren 1bacfe41b7 feat: integrate govdoc platform updates
2026-05-18 14:35:25 +08:00

13 KiB
Raw Blame History

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

1. 文档目的

本文档只解决一个问题：

  • 在不改变“内部公文”业务语义的前提下，如何把当前前端实现拆成一套与“交叉评查”同级的独立页面架构

本文档关注的是：

  • 页面编排边界
  • 组件职责边界
  • govdoc 与 reviews / cross-checking 的复用边界
  • 分阶段实施顺序

本文档不做以下事情：

  • 不改后端业务语义
  • 不要求照搬旧项目代码
  • 不把 Collabora 当成整个中栏预览架构

2. 结论先行

内部公文前端应按以下原则重构：

像交叉评查一样独立成页，但复用 reviews 的定位型预览能力。

准确解释如下：

  • 内部公文应有自己独立的页面 orchestrator
  • 内部公文应有自己独立的业务组件层
  • 内部公文应有自己独立的 TS service / adapter 层
  • 中栏 PDF / DOCX 预览不应重新发明一套，而应优先复用 reviews 已有能力
  • Collabora 只应作为 DOCX viewer，不应承担“问题定位主架构”

因此，目标不是：

  • 把当前 govdoc-audit 页面继续补丁式扩写

而是：

  • 把内部公文前端收敛为“独立页面编排 + 统一预览协议 + 独立业务壳”的平台化实现

3. 当前实现现状

3.1 当前内部公文前端入口

当前内部公文详情页主入口为：

当前内部公文列表页主入口为：

当前路由入口为：

当前详情页已经具备：

  • 顶部摘要与报告下载操作
  • 评查 / 结构 / 大纲 / 实体 tab
  • 中栏文档视图
  • 右栏 findings / checked rules 展示

问题不在于“没有功能”，而在于“页面职责混装”。

3.2 当前详情页耦合点

当前 audit.tsx 同时承担了以下职责：

  • 页面数据加载
  • 顶部操作区渲染
  • tab 状态切换
  • 结果统计条渲染
  • 中栏文档视图调度
  • 右栏问题面板调度
  • 规则弹窗调度

这会带来三个问题：

  • 页面 orchestrator 和业务组件未分层
  • 中栏预览协议没有向平台现有 reviews 能力对齐
  • 右栏问题区与 reviews / cross-checking 的定位交互无法复用

3.3 当前中栏预览为什么不应继续沿现状扩写

当前内部公文中栏主要使用：

而平台现有成熟的“定位型预览”能力在：

必须明确：

  • PDF 中栏定位主能力不是 Collabora
  • DOCX 中栏当前虽然使用 CollaboraViewer，但它承担的是文档渲染，不是完整的问题定位架构

如果内部公文要做到：

  • 点击问题点后定位到对应页
  • 对问题字段/段落做高亮
  • 为后续“问题行定位”保留升级空间

则中栏必须对齐现有平台预览输入协议，而不是继续把 DocView 做成一套孤岛实现。

4. 目标架构

4.1 总体原则

前端目标架构应满足以下四条：

  • 内部公文页面独立编排
  • 中栏预览能力平台复用
  • 业务面板 govdoc 自治
  • 数据适配集中在 adapter 层

可以概括为：

govdoc 自己负责业务壳，platform 负责通用预览能力。

4.2 目标目录结构

建议拆分为以下结构：

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 细节
  • 预览底层渲染逻辑

这部分应当参照：

列表页 orchestrator

建议新增：

  • components/govdoc-audit/GovdocAuditListPage.tsx

该组件负责：

  • 列表数据加载
  • 筛选状态
  • 批量操作状态
  • 导出与删除
  • 跳转详情页

它应继续保持内部公文自己的筛选语义，但 UI 节奏应向平台文档列表页靠拢。

列表页设计参照：

5. 与 reviews / cross-checking 的复用边界

5.1 应复用的能力

内部公文应复用以下能力：

  • PDF 中栏预览组件
  • DOCX 中栏预览组件
  • 问题点点击后的预览定位协议
  • 页码跳转、高亮、bbox / charPositions 定位能力

优先复用对象：

复用的是：

  • 预览能力
  • 定位协议
  • 用户交互模型

不是：

  • 合同业务语义
  • 卷宗业务命名
  • 旧页面外壳

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

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

Reference in New Issue View Git Blame Copy Permalink