Todo Reference 트러블슈팅

Note

Todo 본문 안에서 다른 Todo를 - refs #번호 형태로 참조하는 기능을 붙이는 과정에서, 실제로 부딪힌 문제와 판단 기준을 정리한 문서. 구현 순서보다 문제 정의, 시도 방향, 한계, 최종 상태 중심의 기록. PR

문제 정의

• Todo 본문 안에서 다른 Todo를 짧은 문법으로 참조하고 싶은 요구 존재
• 사용자는 GitHub PR처럼 #번호 중심의 입력을 기대하는 상태
• 기존 Todo 식별자는 UUID 기반이므로, 사용자 문법과 내부 식별자가 직접 연결되지 않는 구조
• MarkdownUI는 일반 Markdown 링크는 처리 가능하지만 - refs #번호 같은 예약어는 바로 이해하지 못하는 상태
• 최종적으로는 다음 조건을 만족해야 하는 상황
  • 기존 Todo 포함 전체 데이터셋에서 같은 참조 규칙 성립
  • 신규 Todo 생성 시 번호 자동 부여 필요
  • 제목 옆에 #번호 노출 필요
  • Markdown 프리뷰와 상세 본문 모두 같은 참조 표현 필요
  • 참조 항목 탭 시 관련 Todo 확인 가능해야 하는 상태

문제 1. 사용자 문법과 내부 식별자 불일치

• 사용자가 원하는 입력 형태는 #번호 같은 짧은 문법
• 기존 Todo 식별자는 UUID 기반
• 입력 문법과 저장 구조가 바로 이어지지 않는 상태

고민한 것

• 사용자가 내부 식별자를 직접 알아야 하는 구조 허용 가능 여부
• 사람이 읽는 참조값과 시스템이 쓰는 참조값의 분리 필요성
• 참조 기능 추가 이후에도 기존 저장 구조 유지 가능성

정리

• 사용자 문법은 #번호
• 내부 참조는 UUID
• 둘 사이를 이어주는 별도 숫자 식별자의 필요

문제 2. 기존 Todo에 번호가 없는 상태

• 새 Todo는 번호 부여 가능
• 기존 Todo에는 번호 부재
• refs #번호 문법이 전체 데이터셋에 대해 성립하지 않는 상태

고민한 것

• 기존 데이터의 새 체계 편입 필요성
• 기존 Todo 번호 부여 기준 순서의 정의 필요
• 앱 진입 흐름 안에서 처리할지, 별도 작업으로 처리할지의 구분 필요

정리

• 기존 데이터의 전체 편입 필요
• 순서 기준의 고정 필요
• 앱 흐름과 분리된 백필 필요

문제 3. 문서 수 기반 번호 발급 방식의 불안정성

• 문서 수를 읽어 다음 번호를 계산하는 접근 검토
• 삭제, 동시 생성, 멀티 디바이스 상황에서 번호 충돌 가능성 존재

고민한 것

• 번호의 단순 표시용 여부와 영구 식별자 여부
• 삭제 이후 번호 재사용 허용 여부
• 동시 생성 상황에서 중복 없는 번호 보장 필요성

정리

• number를 영구 식별자에 가까운 값으로 보는 판단
• 문서 수 기반 계산 방식의 부적합성
• 유저별 카운터 문서 필요

문제 4. 백필을 어떤 경로로 처리할지의 문제

• 기존 문서를 순회하며 번호를 붙여야 하는 상태
• 앱 런타임 조회는 TodoResponse -> Todo 경로 전제
• 번호만 붙이면 되는 백필에 전체 엔티티 조건이 걸릴 가능성 존재

고민한 것

• 백필이 Todo 전체 모델을 알아야 하는지 여부
• 번호 부여에 필요한 최소 필드 범위
• 앱 런타임과 운영성 작업을 같은 경로로 묶는 구조의 적절성

정리

• 백필을 별도 운영 작업으로 보는 판단
• 최소 필드 중심 처리 방식의 안전성
• 앱 사용 흐름과 분리된 스크립트 처리 방향

문제 5. 신규 생성과 수정이 같은 저장 경로를 타는 구조

• Todo 저장이 하나의 upsert 경로를 타는 구조
• number는 신규 생성 시에만 부여되어야 하고 수정에서는 유지되어야 하는 조건

고민한 것

• 생성과 수정 구분 기준의 정의 필요
• 메모리상 UUID 존재 여부를 기존 문서 기준으로 볼 수 있는지 여부
• 생성 여부 판단과 번호 증가를 분리할 때의 충돌 가능성

정리

• 기준을 Firestore 문서 존재 여부로 보는 판단
• 신규 생성 시에만 number 할당
• 생성 여부 판단과 카운터 증가를 같은 트랜잭션 안에서 처리하는 방향

문제 6. MarkdownUI가 - refs #번호를 직접 이해하지 못하는 상태

• MarkdownUI는 일반 링크는 렌더링 가능
• - refs #번호는 일반 Markdown 문법이 아니라서 직접 인식하지 못하는 상태

고민한 것

• 본문 전체를 일반 Markdown 링크 문자열로 치환할지 여부
• 참조 줄만 별도 표현 대상으로 볼지 여부
• 사용자 문법과 렌더링 표현을 분리할 필요성

정리

• 일반 본문과 참조 줄을 같은 방식으로 처리하지 않는 방향
• 참조 줄만 따로 인식해 별도 렌더링하는 구조 선택

시도 1. #번호 -> todoId 치환 중심 접근

• 번호를 문서 ID로 바꿔 일반 링크처럼 렌더링하는 방향 검토
• 본문을 링크 형태로 바꾸고 openURL로 처리하는 구조 검토

한계

• Markdown 링크로는 표현 가능하지만, 원하는 UI 제어 범위가 좁은 상태
• 제목, 번호, 아이콘을 섞은 참조 전용 표현에는 한계 존재
• 일반 링크 스타일과 참조 UI 요구사항이 정확히 일치하지 않는 문제

정리

• 단순 치환만으로는 최종 UI 요구사항 충족 어려움
• 참조 줄을 전용 UI로 분리하는 방향이 더 적절하다는 판단

문제 7. 참조 줄은 링크처럼 보여야 하지만 일반 링크와 같지 않은 문제

• 요구한 UI는 제목, 번호, 아이콘이 섞인 커스텀 형태
• 번호는 .secondary 톤으로 보이되, 제목과 같은 링크 흐름 안에 있어야 하는 상태
• 일반 Markdown 링크 테마만으로는 이런 세밀한 스타일 제어가 어려운 상태

고민한 것

• 참조 줄을 일반 링크처럼 계속 밀어붙일지 여부
• 이미지, 제목, 번호를 분리된 하위 요소로 다뤄야 하는지 여부
• Markdown 테마 오버라이드만으로 해결 가능한지 여부

정리

• 참조 줄을 일반 링크가 아닌 전용 행 컴포넌트로 보는 방향
• TodoMarkdownContentView에서 참조 줄만 별도 렌더링하는 구조 선택

문제 8. 참조 렌더링에 필요한 데이터 범위 문제

• 처음에는 number -> todoId 정도만 알면 충분해 보였던 상태
• 실제 렌더링에는 제목과 kind 기반 아이콘 정보까지 필요해진 상태

고민한 것

• 참조 줄 UI에 필요한 최소 데이터 범위
• id만 가져오고 상세 진입 시 추가 조회하는 구조의 적절성
• 렌더링 전용 데이터 단위를 따로 둘 필요성

정리

• 참조 렌더링에는 id, title, kind 필요
• 이를 TodoReferenceItem으로 분리하는 방향 선택
• 조회 결과는 number -> TodoReferenceItem 딕셔너리 구조 선택

문제 9. 배열과 딕셔너리 중 어떤 형태가 맞는지의 문제

• 본문에서는 #번호를 기준으로 참조 대상을 찾아야 하는 구조
• 단순 배열이면 렌더링할 때마다 탐색이 필요한 상태

고민한 것

• 기준 키가 id인지 number인지 여부
• 조회 결과를 정렬된 배열로 둘지, 키 기반 맵으로 둘지 여부
• value 안에 number를 중복 보관할 필요 여부

정리

• 기준 키는 number
• number -> TodoReferenceItem 형태가 가장 자연스러운 구조
• value 내부 중복 number는 제거 방향 선택

최종 상태 요약

• 사용자 문법은 - refs #번호
• 사용자용 식별자는 number, 내부 식별자는 UUID
• 기존 Todo는 백필을 통해 번호 체계에 편입된 상태
• 신규 Todo는 카운터 기반 번호 부여 구조
• 제목 우측에 #번호 노출 상태
• 상세 본문과 프리뷰에서 같은 참조 규칙 사용 상태
• 참조 줄은 일반 Markdown 링크가 아닌 전용 컴포넌트로 렌더링하는 구조
• 참조 줄 탭 시 관련 Todo를 시트로 확인하는 흐름
• 참조 데이터는 referenceItems: [Int: TodoReferenceItem] 기준으로 관리하는 상태