leaudit-platform-backend/docs/内部公文模块/内部公文模块迁移方案.md

# 内部公文模块迁移方案

## 1. 目标定位

`govdoc-audit` 不应作为独立系统继续外挂，而应正式收口为当前 `leaudit-platform` 中的一个一等业务模块。

建议模块名：

- `govdoc`
- 中文显示名：`内部公文处理`

它在当前项目中的定位应为：

- 一个“公文处理与格式审查模块”
- 共享当前平台的用户、权限、文档、OSS、任务系统
- 拥有自己独立的规则、运行、结果、报告模型

---

## 2. 总体迁移原则

一句话原则：

- 迁“引擎”
- 不迁“壳子”

应迁入当前项目的内容：

- 公文解析器
- 段落角色识别
- 语义实体提取
- YAML DSL
- 规则执行器
- HTML / DOCX / JSON 报告生成

不建议直接迁入的内容：

- 原 `FastAPI` API 层
- 原 `SQLite` 存储层
- 原 `web` 前端
- 原本地 `var/documents` 落盘模式

原因是当前平台已经具备更成熟的基础设施：

- 统一 FastAPI 应用
- JWT / RBAC
- 地区隔离
- 文档主档与文件版本
- MinIO / OSS
- Celery 异步任务
- bridge 执行链

因此正确方案不是再造第二个平台，而是把 `govdoc-audit` 变成当前平台中的一个能力模块。

---

## 3. 模块化后的目标形态

### 3.1 后端模块职责

该模块应负责：

- 公文上传
- 公文格式审查
- 审查结果查询
- 规则查看
- 报告下载
- 审查过程留痕

不负责：

- 通用 RAG
- 合同评审
- 交叉评查

### 3.2 前端模块职责

前端中应新增一个独立入口模块，页面建议包括：

- 公文上传页
- 审查列表页
- 审查详情页
- 规则查看页
- 报告下载入口
- 模块配置页（可选）

路由建议：

- `/govdoc`
- `/govdoc/upload`
- `/govdoc/list`
- `/govdoc/detail/:documentId`

---

## 4. 推荐架构分层

建议按 6 层拆分：

1. 接口层
2. 服务层
3. 执行桥接层
4. 引擎内核层
5. 持久化层
6. 展示层

### 4.1 接口层

建议新增：

- `fastapi_modules/fastapi_leaudit/controllers/govdocController.py`

职责：

- 上传公文
- 查询公文列表
- 发起审查
- 查询运行状态
- 查询结果详情
- 下载 HTML / DOCX / 原文
- 查询规则清单

控制器只做：

- JWT 鉴权
- DTO 收参
- 调 service
- 统一返回 Result

### 4.2 服务层

建议新增：

- `fastapi_modules/fastapi_leaudit/services/govdocService.py`
- `fastapi_modules/fastapi_leaudit/services/impl/govdocServiceImpl.py`

职责：

- 复用当前文档服务做上传与元数据管理
- 创建公文审查 run
- 调度异步任务
- 聚合查询结果
- 组织前端详情数据

### 4.3 执行桥接层

建议新增目录：

```text
fastapi_modules/fastapi_leaudit/govdoc_bridge/
  __init__.py
  tasks.py
  runner.py
  input_resolver.py
  rules_resolver.py
  storage_adapter.py
  result_adapter.py
  report_adapter.py
  context_builder.py
  security_guard.py
```

职责：

- 从当前平台读取文档与文件元数据
- 从 OSS 下载文档到本地临时文件
- 解析规则版本并准备本地规则文件
- 调用 `govdoc` 引擎执行
- 将结果适配回当前平台数据库和 OSS

这是整个模块接入的关键层。

### 4.4 引擎内核层

建议把 `govdoc-audit` 裁剪后并入当前仓库：

```text
fastapi_modules/fastapi_leaudit/govdoc_engine/
  __init__.py
  models.py
  pipeline.py
  parser/
  dsl/
  engine/
  reporter/
  llm/
```

建议迁入：

- `parser/`
- `dsl/`
- `engine/`
- `reporter/`
- `llm/`
- `models.py`
- `pipeline.py`

明确不迁：

- 原 `api/`
- 原 `storage/`
- 原 `services/storage_service.py`
- 原 `web/`

### 4.5 持久化层

不建议继续使用原项目自己的 `SQLite + var/documents` 模式。

应基于当前平台数据库新增公文模块结果域表。

### 4.6 展示层

不迁原 `govdoc-audit/web`。

应直接在当前前端项目中新增 `govdoc` 模块页面，复用现有：

- 登录态
- 权限体系
- 侧边栏菜单
- UI 样式体系

---

## 5. 数据模型建议

### 5.1 应复用的平台公共表

建议直接复用：

- `sso_users`
- `roles`
- `user_role`
- `permissions`
- `role_permissions`
- `sys_routes`
- `role_route`
- `leaudit_documents`
- `leaudit_document_files`

这些表负责：

- 用户身份
- 权限控制
- 地区隔离
- 文档主档
- 文件版本
- OSS 关联

### 5.2 建议补充的主档字段

建议在 `leaudit_documents` 增加一个模块标识字段，例如：

- `engine_type`

可选值：

- `leaudit`
- `govdoc`
- `rag`

这样平台可以明确知道某份文档应走哪条处理链。

### 5.3 建议新增的公文模块结果域表

第一阶段建议至少新增：

- `govdoc_runs`
- `govdoc_rule_results`
- `govdoc_report_artifacts`

后续可补：

- `govdoc_entities`
- `govdoc_rule_sets`
- `govdoc_rule_versions`

推荐理解方式：

- 公共主档复用
- 领域结果隔离

不要把公文模块结果硬塞进现有 `leaudit_audit_runs` / `leaudit_rule_results`。

原因：

- 语义不完全一致
- 结果模型不完全兼容
- 统计口径会混乱
- 后期拆分成本更高

---

## 6. 模块权限设计建议

建议一开始就单独定义 `govdoc` 模块权限键：

- `govdoc:module:read`
- `govdoc:document:create`
- `govdoc:document:read`
- `govdoc:document:update`
- `govdoc:document:delete`
- `govdoc:run:create`
- `govdoc:run:read`
- `govdoc:report:read`
- `govdoc:rule:read`
- `govdoc:rule:manage`

权限层继续复用当前平台：

- JWT 鉴权
- RBAC
- 地区隔离

数据范围继续遵守当前平台规则：

- 省级管理员：全量
- 地区管理员：本地区
- 普通用户：本人数据

---

## 7. 迁移实施步骤

建议分 5 期推进。

### 第一期：内核迁入

目标：

- 把 `govdoc-audit` 裁成当前项目内可调用的纯引擎内核

动作：

- 新建 `govdoc_engine/`
- 迁入 `parser / dsl / engine / reporter / llm`
- 去掉原 `api / storage / web` 依赖
- 改成本项目统一 import 结构
- 规则文件暂放本地规则目录

产出：

- 当前项目内可以本地调用一份 `.docx` 执行公文审查

### 第二期：bridge 接入

目标：

- 接入当前 worker 执行链

动作：

- 新建 `govdoc_bridge/tasks.py`
- 新建 `govdoc_bridge/storage_adapter.py`
- 新建 `govdoc_bridge/result_adapter.py`
- 复用 OSS 下载到本地临时文件
- 复用 Celery 异步执行
- 结果回写 DB + 上传 OSS

产出：

- 当前项目可异步跑公文审查任务

### 第三期：服务与接口接入

目标：

- 正式形成后端模块 API

动作：

- 新增 `govdocController.py`
- 新增 `govdocServiceImpl.py`
- 接入 JWT
- 接入地区隔离
- 接入上传、列表、详情、运行状态、报告下载

产出：

- 前端可以通过当前后端 API 正式使用公文模块

### 第四期：前端模块接入

目标：

- 当前平台页面可用

动作：

- 新增侧边栏模块
- 新增上传页、列表页、详情页
- 详情页展示：
  - 分数
  - findings
  - entities
  - 原文段落联动
  - HTML / DOCX 报告下载
- 接入权限控制

产出：

- 用户可在当前平台直接使用“内部公文处理”

### 第五期：平台化收口

目标：

- 进入长期可维护状态

动作：

- 规则版本化
- 报告产物统一 OSS
- 文件转换 / 解析隔离执行
- LLM / OCR 白名单与审计
- 指标监控
- 错误告警
- 运行留痕

产出：

- 模块正式生产可用

---

## 8. 推荐目录结构

```text
fastapi_modules/fastapi_leaudit/
  controllers/
    govdocController.py

  services/
    govdocService.py
    impl/
      govdocServiceImpl.py

  govdoc_bridge/
    __init__.py
    tasks.py
    runner.py
    input_resolver.py
    rules_resolver.py
    storage_adapter.py
    result_adapter.py
    report_adapter.py
    security_guard.py

  govdoc_engine/
    __init__.py
    models.py
    pipeline.py
    parser/
    dsl/
    engine/
    reporter/
    llm/

  models/
    govdocRun.py
    govdocRuleResult.py
    govdocEntity.py
    govdocReportArtifact.py
    govdocRuleSet.py
    govdocRuleVersion.py
```

文档与 SQL：

```text
docs/内部公文模块/
  内部公文模块迁移方案.md
  内部公文模块数据表复用与新增建议.md

scripts/创建sql/
  schema_add_govdoc_module.sql
  seed_govdoc_permissions.sql
  seed_govdoc_entry_module.sql
```

---

## 9. 最终建议

最优方案不是：

- 保留 `govdoc-audit` 为独立服务
- 当前平台只做代理壳

而应该是：

- 把 `govdoc-audit` 裁成 `govdoc_engine`
- 通过 `govdoc_bridge + Celery + OSS + RBAC + 地区隔离`
- 正式并入 `leaudit-platform`

最终形成：

- 平台共享底座
- 模块独立结果域
- 前后端统一接入
- 规则、报告、运行态统一纳入当前项目

这是最稳、最适合长期维护的一条路。