109 lines
4.6 KiB
Markdown
109 lines
4.6 KiB
Markdown
# 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 换行符，文件末尾保留换行符
|
||
- **中文内容**：绝不修改中文注释或文本。编辑中文附近代码时，完整保留原有中文内容
|