# 기록 `.md` 의 어디가 Studio 의 어느 칸인가

## 세 자리

| 기록 `.md` | Studio |
|---|---|
| frontmatter | 메타데이터. 화면 칸이 아니다 |
| 제목 바로 아래 첫 문단 | **`요약` 칸** |
| `## <이름>` | **같은 이름의 칸** |

`## 요약` 이라는 절을 만들지 않는다 — Studio 에 그런 칸이 없어 통째로 사라진다. `## 출처` 도
칸이 아니다. 원본 경로는 frontmatter 의 `source` 에 있다.

## 종류마다의 칸

| 종류 | 기록 `.md` 의 `##` 이름 | 본문 |
|---|---|---|
| **Case** | `관계` · `문제` · `결론` · `검증 환경` · `재현 조건` · `본문` | 있음 |
| **Concept** | `관계` · `본문` | 있음 |
| **Reference** | `관계` · `목적` · `규칙` · `적용 조건` · `예외` · `예시` | 없음 |
| **Question** | `관계` · `사실` · `가정` · `미지수` · `제약` · `선택지` · `다음 검증` | 없음 |
| **Decision** | **`근거`** · `결정문` · `판단 이유` · `영향` | 없음 |

**Decision 만 관계 절 이름이 `근거` 다.** 그리고 근거가 1개 이상 없으면 게시가 거절된다.

## 화면의 라벨은 기록의 절 이름과 다르다

**이것이 이 문서에서 가장 자주 틀리는 자리다.** 위 표는 기록 `.md` 가 쓰는 이름이고,
편집 화면의 라벨은 다른 말을 쓴다. 그리고 `/studio/documents/new` 의 종류 카드에 적힌 요약
(`목적 · 규칙 · 적용 조건 · 예외 · 예시`)은 **카드 문구이지 편집 화면의 라벨이 아니다.**

Reference 에서 실제로 확인한 대응이다.

| 기록의 `##` | 편집 화면의 라벨 |
|---|---|
| `목적` | **`이 기준을 쓰는 이유`** |
| `규칙` | **`판단 기준`** — 제목과 본문 두 칸이 한 줄이다 |
| `적용 조건` | **`적용할 때`** |
| `예외` | **`예외와 주의`** |
| `예시` | `예시` |
| `관계` | `관계` |

종류 이름도 자리마다 다르다. 상태 레일은 Reference 를 **`적용 기준`** 이라고 부르고,
`새 문서` 화면의 라디오는 `Reference` 다.

**화면을 먼저 스냅샷으로 읽고 그 라벨을 쓴다.** 이 표를 외워서 넣지 않는다 — 화면이 바뀌면
표가 먼저 낡는다.

## 기록에 없는데 화면에 있는 칸

| 칸 | 무엇 |
|---|---|
| `축` | 주제 안의 변이(SPA · Mediator · BFF · Forward-Auth). **주제를 고른 뒤에 나타난다.** 안 고르면 주제 공통 기록이 된다 |
| `마지막 검증일` | 기록의 `verifiedOn` 이다. 없으면 비워 둔다 |

**근거가 없으면 비워 둔다.** `verifiedOn` 이 없는 채로 저장하면 미리보기에 「마지막 검증」 절이
값 없이 뜬다. 그것은 날짜를 지어내는 것보다 낫다 — 게시 전에 사람이 채울지 정한다.

## frontmatter 에서 화면으로 가는 값

| frontmatter | 어디로 |
|---|---|
| `id` | 편집 주소 `/studio/documents/<id>/edit` |
| `kind` | 새 문서를 만들 때 고르는 종류 |
| `slug` · `title` | 화면 위쪽의 슬러그·제목 칸 |
| `topic` · `topicName` · `project` | 주제·프로젝트 선택 |
| `basisVersion` (Concept) | 기준 버전 칸 |
| `questionStatus` (Question) · `decisionStatus` (Decision) | 상태 선택 |
| `assets[].file` | 올릴 Asset 파일 |
| `assets[].key` | 본문 `:::evidence key` 의 저장소 쪽 이름. 올리면 서버 키로 바뀐다 |

**계약이 화면에 주는 상태와 도메인이 들고 있는 상태가 다르다.** `QuestionStatus` 는 화면에서
`OPEN`·`RESOLVED` 둘인데 도메인은 `OPEN`·`INVESTIGATING`·`PAUSED`·`RESOLVED` 넷이고,
Decision 의 도메인 `ACCEPTED` 가 화면에서는 `ADOPTED` 로 보인다. 화면에서 고른 값이 도메인
상태를 덮어쓰지는 않는다.

## 본문이 없는 세 종류

`Reference`·`Question`·`Decision` 의 칸은 **평문으로 렌더링된다.**

- 백틱과 파이프가 글자 그대로 보인다. 코드·표를 넣지 않는다
- 줄바꿈은 `<br>` 로만 살아난다
- 나열은 쉼표로 잇지 말고 `이름 : 값` 으로 줄을 나눈다

코드·표·그림이 필요하면 짝이 되는 Case 나 Concept 에 담고 `관계` 로 가리킨다.

## 본문을 넣기 전에

저장소의 `.md` 는 그림을 마크다운 이미지로 싣는다. Studio 는 `:::evidence` 를 쓴다. 바꾸는 것은
스크립트가 한다.

```bash
python3 scripts/studio-body.py <기록.md> --body-only                    # 저장소 key 그대로
python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d --body-only # 서버가 준 key 로
```

저장소 파일 자체는 고치지 않는다.

## 되돌아오는 값

저장이 끝나면 Studio 가 `id` 를 준다. 새로 만든 기록이면 frontmatter 의 `id` 와 `studio:` 를
채운다. 그 두 칸이 차면 색인이 `publication` 을 `게시됨` 으로 적는데, **그것은 「Studio 에
있다」는 뜻이고 공개됐다는 뜻이 아니다.** 공개 여부는 `status` 와 `public:` 이 말한다.