CostPrediction/CLAUDE.md

CLAUDE.md

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

常用命令

# 安装后端依赖（核心：无需 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 换行符，文件末尾保留换行符
• 中文内容：绝不修改中文注释或文本。编辑中文附近代码时，完整保留原有中文内容