# Battery_demo

**Repository Path**: Manhattan_coffee/battery_demo

## Basic Information

- **Project Name**: Battery_demo
- **Description**: 电池组自动设计 Demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电池组自动设计 Demo

这是一个 FastAPI 演示项目：根据电池仓尺寸、电压/容量需求和间隙/BMS 预留，自动求解单层电芯排布，并用 CadQuery 导出可编辑 STEP 模型。

## 功能概览
- 内置圆柱电芯数据库（18650/21700，单方案单品牌）
- 电压智能逻辑：按化学体系的行业预设 + 无预设时四舍五入
- 矩形/六边形排布，支持 BMS 体积预留
- STEP 输出（开顶外壳 + 图例铭牌含尺寸信息）+ STL 预览（电芯 + 半透明外壳）+ BOM 文件
- UI 支持方案筛选与多方案对比

## 环境要求
- Python 3.9+
- 依赖：`fastapi`、`uvicorn`、`cadquery`（生成 STEP 必需）

安装：
```bash
pip install fastapi uvicorn cadquery
```

## 快速启动
```bash
uvicorn main:app --reload
```

访问 `http://127.0.0.1:8000/ui` 使用可视化页面，`/docs` 查看交互式文档，也可直接使用 `test_main.http`。
前端依赖已内置于 `static/vendor`，无需外网即可打开 UI。

## 输出说明
- STEP 文件默认写入 `output/` 目录（运行时自动创建）。
- 若提供 `target_capacity_ah`，并联数按满足目标容量的最小值计算；若不提供，则按当前布局可放入的最大并联数计算。
- 响应中包含 `shrink_info`：建议电仓尺寸与缩减量，便于解释空间富余。
- STEP/STL 输出包含正负极耳示意几何体。
- 保护板固定放在电芯上方，电芯与保护板间距为 `collector_clearance_mm`（默认 15mm），保护板与外壳顶部间距为 `top_clearance_mm`（固定 10mm）。
- `auto_shrink_box=true` 时，STEP/STL 外壳会按 `shrink_info` 建议尺寸缩小。
- 若本地未安装 `cadquery`，`/solve` 仍会返回文本方案结果，只是跳过 STEP/STL 导出并给出 warning。

## 项目结构
- `main.py` FastAPI 应用、求解逻辑、CAD 导出
- `test_main.http` 示例请求
- `API.md` 接口说明
- `EXAMPLES.md` 使用实例说明
- `AGENTS.md` 贡献指南
- `static/vendor` 前端离线依赖（Vue / Three.js）
- `data/cells.csv` 电芯数据库（可扩展）

## 备注
- 当前 UI 默认参数已对齐现有电芯库，便于直接演示出方案。
- `chemistry` 控制电压预设表（NMC/LFP/LTO）。非标电压自动回退到四舍五入方案。
- 默认 `wall_gap_mm=10.0`、`gap_mm=0.5`、`top_clearance_mm=10.0`、`tab_thickness_mm=3.0`、`collector_clearance_mm=15.0`（wall/top 固定为 10）。
- 目前仅支持单层（XY 平面）排布。
- 当矩形/六边形排布无法容纳所需电芯数量时，会按顺序尝试侧面堆叠、阶梯式、背靠背、混合方向。