klaus/voiceon-character-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
00f06b992f25dbfe3b700babfa6dc28ed08f967b
voiceon-character-admin/docs/20260806_커뮤니티댓글답글/prd.md

12 KiB
Raw Blame History

커뮤니티 댓글 직접 답글 PRD

문서 정보

항목 내용
문서 상태 구현 기준 확정
작성일 2026-08-06
최종 수정일 2026-08-06
대상 기능 커뮤니티 게시글 댓글의 직접 답글 작성 진입
작성자·결정권자 Codex 작성, 사용자 결정
상위 제품 기준 AI 캐릭터 관리자 웹 PRD
선행 기능 기준 오디오 콘텐츠 댓글 답글 PRD
관련 API Contract api-contract.md
관련 구현 계획 plan-task.md
관련 review Phase 1 커뮤니티 댓글 직접 답글 리뷰

요구사항 상태

상태 의미
확정 구현과 검증 기준으로 사용한다.
미결 제품 결정 전에는 구현하지 않는다.
외부 의존 외부 계약이 제공될 때까지 영향 범위를 구현 완료로 표시하지 않는다.
제외 현재 기능 범위에 포함하지 않는다.

1. Overview

활성 AI 캐릭터의 커뮤니티 게시글 원댓글에 직접 답글을 작성할 수 있게 한다. 원댓글 아래에는 여러 개의 직접 답글을 추가할 수 있지만, 답글에 다시 답글을 다는 3단계 구조는 허용하지 않는다. 기존 오디오 콘텐츠 댓글과 같은 진입 UI, 답글 영역, 작성 form과 mutation 상태를 재사용한다.

2. Problem Statement

커뮤니티 답글 조회·작성 API와 UI는 이미 구현돼 있어 답글이 하나 이상인 원댓글에는 추가 답글을 작성할 수 있다. 그러나 replyCount=0인 원댓글에는 답글 영역을 여는 action이 없어 첫 답글을 작성할 수 없다.

문제를 해결했다는 판단은 답글 0개인 활성 커뮤니티 원댓글에서 답글 작성을 눌러 첫 답글을 등록하고, 같은 원댓글에 여러 직접 답글을 계속 추가할 수 있는지로 한다.

3. Goals

3.1 제품 목표

  • 활성 커뮤니티 게시글의 모든 원댓글에 첫 답글을 작성할 수 있다.
  • 하나의 원댓글 아래 여러 직접 답글을 작성·조회할 수 있다.
  • 원댓글과 직접 답글로 끝나는 기존 2단계 댓글 구조를 유지한다.

3.2 UX 목표

  • 답글이 0개인 원댓글에는 답글 작성이라는 명확한 진입점을 표시한다.
  • 버튼을 누르면 기존 답글 영역과 작성 form을 펼친다.
  • 기존 답글이 있는 원댓글은 답글 보기로 같은 영역을 열고 추가 답글을 작성한다.
  • 기존 loading, 오류, 전송 중, 실패 후 초안 보존 동작을 유지한다.

4. Non-Goals

  • 답글의 답글을 포함한 3단계 이상의 댓글 구조
  • 답글 form 상시 노출
  • 새 endpoint, DTO, 상태관리, 컴포넌트 또는 UI dependency 추가
  • 오디오 콘텐츠 댓글 동작이나 payload 정책 변경
  • 기존 답글 수정·삭제·pagination 정책 변경
  • optimistic update 또는 답글 전체 선조회

5. Target Users and Permissions

사용자 목표 주요 작업 사용 환경
ADMIN AI 캐릭터 명의로 커뮤니티 원댓글에 직접 답글 작성 답글 영역 열기, 작성, 재시도 desktop, tablet, mobile
  • 인증과 ADMIN 권한은 상위 제품 기준을 따른다.
  • 활성 AI 캐릭터 workspace에서만 답글 작성 control을 제공한다.
  • 비활성 AI 캐릭터 workspace는 기존처럼 조회 전용이다.
  • 원댓글 작성자가 팬인지 AI 캐릭터인지와 관계없이 답글을 작성할 수 있다.

6. 핵심 사용자 흐름

  1. 관리자가 활성 AI 캐릭터의 커뮤니티 게시글 목록에 진입한다.
  2. 게시글 Sheet를 열고 답글이 0개인 원댓글에서 답글 작성을 누른다.
  3. UI가 해당 원댓글의 직접 답글 GET을 실행하고 답글 영역과 작성 form을 표시한다.
  4. 관리자가 내용을 입력해 등록한다.
  5. 기존 커뮤니티 댓글 POST에 원댓글 ID를 parentId로 보내고 성공 후 원댓글·열린 답글 목록을 재조회한다.
  6. 관리자는 같은 form으로 동일 원댓글에 추가 직접 답글을 작성할 수 있다.
  7. 실패하면 오류를 표시하고 입력 초안을 유지해 재시도할 수 있다.

7. 정보 구조와 라우팅

/ai-characters/:characterId/community-posts
  └─ 커뮤니티 게시글 Sheet
      └─ 댓글 관리
          └─ 원댓글
              └─ 직접 답글 목록 및 작성 form
  • 새 route와 query parameter를 추가하지 않는다.
  • 기존 CommunityPostSheet의 CommentThread 안에서만 동작한다.
  • 답글 pagination 상태는 기존 component의 로컬 상태를 사용한다.

8. 기능 요구사항

ID 상태 요구사항 수용 기준 계약/Goal 연결
CCR-001 확정 활성 Community target의 답글 0개 원댓글에 답글 작성 버튼을 표시한다. replyCount=0, canMutate=true인 Community root에서 버튼을 찾을 수 있다. contract 불필요, P1-T1
CCR-002 확정 답글 작성을 누르면 선택한 원댓글의 기존 직접 답글 영역과 작성 form을 연다. 버튼 클릭 뒤 해당 원댓글 이름과 연결된 답글 region·textarea·등록 버튼이 표시되고 page 0 GET을 한 번 요청한다. 답글 GET, P1-T1
CCR-003 확정 첫 답글과 후속 직접 답글은 기존 Community 댓글 POST를 사용한다. body가 trim된 comment, 원댓글 ID parentId, isSecret=false를 포함하고 languageCode는 보내지 않는다. 댓글 POST, P1-T1
CCR-004 확정 하나의 원댓글에는 여러 직접 답글을 추가할 수 있다. 답글 등록 성공 후 form을 다시 사용할 수 있고 원댓글·현재 답글 page를 재조회해 추가된 답글을 표시한다. 답글 GET·댓글 POST, P1-T1, P1-GATE
CCR-005 확정 댓글 구조는 원댓글과 직접 답글의 2단계로 제한한다. reply row에는 답글 action이 없고 답글 ID를 parentId로 보내는 작성 경로가 없다. 댓글 POST, P1-T1
CCR-006 확정 기존 권한과 mutation 상태를 유지한다. canMutate=false이면 첫 답글 작성 진입과 form이 없고, pending 중 중복 POST가 없으며 실패 시 초안 유지·성공 시 초기화된다. NullSuccess, P1-GATE

9. 반응형 기능 범위

기능 Desktop Tablet Mobile 비고
답글 작성·답글 보기 진입 지원 지원 지원 기존 댓글 action layout 재사용
여러 직접 답글 조회·작성 지원 지원 지원 기존 page size 20과 pagination 재사용
  • 상위 제품의 최소 320px, 200% zoom, keyboard-only와 touch target 기준을 유지한다.
  • Sheet 내부에서 수평 overflow 없이 form과 action을 사용할 수 있어야 한다.

10. UI/UX Expectations

10.1 디자인과 component 원칙

  • CommentThread, CommentItem, CommentForm을 재사용한다.
  • 오디오와 커뮤니티에 동일한 action label과 펼침 동작을 사용한다.
  • 새 component나 dependency를 추가하지 않는다.
  • 기존 답글이 있는 원댓글의 답글 보기 UI는 유지한다.

10.2 화면 상태

  • 클릭 직후 기존 답글 loading 상태를 표시한다.
  • 빈 답글 응답 뒤에도 작성 form을 표시한다.
  • 조회 오류는 기존 재시도 UI를 사용한다.
  • 작성 중·성공·실패는 기존 Comments mutation 정책을 사용한다.
  • 답글 작성 성공 후 form은 빈 값으로 초기화되고 다시 입력할 수 있다.

10.3 접근성

  • 버튼의 accessible name은 원댓글 내용과 답글 작성 또는 답글 보기를 조합해 식별 가능해야 한다.
  • form의 visible label과 오류 연결, keyboard focus 표시를 유지한다.
  • 답글 region은 원댓글 내용과 답글을 조합한 accessible name을 유지한다.
  • keyboard-only로 Sheet의 원댓글에서 답글 form까지 진입하고 등록할 수 있어야 한다.

11. API 계약

11.1 공통 규칙

11.2 Endpoint 추적

요구사항 Method Path 계약 상태 소유 Goal
CCR-002, CCR-004 GET /api/v2/admin/ai-characters/{characterId}/community-posts/{postId}/comments/{commentId}/replies 기존 제공·구현됨 P1-T1
CCR-003~005 POST /api/v2/admin/ai-characters/{characterId}/community-posts/{postId}/comments 기존 제공·구현됨 P1-T1

11.3 외부 제공 대기 계약

없음. 필요한 GET·POST, DTO와 mock handler가 이미 제공돼 있다.

12. 보안과 데이터 취급

  • 기존 Bearer 인증, ADMIN 권한과 characterId·postId target 격리를 유지한다.
  • parentId는 현재 Community target에서 응답받은 활성 원댓글 ID만 사용한다.
  • 댓글 본문과 인증 정보는 console, 분석 이벤트와 영구 저장소에 기록하지 않는다.
  • 401·403은 공통 인증·인가 정책을 따른다.
  • 클라이언트 validation은 서버의 target·parent 소유권 검증을 대체하지 않는다.

13. 성능과 품질 요구사항

  • 답글 action을 누를 때 선택한 원댓글의 답글 page 0만 기존 방식으로 조회한다.
  • 답글 page size 20과 기존 pagination을 유지하며 전체 답글을 선조회하지 않는다.
  • 새 dependency, 캐시 계층과 optimistic update를 추가하지 않는다.
  • Vitest focused test, Comments 회귀, Chromium mock E2E, typecheck와 lint를 통과한다.
  • server 404나 network error를 mock으로 자동 전환하지 않는다.

14. 성공 기준

14.1 기능 수용 기준

  • 답글 0개인 활성 Community root에서 첫 답글을 작성한다. (CCR-001~003)
  • 같은 원댓글에 여러 직접 답글을 작성·조회한다. (CCR-004)
  • reply row와 비활성 workspace의 2단계·권한 경계가 유지된다. (CCR-005~006)
  • 실패·재시도와 중복 제출 방지가 회귀하지 않는다. (CCR-006)

14.2 UI/UX 수용 기준

  • 버튼·답글 region·form의 accessible name과 label이 연결된다.
  • 320px·200% zoom에서 수평 overflow 없이 답글을 작성한다.
  • keyboard-only로 답글 form에 진입하고 등록할 수 있다.

14.3 추적성 완료 기준

  • 모든 확정 요구사항이 API 또는 contract 불필요 판정, P1-T1, P1-GATE와 연결된다.
  • 구현·검증 결과가 plan-task.md의 Progress에 기록된다.
  • 완료된 Phase의 리뷰가 reviews/ 아래에 기록된다.

15. Open Questions

없음.

16. 요구사항 추적표

요구사항 범위 API Contract 계획 Phase Goal 자동 검증 수동 검증
CCR-001~006 api-contract.md 1 P1-T1, P1-GATE comment-thread.test.tsx, comments.spec.ts 활성 Community 첫·추가 답글, 비활성·2단계·320px·keyboard 경계

17. Decision Log

날짜 ID 상태 결정 근거 영향 요구사항·계약·Goal
2026-08-06 CCR-DEC-001 확정 오디오 콘텐츠와 동일한 첫 답글 진입을 활성 커뮤니티 원댓글에도 적용한다. 사용자 요청 CCR-001~003, P1-T1
2026-08-06 CCR-DEC-002 확정 댓글 트리는 원댓글 아래 여러 직접 답글을 허용하되 답글의 답글은 허용하지 않는다. 사용자 요청의 “1단계 추가, 여러 개” 조건 CCR-004~005, api-contract.md
2026-08-06 CCR-DEC-003 확정 새 API·컴포넌트 없이 기존 Community GET·POST와 Comments UI를 재사용한다. OpenAPI와 구현 확인 CCR-002~006, P1-T1

18. 변경 관리

  • 범위가 바뀌면 이 문서의 Decision Log와 요구사항을 먼저 갱신한다.
  • API가 바뀌면 api-contract.md와 원본 OpenAPI의 제공 버전을 확인한다.
  • 구현 범위가 바뀌면 코드보다 plan-task.md를 먼저 갱신한다.
  • 기존 Progress, review와 검증 기록은 삭제하거나 덮어쓰지 않는다.