Aislo/.agent/test/02_Database_Schema.md

document_type, priority

document_type	priority
database	CRITICAL

데이터베이스 스키마 명세 (MariaDB)

MariaDB v10.6+를 사용하며, 총 18개의 테이블로 구성됩니다. ORM 없이 Raw SQL과 aiomysql 드라이버를 사용합니다. 공간 데이터(GEOMETRY)는 지원 한계로 인해 JSONB 또는 TEXT(GeoJSON)로 저장합니다.

테이블 목록 및 컬럼 구조

1. 사용자 & 프로젝트 (Core)

• users: id(PK), email, password_hash, name, position, department, phone, company_id(FK)
• companies: id(PK), name, business_registration_number, business_address, business_owner, business_status
• projects: id(UUID, PK), user_id(FK), company_id(FK), name, region, road_type, status, crs_epsg, storage_path
• project_versions: id, project_id, version_num, data(JSONB)

2. 파일 & 지표면 데이터 (WF0, WF1)

• input_files: id(PK), project_id(FK), file_type(las, tif 등), original_filename, raw_file_path, crs_epsg, metadata(JSONB)
• processed_point_cloud: id, input_file_id, project_id, processed_file_path, converted_file_path, min_z, max_z 등 통계치
• surface_models: id, project_id, model_type(dem_grid, tin 등), model_file_path, generation_params(JSONB)
• terrain_layers: id, surface_model_id, layer_name, layer_file_path(geojson 등)

3. 경로 설계 (WF2)

• routes: id(PK), project_id, surface_model_id, status, geometry(LineString JSON), route_data_path, constraints(JSONB)
• route_points: id, route_id, chainage_m, geometry(Point JSON), elevation_m
• route_statistics: id, route_id, mean_slope, cut_volume_m3, fill_volume_m3

4. 종횡단 및 구조물 설계 (WF3, WF4)

• longitudinal_sections: id, project_id, route_id, longitudinal_file_path, data(JSONB - chainages, elevations 등 배열)
• cross_sections: id, route_id, chainage_m, cross_section_file_path, data(JSONB - left_slope, cut_volume_m3 등)
• structures: id, cross_section_id, structure_type, location(LEFT/RIGHT/CENTER), length_m, geometry(Polygon JSON), structure_data_path

5. 수량 산출 및 산출물 (WF5, WF6)

• quantity_items: id, project_id, category, item_name, quantity_design, quantity_actual, unit_price, quantity_data_path
• outputs: id, project_id, output_type, outputs_directory_path
• output_files: id, output_id, file_type, output_file_path

6. 로그 (Audit)

• audit_logs, change_logs

---

💡 주요 원칙 (DB vs File System)

• DB에는 메타데이터와 파일 시스템의 "상대 경로"만 기록합니다. (예: input_files.raw_file_path = "B03_FileInput/input/las/cloud.las")
• 대용량 파일(LAS, TIF, GeoJSON)은 MariaDB에 Blob으로 저장하지 않습니다.

📝 쿼리 작성 예제 (Raw SQL & aiomysql)

# 쿼리에는 ORM이 아닌 %s 플레이스홀더를 사용해야 함
async def get_project_route(pool, project_id: str):
    async with pool.acquire() as conn:
        async with conn.cursor() as cur:
            await cur.execute("""
                SELECT r.id, r.total_length_m, r.route_data_path 
                FROM routes r 
                WHERE r.project_id = %s
                ORDER BY r.computed_at DESC LIMIT 1
            """, (project_id,))
            return await cur.fetchone()