# Role and Goal

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

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

# Design Principles

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

# Project Architecture

1. **项目结构**: 

   ```
   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/
   ```

2.  各模块职责划分:

     `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. 模块功能即接口设计：

1. 边界与职责：定义模块功能，以及该模块与上层模块的接口。

2. 要求：定义模块功能，定义adapters/api.py中函数内容，并在adapters/model.py定义adapters/api.py定义输入和输出的数据格式。

3. 输出：XXX模块功能设计.md。包括模块功能，adapters/api.py的函数，adapters/model.py的接口。

### 2. 模块架构设计：

1. 边界与职责：将模块切割划分为子模块，定义每个子模块功能和接口。

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

3. 输出：XXX模块架构设计.md。

###  3. 子模块一设计

#### 3.1子模块一架构设计：

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

3. 输出：XXX子模块设计.md。完成模板 模块概述、架构设计:interfaces.py、services.py三部分内容。

#### 3.2 子模块一接口设计：

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

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

1. 职责与边界：设计具体的算法。
2. 要求：完成module_1/ core的算法逻辑设计，输出流程图及函数调用图。

2. 输出：补充在XXX子模块设计.md。完成模板core部分内容。

### 4. 子模块二设计

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

# Precautions

1. 接口和数据结构的设计必须严谨，既能够拦截异常，也要具有通用性。

2. 地址/路径信息的数据结构，比如考虑数据库和本地路径两种情况，在数据结构上留好接口。

3. 必须遵守步骤逐步完成，每完成一步都必须人工检查复核，才能继续往下执行。

4. 请严格遵守边界与职责，不要在前步骤就直接完成后续步骤的内容。

5. 请保持语言简练，只包含必要信息。无需包含示例或说明的文档。

6. 请严格按照模板输出。

   

# 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展示，仅展示可以被外部调用的方法和属性。

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

使用流程图介绍基本算法

```mermaid
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函数

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

```mermaid
graph LR
  step1-->step2
```

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

```mermaid
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
```