CategorizeLabel/README.md

# 产品分类模块（CategorizeLabel）

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-77%20passed-green.svg)](tests/)
[![Code Style](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/)

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

## ✨ 特性

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

## 📋 快速开始

### 1. 安装依赖

```bash
# 使用Poetry（推荐）
poetry install

# 或使用pip
pip install -e .
```

### 2. 配置API Key

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

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

### 3. 编辑配置文件

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

```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. 运行分类

```bash
# 使用默认配置文件
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 - 任务完成，开始下载结果
```

实时日志可以帮助您：
- ✅ 了解任务是否正在正常运行
- ✅ 预估任务完成时间
- ✅ 及时发现并处理错误

详细说明请参考 [进度日志功能说明](docs/进度日志功能说明.md)

## 📚 文档

- [使用说明](docs/使用说明.md) - 详细的使用指南
- [进度日志功能](docs/进度日志功能说明.md) - 实时进度反馈功能说明（新增）
- [测试报告](docs/测试报告.md) - 完整的测试覆盖报告
- [架构设计](docs/project_docs/产品分类模块架构设计.md) - 详细的架构设计文档
- [功能设计](docs/project_docs/产品分类模块功能设计.md) - 功能需求文档
- [API文档](docs/API/Tongyi-API.md) - 通义千问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             # 项目配置
```

## 🧪 运行测试

```bash
# 运行所有测试
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)
```json
{"category":"门票","type":"自然类","sub_type":"自然风光"}
{"category":"住宿","type":"商务酒店","sub_type":""}
```

### 输出：分类结果 (JSONL)
```json
{"product_id":"P001","category":"门票","type":"自然类","sub_type":"自然风光"}
{"product_id":"P002","category":"住宿","type":"商务酒店","sub_type":""}
```

## 💡 使用场景

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

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

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

## 👥 开发团队

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

---

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