211 lines
9.4 KiB
Markdown
211 lines
9.4 KiB
Markdown
# 프로젝트 행동지침 및 기술 스택 명세 (agent.md)
|
|
|
|
## 프로젝트 & DB 정보
|
|
|
|
### 📌 프로그램명
|
|
**Aislo (아이슬로)**
|
|
- **의미**: AI (인공지능) + Slotti (핀란드어: 임도/산림 도로)
|
|
- **콘셉트**: 산림의 미래를 열어가는 인공지능 경로 설계 솔루션
|
|
|
|
---
|
|
|
|
## 1. 기술 환경 및 기본 스택 (Technical Stack Baseline)
|
|
프로젝트의 코드를 작성, 테스트 또는 검증할 환경 명확화 및 호환 기준 제시.
|
|
|
|
### A. 백엔드 프레임워크 (Python)
|
|
* **Runtime:** Python v3.12.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 [파일명]` 실행
|
|
* **외부 라이브러리 활용:** 외부 라이브러리 활용 시 프로젝트에 맞춰 호환 라이브러리 선정하고, 불필요한 함수는 작성하지 않도록 최소화.
|
|
* **서버실행은 사용자가 실행:** 필요한 경우 의존성 설치까지는 OK, 단 서버실행은 사용자가 진행
|
|
|
|
---
|
|
|
|
## 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 파싱 후 기하 연산
|
|
|
|
### 4.5 역할 기반 접근 제어 (RBAC - Role-Based Access Control)
|
|
|
|
**3가지 사용자 역할:**
|
|
|
|
| 역할 | 영문 | 설명 | 접근 권한 |
|
|
|------|------|------|---------|
|
|
| 시스템 관리자 | SYSTEM_ADMIN | 최고 관리자 | 전체 회사/사용자/프로젝트 조회 및 관리 |
|
|
| 회사 관리자 | ADMIN | 회사의 주요 아이디 (초기 로그인) | 회사 내 팀원/프로젝트 관리, 가입 요청 승인 |
|
|
| 일반 사용자 | USER | 팀원 | 개인 프로젝트 생성/수정, 워크플로우 진행 |
|
|
|
|
**회사 마스터 (is_master) 플래그:**
|
|
- TRUE: 회사 생성자 또는 ADMIN 역할 (팀원 승인/거부 권한)
|
|
- FALSE: 일반 팀원
|
|
|
|
**사용자 상태 생명주기:**
|
|
```
|
|
PENDING_EMAIL (임시)
|
|
↓ (이메일 인증)
|
|
NO_COMPANY (로그인 가능, 회사 미연결)
|
|
↓ (회사 생성 또는 참여 신청)
|
|
PENDING (승인 대기) 또는 ACTIVE (회사 연결 완료)
|
|
↓
|
|
ACTIVE (모든 기능 접근)
|
|
↓ (퇴사/비활성화)
|
|
INACTIVE 또는 REJECTED
|
|
```
|
|
|
|
---
|
|
|
|
## 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/plan_register_split.md` — B01_Dashboard 설계 및 역할별 기능
|
|
- `.agent/plan_register_split_validation.md` — 검증 항목 및 테스트 체크리스트
|
|
|
|
2. **구조 설계:** `.agent/structure.md` 읽기
|
|
- 폴더/파일 명명 규칙
|
|
- 전체 디렉토리 트리 구조
|
|
|
|
3. **DB 스키마:** `.agent/db_schema.md` 읽기
|
|
- 사용자/회사/조직 테이블 (5개)
|
|
- 프로젝트 및 워크플로우 테이블
|
|
- 테이블 관계도
|
|
|
|
4. **백엔드 구현:** `.agent/backend.md` 읽기
|
|
- 아키텍처 및 라우팅
|
|
- DB 및 MariaDB 설정
|
|
- 인증 시스템 (로그인/역할/인가)
|
|
- 역할 기반 접근 제어 (RBAC)
|
|
|
|
5. **프론트 구현:** `.agent/frontend.md` 읽기
|
|
- UI 요소 및 레이아웃 제약
|
|
- 인증 및 라우팅 가드
|
|
- 역할 기반 대시보드 렌더링
|
|
|
|
6. **마이그레이션:** `.agent/migration_plan.md` 읽기 (필요 시)
|
|
|
|
7. **프로젝트 정보:** `.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) |
|
|
| **테이블 수** | 23개 (조직/인증 5개 포함) |
|
|
| **폴더 구조** | 워크플로우 기반 (B03~B09) |
|
|
| **인증 방식** | HttpOnly Secure 세션 쿠키 |
|
|
| **사용자 역할** | SYSTEM_ADMIN, ADMIN, USER (3가지) |
|
|
| **대시보드** | B01_Dashboard (역할별 동적 렌더링) |
|
|
|
|
## graphify
|
|
|
|
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
|
|
|
|
Rules:
|
|
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
|
|
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
|
|
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
|
|
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
|