디자인 저장소 v3 카드 구조

문장형 판단과 값형 속성, 근거 유형, 필드별 신뢰도, basis, raw_refs를 기준으로 정리한 구조 문서입니다.

v3 구조 홈Markdown 원본

문서 원본

# 디자인 저장소 v3 카드 구조

v3의 목적은 디자인 사례를 "근거가 붙은 지식 카드"로 저장하는 것입니다.  
사람이 raw YAML을 열어도 읽을 수 있어야 하고, RAG는 문장형 판단과 값형 속성을 함께 검색해야 하며, 필요하면 원본 자료로 되돌아가 검증할 수 있어야 합니다.

## 핵심 변화

| v2 | v3 |
| --- | --- |
| 모든 값을 `value`, `values` 또는 `statement`로 혼용 | 문장형 판단은 `statement`, 분류·키워드는 `value/values` |
| `source_label` | `grounding` |
| `confidence: 높음/중간/낮음` | 필드별 `confidence: Gold/Silver/Bronze/No data` |
| `quote_snippets`, `evidence`, `source_passages` | 판단 안의 `basis`로 흡수 |
| `quote_id`, `evidence_id`, `passage_id` 추적 | `basis.source_ref`와 `basis.locator`로 원본 위치 표시 |
| 빈 `정보 없음` 필드 반복 | 본문에서는 생략하고 `missing_fields`에만 기록 |
| raw HTML, 원문 전체, 로그가 카드 안에 섞임 | `raw_refs`로 카드 밖 원본 파일 참조 |

## 필드 타입

8가지 카테고리와 설계 이유의 하위 속성은 모두 문장으로 만들지 않습니다.  
설명과 논리가 필요한 곳만 `statement field`로 저장하고, 분류·키워드·CMF처럼 검색과 필터에 쓰는 값은 `structured field`로 저장합니다.

### statement field

문제, 의도, 해결 방식처럼 이유와 관계를 설명해야 하는 필드입니다.

```yaml
statement: 사람이 읽는 완성 문장
tags:
  - RAG/필터/매핑용 짧은 값
grounding: original_text | original_plus_inference | image_observation | image_plus_inference | inference | no_data
confidence: Gold | Silver | Bronze | No data
basis:
  - quote: 짧은 원문 인용
    source_ref: raw/behance/newbe/source.txt
    locator: description paragraph 1
```

주요 사용처:

- `summary.one_line`
- `summary.why_it_matters`
- `problem.problem_definition`
- `problem.tension`
- `design_logic.perceived_problem`
- `design_logic.intent`
- `design_logic.solution`
- `design_logic.user_experience`
- `design_logic.reusable_principle`

### structured field

제품 유형, 사용자군, 색상, 소재, 형태 키워드처럼 값 자체가 중요한 필드입니다.

```yaml
value: 개인용 헤어 스타일링 스테이션
tags:
  - 헤어 스타일링
  - 퍼스널 케어
grounding: original_text
confidence: Gold
basis:
  - quote: a personal hair styling station
    source_ref: raw/behance/newbe/source.txt
    locator: description paragraph 1
```

값이 여러 개라면 `values`를 씁니다.

```yaml
values:
  - 자기표현
  - 개인화
  - 쉬운 시작
grounding: original_plus_inference
confidence: Silver
basis:
  - reasoning: 원문 설명과 사용 맥락을 바탕으로 경험 가치를 판단했습니다.
```

주요 사용처:

- `product_category`
- `user.user_group`
- `user.needs`
- `use_context.place`
- `use_context.situation`
- `experience_value.core_value`
- `experience_value.user_effect`
- `form_strategy.shape_keywords`
- `form_strategy.structure`
- `form_strategy.detail_strategy`
- `problem.opportunity_area`
- `cmf`
- `technology_production.core_technology`
- `technology_production.interface`

### basis 원칙

`basis`는 판단을 검증하기 위한 최소 근거입니다. 근거를 다시 요약하지 않습니다.

- 원문 근거: `quote`
- 이미지 근거: `observation`
- 추론 근거: `reasoning`

`summary`는 카드 상단 요약 묶음에서만 쓰고, `basis` 안에는 쓰지 않습니다.

### grounding 정의

| 값 | 뜻 | 사용처 |
| --- | --- | --- |
| `original_text` | 원문에 직접 적힌 내용 | 사실 확인, 보고서 근거 |
| `original_plus_inference` | 원문 단서가 있고 해석이 일부 들어간 내용 | 리서치 문장, 사용자/문제 해석 |
| `image_observation` | 이미지에서 직접 관찰한 내용 | 형태, CMF, 구성 방식 |
| `image_plus_inference` | 이미지 관찰에 해석이 일부 들어간 내용 | 형태 전략, 사용 맥락 추정 |
| `inference` | 원문/이미지 단서를 바탕으로 확장한 판단 | 디자인 매핑, 재사용 원칙 |
| `no_data` | 근거가 없거나 확인할 수 없음 | 본문에는 보통 저장하지 않음 |

### confidence 정의

Gold/Silver/Bronze는 카드 전체의 총합 점수가 아니라 각 필드의 근거 등급입니다.  
카드 전체 상태는 `quality_summary`에서 필드별 등급 분포와 검수 필요 여부로 따로 계산합니다.

| 값 | 뜻 |
| --- | --- |
| `Gold` | 원문에 직접 있고 해석 여지가 작음 |
| `Silver` | 원문 또는 이미지 단서가 있지만 해석이 일부 들어감 |
| `Bronze` | 이미지 관찰 또는 약한 추론에 가까움 |
| `No data` | 확인된 정보가 없음 |

## 카드 최상위 구조

```yaml
schema: piix.design_knowledge.card
card_version: "3.0"
card_id:

identity:
  product_name:
  brand:
  designers:
  studio:
  source_url:
  source_type:
  collected_at:

summary:
  one_line:
  why_it_matters:

knowledge:
  product_category:
  user:
  use_context:
  problem:
  experience_value:
  form_strategy:
  cmf:
  technology_production:

design_logic:
  perceived_problem:
  intent:
  solution:
  key_design_choices:
  user_experience:
  reusable_principle:

quality_summary:
  field_count:
  confidence_distribution:
  grounding_distribution:
  missing_field_count:
  review_status:

raw_refs:
  source_card_file:
  raw_text_file:
  raw_html_file:
  images_dir:
  ocr_file:
  scrape_log:
  run_log:
  index_file:

missing_fields:
```

## 8가지 카테고리와 하위 속성

### product_category(제품 카테고리)

- `main_category(대분류)`
- `product_type(구체 제품유형)`
- `sub_category(하위 카테고리)`
- `adjacent_domain(인접 도메인)`

### user(사용자)

- `user_group(사용자군)`
- `persona(페르소나)`
- `skill_level(숙련도)`
- `needs(욕구)`
- `things_to_avoid(회피하고 싶은 것)`

### use_context(사용 맥락)

- `place(사용 공간)`
- `situation(사용 상황)`
- `moment(사용 순간)`
- `frequency(사용 빈도)`
- `surrounding_environment(주변 환경)`

### problem(문제)

- `problem_definition(문제 정의)`
- `pain_points(불편 지점)`
- `tension(긴장/충돌)`
- `opportunity_area(기회 영역)`
- `limits_of_existing_solution(기존 방식의 한계)`

### experience_value(경험 가치)

- `core_value(핵심 가치)`
- `emotional_tone(정서 톤)`
- `user_effect(사용자 효과)`
- `before_after(전후 변화)`
- `brand_experience(브랜드 경험)`

### form_strategy(형태 전략)

- `shape_keywords(형상 키워드)`
- `structure(구성 방식)`
- `volume_language(볼륨 언어)`
- `detail_strategy(디테일 전략)`
- `visual_hierarchy(시각적 위계)`
- `product_typology(제품 유형/전형)`

### cmf(CMF)

- `color.main_color(주 색상)`
- `color.accent_color(보조 색상)`
- `color.tone(톤)`
- `color.contrast(대비)`
- `material.main_material(주 소재)`
- `material.secondary_material(부 소재)`
- `material.structural_material(구조 소재)`
- `material.surface_material(표면 소재)`
- `material.transparent_material(투명 소재)`
- `material.flexible_material(유연 소재)`
- `finish.surface_finish(표면 마감)`
- `finish.gloss(광택)`
- `finish.texture(질감)`
- `finish.touch(촉감)`
- `finish.processing_feel(가공 느낌)`

### technology_production(기술/생산 선택)

- `core_technology(핵심 기술)`
- `internal_components(내부 구성요소)`
- `structure_type(구조 타입)`
- `interface(인터페이스)`
- `production_method(생산 방식)`
- `manufacturing_hint(제조 힌트)`
- `constraints(제약 조건)`
- `safety_durability(안전/내구 조건)`

## 설계 이유 흐름

설계 이유는 디자이너, 브랜드, 평가자가 바라본 문제-의도-해결 방식-사용자 경험을 문장으로 저장합니다.

- `perceived_problem(바라본 문제)`
- `intent(의도)`
- `solution(해결 방식)`
- `key_design_choices(주요 디자인 선택)`
- `user_experience(사용자 경험)`
- `reusable_principle(재사용 가능한 원칙)`

## RAG 인덱싱 원칙

- 기본 검색 대상: `statement`, `value`, `values`, `tags`, `basis.quote`, `basis.observation`, `basis.reasoning`
- 원문 기반 모드: `grounding=original_text`만 사용
- 추론 포함 모드: `original_text`, `original_plus_inference`, `image_observation`, `image_plus_inference`, `inference` 사용
- 필터/가중치 우선 필드: `problem`, `user`, `use_context`, `experience_value`, `form_strategy`, `cmf`, `design_logic`
- 카드 전체 품질 판단: `quality_summary.confidence_distribution`, `quality_summary.missing_field_count`, `quality_summary.review_status`
- raw 원문 전체, HTML, 로그는 기본 검색 대상에서 제외

## 카드 본문에서 뺄 것

- `quote_snippets`
- `source_passages`
- `evidence`
- `quote_id`
- `evidence_id`
- `passage_id`
- 빈 `정보 없음` 하위 필드
- raw HTML 전문
- 원문 전문
- 전체 이미지 목록
- 실행 로그 전문

필요하면 위 자료는 `raw_refs`에서 파일로 연결합니다.