# 허생.exe 데모 - 기술 구조

## 아키텍처 개요

```
┌─────────────────────────────────────────────────────────┐
│                    사용자 브라우저                        │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ Dashboard   │  │ Assumptions │  │ Experiment  │     │
│  │ (index)     │  │ (관리)      │  │ (상세)      │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│         └────────────────┼────────────────┘             │
│                          ↓                              │
│  ┌─────────────────────────────────────────────────┐   │
│  │              JavaScript 모듈                     │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐           │   │
│  │  │storage  │ │ models  │ │  state  │           │   │
│  │  └─────────┘ └─────────┘ └─────────┘           │   │
│  │  ┌─────────┐ ┌─────────┐                       │   │
│  │  │ deltaK  │ │   ui    │                       │   │
│  │  └─────────┘ └─────────┘                       │   │
│  └─────────────────────────────────────────────────┘   │
│                          ↓                              │
│  ┌─────────────────────────────────────────────────┐   │
│  │              LocalStorage                        │   │
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐     │   │
│  │  │assumptions│ │experiments│ │ judgments │     │   │
│  │  └───────────┘ └───────────┘ └───────────┘     │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

---

## 파일 구조

```
/demo/
├── index.html              # 대시보드 (메인 화면)
├── assumptions.html        # 가정 관리 화면
├── experiment.html         # 실험 상세 화면
├── ARCHITECTURE.md         # 이 문서
│
├── css/
│   └── style.css          # 전체 스타일
│
├── js/
│   ├── storage.js         # LocalStorage CRUD
│   ├── models.js          # 데이터 모델 + ID 생성 + 샘플 데이터
│   ├── state.js           # 실험 상태 전이 로직
│   ├── deltaK.js          # ΔK 계산 로직
│   ├── ui.js              # 공통 UI 컴포넌트
│   ├── dashboard.js       # 대시보드 로직
│   ├── assumptions.js     # 가정 관리 로직
│   └── experiment.js      # 실험 상세 로직
│
└── manual/
    ├── README.md          # 매뉴얼 인덱스
    ├── 01-concept.md      # 개념 설명
    ├── 02-quickstart.md   # 퀵스타트
    ├── 03-features.md     # 기능 상세
    └── 04-faq.md          # FAQ
```

---

## 파일별 역할

| 파일 | 역할 | 의존성 |
|------|------|--------|
| storage.js | LocalStorage CRUD, 활동 로그 | 없음 |
| deltaK.js | ΔK 계산 | storage.js |
| models.js | 데이터 생성, ID 규칙, 샘플 데이터 | storage.js, deltaK.js |
| state.js | 실험 상태 전이 | storage.js |
| ui.js | 공통 UI 컴포넌트 | state.js |
| dashboard.js | 대시보드 로직 | 전체 |
| assumptions.js | 가정 관리 로직 | 전체 |
| experiment.js | 실험 상세 로직 | 전체 |

---

## 스크립트 로드 순서

```html
<script src="js/storage.js"></script>   <!-- 1. 저장소 -->
<script src="js/deltaK.js"></script>    <!-- 2. ΔK 계산 -->
<script src="js/models.js"></script>    <!-- 3. 모델 -->
<script src="js/state.js"></script>     <!-- 4. 상태 전이 -->
<script src="js/ui.js"></script>        <!-- 5. UI -->
<script src="js/[page].js"></script>    <!-- 6. 페이지별 -->
```

순서가 중요한 이유:
- `models.js`는 `deltaK.js`의 `calculateDeltaK()` 사용
- `ui.js`는 `state.js`의 `getStateInfo()` 사용
- 페이지 JS는 모든 유틸리티 필요

---

## Kernel Lock (불변 규칙)

### ID 형식

```javascript
// Assumption: A-YYYYMMDD-xxxx
"A-20260112-x7k2"

// Experiment: HSE-XXX (순번)
"HSE-001", "HSE-002", ...

// Judgment: J-YYYYMMDD-xxxx
"J-20260112-j1k2"
```

### 상태 전이

```
Experiment:
  draft → ready → running → completed
                       ↓
                     failed
                       ↓
                    aborted

* aborted는 종료 상태 제외 어디서든 가능
```

### ΔK 계산

```javascript
Math.abs(newBelief - previousBelief) >= 0.3 ? 1 : 0
```

- 0.3 이상 변화 → ΔK +1
- 0.3 미만 변화 → ΔK +0
- Type C 가정 → ΔK 계산 제외

---

## 데이터 스키마

### Assumption

```javascript
{
  id: "A-YYYYMMDD-xxxx",
  type: "A" | "B" | "C",
  statement: "string (max 200자)",
  preBelief: 0.0 ~ 1.0,
  postBelief: null | 0.0 ~ 1.0,
  status: "unverified" | "verified" | "falsified" | "modified",
  createdAt: "ISO timestamp"
}
```

### Experiment

```javascript
{
  id: "HSE-XXX",
  hypothesis: "string",
  status: "draft" | "ready" | "running" | "completed" | "failed" | "aborted",
  assumptionIds: ["A-xxx", ...],
  budget: number,
  actualCost: number,
  createdAt: "ISO timestamp",
  startedAt: null | "ISO timestamp",
  completedAt: null | "ISO timestamp"
}
```

### Judgment

```javascript
{
  id: "J-YYYYMMDD-xxxx",
  experimentId: "HSE-XXX" | null,
  assumptionId: "A-xxx",
  previousBelief: 0.0 ~ 1.0,
  newBelief: 0.0 ~ 1.0,
  deltaK: 0 | 1,
  reasoning: "string",
  createdAt: "ISO timestamp"
}
```

### Activity Log

```javascript
{
  action: "string",
  detail: "string",
  timestamp: "ISO timestamp"
}
```

---

## LocalStorage 키

| 키 | 내용 |
|-----|------|
| `hse_assumptions` | 가정 배열 |
| `hse_experiments` | 실험 배열 |
| `hse_judgments` | 판단 기록 배열 |
| `hse_activity_log` | 활동 로그 배열 (최대 50개) |

---

## 상태 색상 매핑

### 실험 상태

| 상태 | CSS 클래스 | 색상 |
|------|-----------|------|
| draft | badge-neutral | 회색 |
| ready | badge-primary | 파랑 |
| running | badge-warning | 노랑 |
| completed | badge-success | 초록 |
| failed | badge-danger | 빨강 |
| aborted | badge-danger | 빨강 |

### 가정 상태

| 상태 | CSS 클래스 | 색상 |
|------|-----------|------|
| unverified | badge-warning | 노랑 |
| verified | badge-success | 초록 |
| falsified | badge-danger | 빨강 |
| modified | badge-primary | 파랑 |

### 가정 타입

| 타입 | CSS 클래스 | 색상 |
|------|-----------|------|
| A | type-A | 파랑 |
| B | type-B | 노랑 |
| C | type-C | 보라 |

---

## 배포

### GitHub Pages

```
Repository: dtslib1979/buddies.kr
Path: /demo
URL: https://dtslib1979.github.io/buddies.kr/demo/
```

### 로컬 테스트

```bash
cd demo
python -m http.server 8000
# http://localhost:8000
```

---

## 제한사항 (데모 버전)

1. **데이터 동기화 없음**: LocalStorage만 사용
2. **백업/복원 없음**: 브라우저 데이터 삭제 시 유실
3. **멀티 유저 없음**: 1인 사용 전용
4. **L (Lie Index)**: 항상 0 (수동 관리 필요)
5. **오프라인 전용**: 네트워크 기능 없음

---

*마지막 업데이트: 2026-01-12*