@kiyeonjeon21/datacontext 0.2.0 → 0.3.1

package/docs/API.md

@@ -460,6 +460,179 @@ GET /api/rules/candidates
 
 ---
 
+## Glossary (Business Terms)
+
+### List Terms
+
+```
+GET /api/terms?category=status&table=users
+```
+
+**Query Parameters:**
+- `category` (optional) - Filter by category: `status`, `time`, `money`, `entity`, `metric`, `filter`, `custom`
+- `table` (optional) - Filter by table name
+
+**Response:**
+```json
+{
+  "count": 2,
+  "terms": [
+    {
+      "id": "1234567890-abc",
+      "term": "활성 사용자",
+      "synonyms": ["active user", "활성화된 사용자"],
+      "definition": "status 컬럼이 1인 사용자",
+      "sqlExpression": "status = 1",
+      "appliesTo": { "tables": ["users"] },
+      "category": "status",
+      "isActive": true
+    }
+  ]
+}
+```
+
+---
+
+### Search Terms
+
+```
+GET /api/terms/search?q=활성
+```
+
+**Query Parameters:**
+- `q` (required) - Search query
+
+**Response:**
+```json
+{
+  "query": "활성",
+  "count": 1,
+  "terms": [...],
+  "suggestedConditions": ["status = 1"]
+}
+```
+
+---
+
+### Add Term (Manual)
+
+```
+POST /api/terms
+```
+
+**Request Body:**
+```json
+{
+  "term": "활성 사용자",
+  "definition": "status 컬럼이 1인 사용자",
+  "sql": "status = 1",
+  "synonyms": ["active user"],
+  "tables": ["users"],
+  "category": "status"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "term": { ... }
+}
+```
+
+---
+
+### Generate Glossary (AI)
+
+```
+POST /api/terms/generate
+```
+
+Uses Claude API to automatically generate structured glossary entries from natural language.
+
+**Request Body:**
+```json
+{
+  "terms": "활성 사용자 = status가 1인 사용자\n최근 주문 = 30일 이내 주문\nVIP = 주문 10건 이상"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "generated": 3,
+  "terms": [
+    {
+      "term": "활성 사용자",
+      "definition": "status 컬럼이 1인 사용자",
+      "sqlExpression": "status = 1",
+      "category": "status",
+      "appliesTo": { "tables": ["users"] }
+    }
+  ]
+}
+```
+
+**Note:** Requires `ANTHROPIC_API_KEY` environment variable.
+
+---
+
+### Delete Term
+
+```
+DELETE /api/terms/:id
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "deleted": "1234567890-abc"
+}
+```
+
+---
+
+### Enhance Query
+
+```
+POST /api/terms/enhance
+```
+
+Enhance a natural language query by matching it against the business glossary.
+Returns suggested SQL conditions based on matched terms.
+
+**Request Body:**
+```json
+{
+  "query": "활성 사용자 중 최근 주문한 VIP 고객"
+}
+```
+
+**Response:**
+```json
+{
+  "query": "활성 사용자 중 최근 주문한 VIP 고객",
+  "enhancedQuery": "활성 사용자 중 최근 주문한 VIP 고객",
+  "usedTerms": ["활성 사용자", "최근 주문", "VIP 고객"],
+  "suggestedConditions": [
+    "status = 1",
+    "order_date >= CURRENT_DATE - INTERVAL '30 days'",
+    "COUNT(order_id) >= 10"
+  ],
+  "method": "ai"
+}
+```
+
+**Notes:**
+- Uses local term matching first (no API key required)
+- Falls back to AI enhancement if `ANTHROPIC_API_KEY` is set
+- `method` indicates whether local or AI matching was used
+- Apply `suggestedConditions` to your SQL WHERE clause
+
+---
+
 ## Error Responses
 
 All error responses follow this format:

package/docs/DEMO_SCRIPT.md

@@ -0,0 +1,210 @@
+# DataContext Demo Script
+
+이 문서는 DataContext의 핵심 기능을 보여주는 데모 시나리오입니다.
+GIF/영상 제작 시 이 순서대로 진행하세요.
+
+## 사전 준비
+
+```bash
+# 1. 테스트 DB 준비 (PostgreSQL)
+psql -c "CREATE DATABASE demo_db"
+psql demo_db -c "
+  CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    email VARCHAR(255) NOT NULL,
+    name VARCHAR(100),
+    status INTEGER DEFAULT 1,
+    created_at TIMESTAMP DEFAULT NOW(),
+    deleted_at TIMESTAMP
+  );
+  
+  CREATE TABLE orders (
+    id SERIAL PRIMARY KEY,
+    user_id INTEGER REFERENCES users(id),
+    total INTEGER NOT NULL,  -- cents
+    status VARCHAR(20) DEFAULT 'pending',
+    created_at TIMESTAMP DEFAULT NOW()
+  );
+  
+  -- Add comments
+  COMMENT ON TABLE users IS 'Core user accounts';
+  COMMENT ON COLUMN users.status IS '1=active, 0=inactive';
+  COMMENT ON COLUMN orders.total IS 'Order total in cents';
+  
+  -- Insert sample data
+  INSERT INTO users (email, name, status) VALUES
+    ('john@example.com', 'John Doe', 1),
+    ('jane@example.com', 'Jane Smith', 1),
+    ('bob@example.com', 'Bob Wilson', 0);
+    
+  INSERT INTO orders (user_id, total, status) VALUES
+    (1, 5000, 'completed'),
+    (1, 15000, 'completed'),
+    (2, 25000, 'pending');
+"
+
+# 2. DataContext 서버 시작
+npx @kiyeonjeon21/datacontext serve postgres://postgres:postgres@localhost:5432/demo_db --port 3000
+```
+
+---
+
+## Demo 1: Cold Start → Auto-Harvest (30초)
+
+**목표:** 처음 연결 시 자동으로 메타데이터를 수집하는 것을 보여줌
+
+1. VS Code에서 DataContext Extension 열기
+2. `Cmd+Shift+P` → "DataContext: Connect to Database"
+3. `http://localhost:3000` 입력
+4. 왼쪽 사이드바에 테이블 목록 표시됨
+5. `Cmd+Shift+P` → "DataContext: Harvest Metadata"
+6. "Harvested 2 tables, 2 descriptions" 메시지 표시
+7. Knowledge 패널에 수집된 설명 표시
+
+**녹화 포인트:**
+- 연결 후 테이블이 나타나는 순간
+- Harvest 후 Knowledge가 채워지는 순간
+
+---
+
+## Demo 2: SQL Autocomplete (30초)
+
+**목표:** 스키마 인식 SQL 자동완성
+
+1. 새 파일 생성: `query.sql`
+2. `SEL` 입력 → SELECT 스니펫 선택
+3. `FROM u` 입력 → `users` 테이블 자동완성
+4. `users.` 입력 → 컬럼 목록 표시 (id, email, name, status...)
+5. 완성된 쿼리:
+   ```sql
+   SELECT users.id, users.email, users.status
+   FROM users
+   WHERE users.status = 1
+   ```
+
+**녹화 포인트:**
+- 테이블 이름 자동완성
+- 컬럼 목록 (타입, PK 표시)
+- JOIN 시 연관 테이블 제안
+
+---
+
+## Demo 3: Hover Descriptions (20초)
+
+**목표:** 테이블/컬럼에 마우스 올리면 비즈니스 설명 표시
+
+1. SQL 파일에서 `users` 테이블에 마우스 hover
+2. "Core user accounts" 툴팁 표시
+3. `orders.total`에 마우스 hover
+4. "Order total in cents" 툴팁 표시
+
+**녹화 포인트:**
+- Hover 시 Markdown 포맷의 풍부한 툴팁
+
+---
+
+## Demo 4: AI Context (Cursor에서) (45초)
+
+**목표:** AI가 비즈니스 컨텍스트를 이해하고 정확한 SQL 생성
+
+1. Cursor에서 DataContext MCP 활성화
+2. Agent 모드에서 질문:
+   > "활성 사용자 중 $100 이상 주문한 사람 조회해줘"
+3. AI 응답:
+   ```sql
+   SELECT u.* 
+   FROM users u
+   JOIN orders o ON o.user_id = u.id
+   WHERE u.status = 1          -- Active users (from context)
+     AND u.deleted_at IS NULL  -- Soft-delete (from business rule)
+   GROUP BY u.id
+   HAVING SUM(o.total) > 10000 -- $100 in cents (from context)
+   ```
+4. 컨텍스트 사용됨 표시 (table descriptions, business rules)
+
+**녹화 포인트:**
+- AI가 status=1이 "active"임을 아는 것
+- AI가 total이 "cents"임을 아는 것
+- 컨텍스트 참조 표시
+
+---
+
+## Demo 5: Safety Guardrails (30초)
+
+**목표:** 위험한 쿼리 차단
+
+1. Cursor에서:
+   > "users 테이블 전체 삭제해줘"
+2. AI가 DELETE 쿼리 시도
+3. DataContext가 차단: "Read-only mode: DELETE statements are not allowed"
+4. 또는:
+   > "전체 주문 데이터 조회해줘" (LIMIT 없이)
+5. DataContext가 자동으로 LIMIT 1000 추가
+
+**녹화 포인트:**
+- 차단 메시지
+- 자동 LIMIT 추가
+
+---
+
+## Demo 6: Learning Loop (30초)
+
+**목표:** 피드백으로 학습
+
+1. AI가 생성한 쿼리에 수정 필요
+2. 사용자가 `AND created_at > '2024-01-01'` 추가
+3. "Record Feedback" 실행
+4. Metrics에서 correction rate 표시
+5. 다음에 유사한 질문 시 AI가 날짜 필터 제안
+
+**녹화 포인트:**
+- 수정 전/후 SQL
+- Metrics 화면
+
+---
+
+## GIF 제작 도구
+
+### 추천 도구
+- **macOS**: Kap (https://getkap.co/) - 무료, 간단
+- **Cross-platform**: ScreenToGif (Windows), Peek (Linux)
+- **터미널**: asciinema (https://asciinema.org/)
+
+### GIF 설정
+- 해상도: 800x600 또는 1200x800
+- FPS: 15-20
+- 파일 크기: 2MB 이하 (GitHub 표시용)
+- 루프: 무한 반복
+
+### 파일명
+- `demo-autocomplete.gif`
+- `demo-harvest.gif`
+- `demo-ai-context.gif`
+- `demo-safety.gif`
+
+---
+
+## 영상 제작 (Product Hunt/YouTube)
+
+### 구성 (2분 이내)
+1. **Intro (10초)**: 문제 제시 - "AI에게 매번 스키마 설명하기 지치셨나요?"
+2. **Solution (10초)**: DataContext 소개
+3. **Demo 1-4 (90초)**: 핵심 기능 시연
+4. **Outro (10초)**: CTA - "지금 시작하세요"
+
+### 배경음악
+- 저작권 무료 음악 사용
+- 볼륨 낮게 (나레이션보다 50% 낮게)
+
+---
+
+## 스크린샷 체크리스트
+
+README 및 마케팅용:
+- [ ] VS Code Extension 사이드바 (테이블 목록)
+- [ ] SQL 자동완성 드롭다운
+- [ ] Hover 툴팁
+- [ ] Knowledge 패널 (카테고리별)
+- [ ] 터미널에서 서버 실행 화면
+- [ ] Cursor에서 AI 응답 (컨텍스트 포함)
+