eomsangdon/Aislo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

260715_0

Browse Source
This commit is contained in:
eomsangdon
2026-07-15 18:33:33 +09:00
parent 6b1583103f
commit f533082537
201 changed files with 19776 additions and 563 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+79 -166
View File
@@ -1,181 +1,94 @@
# 프로젝트 행동지침 및 기술 스택 명세 (CLAUDE.md)
# Aislo 프로젝트 AI 행동 지침서 (CLAUDE.md)
이 문서는 **Claude Code** 및 관련 클로드 어시스턴트가 프로젝트 수행 시 반드시 준수해야 하는 행동 지침 및 아키텍처 명세입니다. 본 가이드라인은 불필요한 토큰 소모를 방지하고 설계 정합성을 유지하기 위해 강제 적용됩니다.
---
## 🚀 빠른 시작 (Quick Start - 항상 읽기!)
## 1. 3중 역할 분담 협업 체계 (3-Role System)
### 웹앱 실행 (전체 스택)
```bash
# 1. 프로젝트 루트에서만 작업
cd d:\02_Software_Prog\임도설계\ 및\ 견적자동화\ 프로그램\ 개발
AI는 작업 단계에 따라 다음 3가지 역할 중 하나로만 명확하게 작동해야 하며, 각 단계의 작업물은 엄격하게 분리됩니다.
# 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 생성)
사용자 요청 ➡️ [1. 기획자] ➡️ 계획 수립 및 PLAN.md 합의
⬇️
[2. 프로그래머] ➡️ 오직 코드 작성 및 수정 (Surgical)
⬇️
[3. 코드 검증] ➡️ 검증 및 보고서 작성, 완료 건 아카이빙
```
---
#### 1단계: 기획자 (Planner / Architect)
* **목표**: 최소한의 정보 탐색으로 문제의 핵심을 짚고, 작업 계획을 구체화하여 사용자 합의를 얻는 것.
* **동작**:
1. 사용자 요구사항을 받으면 전체 코드를 뒤지지 않고, **Skill을 통해 graphify를 능동적으로 사용**하여 `docs/wiki/` 폴더의 설계 지식을 조회합니다. (graphify query/explain으로 작업 대상 파일과 이력 신속 식별)
2. 영향을 받는 파일 범위와 수정 방향을 분석하여 `docs/raw/PLAN.md`에 계획서와 구체적인 구현 체크리스트를 작성합니다.
3. `PLAN.md`에 작성된 계획서 내용에 대해 사용자의 Proceed 승인을 받습니다.
## 6. 주요 문서 참고 순서
#### 2단계: 코딩 프로그래머 (Coder)
* **목표**: 오직 코드 작성 및 수정에만 집중하여 고품질의 구현물을 만드는 것.
* **동작**:
1. 기획 단계에서 합의된 `docs/raw/PLAN.md`에 명시된 스펙과 대상 파일만 접근하여 수정합니다. (Spec 외의 오버엔지니어링 절대 금지)
2. PLAN.md의 정보가 충분하지 않으면, 실제 코드를 읽어보고 설계 의도를 파악합니다.
3. 그래도 모호하면 기획자(사용자)에게 피드백을 요청합니다.
4. 수정 시 **Surgical Changes(정밀 수정) 원칙**을 지켜 주변 코드나 서식을 손대지 않습니다.
5. 수정이 끝나면 프로그래머는 계획서의 구현 체크리스트에 스스로 완료 표시를 합니다.
6. *주의*: graphify는 실행하지 않습니다. (기획자가 `docs/wiki/` 기반 정보를 이미 수집했으므로 PLAN.md로 충분)
1. **구조 설계:** `.agent/structure.md` 읽기
2. **프론트 구현:** `.agent/frontend.md` 읽기 (대시보드 관리 UI: `.agent/plan_dashboard_management.md` 병행)
3. **백엔드 구현:** `.agent/backend.md` 읽기 (대시보드 관리 API: `.agent/plan_dashboard_management.md` 병행)
4. **마이그레이션:** `.agent/migration_plan.md` 읽기
5. **DB 스키마:** `.agent/db_schema_simple.md` 읽기
6. **프로젝트 정보:** `.agent/project_info.md` 읽기
#### 3단계: 코드 검증 (Verifier / QA)
* **목표**: 구현된 코드가 실무 기준에 맞는지 정밀 검증하고 설계 지식을 현행화하는 것.
* **동작**:
1. 코드가 작성되면 오직 수정한 코드만을 대조하여 실무 적합성 및 기술 검증을 수행합니다.
2. 검증 결과를 바탕으로 `docs/raw/verification/{YYYY-MM-DD}_verify_{기능명}.md` 보고서를 작성합니다.
3. `docs/raw/PLAN.md`에서 완료된 항목을 잘라내어(Cut) `docs/raw/plans/{YYYY-MM-DD}_plan_{기능명}.md` 파일로 이관하고, `PLAN.md`에서는 제거합니다.
4. 관련 `docs/wiki/` 문서를 현행화(`status: stable` 전환)합니다.
5. **Lint를 실행**하여 `docs/wiki/` 폴더 전체를 검사합니다. (graphify 호출 없음)
6. 발견된 모든 문제점을 해결한 후, **Skill을 통해 graphify update를 최종 1회만 실행**합니다.
---
## 7. 요약
## 2. 작업 관리 표준 (Live-PLAN 및 아카이빙)
| 항목 | 값 |
|------|-----|
| **프로그램명** | 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) |
* **현재 작업판 (`docs/raw/PLAN.md`)**:
* 현재 개발해야 할 신규 작업, 활성 작업 체크리스트, 미결 사항(Backlog)만 남겨놓는 살아있는 유일한 계획서입니다.
* 이 파일에 적힌 백로그가 완전히 비워지면 프로젝트가 최종 완료된 것으로 판단합니다.
* **완료 이력 백업 (`docs/raw/plans/`)**:
* 검증이 완료된 작업은 `PLAN.md`에서 즉시 삭제되고, `{YYYY-MM-DD}_plan_{기능명}.md` 문서로 이관 보관됩니다.
* **세션 종료 전 2중 검증**:
* **Ingest**: `docs/raw/guidelines/`, `docs/raw/plans/`, `docs/raw/verification/` 폴더의 신규 파일을 `docs/wiki/`에 반영합니다.
* **Lint**: `docs/wiki/` 폴더를 탐색하여 데이터 모순, 누락, 포맷 오류 등을 점검합니다.
---
## 3. 기술 환경 및 제약 조건 (Baseline Constraints)
### 📌 기본 기술 스택
* **Backend**: Python v3.12.7 / FastAPI / Pydantic (aiomysql 비동기 드라이버 사용, ORM 금지, Raw SQL 쿼리)
* **Frontend**: TypeScript / Node.js / HTML5 Canvas 및 WebGL (WebGL WebCAD)
* **Database**: MariaDB v10.6+ (공간 데이터는 GEOMETRY 미지원으로 인해 JSON 포맷 저장)
* **GIS Engine**: Trimesh, Whitebox, Geopandas, Shapely, Rasterio, Laspy
### 📌 코딩 규칙
* **700줄 제한**: 단일 소스코드 파일은 700줄을 초과할 수 없습니다. 초과할 경우 기능별로 파일을 분리해야 합니다.
* **Surgical Edit**: 변경해야 할 최소한의 라인만 정확하게 수정합니다.
* **포맷팅 적용**: 작업 완료 시 해당 언어의 포맷터(Python: `ruff format`, TS/CSS: `prettier`)를 반드시 실행합니다.
### 📌 지식 그래프(graphify) 운영 규칙
* **분석 대상 범위**: `docs/wiki/` 폴더만을 대상으로 합니다.
* 검색 범위: `docs/wiki/` 하위 모든 마크다운 파일
* 업데이트 범위: `docs/wiki/` 폴더만
* 따라서 프로그래머는 PLAN.md의 정보(wiki 기반)를 신뢰하고 코드 작성에만 집중 가능
* **Skill 기반 호출** (외부 cmd 명령 제거):
* 기획자: `Skill` 도구로 graphify를 능동적으로 호출하여 정보 수집
* 검증자: `Skill` 도구로 graphify update 실행
* 조회 옵션:
* `graphify query "질문 내용"` - 구조 기반 질문
* `graphify path "개념A" "개념B"` - 노드 관계 추적
* `graphify explain "개념명"` - 개별 개념 상세 설명
* **실행 권한 및 타이밍**:
* **기획자(1단계)**: graphify query/explain/path 언제든 실행 가능 (계획 수립 시)
* **프로그래머(2단계)**: graphify 실행 금지 (PLAN.md로 충분)
* **검증자(3단계)**: graphify update는 문서 갱신 후 최종 1회만 실행