eomsangdon/Aislo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f8633bb1fe08a1a337110b282c616f66a66f2ecd
Aislo/CLAUDE.md
T

Symbolic link
7.7 KiB
Raw Blame History

프로젝트 행동지침 및 기술 스택 명세 (CLAUDE.md)

🚀 빠른 시작 (Quick Start - 항상 읽기!)

웹앱 실행 (전체 스택)

# 1. 프로젝트 루트에서만 작업
cd d:\02_Software_Prog\임도설계\ 및\ 견적자동화\ 프로그램\ 개발

# 2. Python 가상환경 활성화
.\venv\Scripts\activate

# 3. 웹서버 실행 (백엔드 + 프론트엔드 동시 시작)
python main.py

# 브라우저: http://localhost:8000

중요 구조

  • 빌드 설정: 루트(package.json, tsconfig.json, vite.config.ts) — 유일한 빌드 설정
  • 프론트엔드 소스: A00_Common/ (진입점), A0*/, B0*/ (페이지들)
  • 프론트엔드 공유 자산: ui_template/, config/ (TypeScript 설정용)
  • 백엔드: main.py, common_util/, config/ (Python 설정)
  • DB: db_management/ (마이그레이션 SQL)

주의사항

  • ❌ config/ 폴더에 빌드 설정 파일 두지 말 것 (루트만 사용)
  • ❌ npm run build는 프로젝트 루트에서만 실행
  • ✅ python main.py로 전체 스택 자동 시작 (프론트엔드 빌드 포함)
  • ✅ 코더 AI는 .agent/CODER_HANDOFF.md 참고

프로젝트 & DB 정보

📌 프로그램명

Aislo (아이슬로)

  • 의미: AI (인공지능) + Slotti (핀란드어: 임도/산림 도로)
  • 콘셉트: 산림의 미래를 열어가는 인공지능 경로 설계 솔루션

1. 기술 환경 및 기본 스택 (Technical Stack Baseline)

프로젝트의 코드를 작성, 테스트 또는 검증할 환경 명확화 및 호환 기준 제시.

A. 백엔드 프레임워크 (Python)

  • Runtime: Python v3.12 or v3.13.7
  • Framework: FastAPI / Pydantic
  • Geometry/GIS Engine: Trimesh, Whitebox, Geopandas, Shapely, Rasterio, Laspy

B. 데이터베이스 (MariaDB)

  • DBMS: MariaDB v10.6+
  • Character Set: utf8mb4 (한글 완벽 지원)
  • Collation: utf8mb4_unicode_ci
  • DB Driver (비동기): aiomysql (순수 Python, Windows 호환. asyncmy는 Cython 빌드 필요로 미채택)
  • 쿼리 방식: Raw SQL (ORM 사용 금지)
  • 공간 데이터: JSON 기반 저장 (MariaDB는 PostGIS 미지원)

C. 프론트엔드 & WebCAD (TypeScript & WebGL)

  • Language/Runtime: TypeScript / Node.js
  • Rendering: HTML5 Canvas 및 WebGL 기반 WebCAD 시스템 구현

D. 인코딩 및 다국어 표준

  • 인코딩: 텍스트 파일은 UTF-8 표준으로 통일

2. 문맥 라우팅 및 문서 구조 (Context Routing)

코드 작성 및 기술 검증 시 문서 우선순위에 따른 계층적 레퍼런스 필수 읽기.

  • 1단계 (필수): .agent/structure.md 읽기 후 신규 폴더 생성 기준 분석.
  • 2단계 (선택 읽기): 프로젝트 구현에 필요한 세부 기술 명세 읽기.
    • 그룹 A (UI, 스타일, 컴포넌트, WebCAD): .agent/frontend.md 필수 추가 읽기.
    • 그룹 B (알고리즘, 저장, DB, MariaDB 값 제어): .agent/backend.md 필수 추가 읽기.
    • 그룹 C (DB 구조 변경): DB 구조 변경 시 .agent/db_schema.md 선택적 읽기.

3. 코드 작성 기본 제약 (Constraints)

  • 구조 준수: .agent/structure.md 트리 구조 엄격 준수.
  • 700줄 제한: 단일 파일 코드 작성/수정 시 700줄 이상이 될 경우 사전 공지. 기능별 파일 분할 후 structure.md 갱신 필수.
  • 안전 보관: 백엔드 작업 시 보안 저장소 경로 명시 및 임의 삭제 방지 필수.
  • 경로 활용: 단계별 페이지 기반 폴더 구조(B03~B09)와 DB 경로 열의 기준은 .agent/db_schema_simple.md의 「파일시스템 경로와 DB 링크」를 따른다.
  • 일관성 검증: 설계 단계에서부터 DB 설계, 파일 경로, API 라우팅이 모두 동일한 워크플로우 기준으로 통일되어야 한다. (불일치 발생 시 설계 단계에서 재논의 필수)
  • 코드 포맷팅 (자동화 도구): 프로젝트의 코드 작성이 완료되는 시, 반드시 프로젝트 루트에서 각 언어별 포맷터를 재실행하여 스타일을 통일해야 한다.
    • Python 포맷팅 명령어: ruff format [파일명] 및 ruff check --fix [파일명] 실행
    • TypeScript/CSS 포맷팅 명령어: npx prettier --write [파일명] 실행
  • 외부 라이브러리 활용: 외부 라이브러리 활용 시 프로젝트에 맞춰 호환 라이브러리 선정하고, 불필요한 함수는 작성하지 않도록 최소화.

4. 데이터베이스 상세 명세 (Database Specification)

4.1 스키마 기본 정보

  • DB 명: aislo_db
  • DBMS: MariaDB v10.6+
  • 인코딩: utf8mb4_unicode_ci
  • 테이블 수: 18개
  • 드라이버: aiomysql (비동기)

4.2 파일 경로 추적 (Path Tracking)

모든 중간 산출물의 파일 경로를 DB에 기록:

  • input_files.raw_file_path — 원본 입력 파일
  • processed_point_cloud.converted_file_path — 변환된 포인트클라우드
  • surface_models.model_file_path — 지표면 모델
  • routes.route_data_path — 경로 데이터
  • longitudinal_sections.longitudinal_file_path — 종단면
  • cross_sections.cross_section_file_path — 횡단면
  • structures.structure_data_path — 구조물 배치
  • quantity_items.quantity_data_path — 수량 항목
  • outputs.outputs_directory_path — 산출물 폴더
  • output_files.output_file_path — 개별 산출 파일

4.3 저장소 구조 (Workflow-based Folder Structure)

storage/{company_slug}/{user_slug}/{project_id}/
├── B03_FileInput/input/                (WF0: 원본 입력)
├── B04_wf1_Surface/processed/          (WF1: 변환된 포인트클라우드 & 모델)
├── B05_wf2_Route/route/                (WF2: 경로 설계)
├── B06_wf3_ProfileCross/               (WF3: 종단면 & 횡단면)
├── B07_wf4_DesignDetail/structures/    (WF4: 구조물 배치)
├── B08_wf5_Quantity/quantities/        (WF5: 수량 산출)
└── B09_wf6_Estimation/v1,v2,.../      (WF6: 최종 산출물)

4.4 공간 데이터 처리 (MariaDB 특성)

  • 지하형 기하 데이터: GEOMETRY 타입 미지원 → JSON으로 저장
  • 좌표 저장 예: {"type": "Point", "coordinates": [127.5, 37.5]}
  • 경로 저장 예: {"type": "LineString", "coordinates": [[127.5, 37.5], [127.6, 37.6]]}
  • 애플리케이션 처리: Python의 Shapely, Geopandas에서 JSON 파싱 후 기하 연산

5. 워크플로우 6단계 (6-Stage Workflow)

WF0: B03_FileInput (파일 입력)
  ↓ (LAS, TIF, TFW, PRJ, DXF 업로드)
WF1: B04_wf1_Surface (지표면 분석)
  ↓ (DEM, TIN, 포인트클라우드 변환)
WF2: B05_wf2_Route (경로 설계)
  ↓ (최적 경로 계산)
WF3: B06_wf3_ProfileCross (종횡단 생성)
  ↓ (종단면, 횡단면 생성)
WF4: B07_wf4_DesignDetail (상세 설계)
  ↓ (구조물 배치)
WF5: B08_wf5_Quantity (수량 산출)
  ↓ (수량 항목 계산)
WF6: B09_wf6_Estimation (견적·문서)
  ↓ (Excel, PDF, DXF 생성)

6. 주요 문서 참고 순서

  1. 구조 설계: .agent/structure.md 읽기
  2. 프론트 구현: .agent/frontend.md 읽기
  3. 백엔드 구현: .agent/backend.md 읽기
  4. 마이그레이션: .agent/migration_plan.md 읽기
  5. DB 스키마: .agent/db_schema_simple.md 읽기
  6. 프로젝트 정보: .agent/project_info.md 읽기

7. 요약

항목 값
프로그램명 Aislo (아이슬로)
DB 명 aislo_db
DBMS MariaDB v10.6+
인코딩 utf8mb4_unicode_ci
Backend Python 3.12+ / FastAPI
Frontend TypeScript / Node.js
드라이버 aiomysql
워크플로우 6단계 (WF0~WF6)
테이블 수 18개
폴더 구조 워크플로우 기반 (B03~B09)
Reference in New Issue View Git Blame Copy Permalink