{
  "id": "627e1b0c-9450-4cb3-b0b6-6d1de1b1e175",
  "slug": "ref/khub/common-khub-직접-등록-표준-가이드-notion-우회",
  "doc_type": "ref",
  "title": "📝 KHub 직접 등록 표준 가이드 (Notion 우회)",
  "title_en": null,
  "one_liner": "# 📝 KHub 직접 등록 표준 가이드 > 최종 업데이트: 2026-02-17 KST > KHub 검색: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\") --- ## 왜 직접 등록인가 | 경로 | 방식 | 소요 | 부하 | 추천 용도 | ",
  "summary_bullets": [],
  "body_md": "# 📝 KHub 직접 등록 표준 가이드\n\n> 최종 업데이트: 2026-02-17 KST\n> KHub 검색: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\")\n\n---\n\n## 왜 직접 등록인가\n\n| 경로 | 방식 | 소요 | 부하 | 추천 용도 |\n|------|------|------|------|----------|\n| Notion 경유 | Notion 작성 → KHUB-002 동기화 | 1시간 | 높음 (방 죽음 발생) | 외부 파트너 공유 문서만 |\n| **직접 등록** | Supabase INSERT (HTTP or MCP) | **즉시** | 없음 | DevLog, 기술문서, 작업기록 |\n\n현재 문서 분포: manual 41개 vs notion 37개 — 이미 직접 등록이 과반\n\n---\n\n## 등록 방법\n\n### 방법 A: Supabase MCP (supabase-growthplatform) — 짧은 문서\n\nexecute_sql로 직접 INSERT:\n\n```sql\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '{제목}',\n  '{마크다운 내용}',\n  '{프로젝트코드}',\n  'manual',\n  'qa',\n  true,\n  '{카테고리ID}',\n  '{\"tags\": [\"태그1\", \"태그2\"], \"version\": \"1.0\"}'::jsonb\n) RETURNING id, title;\n```\n\n### 방법 B: HTTP API (bash_tool) — 긴 문서용 (권장)\n\n파일로 만든 후 curl POST:\n\n```bash\n# AP-08: API 키 조회\nSB_KEY=$(Supabase gp_admin_secrets에서 조회)\nSB_URL=\"https://ihzttwgqahhzlrqozleh.supabase.co\"\n\n# 파일 내용을 JSON 이스케이프\nCONTENT=$(cat 파일.md | python3 -c \"import sys,json; print(json.dumps(sys.stdin.read()))\")\n\n# AP-01: 3헤더 필수\ncurl -s -X POST \"${SB_URL}/rest/v1/khub_documents\" \\\n  -H \"apikey: ${SB_KEY}\" \\\n  -H \"Authorization: Bearer ${SB_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Prefer: return=representation\" \\\n  -d \"{\n    \\\"title\\\": \\\"문서 제목\\\",\n    \\\"content\\\": ${CONTENT},\n    \\\"project_code\\\": \\\"COMMON\\\",\n    \\\"source_type\\\": \\\"manual\\\",\n    \\\"environment\\\": \\\"qa\\\",\n    \\\"is_active\\\": true,\n    \\\"category_id\\\": \\\"753edf2d-171d-4edb-87a0-20fe9e875712\\\",\n    \\\"metadata\\\": {\\\"tags\\\": [\\\"태그\\\"]}\n  }\"\n```\n\n---\n\n## 필수 필드\n\n| 필드 | 값 | 설명 |\n|------|-----|------|\n| title | 문서 제목 | 이모지 포함 가능 |\n| content | 마크다운 본문 | 길이 제한 없음 |\n| project_code | COMMON, GEOCARE, DATA_ENG, PREMIUM_GEO, GEO_COMMERCE | 필수 |\n| source_type | **manual** | ⚠️ 반드시 manual (notion이면 동기화 충돌) |\n| environment | **qa** | CHECK 제약조건: qa만 허용 |\n| is_active | true | false면 검색 제외 |\n\n## 선택 필드\n\n| 필드 | 값 | 설명 |\n|------|-----|------|\n| category_id | UUID | 아래 카테고리 참조 |\n| metadata | JSONB | tags, version, author 등 |\n| source_url | URL | 원본 링크 (있으면) |\n\n## 카테고리 ID\n\n| 코드 | ID | 이름 |\n|------|-----|------|\n| GUIDE | 753edf2d-171d-4edb-87a0-20fe9e875712 | 가이드 문서 |\n| TECH | 5f5efdea-2a5d-47bb-ae70-25ee0d3ff7de | 기술 문서 |\n| PRODUCT | 8145df4d-65ce-4d8e-bdf3-c637a80d531b | 제품 전략 |\n| FAQ | b717c327-451a-44e8-a2a1-cc9c1fea42b0 | FAQ |\n\n---\n\n## DevLog 등록 템플릿\n\n### Snapshot (Tier 1) — 덮어쓰기\n\n기존 Snapshot이 있으면 UPDATE, 없으면 INSERT:\n\n```sql\n-- 기존 Snapshot 찾기\nSELECT id FROM khub_documents\nWHERE title LIKE '%DevLog Snapshot%'\n  AND project_code = '{코드}'\n  AND is_active = true;\n\n-- 있으면 UPDATE\nUPDATE khub_documents\nSET content = '{새 내용}', updated_at = now()\nWHERE id = '{기존ID}';\n\n-- 없으면 INSERT\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '📸 {프로젝트} DevLog Snapshot',\n  '{내용 — 3000자 이하}',\n  '{코드}', 'manual', 'qa', true,\n  '753edf2d-171d-4edb-87a0-20fe9e875712',\n  '{\"tags\": [\"DevLog\", \"Snapshot\"], \"tier\": \"1\"}'::jsonb\n) RETURNING id, title;\n```\n\n### Task DevLog (Tier 2) — 신규 생성\n\n```sql\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '📋 {작업명} — DevLog',\n  '{마크다운 내용}',\n  '{코드}', 'manual', 'qa', true,\n  '753edf2d-171d-4edb-87a0-20fe9e875712',\n  '{\"tags\": [\"DevLog\", \"Task\"], \"tier\": \"2\"}'::jsonb\n) RETURNING id, title;\n```\n\n---\n\n## 수정/삭제\n\n### 수정 (manual 문서만)\n\n```sql\nUPDATE khub_documents\nSET content = '{새 내용}', title = '{새 제목}', updated_at = now()\nWHERE id = '{문서ID}' AND source_type = 'manual';\n```\n\n### 비활성화 (삭제 대신)\n\n```sql\nUPDATE khub_documents\nSET is_active = false, updated_at = now()\nWHERE id = '{문서ID}';\n```\n\n---\n\n## 충돌 방지 규칙\n\n| source_type | Supabase 직접 수정 | Notion 수정 | 비고 |\n|-------------|-------------------|-------------|------|\n| manual | ✅ 자유 | ❌ 해당 없음 | 직접 등록 문서 |\n| notion | ⛔ 금지 | ✅ | 다음 동기화 시 Notion 내용으로 원복됨 |\n\n**절대 규칙**: source_type=notion 문서를 Supabase에서 직접 UPDATE하지 말 것\n\n---\n\n## 검색 확인\n\n등록 후 바로 검색 가능 (키워드 검색 즉시, 시맨틱 검색 ~30분 후):\n\n```\nkhub_search(\"{키워드}\", project_code:\"{코드}\")\nkhub_get_document(\"{반환된 ID}\")\n```\n\n---\n\n## 각 프로젝트 Instructions에 복붙할 섹션\n\n```markdown\n## KHub/DevLog 등록 규칙\n\n등록: Supabase 직접 INSERT (Notion 경유 금지 — 부하로 방 죽음 발생)\n- DB: supabase-growthplatform (ihzttwgqahhzlrqozleh)\n- source_type: 'manual' 필수\n- environment: 'qa' 필수\n- 가이드: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\")\n\nDevLog:\n- Snapshot(Tier1): 기존 문서 UPDATE (같은 제목 유지, 3000자 이하)\n- Task(Tier2): 신규 INSERT (📋 {작업명} — DevLog)\n- ⛔ Notion 경유 금지 — 직접 INSERT만 사용\n```\n",
  "related_slugs": [],
  "faq": [],
  "jsonld": null,
  "keywords": [],
  "source_id": "1e42abd4-5f4a-4b1a-acbe-8f1c33c7ca2d",
  "video_url": null,
  "duration_sec": null,
  "thumbnail_url": null,
  "image_url": null,
  "caption": null,
  "solution_slug": null,
  "captured_at": null,
  "width": null,
  "height": null,
  "created_at": "2026-08-24T11:53:44.908861+00:00",
  "updated_at": "2026-08-24T11:53:44.908861+00:00",
  "visibility": "public",
  "source_stage": "1",
  "anonymized": true,
  "source_key": "legacy-khub",
  "origin": "ingest",
  "locked": false,
  "locked_by": null,
  "locked_at": null,
  "gate_state": {
    "g1": {
      "hits": [],
      "pass": true
    },
    "g2": {
      "pass": true,
      "total": 45,
      "issues": [
        "숫자·규격 같은 검증 가능한 구체가 부족합니다",
        "핵심 요약 불릿이 3개 미만입니다",
        "Q&A 쌍이 3개 미만입니다"
      ],
      "applies": true
    },
    "g3": {
      "pass": true,
      "required": false
    },
    "stage": "1",
    "decided_at": "2026-08-24T11:53:44.334Z"
  },
  "raw_id": "42ba64af-3b3a-4365-b75e-55833ef3dc16",
  "search_text": "📝 KHub 직접 등록 표준 가이드 (Notion 우회)  # 📝 KHub 직접 등록 표준 가이드 > 최종 업데이트: 2026-02-17 KST > KHub 검색: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\") --- ## 왜 직접 등록인가 | 경로 | 방식 | 소요 | 부하 | 추천 용도 |   # 📝 KHub 직접 등록 표준 가이드\n\n> 최종 업데이트: 2026-02-17 KST\n> KHub 검색: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\")\n\n---\n\n## 왜 직접 등록인가\n\n| 경로 | 방식 | 소요 | 부하 | 추천 용도 |\n|------|------|------|------|----------|\n| Notion 경유 | Notion 작성 → KHUB-002 동기화 | 1시간 | 높음 (방 죽음 발생) | 외부 파트너 공유 문서만 |\n| **직접 등록** | Supabase INSERT (HTTP or MCP) | **즉시** | 없음 | DevLog, 기술문서, 작업기록 |\n\n현재 문서 분포: manual 41개 vs notion 37개 — 이미 직접 등록이 과반\n\n---\n\n## 등록 방법\n\n### 방법 A: Supabase MCP (supabase-growthplatform) — 짧은 문서\n\nexecute_sql로 직접 INSERT:\n\n```sql\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '{제목}',\n  '{마크다운 내용}',\n  '{프로젝트코드}',\n  'manual',\n  'qa',\n  true,\n  '{카테고리ID}',\n  '{\"tags\": [\"태그1\", \"태그2\"], \"version\": \"1.0\"}'::jsonb\n) RETURNING id, title;\n```\n\n### 방법 B: HTTP API (bash_tool) — 긴 문서용 (권장)\n\n파일로 만든 후 curl POST:\n\n```bash\n# AP-08: API 키 조회\nSB_KEY=$(Supabase gp_admin_secrets에서 조회)\nSB_URL=\"https://ihzttwgqahhzlrqozleh.supabase.co\"\n\n# 파일 내용을 JSON 이스케이프\nCONTENT=$(cat 파일.md | python3 -c \"import sys,json; print(json.dumps(sys.stdin.read()))\")\n\n# AP-01: 3헤더 필수\ncurl -s -X POST \"${SB_URL}/rest/v1/khub_documents\" \\\n  -H \"apikey: ${SB_KEY}\" \\\n  -H \"Authorization: Bearer ${SB_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Prefer: return=representation\" \\\n  -d \"{\n    \\\"title\\\": \\\"문서 제목\\\",\n    \\\"content\\\": ${CONTENT},\n    \\\"project_code\\\": \\\"COMMON\\\",\n    \\\"source_type\\\": \\\"manual\\\",\n    \\\"environment\\\": \\\"qa\\\",\n    \\\"is_active\\\": true,\n    \\\"category_id\\\": \\\"753edf2d-171d-4edb-87a0-20fe9e875712\\\",\n    \\\"metadata\\\": {\\\"tags\\\": [\\\"태그\\\"]}\n  }\"\n```\n\n---\n\n## 필수 필드\n\n| 필드 | 값 | 설명 |\n|------|-----|------|\n| title | 문서 제목 | 이모지 포함 가능 |\n| content | 마크다운 본문 | 길이 제한 없음 |\n| project_code | COMMON, GEOCARE, DATA_ENG, PREMIUM_GEO, GEO_COMMERCE | 필수 |\n| source_type | **manual** | ⚠️ 반드시 manual (notion이면 동기화 충돌) |\n| environment | **qa** | CHECK 제약조건: qa만 허용 |\n| is_active | true | false면 검색 제외 |\n\n## 선택 필드\n\n| 필드 | 값 | 설명 |\n|------|-----|------|\n| category_id | UUID | 아래 카테고리 참조 |\n| metadata | JSONB | tags, version, author 등 |\n| source_url | URL | 원본 링크 (있으면) |\n\n## 카테고리 ID\n\n| 코드 | ID | 이름 |\n|------|-----|------|\n| GUIDE | 753edf2d-171d-4edb-87a0-20fe9e875712 | 가이드 문서 |\n| TECH | 5f5efdea-2a5d-47bb-ae70-25ee0d3ff7de | 기술 문서 |\n| PRODUCT | 8145df4d-65ce-4d8e-bdf3-c637a80d531b | 제품 전략 |\n| FAQ | b717c327-451a-44e8-a2a1-cc9c1fea42b0 | FAQ |\n\n---\n\n## DevLog 등록 템플릿\n\n### Snapshot (Tier 1) — 덮어쓰기\n\n기존 Snapshot이 있으면 UPDATE, 없으면 INSERT:\n\n```sql\n-- 기존 Snapshot 찾기\nSELECT id FROM khub_documents\nWHERE title LIKE '%DevLog Snapshot%'\n  AND project_code = '{코드}'\n  AND is_active = true;\n\n-- 있으면 UPDATE\nUPDATE khub_documents\nSET content = '{새 내용}', updated_at = now()\nWHERE id = '{기존ID}';\n\n-- 없으면 INSERT\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '📸 {프로젝트} DevLog Snapshot',\n  '{내용 — 3000자 이하}',\n  '{코드}', 'manual', 'qa', true,\n  '753edf2d-171d-4edb-87a0-20fe9e875712',\n  '{\"tags\": [\"DevLog\", \"Snapshot\"], \"tier\": \"1\"}'::jsonb\n) RETURNING id, title;\n```\n\n### Task DevLog (Tier 2) — 신규 생성\n\n```sql\nINSERT INTO khub_documents (\n  title, content, project_code, source_type, environment,\n  is_active, category_id, metadata\n) VALUES (\n  '📋 {작업명} — DevLog',\n  '{마크다운 내용}',\n  '{코드}', 'manual', 'qa', true,\n  '753edf2d-171d-4edb-87a0-20fe9e875712',\n  '{\"tags\": [\"DevLog\", \"Task\"], \"tier\": \"2\"}'::jsonb\n) RETURNING id, title;\n```\n\n---\n\n## 수정/삭제\n\n### 수정 (manual 문서만)\n\n```sql\nUPDATE khub_documents\nSET content = '{새 내용}', title = '{새 제목}', updated_at = now()\nWHERE id = '{문서ID}' AND source_type = 'manual';\n```\n\n### 비활성화 (삭제 대신)\n\n```sql\nUPDATE khub_documents\nSET is_active = false, updated_at = now()\nWHERE id = '{문서ID}';\n```\n\n---\n\n## 충돌 방지 규칙\n\n| source_type | Supabase 직접 수정 | Notion 수정 | 비고 |\n|-------------|-------------------|-------------|------|\n| manual | ✅ 자유 | ❌ 해당 없음 | 직접 등록 문서 |\n| notion | ⛔ 금지 | ✅ | 다음 동기화 시 Notion 내용으로 원복됨 |\n\n**절대 규칙**: source_type=notion 문서를 Supabase에서 직접 UPDATE하지 말 것\n\n---\n\n## 검색 확인\n\n등록 후 바로 검색 가능 (키워드 검색 즉시, 시맨틱 검색 ~30분 후):\n\n```\nkhub_search(\"{키워드}\", project_code:\"{코드}\")\nkhub_get_document(\"{반환된 ID}\")\n```\n\n---\n\n## 각 프로젝트 Instructions에 복붙할 섹션\n\n```markdown\n## KHub/DevLog 등록 규칙\n\n등록: Supabase 직접 INSERT (Notion 경유 금지 — 부하로 방 죽음 발생)\n- DB: supabase-growthplatform (ihzttwgqahhzlrqozleh)\n- source_type: 'manual' 필수\n- environment: 'qa' 필수\n- 가이드: khub_search(\"KHub 직접 등록\", project_code:\"COMMON\")\n\nDevLog:\n- Snapshot(Tier1): 기존 문서 UPDATE (같은 제목 유지, 3000자 이하)\n- Task(Tier2): 신규 INSERT (📋 {작업명} — DevLog)\n- ⛔ Notion 경유 금지 — 직접 INSERT만 사용\n```\n",
  "embedding": null,
  "embedded_at": null,
  "embedding_hash": null,
  "backlinks": [],
  "html_url": "https://bizspring.ai/kb/ref/khub/common-khub-직접-등록-표준-가이드-notion-우회",
  "markdown_url": "https://bizspring.ai/kb/ref/khub/common-khub-직접-등록-표준-가이드-notion-우회.md"
}