결과·버그 보고서 작성과 5단계 처리

작업 시작 전에 작업 시작·반복 QA 메뉴얼을 읽고 작업 메뉴얼을 등록·갱신합니다. 최초 필요한 작업은 최대30개, 이후에는1~5개씩 반복하며 전체 미완료 목록과 QA 이력을 보존합니다. 메뉴얼 JSON 템플릿을 사용합니다.

사람과 AI는 같은 JSON 계약 v2를 사용합니다. 사이트의 작성 폼, AI용 CLI, GitHub 자동 접수가 모두 assets/report-contract.mjs의 validateReport를 호출합니다. Markdown만 따로 만들어 필수 입력을 우회하지 않습니다. v2 게시물은 원본 JSON을 함께 보존하며 빌드가 두 파일의 일치를 확인합니다.

버그 처리 5단계

JSON 값	화면	의미
new	접수	현상과 재현 자료가 등록됨
review	검토	재현·원인·우선순위를 확인 중
in_progress	진행	담당자가 수정·분석을 수행 중
resolved	해결	수정 내용과 검증 근거를 기록한 상태
closed	종료	결과를 확인하고 처리를 마침

해결·종료에는 changes와 verification이 필요합니다. 원인이 확인되지 않았으면 cause를 비워두고 미확인으로 기록합니다. 다시 열린 GitHub 버그 이슈는 검토 단계로 돌아갑니다. GitHub에서 종료한 이슈도 수정·검증 근거가 없으면 사이트에 종료로 반영하지 않고 검사에서 차단합니다.

사람이 작성하기

사이트 상단의 보고서 작성으로 이동합니다.
프로젝트와 결과·버그 분류를 고르고 실제 내용을 입력합니다.
검사·미리보기로 공통 JSON과 게시물 내용을 확인합니다.
공개 가능한 정보인지 확인하고 GitHub에서 최종 등록을 누릅니다.
GitHub 로그인 후 최종 제출합니다. 자동 검사·배포가 끝나면 사이트에 TF-이슈번호로 표시됩니다.

브라우저 임시저장은 해당 기기의 초안일 뿐 공개 등록이 아닙니다. 등록 전 GitHub 화면으로 이동했다는 것만으로 제출 완료로 간주하지 않습니다. 내용이 등록 URL 제한보다 길면 JSON을 복사·다운로드해 GitHub의 Tracefolio 등록 양식에 붙여넣습니다.

AI가 작성하기

같은 JSON 템플릿을 실제 값으로 채운 다음 공통 CLI를 실행합니다. CLI는 프로젝트의 assets/submissions에 원본 JSON, posts에 Markdown을 생성합니다.

node 리포트/create-report.mjs --input report.json --dry-run
node 리포트/create-report.mjs --input report.json
node 리포트/build.mjs
node 리포트/verify.mjs
node --test 리포트/tests/*.test.mjs

AI도 접수 저장소를 사용할 때는 GitHub 이슈 본문에  표시와 JSON 코드 블록을 넣습니다. 이슈 제목·본문은 공개되며 인증정보와 개인 로그를 포함하지 않습니다.

단계 변경과 이력

등록된 GitHub 이슈의 JSON workflow를 변경하면 새 게시물 버전과 단계 이력을 보존합니다. 이슈를 종료·재개하는 이벤트도 처리합니다. 사이트 목록은 같은 이슈의 최신 버전만 표시하고 이전 HTML과 JSON은 보존합니다. 담당자는 기록 필드이며 자동으로 GitHub 사용자를 배정하거나 별도 메시지를 보내지 않습니다.

공통 JSON 필드

구분	필드
필수	schemaVersion: 2, project, kind: result 또는 bug, title, summary, outcome
결과	type, state; 완료 상태에는 verification 필수
버그	workflow, environment, steps, expected, actual; 해결·종료에는 changes와 verification 필수
운영	priority, severity, reporter, assignee
근거	cause, changes, verification, remaining
시간·검색	proposedTime, actualTime, xerjUsage, xerjEvidence

빠진 시간·검증·원인을 추측으로 채우지 않습니다. 작성자가 제공하지 않은 항목은 미기록 또는 미확인으로 표시합니다. 세부 필드는 JSON 템플릿을 기준으로 합니다. 이미 작성된 v1·과거 기록은 읽기 호환을 유지하지만 새 보고서는 공통 계약 v2로 작성합니다.

프로젝트 소항목

사이드바의 턴룸 아래 공통·통합 작업(turnroom), Pixora(pixora), Design Data Table(designdatatable)을 소항목으로 관리합니다. 상위 항목은 세 제품의 글을 합쳐 보여주며, 소항목은 해당 제품만 보여줍니다. 묶음 정의는 project-groups.json에서 관리합니다.

사람은 작성 폼의 턴룸 그룹에서 소항목을 고릅니다. AI는 기존 JSON project에 해당 소항목 ID를 기록합니다. 상위 묶음 ID인 products 또는 collection:products를 보고서 project로 쓰지 않습니다. 프로젝트별 폴더·원본·이전 링크는 유지합니다. 소항목에서 결과·버그 분류와 버그 5단계를 함께 필터링할 수 있습니다.

QA 토론 · 개선 제안 · 새 기능 요청

보고서 상세의 토론 시작은 프로젝트와 원본 보고서를 자동 연결합니다. QA 토론 메뉴에서는 프로젝트·종류·논의 상태·검색으로 글을 찾고 원본 QA와 함께 다시 읽을 수 있습니다. 작성은 사이트 폼 또는 토론 JSON 템플릿과 같은 create-report.mjs --input 절차를 사용합니다. GitHub에서 최종 등록해야 공개 사이트에 반영되며 로그인 전의 미리보기·초안 저장은 등록이 아닙니다.

kind: discussion, type: 토론. 결과·버그 수에는 섞지 않고 QA 토론 목록에 표시합니다.
topic: qa(QA 토론), gap(부족한 점), proposal(개선 제안), feature(새 기능 요청).
discussionState: open(논의 중), considering(검토 중), accepted(채택), deferred(보류), implemented(반영 완료).
relatedReport: 같은 프로젝트의 실제 HTML 경로입니다. 예: projects/프로젝트ID/reports/파일.html. qa 종류에는 필수이며 다른 제안은 독립 글로도 작성할 수 있습니다.
replyTo: 후속 글을 쓸 때 원본 토론의 HTML 경로를 기록합니다. 같은 프로젝트·같은 QA의 토론만 연결하며 순환 참조를 허용하지 않습니다.
outcome에는 관찰 사실과 논의할 질문, verification에는 QA 근거·실제 화면, changes에는 제안·대안·기대 효과, decision에는 결정 이유·담당자·후속 작업, remaining에는 열린 질문을 기록합니다. 제안과 검증된 사실을 구분합니다.
채택·보류·반영 완료에는 decision이 필수이며, 반영 완료에는 verification도 필수입니다. 승인받지 않은 제안을 채택·구현 완료로 표시하지 않습니다.

토론의 H2는 토론 내용 → QA 근거와 맥락 → 제안 및 대안 → 결정과 후속 작업 → 작업 시간입니다. JSON 원본·Markdown·생성 HTML은 기존과 같이 프로젝트별 assets/submissions, posts, reports에 보존합니다. GitHub로 등록한 글의 수정 이력은 버전별로 보존하고 목록에는 같은 이슈의 최신 글만 표시합니다. 후속 글 쓰기는 별도 글을 남겨 결론·보류 이유·새 제안의 맥락을 이어갑니다. GitHub 댓글은 토론 글의 외부 링크에서 볼 수 있으며 사이트에 자동 복제하지 않습니다.

작업 메뉴얼 형식

kind: manual은 결과·버그·토론과 별도 목록으로 관리합니다. 목표와 완료 기준 → 순차 작업 메뉴얼 → QA 반복 기록 → 남은 작업과 다음 반복 → 작업 시간 순서의 공통 H2를 사용합니다. 완료는 모든 작업의 결과·현재 버전 QA 통과와 전체 최종 QA가 필요합니다. 작업 메뉴얼의 상태는 버그 처리5단계와 구분합니다.