# 存储架构说明

## 架构概述

本项目采用 **RustFS (S3兼容)** 作为对象存储和 **PostgreSQL** 作为元数据存储的双层存储架构。

```
┌─────────────────────────────────────────────────────────────┐
│                     应用层 (FastAPI)                    │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                              │
┌───────▼────────┐        ┌─────────▼─────────┐
│   PostgreSQL    │        │     RustFS/S3     │
│   (元数据)      │        │   (对象存储)       │
│                │        │                  │
│ - users        │        │ - stp-files      │
│ - stp_files    │        │ - geometry       │
│ - geometry_data│        │ - mold-cavities │
│ - mold_cavity  │        │ - html-files     │
│ - features     │        │ - user-files     │
│ - logs        │        │                  │
└────────────────┘        └──────────────────┘
```

## PostgreSQL 数据表

### 用户管理
- `users` - 用户信息（用户名、邮箱、密码等）

### 文件管理
- `stp_files` - STP文件元数据（文件名、哈希、大小、状态等）
- `html_files` - HTML报告文件元数据

### 几何数据
- `geometry_data` - 几何分析数据（体积、表面积、边界框等）
- `mold_cavity_data` - 模具型腔数据（工艺参数、质量评估等）
- `feature_detections` - 特征检测结果（壁厚、拔模角等）
- `design_recommendations` - 设计建议（优先级、参数等）

### 任务和日志
- `processing_tasks` - 处理任务记录
- `user_activities` - 用户活动日志
- `system_logs` - 系统日志

## RustFS 存储桶

| 存储桶名称 | 用途 | 存储内容 |
|-------------|------|---------|
| `moldinsight-stp-files` | STP/STEP文件 | 用户上传的原始3D模型文件 |
| `moldinsight-geometry` | 几何数据 | 几何分析结果的JSON数据 |
| `moldinsight-mold-cavities` | 模具型腔数据 | 模具设计的详细JSON数据 |
| `moldinsight-html` | HTML文件 | 生成的HTML报告文件 |
| `moldinsight-user-files` | 用户文件 | 其他用户上传的文件 |

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动 PostgreSQL

使用 Docker Compose（推荐）：
```bash
docker-compose up -d postgres
```

或手动启动：
```bash
# 创建数据库
createdb moldinsight

# 运行数据库容器
docker run -d \
  --name postgres \
  -e POSTGRES_DB=moldinsight \
  -e POSTGRES_USER=moldinsight_user \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  postgres:15
```

### 3. 启动 MinIO

使用 Docker Compose（推荐）：
```bash
docker-compose up -d minio
```

或手动启动：
```bash
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"
```

### 4. 配置环境变量

```bash
# 复制示例配置
cp .env.example .env

# 编辑 .env 文件，修改数据库和MinIO配置
nano .env
```

### 5. 初始化数据库和存储

```bash
# 初始化数据库
python src/database/init_db.py

# 初始化MinIO存储
python src/storage/init_storage.py
```

### 6. 启动服务

```bash
python src/main.py
```

## 使用示例

### 保存STP文件

```python
from services.storage_integration import storage_integration
from database.database import db_manager

async def upload_file(file_path: str):
    async with db_manager.get_session() as session:
        stp_file = await storage_integration.save_stp_file(
            session=session,
            file_path=Path(file_path),
            original_filename="model.stp",
            user_id=1
        )
        print(f"文件已保存，ID: {stp_file.id}")
```

### 保存几何数据

```python
async def save_geometry(stp_file_id: int, geometry_data: dict):
    async with db_manager.get_session() as session:
        geo_data = await storage_integration.save_geometry_data(
            session=session,
            stp_file_id=stp_file_id,
            geometry_json=geometry_data,
            analysis_method="pythonocc"
        )
        print(f"几何数据已保存，ID: {geo_data.id}")
```

### 获取文件数据

```python
async def get_file_data(stp_file_id: int):
    async with db_manager.get_session() as session:
        data = await storage_integration.get_stp_file_with_data(
            session=session,
            stp_file_id=stp_file_id
        )
        
        # 访问几何数据
        geometry = data['geometry_data']
        print(f"体积: {geometry['volume']}")
        print(f"表面积: {geometry['surface_area']}")
        
        # 访问模具型腔数据
        cavity = data['mold_cavity_data']
        print(f"模具材料: {cavity['mold_material']}")
        
        # 访问特征和建议
        for feature in data['features']:
            print(f"特征: {feature['feature_type']}")
```

## 数据清理策略

### MinIO 对象存储
- 设置生命周期策略自动删除旧文件
- 示例：删除30天前的临时文件

### PostgreSQL
- 定期清理已删除用户的记录
- 归档超过6个月的日志数据

## 监控和维护

### 检查存储使用情况
```bash
# MinIO控制台
# http://localhost:9001
# 用户名: minioadmin
# 密码: minioadmin
```

### 数据库备份
```bash
# 备份数据库
pg_dump -h localhost -U moldinsight_user moldinsight > backup.sql

# 恢复数据库
psql -h localhost -U moldinsight_user moldinsight < backup.sql
```

## 性能优化

### PostgreSQL
- 创建适当的索引（已在模型中定义）
- 定期运行 VACUUM 和 ANALYZE
- 考虑使用连接池（已配置）

### MinIO
- 启用缓存层
- 配置CDN分发静态文件
- 使用多区域复制

## 安全建议

1. **更改默认密码**：生产环境必须更改所有默认密码
2. **启用TLS**：生产环境启用 HTTPS
3. **访问控制**：配置适当的用户权限
4. **数据加密**：敏感数据加密存储
5. **定期备份**：设置自动备份策略

## 故障排除

### 连接MinIO失败
```
错误: 对象存储连接失败
解决: 检查 MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY 配置
```

### 数据库连接失败
```
错误: 数据库连接失败
解决: 检查 DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD 配置
```

### 文件上传失败
```
错误: STP文件上传失败
解决: 检查磁盘空间、网络连接、MinIO权限
```