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. 后端目录结构建议

建议最终目录结构如下：

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/ 的内容

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

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/

迁入后落到：

fastapi_modules/fastapi_leaudit/govdoc_engine/

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

这些不要直接迁：

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

原因：

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

4.3 旧规则文件建议落点

旧规则文件：

rules/govdoc_general/rules.yaml

短期建议：

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

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. 文档目录落点建议

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

docs/内部公文模块/

建议至少保留：

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

后续还可以继续补：

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

---

10. 前端目录结构建议

前端项目在：

• legal-platform-frontend/

建议新增目录结构类似：

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 持久化

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

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