leaudit-platform-backend/docs/内部公文模块/内部公文模块目录结构与代码落点清单.md

# 内部公文模块目录结构与代码落点清单

## 1. 目标

本文档用于把 `govdoc-audit` 迁入当前 `leaudit-platform` 时，明确：

- 模块目录应该放在哪里
- 哪些旧代码要迁
- 哪些当前项目代码要扩展
- 每一层应该承担什么职责
- 第一阶段到第五阶段分别落哪些文件

这份文档不是讲业务方案，而是讲“代码最终应该落到仓库哪里”。

---

## 2. 总体落点原则

迁移后的 `govdoc` 不应再是一个独立系统，而应成为当前仓库中的一个标准业务模块。

总体原则：

- 内核代码进 `fastapi_modules/fastapi_leaudit/govdoc_engine/`
- 平台适配代码进 `fastapi_modules/fastapi_leaudit/govdoc_bridge/`
- 接口代码进 `controllers/`
- 业务编排代码进 `services/impl/`
- ORM 模型进 `models/`
- SQL 进 `scripts/创建sql/`
- 文档进 `docs/内部公文模块/`
- 前端模块进 `legal-platform-frontend/`

---

## 3. 后端目录结构建议

建议最终目录结构如下：

```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
    context_builder.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
```

---

## 4. 旧项目代码迁移落点

旧项目路径：

- `/home/wren-dev/Porject/govdoc-audit/`

### 4.1 建议直接迁入 `govdoc_engine/` 的内容

建议从旧项目迁入这些目录/文件：

```text
src/govdoc_audit/models.py
src/govdoc_audit/pipeline.py
src/govdoc_audit/parser/
src/govdoc_audit/dsl/
src/govdoc_audit/engine/
src/govdoc_audit/reporter/
src/govdoc_audit/llm/
```

迁入后落到：

```text
fastapi_modules/fastapi_leaudit/govdoc_engine/
```

### 4.2 不建议迁入的旧项目内容

这些不要直接迁：

```text
src/govdoc_audit/api/
src/govdoc_audit/storage/
src/govdoc_audit/services/storage_service.py
web/
```

原因：

- API 已由当前平台统一承接
- 存储必须改走当前数据库 + OSS
- 前端要融入当前平台，而不是保留一套独立页面

### 4.3 旧规则文件建议落点

旧规则文件：

```text
rules/govdoc_general/rules.yaml
```

短期建议：

- 先迁到当前仓库本地规则目录，例如：

```text
rules/govdoc/govdoc_general/rules.yaml
```

中期建议：

- 纳入规则版本管理体系
- 上传到 OSS
- 使用 `govdoc_rule_sets` / `govdoc_rule_versions` 控制生效版本

---

## 5. 新增后端文件清单

下面是建议新增的后端文件。

### 5.1 控制器层

新增：

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

职责：

- 上传公文
- 查询公文列表
- 查询文档详情
- 发起审查
- 查询 run 状态
- 查询 findings / entities / reports
- 下载 HTML / DOCX / 原文
- 查询规则清单

同时需要：

- 在 `fastapi_admin/bootstrap_parts/controllers.py` 中注册 `govdocController`

### 5.2 服务接口层

新增：

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

职责：

- 定义 `IGovdocService` 抽象接口

### 5.3 服务实现层

新增：

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

职责：

- 调用文档主档服务
- 创建 `govdoc_runs`
- 编排 worker 执行
- 聚合详情返回前端
- 权限/地区作用域后的结果查询

### 5.4 bridge 层

新增目录：

- `fastapi_modules/fastapi_leaudit/govdoc_bridge/`

建议文件职责如下。

#### `tasks.py`

职责：

- Celery 任务入口
- 抢占 run
- 加载执行上下文
- 调用 `runner.py`

参考现有：

- `fastapi_modules/fastapi_leaudit/leaudit_bridge/tasks.py`

#### `runner.py`

职责：

- 调用 `govdoc_engine.pipeline` 执行完整审查
- 组织执行顺序
- 统一异常转换

#### `input_resolver.py`

职责：

- 从 `leaudit_documents` / `leaudit_document_files` 中定位输入文件
- 从 OSS 下载到本地临时路径
- 附加必要的文件元信息

#### `rules_resolver.py`

职责：

- 解析当前应使用的公文规则版本
- 读取本地规则或从 OSS 下载规则文件
- 校验规则版本可用性

#### `storage_adapter.py`

职责：

- 把 run 状态、结果摘要、规则结果、实体、报告路径写回数据库
- 更新文档处理状态

#### `result_adapter.py`

职责：

- 将 `govdoc_engine` 的原始结果对象映射成数据库模型和前端 VO

#### `report_adapter.py`

职责：

- 处理 HTML、annotated docx、paragraph html、json 结果等产物上传 OSS
- 返回 artifact 清单

#### `context_builder.py`

职责：

- 统一构造一次 run 的执行上下文
- 避免在多个文件中反复拼上下文

#### `security_guard.py`

职责：

- 文件扩展名 / MIME / 大小 / 页数 / 压缩体积 / 临时路径安全校验
- 调用前的执行保护

---

## 6. 建议新增的 ORM 模型文件

建议新增：

- `fastapi_modules/fastapi_leaudit/models/govdocRun.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleResult.py`
- `fastapi_modules/fastapi_leaudit/models/govdocEntity.py`
- `fastapi_modules/fastapi_leaudit/models/govdocReportArtifact.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleSet.py`
- `fastapi_modules/fastapi_leaudit/models/govdocRuleVersion.py`

还需要：

- 更新 `fastapi_modules/fastapi_leaudit/models/__init__.py`

职责建议如下。

### 6.1 `govdocRun.py`

负责：

- 一次公文审查运行记录
- 记录文档、触发人、状态、阶段、得分、摘要、错误信息

### 6.2 `govdocRuleResult.py`

负责：

- 单条规则执行结果
- 记录 rule_id / severity / category / message / location / pass/fail/skipped

### 6.3 `govdocEntity.py`

负责：

- 标题、发文字号、文种、署名、附件、发文机关等实体结果

### 6.4 `govdocReportArtifact.py`

负责：

- HTML 报告、批注 DOCX、段落 HTML、JSON 报告等 OSS 产物索引

### 6.5 `govdocRuleSet.py`

负责：

- 公文规则集定义

### 6.6 `govdocRuleVersion.py`

负责：

- 规则版本与 OSS 路径、sha256、发布态等

---

## 7. 建议扩展的现有后端文件

除了新增文件，还建议扩展这些现有文件。

### 7.1 `fastapi_modules/fastapi_leaudit/models/leauditDocument.py`

建议增加：

- `engineType` / `engine_type`

用途：

- 标识该文档属于 `govdoc` 还是 `leaudit`

### 7.2 `fastapi_modules/fastapi_leaudit/services/impl/documentServiceImpl.py`

建议扩展：

- 上传时支持传入 `engine_type='govdoc'`
- 查询列表时支持按 `engine_type` 过滤
- 详情页聚合时能分发到 `govdoc` 详情构建逻辑

如果不想动太多，也可先由 `govdocServiceImpl` 单独包一层调用文档主档逻辑。

### 7.3 `fastapi_admin/bootstrap_parts/controllers.py`

建议扩展：

- 注册 `govdocController`

### 7.4 `fastapi_modules/fastapi_leaudit/services/impl/rbacAdminServiceImpl.py`

建议扩展：

- 加入 `govdoc:*` 权限种子定义
- 加入 `/govdoc` 路由绑定定义

### 7.5 `fastapi_modules/fastapi_leaudit/services/impl/rbacServiceImpl.py`

建议扩展：

- 为 `/govdoc` 前端入口提供兼容 route blueprint（如果当前系统仍依赖该机制）

---

## 8. SQL 文件落点建议

建议新增以下 SQL 草案文件：

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

职责建议：

### 8.1 `schema_add_govdoc_module.sql`

负责：

- 新增 `govdoc_runs`
- 新增 `govdoc_rule_results`
- 新增 `govdoc_entities`
- 新增 `govdoc_report_artifacts`
- 给 `leaudit_documents` 增加 `engine_type`

### 8.2 `seed_govdoc_permissions.sql`

负责：

- 插入 `govdoc:*:*` 权限点

### 8.3 `seed_govdoc_entry_module.sql`

负责：

- 在入口模块配置中加入 `govdoc`

### 8.4 `seed_govdoc_routes.sql`

负责：

- 加入 `/govdoc` 模块菜单与页面路由绑定

---

## 9. 文档目录落点建议

建议所有迁移文档统一放在：

```text
docs/内部公文模块/
```

建议至少保留：

- `内部公文模块迁移方案.md`
- `内部公文模块数据表复用与新增建议.md`
- `内部公文模块接口与权限设计.md`
- `内部公文模块目录结构与代码落点清单.md`

后续还可以继续补：

- `内部公文模块前端页面设计.md`
- `内部公文模块执行链与安全控制点.md`
- `内部公文模块测试清单.md`

---

## 10. 前端目录结构建议

前端项目在：

- `legal-platform-frontend/`

建议新增目录结构类似：

```text
legal-platform-frontend/
  app/(audit)/govdoc/
    page.tsx
    upload/page.tsx
    list/page.tsx
    detail/[documentId]/page.tsx

  components/govdoc/
    upload-form.tsx
    govdoc-list.tsx
    govdoc-detail.tsx
    findings-panel.tsx
    entity-panel.tsx
    report-toolbar.tsx

  hooks/govdoc/
    useGovdocList.ts
    useGovdocDetail.ts
    useGovdocRun.ts

  lib/api/govdoc/
    client.ts
    types.ts
```

职责建议：

### 10.1 页面层

- 上传页
- 列表页
- 详情页

### 10.2 组件层

- 列表组件
- 详情组件
- findings 面板
- entities 面板
- 报告下载工具栏

### 10.3 hooks 层

- 列表请求
- 详情请求
- run 状态轮询

### 10.4 API 层

- 对接 `/api/v3/govdoc/*`

---

## 11. 第一阶段最小落地文件集

如果先只做一个最小可运行版本，建议第一批先落这些文件：

### 后端

- `controllers/govdocController.py`
- `services/govdocService.py`
- `services/impl/govdocServiceImpl.py`
- `govdoc_bridge/tasks.py`
- `govdoc_bridge/runner.py`
- `govdoc_bridge/input_resolver.py`
- `govdoc_bridge/storage_adapter.py`
- `govdoc_bridge/result_adapter.py`
- `govdoc_engine/`（裁剪内核）
- `models/govdocRun.py`
- `models/govdocRuleResult.py`
- `models/govdocReportArtifact.py`

### SQL

- `schema_add_govdoc_module.sql`
- `seed_govdoc_permissions.sql`

### 前端

- 上传页
- 列表页
- 详情页
- `lib/api/govdoc/client.ts`

这样就可以先跑通：

- 上传
- 发起审查
- 查询 run
- 看结果
- 下载报告

---

## 12. 第二阶段建议补充文件

第二阶段再补：

### 后端

- `models/govdocEntity.py`
- `models/govdocRuleSet.py`
- `models/govdocRuleVersion.py`
- `govdoc_bridge/rules_resolver.py`
- `govdoc_bridge/report_adapter.py`
- `govdoc_bridge/security_guard.py`

### SQL

- `seed_govdoc_entry_module.sql`
- `seed_govdoc_routes.sql`

### 前端

- 规则查看页
- 模块配置页
- 规则版本管理页（如果做）

---

## 13. 与现有 `leaudit_bridge` 的关系

`govdoc_bridge` 不应替换 `leaudit_bridge`，而应与之并行存在。

建议关系：

- `leaudit_bridge` 处理现有评查引擎
- `govdoc_bridge` 处理公文格式审查引擎

共同复用：

- Celery
- OSS
- JWT/RBAC
- 文档主档
- 地区隔离

这样当前平台最终就形成多引擎结构：

- `leaudit`
- `govdoc`
- `rag`（知识库/对话是另一类模块，不完全同构）

---

## 14. 最终建议

如果目标是把 `govdoc-audit` 真正“变成当前项目里的一个模块”，那代码落点必须明确：

- 内核进 `govdoc_engine`
- 平台适配进 `govdoc_bridge`
- 业务编排进 `govdocServiceImpl`
- 对外接口进 `govdocController`
- 运行与结果落 `govdoc_*` 表
- 页面落当前前端 `govdoc` 目录

不要保留成：

- 一个独立 API 项目
- 一个独立前端项目
- 一套独立 SQLite 持久化

那样不叫模块化迁移，只叫外挂系统代理。

当前最稳的落法，就是按本文档这套目录与代码边界执行。