freelang-editor 11.7.4

package/docs/AKL_ARCHITECTURE.md

@@ -0,0 +1,228 @@
+# AKL 마이크로서비스 아키텍처 문서
+
+**작성일**: 2026-05-07  
+**언어**: FreeLang v11  
+**총 서비스**: 24개 | **총 코드**: ~11,000줄 | **총 API**: ~450개 엔드포인트
+
+---
+
+## 1. 서비스 전체 목록
+
+| 서비스 | 포트 | 역할 | DB | 코드 |
+|--------|------|------|----|------|
+| **akl-api** | 39000 | 중앙 인증 허브, 계약/고객/상품 | MariaDB | 357줄·16 라우트 |
+| **akl-admin** | 39002 | 시스템 마스터 콘솔 | SQLite | 233줄·12 라우트 |
+| **akl-storage** | 39001 | 파일 & 오브젝트 스토리지 | SQLite | 314줄·14 라우트 |
+| **akl-audit** | 39006 | 감사 로그 센터 | **KimDB** | 151줄·7 라우트 |
+| **akl-crm** | 39010 | 영업 파이프라인 관리 | **KimDB** | 1433줄·44 라우트 |
+| **akl-estimate** | 39012 | 견적서 관리 | **KimDB** | 196줄·8 라우트 |
+| **akl-inventory** | 39014 | 재고 & WMS | SQLite | 485줄·20 라우트 |
+| **akl-project** | 39016 | 프로젝트 & 태스크 관리 | **KimDB** | 197줄·10 라우트 |
+| **akl-shop** | 39020 | 쇼핑몰 (내부 운영) | **KimDB** | 187줄·10 라우트 |
+| **akl-partner** | 39025 | 외주 기술자 포털 | **KimDB** | 144줄·8 라우트 |
+| **akl-account** | 39026 | 통합 계정관리 (My Page) | SQLite | 153줄·8 라우트 |
+| **akl-hike** | 39061 | 단체 등산 + 정복 지도 | SQLite | 346줄·30 라우트 |
+| **akl-move** | 39060 | 걷기/달리기 GPS 트래커 | SQLite | 332줄·28 라우트 |
+| **akl-writer** | 39043 | 장편 집필 도구 | SQLite | 527줄·35 라우트 |
+| **akl-base** | 40090 | BaaS (Supabase 대체) | MariaDB | 1934줄·65 라우트 |
+| **akl-aws** | 40300 | AWS Lambda/IAM 게이트웨이 | SQLite | 380줄·8 라우트 |
+| **akl-aws-data** | 40301 | DynamoDB/S3 제어 | SQLite | 450줄·12 라우트 |
+| **akl-aws-ai** | 40302 | Rekognition/Comprehend | SQLite | 484줄·13 라우트 |
+| **akl-cloud** | 40310 | GCP/AWS/Azure 멀티클라우드 | SQLite | 533줄·17 라우트 |
+| **akl-bigwash** | 40320 | BigWash AWS 통합 | SQLite | 590줄·12 라우트 |
+| **akl-deploy** | 40325 | FL → Lambda CI/CD | SQLite | 629줄·14 라우트 |
+| **akl-iam** | 40330 | 자체 자격증명 발급 | SQLite | 396줄·14 라우트 |
+| **akl-lib** | — | 공통 라이브러리 | — | 75줄 |
+| **akl-frontends** | — | React/Vue 클라이언트 | — | TS 152개 |
+
+---
+
+## 2. 포트 레지스트리
+
+```
+39000 — akl-api       (인증 허브)
+39001 — akl-storage   (파일 스토리지)
+39002 — akl-admin     (시스템 콘솔)
+39006 — akl-audit     (감사 로그)
+39010 — akl-crm       (영업)
+39012 — akl-estimate  (견적)
+39014 — akl-inventory (재고)
+39016 — akl-project   (프로젝트)
+39020 — akl-shop      (쇼핑몰)
+39025 — akl-partner   (파트너)
+39026 — akl-account   (계정)
+39043 — akl-writer    (집필)
+39060 — akl-move      (GPS 트래커)
+39061 — akl-hike      (등산)
+
+40090 — akl-base      (BaaS)
+40300 — akl-aws       (AWS 게이트웨이)
+40301 — akl-aws-data  (DynamoDB/S3)
+40302 — akl-aws-ai    (AI/ML)
+40310 — akl-cloud     (멀티클라우드)
+40320 — akl-bigwash   (BigWash)
+40325 — akl-deploy    (CI/CD)
+40330 — akl-iam       (IAM)
+```
+
+**범위 규칙**:
+- `39000–39999` — 비즈니스 로직 서비스
+- `40000–40399` — 인프라 / 클라우드 / BaaS
+
+---
+
+## 3. 아키텍처 다이어그램
+
+```
+┌────────────────────────────────────────────────────┐
+│              akl-frontends (React/Vue)              │
+└───────────────────────┬────────────────────────────┘
+                        │ HTTP/Bearer
+         ┌──────────────▼──────────────┐
+         │    akl-api (39000)          │  ← 인증 허브
+         │    MariaDB + JWT 발급       │
+         └──────────────┬──────────────┘
+          ┌─────────────┼─────────────────────────┐
+          │             │                         │
+  ┌───────▼──────┐  ┌───▼────────────┐  ┌────────▼──────┐
+  │  KimDB 계층  │  │  SQLite 계층   │  │  Cloud 계층   │
+  │  (6 서비스)  │  │  (14 서비스)   │  │  (7 서비스)   │
+  │              │  │                │  │               │
+  │ akl-audit    │  │ akl-admin      │  │ akl-base      │
+  │ akl-crm      │  │ akl-storage    │  │ akl-aws       │
+  │ akl-estimate │  │ akl-account    │  │ akl-aws-data  │
+  │ akl-partner  │  │ akl-inventory  │  │ akl-aws-ai    │
+  │ akl-project  │  │ akl-writer     │  │ akl-cloud     │
+  │ akl-shop     │  │ akl-hike       │  │ akl-bigwash   │
+  └──────┬───────┘  │ akl-move       │  │ akl-deploy    │
+         │          │ akl-deploy     │  │ akl-iam       │
+         ▼          └────────────────┘  └───────────────┘
+   localhost:40000
+   (단일 장애점 ⚠️)
+```
+
+---
+
+## 4. 공통 패턴
+
+### 4-1. 인증 패턴 (모든 서비스 공통)
+
+모든 서비스가 요청마다 `akl-api:39000`에 토큰 검증을 요청한다.
+
+```lisp
+(define AUTH_URL "http://localhost:39000/api/auth/userinfo")
+
+(defn get-uid [$req]
+  (let [[$auth (server_req_header $req "authorization")]]
+    (if (nil? $auth) nil
+      (let [[$token (substring $auth 7 (length $auth))]
+            [$res (http_get_bearer AUTH_URL $token)]
+            [$body (json_parse (get $res "body"))]]
+        (if (get $body "success")
+          (get (get $body "data") "userId")
+          nil)))))
+```
+
+**문제**: 모든 인증된 API 요청 = HTTP 왕복 1회 추가 (akl-api 호출)
+
+### 4-2. KimDB 패턴 (6개 서비스)
+
+```lisp
+(define KIMDB "http://localhost:40000/api/c")
+
+(defn db-get [$col]
+  (let [[$res (http_get (str KIMDB "/" $col))]
+        [$body (json_parse (get $res "body"))]]
+    (or (get $body "data") [])))
+
+(defn db-post [$col $item]
+  (http_post (str KIMDB "/" $col)
+    (json_stringify {:data $item})))
+```
+
+**문제**: DB 접근 = HTTP 왕복 1회 추가 (kimdb 호출)
+
+### 4-3. SQLite 패턴 (14개 서비스)
+
+```lisp
+(define DB (sqlite-open "./data/service.db"))
+
+(defn db-query [$sql $params]
+  (sqlite-query DB $sql $params))
+```
+
+**장점**: 로컬 접근, 네트워크 왕복 없음
+
+---
+
+## 5. 문제 진단 (P0~P3)
+
+### ⚠️ P0-1: KimDB 단일 장애점
+
+| 항목 | 내용 |
+|------|------|
+| **영향 서비스** | akl-audit, akl-crm, akl-estimate, akl-partner, akl-project, akl-shop |
+| **위험도** | `localhost:40000` 다운 시 6개 서비스 전체 마비 |
+| **현황** | KimDB = 외부 HTTP API 기반 NoSQL, 스키마 없음 |
+| **해결책** | 각 서비스 → SQLite 로컬 DB 마이그레이션 |
+| **공수** | 서비스당 2~4시간, 총 ~18시간 |
+
+→ 상세: [AKL_P0_KIMDB.md](./AKL_P0_KIMDB.md)
+
+### ⚠️ P0-2: 인증 오버헤드
+
+| 항목 | 내용 |
+|------|------|
+| **영향** | 전체 24개 서비스 |
+| **현황** | 모든 요청 = akl-api HTTP 왕복 (10~30ms 추가) |
+| **해결책** | JWT 로컬 검증 (akl-lib에 `verify-jwt` 함수 추가) |
+| **공수** | 4시간 |
+
+→ 상세: [AKL_P0_AUTH.md](./AKL_P0_AUTH.md) *(예정)*
+
+### P1-1: 에러 응답 포맷 불일치
+
+서비스마다 `res-ok` / `res-err` 자체 구현. akl-lib 공통 함수 강제 사용 필요.
+
+### P1-2: 환경 URL 하드코딩
+
+`localhost:39000`, `localhost:40000` 하드코딩 → `.env` 또는 설정 파일로 분리 필요.
+
+### P2: 문서화 부족
+
+각 서비스 엔드포인트 명세 없음 → OpenAPI 자동 생성 검토.
+
+---
+
+## 6. 개선 로드맵
+
+```
+Phase 1 (P0) — 안정화
+  ├── P0-1: KimDB → SQLite 마이그레이션 (6개 서비스)
+  └── P0-2: JWT 로컬 검증 도입
+
+Phase 2 (P1) — 표준화
+  ├── P1-1: akl-lib 공통 함수 강제 (res-ok, res-err, get-uid)
+  └── P1-2: 환경 변수 중앙화
+
+Phase 3 (P2) — 문서화
+  ├── 서비스별 엔드포인트 명세
+  └── E2E 테스트 스위트
+
+Phase 4 (장기) — 확장성
+  ├── Redis 캐싱 (인증 토큰)
+  └── 서비스 메시 검토
+```
+
+---
+
+## 7. 현황 등급
+
+| 항목 | 등급 | 비고 |
+|------|------|------|
+| 코드 품질 | A | FreeLang v11 통일, 일관된 구조 |
+| 기능 완성도 | A+ | ~450 엔드포인트, 거의 모든 도메인 커버 |
+| 확장성 | B+ | 마이크로서비스 분리, 의존성 관리 미흡 |
+| 운영 안정성 | C+ | KimDB 단일 장애점, 인증 오버헤드 |
+| 문서화 | D | 이 문서가 시작점 |
+| 테스트 커버리지 | F | 0% — 별도 Sprint 필요 |

package/docs/AKL_P0_KIMDB.md

@@ -0,0 +1,215 @@
+# AKL P0-1: KimDB 단일 장애점 — 분석 & 마이그레이션 가이드
+
+**작성일**: 2026-05-07  
+**우선순위**: P0 (Critical)  
+**영향 서비스**: 6개  
+**예상 공수**: 서비스당 2~4시간, 총 ~18시간
+
+---
+
+## 1. 문제 정의
+
+### 현황
+
+6개 서비스가 외부 HTTP API인 KimDB(`localhost:40000`)에 DB로 의존한다.
+
+```
+akl-audit   (39006) ──┐
+akl-crm     (39010) ──┤
+akl-estimate(39012) ──┼──▶ KimDB (localhost:40000) ← 단일 장애점
+akl-partner (39025) ──┤
+akl-project (39016) ──┤
+akl-shop    (39020) ──┘
+```
+
+### 위험 시나리오
+
+```
+KimDB 프로세스 다운
+  → 6개 서비스 모든 DB 쓰기/읽기 실패
+  → HTTP 500 또는 빈 데이터 반환
+  → 서비스 무응답
+```
+
+### 현재 패턴 (공통)
+
+```lisp
+(define KIMDB "http://localhost:40000/api/c")
+
+;; 읽기: HTTP GET → JSON 파싱 → data 추출
+(defn db-get [$col]
+  (let [[$res (http_get (str KIMDB "/" $col))]
+        [$body (json_parse (get $res "body"))]]
+    (or (get $body "data") [])))
+
+;; 쓰기: HTTP POST
+(defn db-post [$col $item]
+  (http_post (str KIMDB "/" $col)
+    (json_stringify {:data $item})))
+```
+
+**추가 문제**: DB 접근마다 HTTP 왕복 (10~30ms) → 쿼리 누적 시 레이턴시 급증
+
+---
+
+## 2. 서비스별 컬렉션 목록
+
+| 서비스 | KimDB 컬렉션 | 역할 |
+|--------|------------|------|
+| **akl-audit** | `audit_logs` | 감사 로그 |
+| **akl-crm** | `crm_contacts`, `crm_events`, `users` | 고객, 이벤트, 사용자 |
+| **akl-estimate** | `akl_estimates` | 견적서 |
+| **akl-partner** | `partner_profiles`, `partner_assignments`, `partner_earnings` | 파트너 |
+| **akl-project** | `proj_projects`, `proj_tasks` | 프로젝트, 태스크 |
+| **akl-shop** | `shop_products`, `shop_orders`, `shop_cart` *(추정)* | 상품, 주문 |
+
+---
+
+## 3. 마이그레이션 전략
+
+### 목표 아키텍처
+
+KimDB HTTP 의존 → SQLite 로컬 파일 DB
+
+```
+각 서비스
+  ├── ./data/service.db   (SQLite)
+  └── app/server.fl       (db-get/db-post → sqlite-query)
+```
+
+### SQLite 헬퍼 표준 (교체 후 공통 패턴)
+
+```lisp
+;; KimDB 헬퍼 제거 후 SQLite 교체
+(define DB (sqlite-open "./data/service.db"))
+
+;; db-get: 전체 목록
+(defn db-get [$table]
+  (sqlite-query DB (str "SELECT * FROM " $table) []))
+
+;; db-get-by-id: ID로 단건 조회
+(defn db-get-by-id [$table $id]
+  (let [[$rows (sqlite-query DB
+          (str "SELECT * FROM " $table " WHERE id = ?") [$id])]]
+    (if (> (length $rows) 0) (get $rows 0) nil)))
+
+;; db-post: 삽입 (JSON blob 방식)
+(defn db-post [$table $doc]
+  (let [[$id (str "id-" (now_ms))]]
+    (sqlite-exec DB
+      (str "INSERT INTO " $table " (id, data, created_at) VALUES (?,?,?)")
+      [$id (json_stringify $doc) (now_iso)])
+    (assoc $doc "id" $id)))
+
+;; db-put: 업데이트
+(defn db-put [$table $id $doc]
+  (sqlite-exec DB
+    (str "UPDATE " $table " SET data=?, updated_at=? WHERE id=?")
+    [(json_stringify $doc) (now_iso) $id])
+  $doc)
+
+;; db-delete: 삭제
+(defn db-delete [$table $id]
+  (sqlite-exec DB
+    (str "DELETE FROM " $table " WHERE id=?") [$id])
+  true)
+```
+
+### 스키마 (공통)
+
+```sql
+-- 각 컬렉션당 테이블 1개 (JSON blob 방식 — KimDB와 동일 패러다임)
+CREATE TABLE IF NOT EXISTS {table_name} (
+  id         TEXT PRIMARY KEY,
+  data       TEXT NOT NULL,          -- JSON blob
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT
+);
+```
+
+---
+
+## 4. 서비스별 마이그레이션 계획
+
+### akl-audit (39006) — 난이도: 쉬움 ⭐
+
+**변경 범위**: `KIMDB` define 제거, `db-get`/`db-post` 재구현  
+**컬렉션**: `audit_logs` 1개  
+**특이사항**: 쓰기 전용 패턴 (로그 INSERT만)
+
+```lisp
+;; Before
+(define KIMDB "http://localhost:40000/api/c")
+
+;; After
+(define DB (sqlite-open "./data/audit.db"))
+(sqlite-exec DB "CREATE TABLE IF NOT EXISTS audit_logs (id TEXT PRIMARY KEY, data TEXT, created_at TEXT)" [])
+```
+
+### akl-estimate (39012) — 난이도: 쉬움 ⭐
+
+**변경 범위**: KimDB 헬퍼 3개 함수 교체  
+**컬렉션**: `akl_estimates` 1개  
+**특이사항**: 단순 CRUD
+
+### akl-partner (39025) — 난이도: 보통 ⭐⭐
+
+**변경 범위**: KimDB 헬퍼 + 관계형 쿼리 일부  
+**컬렉션**: `partner_profiles`, `partner_assignments`, `partner_earnings` 3개  
+**특이사항**: assignments ↔ profiles 조인 패턴 있음
+
+### akl-project (39016) — 난이도: 보통 ⭐⭐
+
+**변경 범위**: KimDB 헬퍼 + 필터 쿼리  
+**컬렉션**: `proj_projects`, `proj_tasks` 2개  
+**특이사항**: tasks의 project_id FK 관계
+
+### akl-shop (39020) — 난이도: 보통 ⭐⭐
+
+**변경 범위**: KimDB 헬퍼 + 재고 차감 트랜잭션  
+**컬렉션**: 상품/주문/장바구니 3개  
+**특이사항**: 주문 시 재고 원자성 보장 필요
+
+### akl-crm (39010) — 난이도: 어려움 ⭐⭐⭐
+
+**변경 범위**: KimDB 헬퍼 전면 교체  
+**컬렉션**: `crm_contacts`, `crm_events`, `users` 3개  
+**코드량**: 1433줄 — 가장 큼  
+**특이사항**: 이벤트 집계 쿼리, 사용자 조인, 파이프라인 단계 필터
+
+---
+
+## 5. 마이그레이션 순서 (권장)
+
+```
+1단계: akl-audit   (가장 단순, 리스크 낮음)
+2단계: akl-estimate
+3단계: akl-partner
+4단계: akl-project
+5단계: akl-shop
+6단계: akl-crm     (가장 복잡, 마지막)
+```
+
+---
+
+## 6. 완료 기준
+
+- [ ] 각 서비스 `KIMDB` 참조 0개
+- [ ] `localhost:40000` 참조 0개
+- [ ] 각 서비스 `/health` 엔드포인트 정상 응답
+- [ ] 기본 CRUD 동작 확인 (수동 테스트)
+- [ ] KimDB 프로세스 중단 시 서비스 정상 유지
+
+---
+
+## 7. 롤백 계획
+
+마이그레이션 전 각 서비스 KimDB 데이터 덤프:
+
+```bash
+curl http://localhost:40000/api/c/audit_logs?limit=10000 > backup_audit_logs.json
+curl http://localhost:40000/api/c/crm_contacts?limit=10000 > backup_crm_contacts.json
+# ... 각 컬렉션별
+```
+
+문제 발생 시 `KIMDB` define 복원으로 즉시 롤백 가능.