---
type: concept
status: stable
related_pages: ["[[B03_FileInput/B03_backend]]", "[[B04_wf1_Surface/B04_backend]]"]
last_updated: 2026-07-12
source: raw/guidelines/db_schema.md
---

# DB: 파일/지표면분석 테이블

← [[overview]]

## upload_sessions (업로드 세션)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `varchar(36)` | NO | PRI | 세션 UUID |
| `project_id` | `varchar(36)` | NO | MUL | FK→projects.id |
| `original_filename` | `varchar(255)` | NO | | 원본 파일명 |
| `file_size_bytes` / `chunk_size_bytes` | `bigint(20)` | NO | | 파일크기 / 청크크기 |
| `total_chunks` / `completed_chunks` | `int(11)` | - | | 전체 청크수 / 완료 청크수 |
| `status` | `enum('PENDING','IN_PROGRESS','COMPLETED','FAILED')` | YES | MUL | `PENDING` |
| `created_at` / `updated_at` | `timestamp` | YES | | 생성 / 최종수정 일시 |

## upload_chunks (업로드 청크 데이터)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `int(11)` | NO | PRI | `auto_increment` |
| `session_id` | `varchar(36)` | NO | MUL | FK→upload_sessions.id |
| `chunk_index` | `int(11)` | NO | | 청크 인덱스 (0, 1, 2...) |
| `chunk_hash` | `varchar(64)` | YES | | 청크 검증용 체크섬 |
| `size_bytes` | `bigint(20)` | NO | | 청크 용량 |
| `stored_at` | `varchar(255)` | YES | | 임시 파일 저장 경로 |
| `completed_at` | `timestamp` | YES | MUL | 완료 일시 |

## input_files (입력 원본 파일)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `int(11)` | NO | PRI | `auto_increment` |
| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
| `file_type` | `varchar(50)` | YES | | `las`/`tif`/`prj`/`tfw`/`dxf` 등 |
| `original_filename` / `raw_file_path` | `varchar` | NO | | 파일명 / storage 상대경로 |
| `file_size_mb` | `float` | YES | | 파일 크기 (MB) |
| `upload_by` / `upload_at` | - | - | MUL | 업로드 유저 FK / 일시 |
| `crs_epsg` | `int(11)` | YES | | EPSG 좌표계 정보 |
| `metadata` | `longtext` | YES | | 헤더/포인트수 등 분석 JSON |
| `status` | `varchar(50)` | YES | | `UPLOADED` ➡️ `PROCESSED` ➡️ `ARCHIVED` |

## processed_point_cloud (필터/변환 포인트클라우드)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `int(11)` | NO | PRI | `auto_increment` |
| `input_file_id` / `project_id` | - | NO | MUL | FK→input_files / projects |
| `process_type` | `varchar(50)` | YES | | 변환 필터 분류 |
| `processed_file_path` / `converted_file_path` | `varchar` | YES | | 저장 경로 / PLY/LAZ 경로 |
| `converted_format` | `varchar(50)` | YES | | 변환 포맷 |
| `point_count` | `int(11)` | YES | | 포인트 개수 |
| `min_z` / `max_z` / `mean_z` | `float` | YES | | 고도 최저 / 최고 / 평균 |
| `x_min` ~ `y_max` | `float` | YES | | X/Y 좌표 바운딩 박스 범위 |
| `density_per_sqm` | `float` | YES | | ㎡당 점 밀도 |
| `classification_summary` | `longtext` | YES | | ground/unclassified 통계 |
| `processing_params` | `longtext` | YES | | 분석 파라미터 JSON |
| `processed_at` / `status` | - | - | | 변환 일시 / `PROCESSING`\|`COMPLETE`\|`FAILED` |

## surface_models (지표면 모델 및 등고선)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `int(11)` | NO | PRI | `auto_increment` |
| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
| `model_type` | `varchar(50)` | YES | | `dem_grid`/`tin`/`mesh`/`contour` |
| `source_file_id` / `processed_cloud_id` | `int(11)` | YES | MUL | FK→input_files / processed |
| `status` | `varchar(50)` | YES | | `PROCESSING` ➡️ `COMPLETE` / `FAILED` |
| `crs_epsg` / `resolution_m` | - | YES | | EPSG 좌표 / DEM 격자 해상도 |
| `model_file_path` | `varchar(500)` | YES | | 스토리지 상대 경로 |
| `generation_params` | `longtext` | YES | | 격자화 알고리즘 인자 JSON |
| `created_at` / `completed_at` | `timestamp` | - | | 생성 / 완료 일시 |

## terrain_layers (지형 레이어)
| 컬럼 | 타입 | Null | Key | Default / Extra |
|---|---|---|---|---|
| `id` | `int(11)` | NO | PRI | `auto_increment` |
| `surface_model_id` | `int(11)` | NO | MUL | FK→surface_models.id |
| `layer_name` | `varchar(100)` | YES | | 레이어 영문/한글 식별자 |
| `geometry_type` | `varchar(50)` | YES | | `POINTCLOUD`/`GRID`/`MESH`/`CONTOUR` |
| `layer_file_path` | `varchar(500)` | YES | | 개별 레이어 실 파일 경로 |
| `file_format` / `file_size_mb` | - | YES | | 포맷 (ply, tfw, las 등) / 크기 |
| `statistics` | `longtext` | YES | | 통계 수치 JSON |
| `created_at` | `timestamp` | NO | | 생성 일시 |

## input_files.status 값
`UPLOADED → PROCESSED → ARCHIVED`

## surface_models.status / processed_point_cloud.status 값
`PROCESSING → COMPLETE / FAILED`

관련 함수 위치 → [[B04_wf1_Surface/B04_db]], 사용 라이브러리 → [[dependencies]]