产品分类模块（CategorizeLabel）

基于通义千问LLM的产品自动分类工具，采用整洁架构设计，支持批量处理。

✨ 特性

• 🚀 批量处理：使用通义千问Batch API，费用仅为实时调用的50%
• 🏗️ 整洁架构：遵循Clean Architecture和SOLID原则
• ✅ 完整测试：77个单元测试，100%通过率
• 📦 易于使用：简单的命令行接口
• 📊 详细日志：完整的运行日志记录
• 📈 实时进度：实时显示任务处理进度和状态（新增）
• 🔧 可扩展：基于接口编程，易于扩展和维护

📋 快速开始

1. 安装依赖

# 使用Poetry（推荐）
poetry install

# 或使用pip
pip install -e .

2. 配置API Key

# Windows PowerShell
$env:DASHSCOPE_API_KEY="your-api-key-here"

# Linux/Mac
export DASHSCOPE_API_KEY="your-api-key-here"

3. 编辑配置文件

编辑 config/config.yaml，设置你的参数：

files:
  input_file: "input/product_list.xlsx"
  category_file: "config/product_type.jsonl"
  output_file: "output/classification_result.jsonl"

api:
  model: "qwen-flash"

4. 运行分类

# 使用默认配置文件
python -m src.main

# 或指定自定义配置
python -m src.main --config config/my_config.yaml

# 或使用命令行参数覆盖配置
python -m src.main --model qwen-plus

5. 监控任务进度 ⚡️新增

程序运行时会实时显示任务处理进度：

2025-10-15 14:30:00 - INFO - 等待Batch任务完成（系统将定期查询并输出进度信息）...
2025-10-15 14:30:00 - INFO - 开始轮询Batch任务状态（轮询间隔: 60秒）
2025-10-15 14:30:05 - INFO - [轮询 #1] 任务状态: in_progress | 已等待: 5秒 | 剩余时间: 23小时59分55秒
2025-10-15 14:30:05 - INFO -   ↳ 处理进度: 45/100 (45.0%) | 失败: 0
2025-10-15 14:31:05 - INFO - [轮询 #2] 任务状态: in_progress | 已等待: 1分5秒 | 剩余时间: 23小时58分55秒
2025-10-15 14:31:05 - INFO -   ↳ 处理进度: 78/100 (78.0%) | 失败: 2
2025-10-15 14:32:05 - INFO - [轮询 #3] 任务状态: completed | 已等待: 2分5秒
2025-10-15 14:32:05 - INFO - 任务完成，开始下载结果

实时日志可以帮助您：

• ✅ 了解任务是否正在正常运行
• ✅ 预估任务完成时间
• ✅ 及时发现并处理错误

详细说明请参考 进度日志功能说明

📚 文档

• 使用说明 - 详细的使用指南
• 进度日志功能 - 实时进度反馈功能说明（新增）
• 测试报告 - 完整的测试覆盖报告
• 架构设计 - 详细的架构设计文档
• 功能设计 - 功能需求文档
• API文档 - 通义千问API使用教程

🏗️ 项目结构

CategorizeLabel/
├── src/                        # 源代码
│   ├── core/                   # 核心实现层
│   │   ├── file_handler.py    # 文件处理
│   │   ├── batch_client.py    # Batch API客户端
│   │   └── prompt_builder.py  # Prompt构建
│   ├── models.py              # 数据模型
│   ├── interfaces.py          # 抽象接口
│   └── main.py                # 主程序入口
├── tests/                      # 单元测试（77个测试）
│   ├── fixtures/              # 测试数据
│   ├── test_models.py         # 22个测试
│   ├── test_file_handler.py   # 20个测试
│   ├── test_batch_client.py   # 15个测试
│   ├── test_prompt_builder.py # 11个测试
│   └── test_main.py           # 9个测试
├── config/                     # 配置文件
├── input/                      # 输入文件目录
├── output/                     # 输出文件目录
├── logs/                       # 日志目录
├── docs/                       # 文档
└── pyproject.toml             # 项目配置

🧪 运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试
pytest tests/test_models.py -v

# 查看测试覆盖率
pytest tests/ --cov=src --cov-report=html

测试结果：77/77 测试通过 ✨

🎯 设计原则

本项目严格遵循以下设计原则：

• 整洁架构（Clean Architecture）：依赖倒置，核心业务逻辑不依赖外部实现
• SOLID原则：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
• 测试驱动开发（TDD）：先写测试，再实现功能
• 依赖注入：通过构造函数注入依赖，便于测试和替换

📊 架构概览

┌─────────────────────────────────────────────┐
│              main.py (组合根)                │
│      初始化所有依赖并编排业务流程              │
└─────────────────────────────────────────────┘
                    ↓
    ┌───────────────┴───────────────┐
    │                               │
    ↓                               ↓
┌─────────┐                   ┌─────────┐
│  core/  │ ←─ interfaces ─→  │ models  │
└─────────┘                   └─────────┘
    │
    ├── FileHandler      (文件处理)
    ├── BatchClient      (API调用)
    └── PromptBuilder    (Prompt构建)

🔧 技术栈

• Python 3.9+
• Pydantic V2：数据验证和模型
• pandas：Excel文件处理
• OpenAI SDK：通义千问API调用
• pytest：单元测试框架
• Poetry：依赖管理

📝 输入输出格式

输入：产品列表 (Excel)

产品编号 | 产品名称        | 景区名称
P001    | 黄山风景区门票   | 黄山
P002    | 黄山温泉酒店     | 黄山

输入：类别配置 (JSONL)

{"category":"门票","type":"自然类","sub_type":"自然风光"}
{"category":"住宿","type":"商务酒店","sub_type":""}

输出：分类结果 (JSONL)

{"product_id":"P001","category":"门票","type":"自然类","sub_type":"自然风光"}
{"product_id":"P002","category":"住宿","type":"商务酒店","sub_type":""}

💡 使用场景

• ✅ 旅游产品自动分类
• ✅ 电商商品分类
• ✅ 内容标签化
• ✅ 大规模数据标注

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

请遵守通义千问API的使用协议。

👥 开发团队

采用AI辅助开发，遵循专业的软件工程实践。

---

项目状态：✅ 开发完成，所有测试通过，可用于生产环境