Kanban 문제 해결

증상 원인 후보 확인 복구
컬럼이 없다 H2가 없음 Source의 ## heading H2 컬럼을 추가한다
카드가 없다 카드가 top-level list/H3 형태가 아님 H2 아래 source 구조 지원되는 list 또는 H3로 정리한다
카드를 옮길 수 없다 검색·완료·아카이브 필터로 source sibling이 숨음 이동 잠김 안내와 filter chip 필터를 초기화한 뒤 다시 이동한다
badge가 일반 텍스트다 suffix가 제목 끝에 연속으로 있지 않음 카드 제목 지원 suffix를 끝에 배치한다
날짜 badge가 잘못됐다 실제 calendar date가 아님 YYYY-MM-DD 값 유효한 날짜로 고친다
Source 위치가 예상과 다르다 저장 전 다시 전환했거나 다른 카드를 이동함 저장 상태와 문서 경로 저장 완료 후 현재 문서 Source를 연다
Hugo에서 일반 Markdown이다 저장 보기 또는 publish materialization이 Kanban이 아님 .glif/projections.json, preview diagnostic Kanban 보기를 저장하고 다시 미리본다

데이터 보존 원칙

Glif가 이동을 거절하면 성공처럼 toast만 내고 원문을 임의 위치로 옮기지 않아야 한다. 문제가 생기면 Source를 열어 현재 Markdown을 먼저 확인한다.

다음

보기모드와 Projection 상세 레퍼런스

이동 전후를 대조하는 방법

카드 이동이나 완료 toggle이 예상과 다르면 다음 순서로 source diff를 확인한다.

  1. 이동 전 Source를 복사하고 줄 번호 또는 SHA-256을 기록한다.
  2. Kanban에서 한 카드만 이동하고 저장 완료 상태를 기다린다.
  3. Source로 돌아가 해당 card의 heading/list와 부모 H2가 바뀌었는지 확인한다.
  4. 의도한 변경만 있으면 diff를 남기고, 다른 section·metadata·asset까지 바뀌었으면 즉시 undo한다.
  5. 새로고침 후 카드와 Source가 같은 상태인지 확인한다.

Kanban의 filter, 검색, 완료 토글은 현재 board session에만 영향을 주는 경우가 있다. 이동이 보이지 않는다고 Source를 수동으로 다시 정렬하면 변경을 두 번 적용할 수 있다.

입력 예제로 최소 재현하기 

# 작업 보드

## 해야 할 일
- [ ] 첫 카드
- [x] 완료된 카드

## 검토 중
### 다음 카드
- 담당: guide

이 fixture로도 컬럼·카드가 보이지 않으면 앱 상태나 문서 binding 문제일 가능성이 높다. 이 fixture가 정상이고 실제 문서만 실패하면 다음을 하나씩 추가한다.

  • H2 컬럼을 하나 더 추가
  • top-level list 또는 H3 카드 추가
  • 날짜·badge suffix 추가
  • nested list와 block을 추가

각 단계 뒤 Source diff를 확인하면 지원되지 않는 Markdown shape를 빠르게 찾을 수 있다.

이동이 거절될 때

  • 검색·완료·아카이브 filter를 모두 초기화한다.
  • 카드가 숨겨진 sibling이 아닌지 확인한다.
  • 대상 컬럼이 실제 H2인지, 카드가 해당 컬럼의 직접 자식인지 확인한다.
  • 저장 오류·읽기 전용 Scope·충돌 dialog가 있는지 확인한다.
  • 계속 거절되면 Source에서 원문을 보존한 채 오류 화면과 현재 Markdown을 함께 기록한다.

일부 이동을 허용하는 것처럼 보이더라도 원문을 추측해 재배치하지 않는다. 지원하지 않는 구조는 fail-closed로 남기고, Source에서 사람이 의도한 구조를 먼저 고친 뒤 다시 시도한다.

Hugo 결과 확인

Hugo 결과는 board의 drag 위치, 검색어, filter chip을 저장하지 않는다. publish 전에 다음을 확인한다.

  • .glif/projections.json의 기본 보기 값이 Kanban인지
  • Binder에 포함한 모든 card source가 build 입력에 있는지
  • board가 일반 Markdown으로 fallback되었다면 preview log와 진단 원인이 있는지
  • 모바일 폭에서 컬럼과 카드가 가로로 넘치지 않는지

보기모드 기능 비교표와 Desktop과 Hugo 결과 비교에서 이 차이를 다른 projection과 대조할 수 있다.

이동 오류를 캡처하는 기준

카드 이동이 실패하면 결과 board만 캡처하지 말고 입력 구조와 filter 상태를 함께 보존한다.

Kanban 카드 편집과 이동 대상의 현재 상태

이동 후 Source 순서와 board 결과를 대조하는 화면

  1. 이동 전 column·card와 검색/filter chip을 캡처한다.
  2. 한 카드만 이동하고 저장 상태를 기다린다.
  3. board와 Source에서 H2·list 순서를 대조한다.
  4. 실패하면 filter를 초기화한 상태와 오류 문구를 다시 캡처한다.
  5. 원문 diff가 의도와 다르면 undo하고 최소 fixture에서 재현한다.