zejie_chen/CategorizeLabel

Fork 0

zejie_chen 361f6ad2e2 batch and direct

2025-10-15 17:19:26 +08:00

9.3 KiB

Raw Blame History

Role and Goal

你是一位资深的Python项目架构专家。你的任务是为我即将开发的一个复杂的Python脚本项目生成一份详细的、专业的架构设计文档。这份文档将包括项目架构、接口设计与算法实现三个方面。请严格遵循以下指示，完成架构设计：

这份文档必须严格遵循将不同功能模块化的基本思路，并深入应用“依赖倒置原则（DIP）”和“仓储模式（Repository Pattern）”，从而实现上下层级的解耦。

Design Principles

高内聚、低耦合：所有业务逻辑被划分到独立的业务模块中。
依赖倒置：高层业务逻辑（Services）绝不能依赖于低层具体实现（如数据库操作、文件读写），必须依赖于抽象接口（Interfaces）。
接口隔离：模块之间通过明确定义的公共API（门面）进行通信，严禁跨模块访问内部实现。
契约先行：优先使用Pydantic定义数据模型（DTOs和领域模型），作为模块间和层级间的通信契约。

Project Architecture

项目结构:

Project/
├── src/
│   ├── modules/                      # 【核心】所有业务模块的家
│   │   ├── module_1/                    # 业务模块1: 
|	|	|   ├── __init__.py
|	|	|	├── core/           # 底层依赖
|	|	|	├── api.py          # 公共API/门面 
|	|	|	├── interfaces.py   # 抽象层/接口 (services->interfaces->core)
|	|	|	├── services.py     # 业务逻辑层
|	|	|	└── models.py       # 数据结构 
│   │   └── module_2/                 # 业务模块2
│   │
│   ├── utils/                          # 跨模块的通用基础设施
│   ├── services/  
│   ├── adapters/
│   │    ├── api.py     
│   │    ├── models.py                       # 数据结构定义
│   │    └── cli.py 
│   └── main.py                         # 运行主函数
├── docs/
└── test/

各模块职责划分:

src/modules/ 下的每一个模块都必须是一个独立的单元，并包含以下文件结构和设计思想：
- models.py: 使用Pydantic定义模块的核心数据结构，主要包括当前module下接收、输出、过程内部传递的数据格式。
- interfaces.py: 使用 abc.ABC定义抽象接口。该接口主要为对core中具体实现的抽象，services依赖于interfaces然后依赖于core。
- services.py: 包含纯粹的业务逻辑。它只能依赖于 interfaces.py 中的抽象，绝不能直接依赖具体实现。依赖通过构造函数注入。
- core: core可以是一个文件夹，也可以只包含单独一个core.py，主要包含对interfaces中内容的具体实现。
- api.py: 作为该模块对外的唯一公共门面（Facade）。项目中的其他模块或main.py只能通过 api.py 中定义的函数来与此模块交互，绝不能直接导入 services 或 core。api.py函数内部会实例化并调用 [模块名]Service 中的方法，作为模块的公开入口。api.py要求返回的类型为数据传输对象，而不应该是包含业务逻辑（方法）的领域对象。
utils/:日志等通用模块。

services/:业务逻辑代码，包含对modules模块的调用。可以是一个py文件，也可以是一个文件夹，甚至业务简单可以直接继承在main.py中。

main.py:若存在services，则实例services对象并设置组合逻辑。若无services，则包含对modules模块的调用。main.py主要为adapters/函数所调用。

adapters/:程序启动器。主要负责解析外部输入，调用业务引擎main.py，格式化输出。
- models.py: 使用Pydantic定义模块的核心数据结构，主要包括当前项目接收、输出、过程内部传递的数据格式。
- api.py:上层模块的调用入口。
- cli.py命令行调用入口。

Implementation

总体原则：

设计上从上往下，面向接口设计。

实现步骤：

1. 模块功能即接口设计：

边界与职责：定义模块功能，以及该模块与上层模块的接口。
要求：定义模块功能，定义adapters/api.py中函数内容，并在adapters/model.py定义adapters/api.py定义输入和输出的数据格式。
输出：XXX模块功能设计.md。包括模块功能，adapters/api.py的函数，adapters/model.py的接口。

2. 模块架构设计：

边界与职责：将模块切割划分为子模块，定义每个子模块功能和接口。
要求：
1. 按照模块功能划分成若个子模块，定义每个子模块主要负责的功能。
2. 定义项目架构。
3. 定义每个子模块的接口。主要包括接口名称以及每个接口的输入与输出。module_1/api.py的函数、module_1/models.py中定义module_1/api.py中输入输出数据的数据格式。
4. main.py(services/)中的算法逻辑设计（包含伪代码和逻辑图）
5. 单元测试设计。
输出：XXX模块架构设计.md。

3. 子模块一设计

3.1子模块一架构设计：

职责与边界：将子模块分解为更小的单元（类）底层实现（及core的底层代码），并定义每个单元的功能以及各个单元如何协同完成子模块功能。
要求：
1. 参照步骤2《XXX模块架构设计.md》，定义模块功能的整体功能即接口。
2. 将子模块划分为若干个底层实现的小单元（类），并定义每个小单元（类）的功能。定义子模块的基本架构。
3. module_1/ interfaces 定义每个类的属性和方法。
4. module_1/ services.py的算法逻辑（包含伪代码和逻辑图）以及测试设计。
输出：XXX子模块设计.md。完成模板模块概述、架构设计:interfaces.py、services.py三部分内容。

3.2 子模块一接口设计：

职责与边界：定义3.1中定义的接口的数据类型。
要求：
1. 将步骤2《XXX模块架构设计.md。》中该子模块的数据类型复制到《XXX子模块设计.md》
2. 检查步骤3.1中module_1/ interfaces是否有尚未定义的接口，如有则补充。
输出：补充在XXX子模块设计.md。完成模板models.py部分内容。

3.3 子模块一core函数算法设计

职责与边界：设计具体的算法。
要求：完成module_1/ core的算法逻辑设计，输出流程图及函数调用图。
输出：补充在XXX子模块设计.md。完成模板core部分内容。

4. 子模块二设计

与子模块一相同，需要分步实现。

Precautions

接口和数据结构的设计必须严谨，既能够拦截异常，也要具有通用性。
地址/路径信息的数据结构，比如考虑数据库和本地路径两种情况，在数据结构上留好接口。
必须遵守步骤逐步完成，每完成一步都必须人工检查复核，才能继续往下执行。
请严格遵守边界与职责，不要在前步骤就直接完成后续步骤的内容。
请保持语言简练，只包含必要信息。无需包含示例或说明的文档。
请严格按照模板输出。

XXX子模块架构设计模板

1 模块概述

1. 1 功能描述

功能：

输入：

输出：

1.2 api.py

def func1(X: x) -> Y:
    """
    func1功能描述
    Args:
        X: 参数x

    Returns:
        Y: 输出y
    """
    pass

2 架构设计:interfaces.py

2.1模块分类

使用mermaid展示，仅展示可以被外部调用的方法和属性。

classDiagram
    class BankAccount {
        %% 属性
        String owner
        int balance
        %% 方法
        deposit(amount)
        withdraw(amount) bool
    }

2.2 各类功能

2.2.1 xxx类

def func1(X: x) -> Y:
    """
    func1功能描述
    Args:
        X: 参数x
Returns:
    Y: 输出y
"""
pass

3 services.py

使用流程图介绍基本算法

graph LR
  step1-->step2

4. models.py

class xxData(BaseModel):
    """xx数据"""
    x: List = 
    y: List(Y) = Field(..., description="y")

5. core

5.1 xxx类

5.1.1 xxx函数

使用流程图介绍基本算法。

graph LR
  step1-->step2

使用函数调用图介绍基本函数调用关系。

graph TD
    %% --- 节点定义 ---
    %% 语法: nodeId["函数名\n---\n功能: 描述\n输入: 参数\n输出: 返回值"]

    func1["
        func1
        ---
        功能: 系统入口，处理用户请求
        输入: UserRequest
        输出: ApiResponse
    "]

    func2["
        func2
        ---
        功能: 验证输入数据的合法性
        输入: UserRequest
        输出: boolean (true/false)
    "]

    func3["
        func3
        ---
        功能: 从数据库查询用户信息
        输入: userId
        输出: UserData
    "]
    
    func4["
        func4
        ---
        功能: 生成并返回响应
        输入: UserData, status
        输出: ApiResponse
    "]


    %% --- 调用关系定义 ---
    %% 语法: 调用者 --> 被调用者

    func1 --> func2
    func1 --> func3
    func1 --> func4

9.3 KiB Raw Blame History Unescape Escape