bidmaster-cli/ARCHITECTURE.md

# BidMaster-CLI 架构与编码规范

## 一、项目架构设计

### 1.1 分层架构
```
项目采用三层架构，严格分离关注点：

1. CLI层 (Interface Layer)
   - 负责命令解析和用户交互
   - 使用Click框架构建

2. Agent层 (Orchestration Layer)
   - 使用LangGraph编排三个Agent
   - Analysis Agent: 文档解析
   - Generation Agent: 内容生成
   - Assembly Agent: 文档组装

3. 工具层 (Tooling Layer)
   - 原子化工具函数
   - RAG检索、文档处理、表格生成
```

### 1.2 目录结构规范
```
bidmaster-cli/
├── src/
│   └── bidmaster/
│       ├── cli/            # 命令行接口 (≤8个文件)
│       ├── agents/         # Agent逻辑 (≤8个文件)
│       ├── tools/          # 工具函数 (≤8个文件)
│       ├── models/         # 数据模型
│       ├── config/         # 配置管理
│       └── utils/          # 公共工具
├── tests/                  # 测试文件
│   ├── unit/
│   └── integration/
├── templates/             # Word模板文件
├── data/                  # 数据存储
└── config/                # 配置文件
```

## 二、编码规范

### 2.1 代码风格
```python
# 强制使用工具链
- Black: 代码格式化 (line-length=88)
- Ruff: 代码检查 (E, F, I, N, UP规则)
- isort: 导入排序 (profile=black)
- mypy: 类型检查 (strict模式)
```

### 2.2 命名规范
```python
# 类名: PascalCase
class WordProcessor:
    pass

# 函数/变量: snake_case
def parse_document(file_path: Path) -> dict:
    result_data = {}

# 常量: UPPER_CASE
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT = 30

# 私有成员: 单下划线前缀
def _internal_method():
    pass
```

### 2.3 类型注解
```python
# 100%类型覆盖，使用Python 3.11+语法
from typing import Optional
from pathlib import Path

def process_file(
    file_path: Path,
    encoding: str = "utf-8"
) -> dict[str, Any]:
    """所有公共函数必须有类型注解"""
    pass
```

## 三、核心开发原则

### 3.1 错误处理
```python
# 立即失败原则，不使用静默处理或后备方案
class BidMasterError(Exception):
    """基础异常类"""

# 错误必须明确抛出
if not file_path.exists():
    raise FileNotFoundError(f"文件不存在: {file_path}")

# 禁止吞没异常
# 错误的做法：
try:
    process()
except:
    pass  # 禁止！

# 正确的做法：
try:
    process()
except SpecificError as e:
    logger.error(f"处理失败: {e}")
    raise  # 重新抛出
```

### 3.2 配置管理
```python
# 使用Pydantic Settings
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # 配置分三层：默认值、配置文件、环境变量
    api_key: str  # 敏感信息只从环境变量读取
    model_name: str = "gpt-4"
    chunk_size: int = 1000

    class Config:
        env_file = ".env"
        env_prefix = "BIDMASTER_"

# 单例模式
settings = Settings()
```

### 3.3 日志规范
```python
import logging

# 分级日志
logger = logging.getLogger(__name__)

# 统一日志格式
formatter = logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 正确使用日志级别
logger.debug("调试信息")
logger.info("正常流程")
logger.warning("警告信息")
logger.error("错误信息")
```

## 四、代码质量保证

### 4.1 Pre-commit配置
```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black
    hooks:
      - id: black
  - repo: https://github.com/charliermarsh/ruff-pre-commit
    hooks:
      - id: ruff
  - repo: https://github.com/pycqa/isort
    hooks:
      - id: isort
```

### 4.2 测试规范
```python
# 使用pytest
import pytest

# 测试文件命名: test_*.py
# 测试函数命名: test_*

@pytest.fixture
def sample_data():
    """测试固件"""
    return {"key": "value"}

def test_parse_document(sample_data):
    """测试用例必须有明确断言"""
    result = parse(sample_data)
    assert result is not None
    assert "key" in result
```

### 4.3 文档规范
```python
def calculate_score(
    data: dict[str, float],
    weights: dict[str, float]
) -> float:
    """计算加权分数

    Args:
        data: 原始数据字典
        weights: 权重字典

    Returns:
        加权后的总分

    Raises:
        ValueError: 当数据和权重键不匹配时
    """
    pass
```

## 五、依赖管理

### 5.1 使用uv管理依赖
```toml
# pyproject.toml
[project]
name = "bidmaster-cli"
requires-python = ">=3.11"

[project.dependencies]
# 只包含必要依赖
chromadb = ">=1.1.0"
click = ">=8.3.0"
langchain = ">=0.3.27"
langgraph = ">=0.6.7"
pydantic-settings = ">=2.10.1"
python-docx = ">=1.2.0"

[project.optional-dependencies]
dev = [
    "black>=25.9.0",
    "ruff>=0.13.1",
    "pytest>=8.4.2",
    "mypy>=1.5.0"
]
```

## 六、运维考虑

### 6.1 版本管理
- 使用语义化版本号 (MAJOR.MINOR.PATCH)
- Git分支策略: main + develop + feature/*

### 6.2 性能监控
- 关键操作添加耗时日志
- 内存使用监控
- 向量数据库定期维护

### 6.3 数据安全
- API密钥等敏感信息环境变量管理
- 定期备份向量数据库
- 日志不记录敏感信息

这套规范确保代码质量、可维护性和团队协作效率。