260715_0

2026-07-15 18:33:33 +09:00
parent 6b1583103f
commit f533082537
201 changed files with 19776 additions and 563 deletions
@@ -0,0 +1,95 @@
+---
+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]]
@@ -0,0 +1,102 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B01_Dashboard/B01_backend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md, raw/guidelines/backend.md
+---
+
+# DB: 로그/모니터링 테이블
+
+← [[overview]]
+
+## login_logs (로그인 시도 로그)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | YES | MUL | FK→users.id |
+| `email` | `varchar(255)` | NO | | |
+| `status` | `enum('SUCCESS','FAILURE')` | NO | | |
+| `failure_reason` / `user_agent` | `varchar(100)` / `text` | YES | | |
+| `login_at` | `timestamp` | NO | MUL | `current_timestamp()` |
+
+## activity_logs (사용자 활동 로그)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id |
+| `action_type` | `varchar(100)` | NO | | 행위 종류 |
+| `action_at` | `timestamp` | NO | | `current_timestamp()` |
+| `resource_id` / `status` | `varchar(255)` / `enum` | - | | 리소스 ID / SUCCESS\|FAILURE |
+| `details` | `longtext` | YES | | JSON 상세 데이터 |
+
+## audit_logs (감사 로그)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | YES | MUL | FK→users.id |
+| `action` / `entity_type` | `varchar(100)` | YES | | CRUD/EXPORT/DOWNLOAD 등 |
+| `entity_id` | `varchar(36)` | YES | | 대상 UUID 등 |
+| `timestamp` / `ip_address` | `timestamp` / `varchar(45)` | - | | 발생시각 / IP 주소 |
+| `details` | `longtext` | YES | | JSON 상세 |
+
+## system_audit_logs (프로젝트/조직 변경 감사 로그)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id (행위자) |
+| `action` / `resource_type` | `varchar(50)` | - | | PROJECT_CREATE 등 / 종류 |
+| `resource_id` | `int(11)` | YES | | |
+| `timestamp` | `timestamp` | YES | MUL | `current_timestamp()` |
+| `ip_address` / `user_agent` | `varchar(50)` / `text` | YES | | IP 주소 / 브라우저 에이전트 |
+
+## system_admin_logs (시스템 관리자 행위 로그)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `admin_user_id` | `int(11)` | NO | MUL | FK→users.id (관리자 ID) |
+| `action_type` / `target_id` | `varchar(100)` / `varchar(255)`| - | | 변경종류(USER_STATUS) / 대상 ID |
+| `action_at` | `timestamp` | NO | | `current_timestamp()` |
+| `details` | `longtext` | YES | | JSON 형태의 변경 상세 |
+
+## system_resources (시스템 자원 계측)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `timestamp` | `timestamp` | YES | MUL | `current_timestamp()` |
+| `cpu_usage_percent` / `memory_usage_percent` | `float` | YES | | |
+| `disk_usage_percent` / `total_storage_mb` | `float` | - | | 디스크사용률 / 전체 스토리지 용량 |
+| `active_user_count` / `active_project_count` | `int(11)` | NO | | 활성 사용자 / 프로젝트 수 |
+
+## support_requests (기술 지원 요청)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `company_id` | `int(11)` | YES | MUL | FK→companies.id |
+| `company_name` / `user_name` | `varchar(255)` | - | | 회사명 / 작성자명 |
+| `user_email` / `user_phone` | `varchar(255)` / `varchar(30)` | - | | 이메일 / 전화번호 |
+| `subject` / `message` | `varchar(255)` / `text` | NO | | 제목 / 문의 메시지 본문 |
+| `status` | `enum('NEW','REVIEWED','RESOLVED','DELETED')` | NO | MUL | `NEW` |
+| `reviewed_by` | `int(11)` | YES | MUL | FK→users.id (검토자) |
+| `created_at` / `reviewed_at` / `review_notes` | - | - | | 접수 / 검토일시 / 메모 |
+
+## change_logs (설계 변경 이력)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | | FK→projects.id |
+| `changed_by` | `int(11)` | YES | MUL | FK→users.id (수정자) |
+| `changed_at` | `timestamp` | NO | | `current_timestamp()` |
+| `entity_type` / `entity_id` | `varchar(100)` / `int(11)` | YES | | 대상엔티티(routes 등) / 대상 PK |
+| `old_value` / `new_value` | `longtext` | YES | | 변경 전 / 후 JSON 스냅샷 |
+| `reason` | `varchar(255)` | YES | | 변경 사유 |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]] (SYSTEM_ADMIN 리소스 현황·시스템 로그 섹션), [[A08_Support/A08_backend|A08_Support]] (support_requests INSERT)
+
+## system_audit_logs — 사용처 (B01, B02)
+- **프로젝트 생성**: `B02_ProjRegister_Repository.py:92` (`PROJECT_CREATE` 기록 ➡️ [[B02_ProjRegister/B02_backend]])
+- **기타 관리 행위**: `B01_Dashboard_Repository.py:245,265` (수정·삭제), `:336,367` (회사 생성), `:609` (감사 로그 조회), `:758,779` (자동화 제어)
+
+## 리소스 API (SYSTEM_ADMIN 전용)
+`GET /api/dashboard/admin/resources?days=30`
+- 실시간 계측(`current`), 30일 다운샘플링 시계열 조회(`history`, ~4MB ➡️ ~55KB 압축), 활성 지표(`stats`) 제공.
@@ -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
+```
@@ -0,0 +1,56 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B01_Dashboard/B01_backend]]", "[[B02_ProjRegister/B02_backend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md, raw/plans/plan_workflow_state_management.md
+---
+
+# DB: 프로젝트 관리 테이블
+
+← [[overview]]
+
+## projects (프로젝트)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `char(36)` | NO | PRI | 프로젝트 UUID |
+| `user_id` / `company_id` | `int(11)` | NO | MUL | FK→users/companies |
+| `name` | `varchar(255)` | NO | | 프로젝트명 |
+| `region` / `road_type` | `varchar(100)` | YES | | 지역 / 임도종류 |
+| `project_year` | `int(11)` | YES | | 사업년도 |
+| `estimated_length_m` | `float` | YES | | 계획 연장(m) |
+| `memo` | `text` | YES | | 메모 |
+| `status` | `varchar(50)` | YES | | `NEW` (호환용 캐시) |
+| `crs_epsg` | `int(11)` | YES | | `5178` (좌표계 EPSG) |
+| `storage_path` | `varchar(500)` | YES | | 상대경로 ➡️ [[storage_paths]] |
+| `created_at` / `updated_at` / `deleted_at` | `timestamp` | - | | 생성 / 수정 / soft-delete |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]] (목록), [[B02_ProjRegister/B02_backend|B02_ProjRegister]] (생성)
+
+## project_versions (프로젝트 버전 스냅샷)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
+| `version_num` | `int(11)` | NO | | 버전 번호 |
+| `status` | `varchar(50)` | YES | | 버전 상태 |
+| `data` | `longtext` | YES | | 설계 스냅샷 JSON 데이터 |
+| `snapshot_at` / `created_at` | `timestamp` | NO | | 생성일시 |
+
+## project_automations (프로젝트 자동화 정책)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
+| `name` | `varchar(100)` | NO | | 자동화 명칭 |
+| `logic_type` | `varchar(50)` | NO | | `trigger_on_stage_complete` 등 |
+| `config_json` | `longtext` | NO | | 설정 값 JSON |
+| `status` | `enum('DRAFT','ACTIVE','INACTIVE')` | NO | MUL | `DRAFT` |
+| `created_by` / `updated_by` | `int(11)` | - | MUL | FK→users.id |
+| `last_executed_at` | `datetime` | YES | | 최종 실행 일시 |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]] (자동화 로직 관리, USER는 조회 차단)
+
+## project_workflow_stages (단계별 상세 상태)
+- 본 테이블은 워크플로우 7단계(stage 0~6)의 세부 진행도(state, params, progress_percent 등)를 관리하는 SSOT입니다.
+- 상세 테이블 정보 및 사용처 ➡️ [[workflow_state]]
@@ -0,0 +1,69 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B05_wf2_Route/B05_backend]]", "[[B06_wf3_ProfileCross/B06_backend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md
+---
+
+# DB: 경로/종횡단 테이블
+
+← [[overview]]
+
+## routes (노선 경로)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
+| `surface_model_id` | `int(11)` | YES | MUL | FK→surface_models.id |
+| `status` | `varchar(50)` | YES | | `DRAFT` ➡️ `CONFIRMED` ➡️ `ARCHIVED` |
+| `start_chainage_m` / `end_chainage_m` | `float` | YES | | 시작 시점 / 끝 시점 연장(m) |
+| `total_length_m` | `float` | YES | | 총 연장(m) |
+| `grade_percent` | `longtext` | YES | | 경사도 정보 JSON |
+| `constraints` / `algorithm_params` | `longtext` | YES | | 회피 구역 JSON / 알고리즘 가중치 파라미터 JSON |
+| `route_data_path` | `varchar(500)` | YES | | 노선 데이터 (GeoJSON) 파일 경로 |
+| `computed_at` / `created_at` | - | - | | 연산 완료 일시 / 생성 일시 |
+
+## route_points (경로 좌표점)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `route_id` | `int(11)` | NO | MUL | FK→routes.id |
+| `chainage_m` | `float` | YES | | 시점 거리(m) |
+| `elevation_m` / `slope_percent` | `float` | YES | | 표고(m) / 종단 경사율(%) |
+| `sequence_num` | `int(11)` | YES | | 점 순서 |
+
+## route_statistics (노선 통계)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `route_id` | `int(11)` | NO | MUL | FK→routes.id |
+| `min_slope` / `max_slope` / `mean_slope` | `float` | YES | | 최저 / 최고 / 평균 경사(%) |
+| `cut_volume_m3` / `fill_volume_m3` | `float` | YES | | 절토량(㎥) / 성토량(㎥) |
+| `tree_cutting_volume` / `cost_score` | `float` | YES | | 벌채량 / 평점 비용 스코어 |
+
+## longitudinal_sections (종단면 설계)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` / `route_id` | `char(36)` / `int` | NO | MUL | FK→projects / routes |
+| `computed_at` | `timestamp` | YES | | 종단 계산 일시 |
+| `data` | `longtext` | YES | | 지반고/계획고/구배 등 설계 데이터 JSON |
+| `longitudinal_file_path` | `varchar(500)` | YES | | 종단도면 캐드 파일 경로 |
+| `status` | `varchar(50)` | YES | | `DRAFT` / `CONFIRMED` |
+
+## cross_sections (횡단면 설계)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` / `route_id` | `char(36)` / `int` | NO | MUL | FK→projects / routes |
+| `chainage_m` / `sequence_num` | - | YES | | 측정 체인 거리(m) / 단면 순서 |
+| `data` | `longtext` | YES | | 좌우 사면 경사, 폭, 절성토 단면적 JSON |
+| `cross_section_file_path` | `varchar(500)` | YES | | 횡단도면 캐드 파일 경로 |
+| `status` | `varchar(50)` | YES | | `DRAFT` / `CONFIRMED` |
+
+## routes.status 흐름
+`DRAFT → CONFIRMED → ARCHIVED`
+
+## cross_sections.data.structures
+횡단면 하나에 배치된 구조물 ID 배열 → [[structure_output]]#structures 참조
@@ -0,0 +1,70 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B07_wf4_DesignDetail/B07_frontend]]", "[[B08_wf5_Quantity/B08_frontend]]", "[[B09_wf6_Estimation/B09_frontend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md
+---
+
+# DB: 구조물/수량/산출물 테이블
+
+← [[overview]]
+
+## structures (배치 구조물)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` / `cross_section_id` | - | - | MUL | FK→projects / cross_sections |
+| `structure_type` | `varchar(100)` | YES | | 낙석방지책 / 계간수로 / 돌붙임 등 |
+| `chainage_m` | `float` | YES | | 구조물 배치 체인 시점 거리(m) |
+| `location` | `varchar(50)` | YES | | 좌 / 우 / 종단 등 배치 위치 |
+| `length_m` / `width_m` / `height_m` | `float` | YES | | 길이 / 폭 / 높이 규격(m) |
+| `material` | `varchar(100)` | YES | | 구조물 재질/자재 |
+| `quantity` / `unit_price` | - | YES | | 수량 / 단가 |
+| `design_notes` | `longtext` | YES | | 특기사항 등 메모 |
+| `structure_data_path` | `varchar(500)` | YES | | 세부 구조 상세 데이터 파일 경로 |
+| `last_modified_by` | `int(11)` | YES | MUL | FK→users.id (최종 수정자) |
+| `created_at` / `updated_at` | `timestamp` | - | | 생성 / 수정 일시 |
+
+## quantity_items (수량 산출 항목)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
+| `category` | `varchar(100)` | YES | | 토공 / 구조물 / 포장 / 배수 등 공종 |
+| `item_name` / `unit` | `varchar` | YES | | 품목 항목명 / 단위 (㎡, m 등) |
+| `quantity_design` / `quantity_actual` | `float` | YES | | 설계 수량 / 최종 반영 수량 |
+| `unit_price` / `total_price` | `float` | YES | | 단가 / 총 금액 |
+| `standard_reference` | `varchar(255)` | YES | | 품셈 근거 코드/출처 |
+| `computed_at` / `quantity_data_path` | - | YES | | 계산 일시 / 상세 산출근거 데이터 파일 경로 |
+| `data` | `longtext` | YES | | 계산 세부 과정 통계 JSON |
+
+## outputs (최종 견적/도면 산출 세션)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `project_id` | `char(36)` | NO | MUL | FK→projects.id |
+| `output_type` | `varchar(100)` | YES | | `estimation_excel`/`drawing_dxf`/`report_pdf`/`all_bundle` |
+| `status` | `varchar(50)` | YES | | `GENERATING` ➡️ `COMPLETE` / `FAILED` |
+| `generated_by` / `generated_at` | - | - | MUL | 생성자 FK / 생성일시 |
+| `version` | `int(11)` | YES | | 산출 버전 |
+| `outputs_directory_path` | `varchar(500)` | YES | | 산출 파일 번들 디렉토리 경로 |
+| `metadata` | `longtext` | YES | | 기타 도면 스케일 등 정보 JSON |
+
+## output_files (개별 산출 파일 리스트)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `output_id` | `int(11)` | NO | MUL | FK→outputs.id |
+| `file_type` | `varchar(50)` | YES | | `xlsx`/`pdf`/`dxf`/`dwg`/`json`/`zip` 등 |
+| `original_filename` | `varchar(255)` | YES | | 원본 파일 식별 이름 |
+| `output_file_path` | `varchar(500)` | YES | | 개별 파일 저장 경로 |
+| `file_size_mb` / `download_count` | - | YES | | 파일 용량 / 다운로드 누적 카운트 |
+| `created_at` | `timestamp` | NO | | 생성일시 |
+
+## quantity_items 총비용 계산 예
+```sql
+SELECT SUM(quantity_actual * unit_price) AS total_cost, category
+FROM quantity_items WHERE project_id = :project_id AND deleted_at IS NULL
+GROUP BY category;
+```
@@ -0,0 +1,7 @@
+# 미확정 테이블 보관소 (Unconfirmed DB Schemas)
+
+본 디렉토리는 소스코드 연동 처리가 완료되지 않았거나, 비즈니스 로직(백엔드/프론트엔드) 상의 구체적인 연결고리가 식별되지 않은 미확정 테이블의 명세서 및 임시 분석 내용을 개별 마크다운 파일로 저장·격리하는 공간입니다.
+
+## 운영 규칙
+1. **임시 격리**: 신규 테이블 추가 또는 레거시 테이블 중 사용처를 즉시 규명하기 어려운 경우 `[테이블명].md`로 파일을 생성해 기록합니다.
+2. **확정 이관**: 소스코드에서의 실제 사용처(라우터, 리포지토리 등)가 명확해지면, 상위의 공식 테이블 그룹(예: `users_auth.md`, `logs_monitoring.md` 등)으로 표 명세를 이관하고 본 폴더 내의 마크다운은 삭제합니다.
@@ -0,0 +1,92 @@
+---
+type: concept
+status: stable
+related_pages: ["[[B01_Dashboard/B01_backend]]"]
+last_updated: 2026-07-12
+source: raw/guidelines/db_schema.md
+---
+
+# DB: 사용자/인증/조직 테이블
+
+← [[overview]]
+
+## users (사용자)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `email` | `varchar(255)` | NO | UNI | |
+| `password_hash` | `varchar(255)` | NO | | |
+| `name` | `varchar(255)` | NO | | |
+| `position` / `department` | `varchar(100)` | YES | | 직위 / 부서 |
+| `phone` | `varchar(20)` | YES | | |
+| `company_id` | `int(11)` | YES | MUL | FK→companies.id |
+| `role` | `enum('SYSTEM_ADMIN','ADMIN','USER')` | NO | MUL | `USER` |
+| `is_master` | `tinyint(1)` | NO | | `0` (마스터 여부) |
+| `status` | `enum('PENDING_EMAIL','NO_COMPANY','PENDING','ACTIVE','INACTIVE','REJECTED')` | NO | MUL | `PENDING_EMAIL` |
+| `auth_expires_at` / `last_login` | `datetime` | YES | | 인증만료 / 최종로그인 |
+| `login_failures` | `int(11)` | NO | | `0` (실패 횟수) |
+| `created_at` / `updated_at` / `deleted_at` | `timestamp` | - | | 생성 / 수정 / soft-delete |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]] (사용자 관리), 전 페이지 공통 인증
+
+## companies (회사)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `name` | `varchar(255)` | NO | UNI | 회사명 |
+| `business_registration_number` | `varchar(20)` | YES | UNI | 사업자번호 |
+| `status` | `enum('ACTIVE','INACTIVE','SUSPENDED')` | NO | | `ACTIVE` |
+| `subscription_status` | `enum('FREE','TRIAL','PAID','EXPIRED')` | NO | | `FREE` |
+| `created_by` | `int(11)` | YES | MUL | FK→users.id (생성자) |
+| `company_code` | `varchar(20)` | YES | | 참여용 코드 |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]]
+
+## sessions (세션)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `varchar(255)` | NO | PRI | 세션 ID (쿠키 값) |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id |
+| `user_agent_hash` | `char(64)` | NO | | |
+| `expires_at` | `timestamp` | NO | MUL | 만료일시 |
+| `last_activity_at` | `timestamp` | NO | | 최종 활동일시 |
+
+**사용처:** 전 페이지 공통 (세션 인증) — 상세 → [[auth_rbac]]
+
+## email_otps (이메일 OTP)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id |
+| `purpose` | `enum('REGISTER','LOGIN','REVERIFY','PASSWORD_CHANGE')` | NO | | 용도 |
+| `otp_hash` | `varchar(255)` | NO | | OTP 해시값 |
+| `expires_at` / `consumed_at` | `timestamp` | - | | 만료일시 / 사용일시 |
+
+## trusted_devices (신뢰 기기)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id |
+| `user_agent_hash` | `char(64)` | NO | | 브라우저 지문 해시 |
+| `verified_at` / `last_used_at` | `timestamp` | NO | | 검증 / 최종 사용 일시 |
+
+## join_requests (회사 가입 신청)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `int(11)` | NO | PRI | `auto_increment` |
+| `user_id` / `company_id` | `int(11)` | NO | MUL | FK→users/companies |
+| `status` | `enum('PENDING','APPROVED','REJECTED')` | NO | | `PENDING` |
+| `requested_at` / `reviewed_at` | `timestamp` | - | | 신청 / 검토 일시 |
+| `reviewed_by` | `int(11)` | YES | MUL | FK→users.id (검토자) |
+
+**사용처:** [[B01_Dashboard/B01_backend|B01_Dashboard]] (`B01_Dashboard_Repository.py:378` 가입 신청·처리)
+
+## user_consents (약관 동의)
+| 컬럼 | 타입 | Null | Key | Default / Extra |
+|---|---|---|---|---|
+| `id` | `bigint(20)` | NO | PRI | `auto_increment` |
+| `user_id` | `int(11)` | NO | MUL | FK→users.id |
+| `terms_version` | `varchar(20)` | NO | | 동의한 약관 버전 |
+| `terms_agreed` / `privacy_agreed` | `tinyint(1)` | NO | | 필수 동의여부 (1=동의) |
+| `marketing_agreed` | `tinyint(1)` | NO | | `0` (선택 마케팅동의) |
+| `agreed_at` | `timestamp` | NO | | 동의 일시 |