8018 MATRIX 홈 문제상황 보고서 — 사용맥락·편의·개선 방향

점검 시각 2026-08-31 12:13~12:25 KST · 대상 http://13.125.131.126:8018/?debug=1 · 기준 커밋 ad675297050e2d2102ce106a360aa545e0de555d · 상태 변경 API는 호출하지 않음

1. 한 줄 결론

8018은 “사이트 허브”와 “진행판”의 외형은 구축됐지만, 사용자가 믿고 결정할 수 있는 운영 홈은 아직 아닙니다. 특히 승인 대기 0건이라는 첫 화면 판단, 승인 링크의 보안 구조, Jira/승인보드/사이트 상태의 정합성이 실제 상황과 맞지 않아 “정상처럼 보이는 문제”가 가장 큽니다.

2. 현재 구축된 것

• 홈 H1: 자산 파이프라인 요약, 창고→장바구니→주방→승인→매트릭스 흐름 스트립, 주요 사이트 링크가 있습니다.
• 사이트맵 H2: 8003, 8004, 8005, 8009, 8010, 8011, 8012, 8013, 8015, 8016, 8018, 8020 상태를 표시합니다.
• 로드맵 H3: 7단계 파이프라인과 매트릭스화/코어화 흐름을 요리 공장 비유로 설명합니다.
• 승인 카드 H4: Workbench 플랜 1건을 카드처럼 보여주고 채팅 전문, 이미지 JSON, 스튜디오, RISU 이어가기 링크를 제공합니다.
• S0/H9: 원본 창고 흐름판, 창고 정리 진행, 슬롯 적립 현황이 추가됐습니다.
• 보고함 H8: 봇 보고서와 개선 진단 HTML을 모아 보는 허브가 있습니다.
• debug=1: 화면·버튼·링크에 디버그 배지를 붙여 컴포넌트를 식별하려는 장치가 있습니다.

3. 이미 개선하겠다고 적힌 방향

기존 2026-08-29 진단 보고서는 P0~P3 문제를 이미 제기했습니다. 핵심 약속은 다음입니다.

• 승인 비밀을 HTML query에 넣지 않기.
• 승인·release 발행을 GET이 아니라 POST+재인증+idempotency로 전환하기.
• 승인보드, Jira, Mongo, 파일 집계가 실패할 때 0으로 속이지 말고 unknown/degraded로 표시하기.
• 8005의 정상 401을 “다운”으로 오판하지 않도록 health와 auth를 분리하기.
• 화면 ID와 파이프라인 단계 ID를 혼용하지 않고 canonical stage map을 두기.
• 단일 파일에 섞인 HTML/CSS/API/승인 로직을 분리하고 테스트를 추가하기.

현재 재점검 결과, 위 약속 중 일부 시각화는 추가됐지만 P0/P1 핵심 문제는 아직 남아 있습니다.

4. 실제 사용맥락에서의 문제

4.1 이사님이 “지금 뭘 승인해야 하지?”를 보러 올 때

홈은 “지금 결정할 것이 없습니다 — 전 라인 정상 가동 중”으로 보일 수 있습니다. 그러나 승인보드 내부에는 review_required 13건, running 17건, accepted 2건이 있습니다. 홈은 decisions만 세거나 Jira 승인대기만 보아 실제 작업 대기열을 놓칩니다.

사용자 영향: 해야 할 결정을 놓치고, 봇은 “승인 기다리는 중”인데 사용자는 “아무것도 없다”고 보게 됩니다.

4.2 사이트 상태를 보러 올 때

사이트맵은 8005를 다운으로 표시합니다. 하지만 8005는 인증이 필요한 서비스라 401을 반환하는 것이 정상일 수 있습니다.

사용자 영향: 실제 장애와 정상 인증 요구를 구분하지 못합니다. 복구할 필요 없는 것을 장애로 보거나, 반대로 진짜 장애를 놓칠 수 있습니다.

4.3 승인 카드를 눌러 근거를 보려 할 때

카드는 1건만 보이고, 이미지가 없는데도 이미지 JSON/스튜디오 링크가 노출됩니다. gate도 “실사 횟수” 위주라 실제 품질, hard-block, 아티팩트 검증이 서버에서 재확인되는 구조로 보이지 않습니다.

사용자 영향: “승인해도 되는 카드인지”보다 “그럴듯한 카드인지”만 보게 됩니다.

4.4 운영자가 debug=1로 문제를 찾을 때

디버그 배지는 유용하지만 기본 노출 규칙이 느슨합니다. ?debug=1에서는 배지가 보이고, 일부 보고 페이지도 debug 배지가 붙습니다. 일반 사용자 UI와 운영자 진단 UI가 분리되지 않았습니다.

사용자 영향: 진단 정보가 일반 사용자의 의미 이해를 방해하고, 보안·접근성 이름에 섞일 수 있습니다.

5. 현재 확인된 문제상황

P0 — 즉시 막아야 할 문제

• 승인 비밀이 HTML query 링크에 들어감: 홈과 승인 카드 HTML에 인증 query가 포함됩니다. 값은 보고서에 기록하지 않았지만 존재 여부는 확인됐습니다.
• 승인/발행이 GET 링크: 카드의 “매트릭스 자산화 결정”이 GET URL입니다. 브라우저 프리패치, 중복 클릭, 외부 접근, referrer에 취약합니다.
• 보안 헤더 없음: 점검한 HTML/API 응답에 CSP, Referrer-Policy, X-Content-Type-Options가 없었습니다.
• API에 내부 저장 경로 노출: /api/dossiers 응답에 서버 내부 원본 위치가 포함됩니다. 공개 DTO에서 제거해야 합니다.

P1 — 사용 판단을 틀리게 만드는 문제

• 승인 대기 false-green: 8018 /api/stats는 board_pending 0, jira_pending 0을 반환하지만, 승인보드 요청에는 review_required 13건이 있습니다.
• Jira 이슈 빈 배열: /api/jira가 빈 배열을 반환합니다. Jira가 실제로 비어 있는지, 인증/쿼리/프로젝트 불일치인지 화면에서 구분되지 않습니다.
• 8005 health 오판: 인증 401을 다운으로 처리합니다.
• 바구니 표시 빈 이름: /api/flow에서 basket_wait 5건이 보이지만 persona 이름은 빈 값입니다. 사용자는 무엇이 대기 중인지 알 수 없습니다.
• release 0과 실제 진행의 의미 불명확: plans_done 5, images 47, candidates 111, capsules 1651인데 release 0입니다. 왜 막혔는지 설명이 없습니다.

P2 — 편의와 이해를 떨어뜨리는 문제

• “다ossier” 명칭 잔존: 일부 화면/링크에 이해하기 어려운 옛 명칭이 남아 있습니다.
• 흐름 단계 혼선: H1에서는 이미지 스튜디오가 S2처럼 보이고, 로드맵에서는 S2가 승인입니다. 화면 ID와 단계 ID가 섞여 있습니다.
• 카드 CTA 과다: 준비 안 된 링크까지 노출되어 사용자가 어디를 눌러야 할지 모릅니다.
• 에러/빈 상태 UX 부족: Jira, Mongo, 파일 읽기 실패가 빈 배열 또는 0으로 바뀌면 “정상”처럼 보입니다.

6. 잘 된 점

• 홈이 여러 사이트를 한 곳에 모으려는 방향은 맞습니다.
• 창고→장바구니→주방→승인→매트릭스라는 사용 비유는 이해하기 쉽습니다.
• H8 보고함과 기존 진단 보고서가 있어 개선 기록을 한 곳에서 볼 수 있습니다.
• S0/H9는 자산 창고 상태를 운영자가 파악하는 데 도움이 됩니다.
• debug 배지는 컴포넌트 식별에는 유용합니다. 다만 운영자 전용으로 격리해야 합니다.

7. 개선 방향

7.1 첫 화면을 세 덩어리로 바꾸기

• 지금 이사님 결정 필요: 승인보드 review_required, Jira 승인대기, 수동 결정 대기만 표시.
• 현재 장애/데이터 지연: 401/다운/unknown/stale을 구분.
• 다음 작업: ZCode, asset_agent, novel_col, manager가 해야 할 일.

7.2 “0건” 대신 상태 의미를 말하기

실패하면 0이 아니라 unknown, stale, auth_required, degraded로 표시해야 합니다. 사용자는 “없음”과 “못 읽음”을 반드시 구분해야 합니다.

7.3 승인 기능은 읽기와 실행을 분리하기

카드 HTML은 근거 열람만 담당하고, 승인/발행은 POST, CSRF, 재인증, idempotency, 서버 gate 재검증, 감사 로그를 통과해야 합니다.

7.4 공통 snapshot API 만들기

H1, H2, H3, H4가 각각 다른 파일과 DB를 읽지 말고, 하나의 snapshot ID를 공유해야 합니다. snapshot에는 값, 오류, observed_at, source, freshness가 함께 있어야 합니다.

7.5 사용자 편의 언어로 바꾸기

• “다ossier” → “승인 카드”.
• “release 0” → “검증은 됐지만 아직 정식 등록된 자산 없음”.
• “8011 복구 대기” → “매트릭스 엔진 등록 단계 막힘 — 담당/다음 액션 표시”.
• “Jira []” → “Jira에서 읽은 이슈 없음 / 또는 읽기 실패”.

8. 추천 작업 순서

1. 오늘 즉시: 승인 query 비밀 제거, GET 승인 비활성화, 보안 헤더 추가, 내부 경로 DTO 제거.
2. 오늘: 8005 health를 인증 상태와 분리하고, 승인보드 review_required를 H1 승인 대기 숫자에 반영.
3. 다음: Jira 빈 배열과 실패를 구분하고, H1에 unknown/degraded/stale 표시.
4. 다음: H1/H2/H4가 같은 snapshot API를 보도록 정리.
5. 그다음: 승인 카드 CTA를 준비된 것만 보이게 하고, 이미지 없음/JSON 없음/채팅 근거 없음 사유를 표시.
6. 마지막: 화면 ID와 파이프라인 단계 ID를 분리하고, debug는 운영자 모드에서만 표시.

9. 완료 기준

• 공개 HTML에 승인 비밀 query가 없다.
• GET 요청만으로 승인 또는 release가 생성되지 않는다.
• H1의 승인 대기 숫자가 승인보드 review_required와 같은 기준으로 나온다.
• 8005는 auth_required와 down을 구분한다.
• Jira 실패는 빈 배열이 아니라 오류/신선도와 함께 표시된다.
• /api/dossiers 공개 DTO에 내부 저장 경로가 없다.
• 카드의 각 버튼은 “준비됨/미준비/왜 미준비인지”가 보인다.
• debug 배지는 운영자 명시 모드에서만 보이고 일반 UI·접근성 이름에 섞이지 않는다.

10. 작업 배분 제안

• AWS ZCode: 8018 보안/상태/UX 수정, snapshot API, H1/H2/H4 정합성 테스트.
• manager: Jira/Notes/port-registry의 RELAY-50·56·57 상태 정리. 404 또는 미동기화는 완료 처리 금지.
• asset_agent: 승인 카드에 들어갈 자산 master_no, source evidence, 검증 단계 정의.
• novel_col: 이미지 JSON/리롤/원본 이미지/작품 근거의 DTO를 8018이 안전하게 표시할 수 있도록 정리.
• aws-audit: 수정 후 false-green, 보안 링크, 401 health, 내부 경로 노출, snapshot 정합성 회귀 테스트.

← 보고함으로