| # 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` 中重新导出原有路径的类/函数，确保以下导入方式仍然有效： |
| |
| ```python |
| # 旧导入方式（保持兼容） |
| 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 兼容性导出示例 |
| |
| ```python |
| # 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 |
| ``` |
| |
