# CLAUDE.md

本文件为 Claude Code（claude.ai/code）在此仓库中工作提供指引。

## 常用命令

```bash
# 安装后端依赖（核心：无需 MySQL、无需 PyTorch）
pip install -e .
pip install -e ".[dev]"       # 含开发工具（pytest, black, mypy）
pip install -e ".[torch]"     # 安装可选 PyTorch（神经网络训练需要）

# 启动后端（Flask，0.0.0.0:5001）
python run.py

# 启动前端开发服务器（另开终端，localhost:3000）
cd frontend && npm install && npm run serve

# 构建前端生产版本
cd frontend && npm run build

# 运行测试
python -m pytest tests/
python -m pytest tests/test_demo_service.py -q   # 单个测试文件
python -m pytest tests/test_demo_routes.py -q

# 代码格式化 / 类型检查
black src/ tests/             # 自动格式化（line-length=88）
mypy src/                     # 类型检查

# 运行独立演示模式（仅需 5 个依赖）
cd demo_standalone && pip install -r requirements.txt && python server.py
```

## 项目概述

基于机器学习的装备成本预测系统。支持两种装备类型：**火箭炮**和**巡飞弹**。

### 技术栈

- **后端**：Python 3.9-3.11, Flask 3.1+
- **数据库**：SQLite（Python 内置，零外部依赖），首次启动自动建表，无需手动安装配置
- **机器学习**：scikit-learn（核心）、XGBoost、LightGBM
- **可选依赖**：PyTorch（仅神经网络训练需要，约 800MB）
- **前端**：Vue 3 (Composition API) + Element Plus + ECharts, 使用 Vite 构建

### 关键文件

| 文件 | 用途 |
|---|---|
| `run.py` | 入口点，启动 Flask 服务器 |
| `src/app.py` | Flask 应用工厂 |
| `src/routes.py` | 所有 API 路由（约 1300 行） |
| `src/model_trainer.py` | ModelTrainer 类 + CostPredictionModel（PyTorch NN） |
| `src/data_preparation.py` | DataPreparation + EquipmentDataset |
| `src/cost_prediction.py` | CostPredictor（预测编排） |
| `src/demo_service.py` | DemoModelService（基于 CSV，无需数据库） |
| `src/database/db_connection.py` | SQLite 数据库连接 + 建表 DDL（内置） |
| `config.py` | 运行时配置 |
| `frontend/src/router/index.js` | Vue Router，共 8 个路由 |
| `frontend/src/api/index.js` | Axios API 客户端 |

## 架构

### 与旧架构的核心变化

| 项目 | 旧架构（MySQL） | 新架构（SQLite） |
|------|----------------|-----------------|
| 数据库 | MySQL 8.0+，需单独安装运行 | SQLite，Python 内置，零依赖 |
| 数据库依赖 | sqlalchemy, pymysql, cryptography, mysql-connector-python | 无（仅用 Python 标准库 sqlite3） |
| PyTorch | 硬依赖（顶层 import，无则崩溃） | 可选依赖（try/except 保护，无 PyTorch 可启动） |
| 前端构建 | Vue CLI + Babel + SCSS | Vite（无需 Babel/SCSS） |
| Vuex | 存在但完全空 | 已移除 |
| 依赖总数（核心）| 15+ | 5（flask, numpy, pandas, scikit-learn, openpyxl） |

### 训练数据流
```
用户界面 → POST /api/train → 查询 SQLite → DataPreparation（特征提取 + 标准化）
→ ModelTrainer.fit_model()（训练 XGBoost, LightGBM, RF, GBM, PyTorch NN, PLS）
→ 保存最优模型 → 写入 SQLite trained_models 表
```

### 预测数据流
```
用户界面 → POST /api/predict → 从 SQLite 加载最优模型 + 标准化器 → 提取特征
→ 特征标准化 → 预测 → ±20% 置信区间 → JSON 返回
```

### 机器学习模型

| 模型 | 标识 | 说明 |
|---|---|---|
| XGBoost | `xgboost` | 针对小数据量使用保守参数 |
| LightGBM | `lightgbm` | 针对小数据量使用保守参数 |
| Random Forest | `rf` | sklearn.ensemble |
| Gradient Boosting | `gbm` | sklearn.ensemble |
| PyTorch NN | `pytorch` | 可选（需安装 torch），针对不同装备类型定制网络结构 |
| PLS 回归 | `pls` | 不参与最优模型评选 |
| Linear/Ridge/SVR/KNN | 仅演示 | 用于算法对比演示 |

## 重要注意事项

- **小数据量机器学习**：所有模型超参数均为保守设置（强正则化、浅树、低学习率、早停）
- **两种装备类型**：火箭炮（27+ 特征）和巡飞弹（24+ 特征），各自有独立数据库表和神经网络结构
- **生产商议价能力特征**：技术等级、规模、供应链、地区等信息被纳入特征，地区成本乘数（如美国 1.2 倍、中国 0.8 倍）
- **SQLite 首次使用**：`data/equipment_cost.db` 文件在首次数据库操作时自动创建，无需手动初始化
- **编码规范**：UTF-8 无 BOM，LF 换行符，文件末尾保留换行符
- **中文内容**：绝不修改中文注释或文本。编辑中文附近代码时，完整保留原有中文内容