life-helper/docs/design/204-flutter-bootstrap/02-drift-schema-catalog.md

02 — Catalog 테이블 8 개 Drift 정의 (#204)

부모 설계서: README.md SoT: schema/protocol.schema.json, break_protocol.schema.json, common_frame.schema.json, methodology.schema.json, frame_pattern.schema.json, reward_menu_item.schema.json, reference.schema.json, diet_pattern.schema.json.

공통 규약

• 모든 카탈로그 테이블 PK = TEXT id (ULID 또는 의미 있는 식별자).
• 모든 enum 값은 TextColumn().named('xxx').withCheckConstraint("xxx IN ('...', ...)") 로 CHECK 박는다.
• 다차원 배열·중첩 객체 (procedure[], phases[], frame_examples[], etc.) 는 JSON TEXT 단일 컬럼에 저장. 카탈로그는 read-only 라서 JSON 쿼리 불필요 (단순 read → freezed 모델로 deserialize).
• reference_ids[] 도 JSON TEXT. M:N 조인 테이블은 본 Phase 에서 만들지 않음 (실용 카운트 작음, Phase 2 에서 join 필요 시 추가).
• additionalProperties: false 인 schema 의 모든 명시 필드는 컬럼화. 단 nested object 는 JSON.

1. protocols (← protocol.schema.json)

class Protocols extends Table {
  TextColumn get id => text()();
  TextColumn get category => text().withCheckConstraint(
      "category IN ('health','meditation','motivation','habit','learning','diet')")();
  TextColumn get title => text()();
  TextColumn get titleEn => text().nullable()();
  TextColumn get what => text()();
  TextColumn get whenText => text().named('when')();
  TextColumn get dose => text()();
  TextColumn get why => text()();
  TextColumn get howJson => text()();              // List<String> JSON
  TextColumn get check => text()();
  TextColumn get caution => text().nullable()();
  TextColumn get defaultAnchorJson => text().nullable()(); // {when,after_what,where}
  TextColumn get minDoseForStart => text().nullable()();
  TextColumn get referenceIdsJson => text().nullable()();  // List<String> JSON
  TextColumn get evidenceStrength => text().nullable().withCheckConstraint(
      "evidence_strength IS NULL OR evidence_strength IN "
      "('strong_rct','meta_analysis','observational','mechanistic','expert_opinion')")();
  TextColumn get sourceDoc => text().nullable().withCheckConstraint(
      "source_doc IS NULL OR source_doc IN "
      "('huberman-protocols.md','diet-protocols.md')")();
  @override Set<Column> get primaryKey => {id};
}

인덱스:

• IDX_protocols_category(category) — UI 의 카테고리 탭 필터.

2. break_protocols (← break_protocol.schema.json)

class BreakProtocols extends Table {
  TextColumn get id => text()();
  TextColumn get category => text().withCheckConstraint(
      "category IN ('alcohol','nicotine','porn_masturbation','social_media',"
      "'sugar','caffeine','cannabis','behavioral')")();
  TextColumn get title => text()();
  TextColumn get hubermanSummary => text()();
  TextColumn get frameExamplesJson => text().nullable()();      // [{level,text}]
  TextColumn get phasesJson => text()();                         // [{week,goal,...}]
  TextColumn get defaultCommonFramesJson => text()();            // ['dopamine_reset',...]
  TextColumn get toolsJson => text().nullable()();
  TextColumn get medicalWarning => text().nullable()();
  TextColumn get referenceIdsJson => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

인덱스: IDX_break_protocols_category(category) UNIQUE — break protocol 은 카테고리당 1 개.

3. common_frames (← common_frame.schema.json)

class CommonFrames extends Table {
  TextColumn get id => text().withCheckConstraint(
      "id IN ('dopamine_reset','urge_surf','environment_design',"
      "'relapse_recovery','recovery_stack')")();
  TextColumn get title => text()();
  TextColumn get what => text()();
  TextColumn get why => text()();
  TextColumn get dose => text().nullable()();
  TextColumn get howJson => text().nullable()();
  TextColumn get check => text()();
  TextColumn get applicableBreakCategoriesJson => text().nullable()();
  TextColumn get referenceIdsJson => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

행 수 시드 = 5 (CommonFrameId enum 5 값).

4. methodologies (← methodology.schema.json)

class Methodologies extends Table {
  TextColumn get id => text()();
  TextColumn get name => text()();
  TextColumn get originator => text()();
  TextColumn get oneLineDefinition => text()();
  TextColumn get coreUnit => text()();
  TextColumn get procedureJson => text().nullable()();
  TextColumn get toolsJson => text().nullable()();
  TextColumn get strengthsJson => text().nullable()();
  TextColumn get weaknessesJson => text().nullable()();
  TextColumn get goodFor => text().nullable()();
  IntColumn get hubermanFitScore => integer().withCheckConstraint(
      "huberman_fit_score BETWEEN 1 AND 5")();
  BoolColumn get isCoreEngine => boolean().withDefault(const Constant(false))();
  TextColumn get referenceIdsJson => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

인덱스: IDX_methodologies_core(is_core_engine) partial WHERE true — 핵심 엔진 3 개 (atomic_habits, tiny_habits, implementation_intentions) 빠른 조회.

5. frame_patterns (← frame_pattern.schema.json)

class FramePatterns extends Table {
  TextColumn get id => text()();
  TextColumn get domain => text().nullable().withCheckConstraint(
      "domain IS NULL OR domain IN ('food','drink','smoking','screen','porn',"
      "'sleep','exercise','general')")();
  TextColumn get avoidanceKeyword => text()();
  TextColumn get l0Example => text()();
  TextColumn get l1SimpleReplace => text().nullable()();
  TextColumn get l2Suggestion => text()();
  TextColumn get l3Identity => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

인덱스: IDX_frame_patterns_keyword(avoidance_keyword) — detectAvoidanceKeywords 가 사전 검색.

6. reward_menu_items (← reward_menu_item.schema.json)

class RewardMenuItems extends Table {
  TextColumn get id => text()();
  TextColumn get tierRecommended => text().withCheckConstraint(
      "tier_recommended IN ('T0','T1','T2','T3','T4')")();
  TextColumn get title => text()();
  TextColumn get description => text().nullable()();
  IntColumn get estimatedCostKrwMin => integer().nullable()();
  IntColumn get estimatedCostKrwMax => integer().nullable()();
  BoolColumn get isEffortTied => boolean().nullable()();
  TextColumn get tagsJson => text().nullable()();
  TextColumn get avoidForBreakHabitsJson => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

인덱스: IDX_reward_menu_tier(tier_recommended).

7. references (← reference.schema.json)

class References extends Table {
  TextColumn get id => text()();
  TextColumn get kind => text().withCheckConstraint(
      "kind IN ('paper','podcast_episode','book','url','korean_explainer')")();
  TextColumn get title => text()();
  TextColumn get authorsJson => text().nullable()();
  IntColumn get year => integer().nullable().withCheckConstraint(
      "year IS NULL OR (year BETWEEN 1900 AND 2100)")();
  TextColumn get journal => text().nullable()();
  TextColumn get doi => text().nullable()();
  TextColumn get url => text().nullable()();
  IntColumn get episodeNumber => integer().nullable()();
  TextColumn get publisher => text().nullable()();
  TextColumn get evidenceStrength => text().nullable().withCheckConstraint(
      "evidence_strength IS NULL OR evidence_strength IN "
      "('strong_rct','meta_analysis','observational','mechanistic','expert_opinion')")();
  BoolColumn get verified => boolean().nullable()();
  TextColumn get note => text().nullable()();
  @override Set<Column> get primaryKey => {id};
}

인덱스: IDX_references_kind(kind), IDX_references_doi(doi) partial WHERE doi IS NOT NULL.

8. diet_patterns (← diet_pattern.schema.json)

OQ-3 결정 (2026-06-11): protocol(category='diet') 와 분리된 별도 카탈로그. 의견 분열 영역의 합리적 선택지 (지중해/케토/TRE/식물성/한식) — 단일 정답 없음, 사용자 체질·문화에 맞춰 조합 대상.

class DietPatterns extends Table {
  TextColumn get id => text()();
  TextColumn get name => text()();
  TextColumn get core => text()();
  TextColumn get strengthsJson => text().nullable()();             // List<String> JSON
  TextColumn get weaknessesJson => text().nullable()();            // List<String> JSON
  TextColumn get evidenceStrength => text().withCheckConstraint(
      "evidence_strength IN ('strong','moderate','mixed','weak')")();
  TextColumn get koreanContextFit => text().nullable().withCheckConstraint(
      "korean_context_fit IS NULL OR korean_context_fit IN ('high','medium','low')")();
  TextColumn get starterLeversJson => text().nullable()();         // List<String> JSON, ≤3 권장
  TextColumn get medicalWarning => text().nullable()();
  TextColumn get linkedProtocolIdsJson => text().nullable()();     // List<String> JSON, protocol(category='diet') id 참조
  TextColumn get referenceIdsJson => text().nullable()();          // List<String> JSON
  @override Set<Column> get primaryKey => {id};
}

인덱스:

• IDX_diet_patterns_evidence(evidence_strength) — UI 의 "근거 강한 순" 정렬 / 필터.
• IDX_diet_patterns_kfit(korean_context_fit) partial WHERE korean_context_fit IS NOT NULL — 한국 식문화 친화도 필터.

linked_protocol_ids 는 JSON TEXT 로 유지. M:N 조인 테이블 미생성 (행 수 작음 — diet_pattern = 5, linked protocol ≤ 6). Phase 2 에서 조인 쿼리 빈도 ↑ 시 정규화 검토.

시드 카운트 추산 (05-seed-data.md 와 sync)

테이블	추산 행 수	비고
references	~50	huberman §8 + methodologies §출처 + breaking §5 + diet §7 합계
protocols	~34	huberman 28 (§1.9 stub 제외) + diet 1.1~1.6 (6)
break_protocols	8	알코올/니코틴/포르노/SNS/설탕/카페인/대마/행동
common_frames	5	dopamine_reset/urge_surf/environment_design/relapse_recovery/recovery_stack
methodologies	21	habit-todo-methodologies.md §1~§21
frame_patterns	~30	habit-todo-methodologies.md "흔한 끊기 목표 변환 30선"
reward_menu_items	~30	habit-todo-methodologies.md "권장 리워드 메뉴 30선"
diet_patterns	5	nutrition/diet-protocols.md §2 (mediterranean / low_carb_keto / tre_if / plant_based / k_diet)

OQ-3 결정 (2026-06-11): diet §2 의 식이 패턴 5 개는 별도 diet_patterns 카탈로그로 분리 (위 §8). protocols(category='diet') 는 diet §1 의 원칙 6 항목만 담는다 (두 카탈로그가 linked_protocol_ids 로 약한 연결).

카탈로그는 read-only

• 모든 카탈로그 테이블에 대한 INSERT 는 SeedImporter 와 마이그레이션만 수행.
• App 코드 (features/) 에서는 SELECT 만.
• 사용자 커스텀 protocol 은 v2 의 user_protocol 별도 테이블 (out of scope).