Hugging Face's logo

Spaces:
jun2024
/
fc
Paused

App Files Community
fc / apps /documents /services /REFACTORING_PLAN.md
jun2024's picture
jun2024
Upload 2241 files
b4f2238 verified
preview code
|
Raw History Blame Contribute Delete
11.9 kB

Documents Services 重构规划

一、当前状态分析

1.1 目录结构概览 

services/ (共50个文件)
├── 根目录散落文件: 30个
│   ├── evidence_service.py
│   ├── evidence_query_service.py
│   ├── evidence_admin_service.py
│   ├── evidence_export_service.py
│   ├── evidence_storage.py
│   ├── evidence_list_placeholder_service.py
│   ├── placeholder_service.py
│   ├── placeholder_admin_service.py
│   ├── placeholder_usage_service.py
│   ├── template_service.py
│   ├── template_matching_service.py
│   ├── document_template_query_service.py
│   ├── document_template_admin_service.py
│   ├── document_template_dto_assembler.py
│   ├── contract_template_query_service.py
│   ├── contract_template_binding_service.py
│   ├── folder_template_admin_service.py
│   ├── folder_service.py
│   ├── generation_service.py
│   ├── pdf_utils.py
│   ├── pdf_merge_service.py
│   ├── pdf_merge_utils.py
│   ├── wiring.py
│   └── ...
│
├── 子文件夹: 6个 (共74个文件)
│   ├── generation/         (18个)
│   ├── placeholders/       (28个)
│   ├── document_template/  (7个)
│   ├── folder_template/    (9个)
│   ├── evidence/          (5个)
│   └── external_template/ (4个)

1.2 问题诊断

问题类型 具体表现 影响
职责分散 evidence 相关功能散落在根目录和 evidence/ 文件夹 难以定位和维护
层级不一致 模板相关服务有 document_template/ 和 folder_template/，但 contract_template_query_service.py 在根目录 违反单一职责
命名冗余 evidence_service.py 和 evidence/evidence_mutation_service.py 并存 功能边界不清
辅助工具散落 pdf_utils.py, wiring.py 等基础设施在根目录 基础设施未归类

二、重构目标

  1. 统一组织逻辑: 按业务模块分包，不再散落
  2. 消除冗余: 合并功能重复的文件
  3. 保持兼容: 通过 __init__.py 导出确保现有导入不变
  4. 提升可维护性: 让目录结构直观反映业务领域

三、具体重构方案

3.1 目标目录结构 

services/
├── evidence/                    # 证据模块（整合）
│   ├── __init__.py              # 合并导出
│   ├── evidence_service.py     # 从根目录移入
│   ├── evidence_query_service.py
│   ├── evidence_admin_service.py
│   ├── evidence_export_service.py
│   ├── evidence_storage.py
│   ├── evidence_list_placeholder_service.py
│   └── evidence/                # 保留原子文件夹
│       ├── __init__.py
│       ├── evidence_file_service.py
│       ├── evidence_mutation_service.py
│       ├── evidence_query_service.py
│       ├── evidence_merge_usecase.py
│       └── page_range_calculator.py
│
├── placeholders/                # 占位符模块（已有结构）
│   ├── __init__.py              # 新增根目录导出
│   ├── placeholder_service.py  # 从根目录移入
│   ├── placeholder_admin_service.py
│   ├── placeholder_usage_service.py
│   ├── base.py
│   ├── registry.py
│   ├── types.py
│   ├── context_builder.py
│   └── authorization_materials/ ...
│   └── basic/ ...
│   └── case/ ...
│   └── contract/ ...
│   └── lawyer/ ...
│   └── litigation/ ...
│   └── party/ ...
│   └── supplementary/ ...
│
├── template/                    # 模板模块（整合）
│   ├── __init__.py
│   ├── template_service.py     # 从根目录移入
│   ├── template_matching_service.py
│   ├── template_audit_log_service.py
│   ├── document_template/      # 保留
│   │   ├── __init__.py
│   │   ├── repo.py
│   │   ├── query_service.py    # 从根目录移入
│   │   ├── admin_service.py     # 从根目录移入
│   │   ├── dto_assembler.py    # 从根目录移入
│   │   └── ...
│   ├── folder_template/        # 保留
│   │   ├── __init__.py
│   │   ├── admin_service.py    # 从根目录移入
│   │   └── ...
│   └── contract_template/
│       ├── __init__.py
│       ├── query_service.py    # 从根目录移入
│       └── binding_service.py  # 从根目录移入
│
├── generation/                  # 文档生成模块（已有结构）
│   ├── __init__.py
│   ├── generation_service.py   # 从根目录移入
│   └── ...
│
├── infrastructure/              # 基础设施模块（新建）
│   ├── __init__.py
│   ├── pdf_utils.py           # 从根目录移入
│   ├── pdf_merge_utils.py     # 从根目录移入
│   ├── pdf_merge_service.py   # 从根目录移入
│   ├── wiring.py              # 从根目录移入
│   └── path_utils.py          # 建议从 generation/ 移入
│
└── code_placeholders/           # 代码占位符模块（整合）
    ├── __init__.py
    ├── registry.py            # 从根目录移入
    ├── catalog_service.py     # 从根目录移入
    ├── autodiscover.py        # 从根目录移入
    └── adapter.py             # prompt_version_service_adapter.py 重命名

3.2 文件移动清单

移动到 evidence/

原路径 新路径 备注
evidence_service.py evidence/evidence_service.py
evidence_query_service.py evidence/evidence_query_service.py 与子文件夹内重名，需合并
evidence_admin_service.py evidence/evidence_admin_service.py
evidence_export_service.py evidence/evidence_export_service.py
evidence_storage.py evidence/evidence_storage.py
evidence_list_placeholder_service.py evidence/evidence_list_placeholder_service.py

移动到 placeholders/

原路径 新路径 备注
placeholder_service.py placeholders/placeholder_service.py
placeholder_admin_service.py placeholders/placeholder_admin_service.py
placeholder_usage_service.py placeholders/placeholder_usage_service.py

移动到 template/

原路径 新路径 备注
template_service.py template/template_service.py
template_matching_service.py template/template_matching_service.py
template_audit_log_service.py template/template_audit_log_service.py
document_template_query_service.py template/document_template/query_service.py
document_template_admin_service.py template/document_template/admin_service.py
document_template_dto_assembler.py template/document_template/dto_assembler.py
folder_template_admin_service.py template/folder_template/admin_service.py
contract_template_query_service.py template/contract_template/query_service.py
contract_template_binding_service.py template/contract_template/binding_service.py

移动到 infrastructure/

原路径 新路径 备注
pdf_utils.py infrastructure/pdf_utils.py
pdf_merge_utils.py infrastructure/pdf_merge_utils.py
pdf_merge_service.py infrastructure/pdf_merge_service.py
wiring.py infrastructure/wiring.py

移动到 code_placeholders/

原路径 新路径 备注
code_placeholder_registry.py code_placeholders/registry.py
code_placeholder_catalog_service.py code_placeholders/catalog_service.py
code_placeholder_autodiscover.py code_placeholders/autodiscover.py
prompt_version_service_adapter.py code_placeholders/adapter.py

移动到 generation/

原路径 新路径 备注
generation_service.py generation/generation_service.py

移动到根目录（保留 `folder_service.py）

-` - 文件夹服务（业务逻辑较独立）

  • document_service_adapter.py - 外部适配器（需要保持在根目录供外部调用）

四、兼容性保障

4.1 使用 init.py 维持向后兼容

在每个模块的 __init__.py 中重新导出原有路径的类/函数，确保以下导入方式仍然有效：

# 旧导入方式（保持兼容）
from apps.documents.services import EvidenceService
from apps.documents.services import PlaceholderService

# 新导入方式（推荐）
from apps.documents.services.evidence import EvidenceService
from apps.documents.services.placeholders import PlaceholderService

4.2 兼容性导出示例 

# services/evidence/__init__.py
from .evidence_service import EvidenceService
from .evidence_query_service import EvidenceQueryService
from .evidence_admin_service import EvidenceAdminService

__all__ = [
    "EvidenceService",
    "EvidenceQueryService", 
    "EvidenceAdminService",
    # 兼容旧导入
]

五、实施步骤

阶段一：创建新目录结构（无风险）

  1. 创建 template/ 目录
  2. 创建 template/document_template/, template/folder_template/, template/contract_template/ 子目录
  3. 创建 infrastructure/ 目录
  4. 创建 code_placeholders/ 目录

阶段二：移动文件并更新导入（低风险）

按模块顺序执行：

  1. 移动 infrastructure/ - 基础设施，依赖最少
  2. 移动 code_placeholders/ - 基础设施之上，依赖较少
  3. 移动 template/ - 模板相关
  4. 移动 evidence/ - 证据相关
  5. 移动 placeholders/ - 占位符相关
  6. 移动 generation/ - 生成相关

每个模块完成后：

  • 更新该模块内的相对导入
  • 更新 __init__.py 导出
  • 运行测试确保功能正常

阶段三：清理与验证（收尾）

  1. 删除不再需要的旧文件
  2. 更新外部调用方的导入路径（可选，保持兼容则跳过）
  3. 运行完整测试套件
  4. 更新相关文档

六、风险评估与缓解

风险 级别 缓解措施
外部调用方导入路径失效 高 使用 __init__.py 保持向后兼容
循环依赖 中 移动前分析依赖图，按正确顺序执行
测试失败 中 每阶段完成后运行测试，及时发现问题
合并冲突 低 使用 IDE 重构功能，避免手动移动

七、预计工作量

阶段 工作内容 预估文件数
阶段一 创建目录 4个目录
阶段二 移动并修复导入 约25个文件
阶段三 清理与验证 -

八、建议执行顺序

  1. 先创建新目录结构（创建空目录和 __init__.py）
  2. 按依赖顺序移动文件：基础设施 → 代码占位符 → 模板 → 证据 → 占位符 → 生成
  3. 每移动一个模块，同时更新该模块的 __init__.py
  4. 保持根目录的 __init__.py 导出所有公共接口
  5. 最后进行清理和验证

附录：依赖关系图（简略） 

infrastructure/          ← 无依赖
    ↑
code_placeholders/       ← 依赖 infrastructure
    ↑
placeholders/            ← 依赖 code_placeholders
    ↑
generation/              ← 依赖 placeholders, infrastructure
    ↑
template/                ← 依赖 placeholders
    ↑
evidence/                ← 依赖 placeholders