260715_0

docs/wiki/concepts/db_schema/overview.md

@@ -0,0 +1,64 @@
+---
+type: concept
+status: stable
+related_pages: []
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md, raw/guidelines/agent.md
+---
+
+# DB 스키마 개요
+
+**DB명:** `aislo_db` / MariaDB v10.6+ / utf8mb4_unicode_ci / 드라이버 aiomysql
+
+> ✅ **모순 해결 (2026-07-12, 실 DB 직접 조회 `SHOW TABLES`로 검증):** 실제 운영 DB는 **34개 테이블**. `db_schema.md`(34개)가 정확했고 `agent.md`의 18개/23개는 갱신 안 된 값 — agent.md 쪽 오기로 판정.
+>
+> **raw 문서에 없던 실제 테이블 2개 발견:**
+> - `project_workflow_stages` — [[../workflow_state]] 설계가 **이미 구현되어 실 DB에 존재**함 (컬럼 구성이 계획서와 정확히 일치). status를 draft→stable로 갱신함.
+> - `system_admin_logs` — 시스템 관리자(SYSTEM_ADMIN)가 회원/조직 상태(`status`) 등을 변경할 때 감사 이력을 INSERT하는 Write-Only 성격의 테이블 ➡️ [[logs_monitoring]].
+>
+> ⚠️ **미확정/미연동 테이블 격리 규칙**:
+> - 분석 중이거나 소스코드와의 구체적인 연결고리(백엔드/프론트엔드 실사용처)가 아직 확정되지 않은 테이블이 신규 추가될 경우, 상위 공식 그룹 파일에 포함하지 않고 [[unconfirmed/README|미확정 폴더(unconfirmed/)]] 내에 개별 `[테이블명].md` 마크다운 파일로 저장하여 격리 관리합니다.
+
+## 테이블 그룹 (9개)
+
+| 그룹 | 테이블 수 | 상세 페이지 |
+|---|---|---|
+| 사용자/인증/조직 (핵심) | 7 | [[users_auth]] |
+| 로그/모니터링 | 8 | [[logs_monitoring]] |
+| 프로젝트 관리 | 3 | [[projects]] |
+| 파일/지표면분석 | 6 | [[files_surface]] |
+| 경로/종횡단 | 5 | [[route_profile]] |
+| 구조물/수량/산출물 | 4 | [[structure_output]] |
+| 미확정/연결 대기 테이블 | 0 | [[unconfirmed/README]] |
+
+## 파일 경로 추적 컬럼 (DB에 경로만 기록, 실 파일은 파일시스템)
+
+| 테이블.컬럼 | 용도 | 사용 단계 |
+|---|---|---|
+| `input_files.raw_file_path` | 원본 입력 파일 | B03 |
+| `processed_point_cloud.converted_file_path` | 변환된 포인트클라우드 | B04 |
+| `surface_models.model_file_path` | 지표면 모델 | B04 |
+| `routes.route_data_path` | 경로 데이터(GeoJSON) | B05 |
+| `longitudinal_sections.longitudinal_file_path` | 종단면 | B06 |
+| `cross_sections.cross_section_file_path` | 횡단면 | B06 |
+| `structures.structure_data_path` | 구조물 배치 | B07 |
+| `quantity_items.quantity_data_path` | 수량 항목 | B08 |
+| `outputs.outputs_directory_path` | 산출물 폴더 | B09 |
+| `output_files.output_file_path` | 개별 산출 파일 | B09 |
+
+상세 경로 규칙 → [[storage_paths]]
+
+## 설계 원칙
+- DB에는 "어디에 무엇이 있는가"의 메타정보만 저장. 실제 대용량 파일(LAS/PLY/TIF/DXF/Excel/PDF/JSON)은 파일시스템.
+- 공간 기하 데이터(GEOMETRY 타입 미지원) → JSON(GeoJSON 형식)으로 저장, 애플리케이션(Shapely/Geopandas)에서 파싱.
+- 모든 주요 테이블에 soft delete(`deleted_at`) 적용.
+
+## 테이블 관계 (핵심 흐름)
+```
+users ─company_id→ companies
+projects ─user_id/company_id→ users/companies
+  └→ input_files → processed_point_cloud → surface_models → terrain_layers
+  └→ routes → route_points/route_statistics/longitudinal_sections/cross_sections → structures
+  └→ quantity_items
+  └→ outputs → output_files
+```