refactor: Clinic Phase 2 DA 반복 이슈 5건 — XSS/CSRF, fixedContent 구조, fact-correction 매칭, card-fixer 통합, overallStatus 확장

[greenheadHQ]

Summary

PR #104 (Clinic Phase 2) DA 피드백 루프에서 3라운드 연속 반복된 5개 이슈를 후속 작업으로 등록한다.
모두 Phase 2의 설계 결정에서 비롯된 기술 부채이며, Phase 3 진입 전 해소가 권장된다.

Context

PR #104에서 DA 에이전트 8개 × 3라운드 실행. 아래 5건이 매 라운드 동일하게 지적되었으나,
Phase 2 범위 내에서 합리적인 트레이드오프로 판단하여 기각 + 이슈 등록 결정.

Proposed Changes

• SECURITY: fix/apply의 Stored XSS / CSRF 방어

  • fixedContent에 대한 sanitize 계층 추가 (DOMPurify 또는 allowlist)
  • 또는 서버 사이드에서 HTML 태그 스트립 (Anki 카드는 HTML이므로 신중한 판단 필요)
  • dev 프록시 CSRF: Same-Origin 검증 또는 CSRF 토큰 도입 검토

• NGMI: fixedContent 문자열 overwrite → 구조화된 액션 모델

  • { actions: [{ type, payload }] } 기반 서버 사이드 적용으로 전환 검토
  • 또는 현재 구조 유지 + changes 배열을 서버에 감사 로그로 전송

• HALLUCINATION: fact correction clean↔raw 텍스트 매칭 개선

  • LLM에게 raw 텍스트(Cloze 마크업 포함)를 함께 전달하여 정확한 claim 추출
  • 또는 퍼지 매칭 (Levenshtein distance) 도입

• CLEAN_CODE: web card-fixer의 apply/diff 함수 통합

  • removeYagniClozes + computeYagniDiff를 단일 함수로 통합 (diff 계산 후 apply는 diff.fixed 반환)
  • applyFactCorrections + computeFactDiff 동일하게 통합

• NGMI: overallStatus에 yagni/verbose 반영 전략

  • 현재: factCheck, freshness, similarity, context 4종만 반영
  • 제안: actionStatus 분리 — "content quality" vs "optimization suggestions" 2축 상태

Notes

• 단일 사용자 내부 도구이므로 SECURITY 이슈의 실제 위험도는 LOW
• fact correction 매칭 문제는 computeFactDiff로 "적용 불가" 감지는 이미 구현됨 (PR feat(web): Clinic 탭 Phase 2 — YAGNI 감지 + 수정 액션 + All-in-One #104 R1 수용)
• Ref: PR feat(web): Clinic 탭 Phase 2 — YAGNI 감지 + 수정 액션 + All-in-One #104, feat(web): Validate 탭 — All-in-One 카드 건강 허브 #93 (Phase 2)

[greenheadHQ]

LLM 이행 가이드 — #109 DA 반복 이슈 5건

대상: packages/web, packages/server, packages/core
목표: PR #104 DA 3회 반복 기술 부채 5건 해소
예상 소요: ~30분 (다중 세션 권장)
난이도: 복잡 (Phase 6)

핵심 원칙

1. 진실 원천 우선: 이 가이드의 값보다 CLI/파일시스템에서 확인한 실제 값이 우선한다.
2. 기존 패턴 존중: 코드베이스에 확립된 네이밍/구조 컨벤션을 따른다.
3. 각 Phase 독립 실행: Phase별로 별도 세션에서 실행 가능하다.

---

Phase 1: 사전 확인 + 아키텍처 파악

다음 명령으로 현재 상태를 확인한다 (병렬 가능):

# 1. fix/apply 엔드포인트 현재 구조
grep -n "fixedContent\|updateNoteFields" packages/server/src/routes/clinic.ts

# 2. AllInOnePanel의 fact correction 로직
grep -n "computeFactDiff\|applyFactCorrections\|hasFactCorrections" packages/web/src/components/clinic/AllInOnePanel.tsx

# 3. card-fixer 현재 함수 목록
grep -n "^export function" packages/web/src/lib/card-fixer.ts

# 4. overallStatus 로직
grep -n "overallStatus\|statusResults" packages/server/src/routes/clinic.ts

# 5. markdown-it 설정 (XSS 관련)
grep -n "html:" packages/web/src/lib/markdown-renderer.ts

# 6. CORS/인증 미들웨어
grep -n "cors\|api-key\|timingSafe" packages/server/src/index.ts | head -10

확인 포인트:

• fixedContent가 서버에서 어떤 검증 없이 updateNoteFields로 전달되는지
• card-fixer.ts에 removeYagniClozes, applyFactCorrections, computeYagniDiff, computeFactDiff 4개 함수가 존재하는지
• markdown-renderer.ts에서 html: true 설정이 있는지
• overallStatus에서 verbose/yagni가 제외되어 있는지

---

Phase 2: card-fixer apply/diff 함수 통합

목표: 4개 함수 → 2개 함수로 통합. apply 함수가 diff 결과를 반환하도록 변경.

파일: packages/web/src/lib/card-fixer.ts

통합 전략

BEFORE (4 함수):

export function removeYagniClozes(content, clozesToRemove): string
export function applyFactCorrections(content, corrections): string
export function computeYagniDiff(content, clozesToRemove): { fixed, changes }
export function computeFactDiff(content, corrections): { fixed, changes }

AFTER (2 함수):

export function removeYagniClozes(content, clozesToRemove): { fixed: string; changes: FixChange[] }
export function applyFactCorrections(content, corrections): { fixed: string; changes: FixChange[] }

각 함수가 fixed (적용된 결과 문자열)와 changes (diff 배열)를 모두 반환.
기존 computeYagniDiff/computeFactDiff의 로직을 각 함수에 통합.

소비자 업데이트

removeYagniClozes 소비자:

• AllInOnePanel.tsx: removeYagniClozes(content, clozes) → .fixed로 접근
• ActionPreview.tsx: computeYagniDiff 호출 → removeYagniClozes 호출로 교체

applyFactCorrections 소비자:

• AllInOnePanel.tsx: applyFactCorrections(content, corrections) → .fixed로 접근
• AllInOnePanel.tsx: computeFactDiff 호출 → applyFactCorrections 호출의 .changes.length로 판단
• ActionPreview.tsx: computeFactDiff 호출 → applyFactCorrections 호출로 교체

---

Phase 3: fact correction 매칭 개선

목표: LLM이 clean text 기반으로 반환한 claim이 원본 HTML/Cloze 텍스트에서도 매칭되도록 개선.

파일: packages/web/src/lib/card-fixer.ts — applyFactCorrections 함수

접근 방식 (권장: HTML/Cloze 투과 매칭)

claim 텍스트를 매칭할 때, HTML 태그와 Cloze 마크업을 "투명하게" 건너뛰는 정규식을 생성:

// claim = "DNS 포트는 53"
// 원본 = "{{c1::DNS}} <b>포트</b>는 {{c2::53}}"
// → claim의 각 문자 사이에 (Cloze/HTML 마크업 허용) 패턴 삽입
function buildFlexiblePattern(claim: string): RegExp {
  const chars = [...claim].map(c => c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
  // 각 문자 사이에 optional HTML/Cloze 마크업 허용
  const markup = '(?:\\{\\{c\\d+::|\\}\\}|::[^}]*|<[^>]*>)*';
  return new RegExp(chars.join(markup), 'g');
}

대안: LLM 프롬프트를 수정하여 raw 텍스트(Cloze 포함) 기반 claim을 반환하도록 변경.
→ 비추천: fact-checker 프롬프트는 다른 5개 도메인과 공유되는 cleanCardText 기반이므로 변경 영향 범위가 큼.

---

Phase 4: overallStatus 확장

목표: yagni/verbose 결과를 별도 축으로 반영하여, 카드의 "콘텐츠 품질"과 "최적화 제안"을 구분.

파일: packages/server/src/routes/clinic.ts

접근 방식

BEFORE:

const statusResults = [factCheckResult, freshnessResult, similarityResult, contextResult];
// verbose, yagni 제외

AFTER:

// 콘텐츠 품질 상태 (기존)
const contentResults = [factCheckResult, freshnessResult, similarityResult, contextResult];
let overallStatus = computeStatus(contentResults);

// 최적화 제안 상태 (신규)
const actionResults = [verboseResult, yagniResult];
let actionStatus = computeStatus(actionResults);

응답에 actionStatus 필드를 추가:

return c.json({
  noteId, overallStatus, actionStatus,
  results: { ... },
  validatedAt: ...
});

소비자 업데이트

• AllValidationResult 타입에 actionStatus 추가 (api.ts)
• useClinicCache: 캐시에 actionStatus 저장
• ClinicWorkspace: 카드 목록 컬러 바에 actionStatus 반영 (overallStatus + actionStatus 중 더 나쁜 것 사용, 또는 별도 아이콘)

---

Phase 5: fixedContent 감사 로그 + XSS 방어

목표:

1. fix/apply 시 changes 배열을 서버에 전송하여 감사 로그 보존
2. fixedContent에 대한 기본 sanitize

5-1. 감사 로그

파일: packages/server/src/routes/clinic.ts

BEFORE:

{ noteId, fixedContent, deckName }

AFTER:

{ noteId, fixedContent, deckName, changes?: Array<{ type, before, after, reason }> }

changes는 optional (backward compat). 서버에서 백업 엔트리에 appliedChanges 필드로 저장.

5-2. XSS 방어

판단 필요: Anki 카드는 본질적으로 HTML이므로 무분별한 sanitize는 카드를 깨뜨림.
권장 접근: <script>, <iframe>, on* 이벤트 핸들러만 제거하는 최소 sanitize.

function sanitizeCardContent(content: string): string {
  return content
    .replace(/<script[\s\S]*?<\/script>/gi, '')
    .replace(/<iframe[\s\S]*?<\/iframe>/gi, '')
    .replace(/\son\w+\s*=/gi, ' data-removed=');
}

대안: DOMPurify 서버 사이드 사용 (bun 호환성 확인 필요).

---

Phase 6: 검증 + 커밋

빌드 확인 (병렬 가능)

cd packages/core && bun run build
cd packages/server && bun run build
cd packages/web && bun run build

기능 검증

# 1. card-fixer 통합: apply 함수가 changes를 반환하는지
grep "changes" packages/web/src/lib/card-fixer.ts

# 2. overallStatus + actionStatus 응답 확인
curl -X POST http://localhost:3000/api/clinic/all \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANKI_SPLITTER_API_KEY" \
  -d '{"noteId":1757399484677,"deckName":"[책] 이것이 취업을 위한 컴퓨터 과학이다"}' \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print('overallStatus:', d.get('overallStatus'), 'actionStatus:', d.get('actionStatus'))"

커밋

git add -A
git commit -m "$(cat <<'EOF'
refactor: Clinic DA 반복 이슈 5건 해소

- card-fixer: apply/diff 4함수 → 2함수 통합
- fact correction: HTML/Cloze 투과 매칭 도입
- overallStatus: actionStatus 분리 (content quality vs optimization)
- fix/apply: changes 감사 로그 전송 + 최소 XSS sanitize
- CACHE_VERSION 4로 bump

Closes #109
EOF
)"

DA 피드백 (필수)

구현 완료 후, /run-da for_pr 스킬을 실행하여 코드 품질을 검증하고,
/create-pr 스킬로 PR을 생성한다.

---

주의사항

• Phase 2 (card-fixer 통합): 소비자 3곳 (AllInOnePanel, ActionPreview, useClinicCache)을 모두 업데이트할 것. 반환 타입 변경이므로 TypeScript가 미수정 부분을 잡아줌.
• Phase 3 (fact 매칭): 정규식 성능을 고려. claim이 100자 이상이면 퍼지 매칭 대신 "적용 불가" 표시가 더 안전할 수 있음.
• Phase 4 (actionStatus): CACHE_VERSION을 4로 bump해야 함. 기존 v3 캐시가 자동 무효화됨.
• Phase 5 (XSS): Anki 카드 HTML을 깨뜨리지 않도록 <img>, <b>, <br>, <table> 등 Anki 표준 태그는 보존할 것.
• 독립 실행: Phase 2-5는 순서 무관하게 독립 실행 가능. Phase 6은 모든 Phase 완료 후 실행.

[greenheadHQ]

LLM 이행 가이드 — #109 DA 반복 이슈 5건

대상: packages/web, packages/server, packages/core
목표: PR #104 DA 3회 반복 기술 부채 5건 해소
예상 소요: ~30분 (다중 세션 권장)
난이도: 복잡 (Phase 6)

핵심 원칙

1. 진실 원천 우선: 이 가이드의 값보다 CLI/파일시스템에서 확인한 실제 값이 우선한다.
2. 기존 패턴 존중: 코드베이스에 확립된 네이밍/구조 컨벤션을 따른다.
3. 각 Phase 독립 실행: Phase별로 별도 세션에서 실행 가능하다.

---

Phase 1: 사전 확인 + 아키텍처 파악

다음 명령으로 현재 상태를 확인한다 (병렬 가능):

# 1. fix/apply 엔드포인트 현재 구조
grep -n "fixedContent\|updateNoteFields" packages/server/src/routes/clinic.ts

# 2. AllInOnePanel의 fact correction 로직
grep -n "computeFactDiff\|applyFactCorrections\|hasFactCorrections" packages/web/src/components/clinic/AllInOnePanel.tsx

# 3. card-fixer 현재 함수 목록
grep -n "^export function" packages/web/src/lib/card-fixer.ts

# 4. overallStatus 로직
grep -n "overallStatus\|statusResults" packages/server/src/routes/clinic.ts

# 5. markdown-it 설정 (XSS 관련)
grep -n "html:" packages/web/src/lib/markdown-renderer.ts

# 6. CORS/인증 미들웨어
grep -n "cors\|api-key\|timingSafe" packages/server/src/index.ts | head -10

---

Phase 2: card-fixer apply/diff 함수 통합

파일: packages/web/src/lib/card-fixer.ts

4개 함수를 2개로 통합. 각 함수가 { fixed, changes } 반환:

// BEFORE: removeYagniClozes → string, computeYagniDiff → { fixed, changes }
// AFTER: removeYagniClozes → { fixed, changes }
export function removeYagniClozes(content, clozesToRemove): { fixed: string; changes: FixChange[] }

// BEFORE: applyFactCorrections → string, computeFactDiff → { fixed, changes }
// AFTER: applyFactCorrections → { fixed, changes }
export function applyFactCorrections(content, corrections): { fixed: string; changes: FixChange[] }

소비자 업데이트:

• AllInOnePanel.tsx: .fixed로 접근, computeFactDiff 호출을 applyFactCorrections로 교체
• ActionPreview.tsx: computeYagniDiff/computeFactDiff 호출을 통합 함수로 교체

---

Phase 3: fact correction 매칭 개선

파일: packages/web/src/lib/card-fixer.ts

claim 텍스트 매칭 시 HTML/Cloze 마크업을 투과하는 정규식 생성:

function buildFlexiblePattern(claim: string): RegExp {
  const chars = [...claim].map(c => c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
  const markup = '(?:\\{\\{c\\d+::|\\}\\}|::[^}]*|<[^>]*>)*';
  return new RegExp(chars.join(markup), 'g');
}

대안: LLM 프롬프트에 raw 텍스트 전달 (비추천 — 영향 범위 큼).

---

Phase 4: overallStatus 확장

파일: packages/server/src/routes/clinic.ts, packages/web/src/lib/api.ts

// 서버: actionStatus 추가
const actionResults = [verboseResult, yagniResult];
let actionStatus = computeStatus(actionResults);
return c.json({ noteId, overallStatus, actionStatus, results, validatedAt });

// 웹: AllValidationResult에 actionStatus 추가
export interface AllValidationResult {
  actionStatus?: ValidationStatus; // 신규
  // ...기존
}

CACHE_VERSION을 4로 bump.

---

Phase 5: fixedContent 감사 로그 + XSS 방어

서버 fix/apply에 changes 배열 수신 + 최소 XSS sanitize:

// 입력 확장
{ noteId, fixedContent, deckName, changes?: Array<{ type, before, after, reason }> }

// sanitize (script/iframe/event handler만 제거)
function sanitizeCardContent(content: string): string {
  return content
    .replace(/<script[\s\S]*?<\/script>/gi, '')
    .replace(/<iframe[\s\S]*?<\/iframe>/gi, '')
    .replace(/\son\w+\s*=/gi, ' data-removed=');
}

---

Phase 6: 검증 + 커밋

cd packages/core && bun run build
cd packages/server && bun run build
cd packages/web && bun run build

git commit -m "refactor: Clinic DA 반복 이슈 5건 해소

- card-fixer: apply/diff 4함수 → 2함수 통합
- fact correction: HTML/Cloze 투과 매칭 도입
- overallStatus: actionStatus 분리
- fix/apply: changes 감사 로그 + 최소 XSS sanitize
- CACHE_VERSION 4

Closes #109"

구현 완료 후, /run-da for_pr 실행 → /create-pr PR 생성.

---

주의사항

• Phase 2-5는 순서 무관, 독립 실행 가능. Phase 6은 마지막.
• Phase 4: CACHE_VERSION bump 필수 (v3→v4).
• Phase 5: Anki 표준 HTML 태그 보존 필수.