# ods_metric

**Repository Path**: netsesame/ods_metric

## Basic Information

- **Project Name**: ods_metric
- **Description**: ODS EXCEL 处理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: metric
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI + SQLModel Backend

Your Python backend has been successfully rebuilt with FastAPI and SQLModel! 🎉

## What's New

### ✅ Modern Architecture
- **FastAPI**: High-performance async web framework
- **SQLModel**: Type-safe database operations with Pydantic integration
- **Automatic API Documentation**: Interactive docs at `/docs`
- **Type Safety**: Full type hints and validation throughout

### ✅ Project Structure
```
app/
├── main.py              # FastAPI application instance
├── config.py            # Configuration settings
├── database.py          # Database connection & session management
├── models/              # SQLModel database models
│   ├── excel.py         # Excel source & data models
│   ├── resource.py      # Resource & field mapping models
│   └── base.py          # Base model classes
├── api/                 # API route modules
│   ├── excel.py         # Excel upload/processing endpoints
│   ├── resource.py      # Resource management endpoints
│   └── sheet.py         # Sheet operations endpoints
└── services/            # Business logic layer
    ├── excel_service.py # Excel processing logic
    └── resource_service.py
```

### ✅ API Endpoints

#### Excel Operations
- `POST /api/excel/upload` - Upload and process Excel files
- `GET /api/excel/history/index` - Get upload history by month
- `GET /api/excel/history/list/{month}` - Get files for specific month
- `DELETE /api/excel/history/{excel_id}` - Delete Excel source
- `GET /api/excel/load/{excel_id}` - Load Excel data by ID

#### Resource Management
- `POST /api/resource/find` - Find resources by similarity
- `POST /api/resource/save` - Save or update resources
- `POST /api/resource/field-mapping/find` - Find field mappings
- `POST /api/resource/field-mapping/list` - Get field mappings

#### Sheet Operations
- `POST /api/sheet/save` - Save sheet data
- `GET /api/sheet/{sheet_id}` - Get sheet by ID

## How to Run

### 1. Install Dependencies
```bash
pip install -r requirements.txt
```

### 2. Configure Database (Optional)
Edit `app/config.py` or set environment variable:
```bash
# For PostgreSQL (production)
export DATABASE_URL="postgresql://user:password@host/database"

# For SQLite (development)
export DATABASE_URL="sqlite:///app.db"
```

### 3. Start the Server
```bash
# Option 1: Use the updated start.py
python start.py

# Option 2: Use uvicorn directly
uvicorn app.main:app --host localhost --port 8000 --reload
```

### 4. Access the Application
- **Web App**: http://localhost:8000/web/index.html
- **API Docs**: http://localhost:8000/docs
- **Health Check**: http://localhost:8000/health

### Docker 镜像构建（前端已在宿主机构建）

如果你选择在宿主机或 CI 上先构建前端，再构建镜像，请按照下列步骤：

1. 在项目根的 `app/` 目录先构建前端：

```bash
cd app
pnpm install
pnpm build
```

2. 回到项目根构建 Docker 镜像（Dockerfile 会直接拷贝 `app/dist`）：

```bash
docker build -t excel-ods-server -f docker/server.Dockerfile .
```

说明：当前 `docker/server.Dockerfile` 假定 `app/dist` 已存在并包含前端构建产物。若希望在镜像内执行前端构建，请告诉我，我可以恢复为多阶段构建并处理 pnpm 的原生构建脚本批准步骤。

## Key Features

### 🔧 **Type Safety**
All models use SQLModel for full type checking and validation.

### 🗄️ **Database Agnostic**
Works with PostgreSQL, SQLite, and other SQLAlchemy-supported databases.

### 📚 **Auto Documentation**
Interactive API documentation automatically generated at `/docs`.

### 🔄 **Database Migrations**
SQLModel automatically creates tables and handles schema changes.

### ⚡ **Performance**
Async/await support for high-performance concurrent requests.

### 🛡️ **Error Handling**
Centralized exception handling with proper HTTP status codes.

## Migration Notes

### What Changed
- **Old**: Custom HTTP server with manual routing
- **New**: FastAPI with automatic routing and validation
- **Old**: Raw SQL queries with psycopg2
- **New**: SQLModel ORM with type safety
- **Old**: Manual JSON serialization
- **New**: Automatic Pydantic serialization

### Backward Compatibility
- All API endpoints maintain the same URLs and response formats
- Database schema remains identical
- Existing web frontend will work without changes

### Legacy Support
- `start_legacy.py` - Original HTTP server (backup)
- All existing modules in `modules/` directory preserved

## Development

### Adding New Endpoints
1. Define models in `app/models/`
2. Create service logic in `app/services/`
3. Add routes in `app/api/`
4. Register router in `app/main.py`

### Database Operations
```python
from sqlmodel import Session
from app.database import get_session
from app.models.excel import DataSource

def get_data_sources(session: Session):
    return session.query(DataSource).all()
```

## Troubleshooting

### Database Connection Issues
- Check `DATABASE_URL` in config
- Ensure database server is running
- Verify connection credentials

### Import Errors
- Ensure all dependencies are installed: `pip install -r requirements.txt`
- Check Python path and virtual environment

### Port Conflicts
- Change port in `app/config.py` or use environment variable:
  ```bash
  export PORT=8001
  ```

---

🎉 **Congratulations!** Your backend is now running on modern FastAPI + SQLModel architecture!