egbim_qa_platform/docs/admin-console-integration-feedback-requirements-2026-09-02.md

관리페이지 통합 관리 피드백 정리

• 작성일: 2026-09-02
• 대상: 관리페이지의 프로젝트 통합 관리페이지(/main/overview)
• 목적: 오늘 피드백을 기준으로 통합 관리페이지 및 관리자 설정의 수정 범위를 먼저 정의한다.
• 문서 상태: 요구사항 및 자동화 시퀀스 초안

1. 반영 범위

이번 범위는 다음 화면을 중심으로 한다.

• 프로젝트 통합 관리페이지
  • 피드백 처리 탭
  • 이슈 처리 탭
  • 상단 요약 지표
  • 피드백 상세 팝업
• 관리자 설정
  • 관리자 목록
  • 프로젝트별 기본 관리자 지정
• 공통 상단 네비게이션
  • 프로필 메뉴
  • 언어 설정
  • 설정 메뉴
• 프로젝트 목록 및 프로젝트 선택 영역

2. 요구사항 목록

2.1 상단 및 공통 네비게이션

1) 관리자 Todo 부연 설명 문구

• 관리자 Todo 아래의 부연 설명 문구를 제거한다.
• 상태: 추후 적용 / 별도 지시 전까지 보류
• 별도 지시가 있을 때까지 현재 문구의 적용 상태는 유지한다.

2) 상단 요약 데이터 박스

• 다음 항목을 제거한다.
  • 이슈 연결률
  • 평균 처리 시간
• 나머지 6개 항목은 한 줄에 표시한다.
• 6개 박스가 화면 너비를 균등하게 사용할 수 있도록 width와 grid를 조정한다.
• 현재 유지 대상 항목:
  • 오늘 등록된 피드백
  • 오늘 답변 대기
  • 담당자 미지정
  • 피드백 상태 처리 필요
  • 전체 피드백
  • 답변 대기

3) 언어 설정 위치

• 최상단에 별도로 노출된 언어 설정 항목을 제거한다.
• 프로필 아이콘 하위 메뉴의 옵션으로 이동한다.
• 언어 설정 항목의 아이콘은 제거한다.

4) 테넌트 설정 및 화면 색상 설정 위치

• 테넌트 설정을 Setting 메뉴 하위 항목으로 이동한다.
• 화면 색상 설정을 Setting 메뉴 하위 항목으로 이동한다.
• 최상단에 직접 노출된 기존 항목은 제거한다.

5) Setting 메뉴 위치 및 아이콘

• Setting 메뉴를 톱니바퀴 아이콘으로 표시한다.
• 프로필 아이콘의 오른쪽에 정렬한다.
• 기존 Setting 텍스트 노출 여부는 아이콘 중심으로 재검토한다.

2.2 통합 관리페이지 피드백 처리 탭

6) Like 검색

• 피드백 처리 탭 상단에 Like 검색 기능을 추가한다.
• 검색 입력과 검색 실행 영역은 기존 리스트 상단 필터 영역과 함께 배치한다.
• 검색 대상과 검색 방식은 현재 피드백 API의 검색 조건을 재사용할 수 있도록 설계한다.

7) 담당자 및 피드백 상태 표시 방식

• 리스트의 담당자와 피드백 상태 항목은 현재 값만 표시한다.
• 리스트 안에서 직접 변경하는 컨트롤은 제거한다.
• 담당자 지정 및 피드백 상태 변경은 피드백 상세 팝업 안에서만 제공한다.
• 상세 팝업에서 변경한 결과는 리스트에 즉시 반영한다.

8) 관리자 댓글 컬럼

• 피드백 리스트의 관리자 댓글 컬럼을 삭제한다.
• 관리자 댓글 작성 및 조회는 상세 팝업에서 처리한다.

9) 생성일 및 업데이트일

• 생성일 옆에 업데이트일을 추가한다.
• 업데이트일은 다음 이벤트가 발생했을 때 변경되어야 한다.
  • 피드백 설정 변경
  • 관리자 댓글 등록
• 업데이트일은 리스트와 상세 팝업에서 동일한 기준으로 표시한다.
• 관리자 댓글이 별도 테이블에 저장되는 현재 구조를 고려해, 댓글 등록 시 피드백의 최종 업데이트 시각을 갱신하거나 별도 통합 업데이트 시각을 제공해야 한다.

2.3 프로젝트 통합 구조

10) 통합 관리페이지의 프로젝트 편입

• 프로젝트 통합 관리페이지를 프로젝트 목록의 프로젝트 항목으로 편입한다.
• 프로젝트 목록 최상단에 고정한다.
• 통합 관리페이지의 프로젝트 번호는 0으로 고정한다.
• 프로젝트 번호 정렬 및 표시 로직은 0번 프로젝트가 항상 최상단에 오도록 조정한다.
• 추후 프로젝트 코드는 4자리 형식으로 변경될 예정이므로, 프로젝트 ID와 표시용 프로젝트 코드를 분리할 수 있도록 설계한다.
• 일반 프로젝트의 기존 이동 및 선택 동작은 유지한다.

2.4 관리자 설정 및 기본 관리자

11) 프로젝트별 기본 관리자 지정

• 관리자 설정에 프로젝트별 기본 관리자 지정 기능을 추가한다.
• 각 프로젝트에 기본 관리자를 지정할 수 있어야 한다.
• 관리자 설정 화면에서 현재 지정된 기본 관리자를 확인하고 변경할 수 있어야 한다.

12) 기본 관리자 자동 담당자 지정

• 프로젝트에 기본 관리자가 지정되어 있으면, 피드백에 별도 담당자가 없을 때 기본 관리자를 담당자로 사용한다.
• 사용자가 별도로 담당자를 지정한 경우에는 별도 지정값을 우선한다.
• 프로젝트에 기본 관리자가 없으면 현재처럼 담당자 항목을 공란으로 표시한다.
• 자동 지정 시점은 피드백 생성 시점과 조회 시점의 데이터 일관성을 고려해 결정한다.

2.5 신규 피드백 표시 및 정렬

13) 읽지 않은 피드백 New 표시

• 누구든지 피드백을 한 번이라도 읽으면 해당 피드백을 읽은 상태로 기록한다.
• 한 명이라도 읽은 피드백은 신규 강조 대상에서 제외한다.
• 아직 아무도 읽지 않은 피드백은 피드백 제목 옆에 NEW를 표시한다.
• NEW는 빨간색으로 강조한다.
• 피드백 상세 팝업 진입 또는 읽음 처리 API 호출 시 읽음 상태가 저장되어야 한다.
• 프로젝트 통합 관리페이지의 목록 갱신 후에도 읽음 상태가 유지되어야 한다.

14) 피드백 리스트 정렬

• 피드백 리스트 상단에 정렬 기능을 추가한다.
• 정렬 기준과 오름차순/내림차순을 선택할 수 있어야 한다.
• 최소 정렬 기준 후보:
  • 생성일
  • 업데이트일
  • 피드백 상태
  • 담당자
  • 우선순위
• 기본 정렬 기준과 정렬 상태 유지 범위는 구현 단계에서 확정한다.

2.6 피드백 상세 팝업 개선

16) 상세 팝업 이슈 처리

• 피드백 상세 팝업에서 연결된 이슈를 확인할 수 있어야 한다.
• 상세 팝업에서 기존 이슈를 피드백에 연결하거나 연결 해제할 수 있어야 한다.
• 연결된 이슈별 상태를 상세 팝업에서 변경할 수 있어야 한다.
• 이슈 연결/해제 및 상태 변경 결과는 목록에 즉시 반영되어야 한다.
• 이슈 연결/해제는 feedback_issue_update, 이슈 상태 변경은 issue_update 권한을 따른다.

17) 이슈 상태 및 피드백 상태 배치

• 상세 팝업의 처리 상태 제목과 설명 문구를 제거한다.
• 이슈 상태와 피드백 상태를 한 줄의 동일한 너비(각 50%)로 배치한다.
• 상태 변경 컨트롤은 각 영역 안에서 제공한다.

18) 사용자 정보 표시

• 피드백 상세 팝업의 사용자 정보에서 부서 항목을 제외한다.
• 이름, 이메일, 전화번호 및 접속 정보 등 나머지 사용자 정보는 유지한다.

19) 댓글/내부 메모가 없는 상세 팝업 높이

• 최초 댓글과 내부 메모가 모두 없는 경우 빈 목록 영역 때문에 불필요한 세로 스크롤이 생기지 않아야 한다.
• 상세 팝업은 실제 콘텐츠 높이에 맞춰 표시하되, 화면 높이를 초과하는 경우에만 내부 스크롤을 제공한다.
• 관리자 댓글 목록과 댓글 작성 영역은 한 화면에서 함께 확인할 수 있도록 배치한다.

20) 상세 팝업 보조 설명 문구

• 첨부파일, 담당자, 내부 메모, 관리자 댓글 등 각 항목의 추가 부연 설명 문구를 제거한다.
• 항목명과 실제 데이터/입력 영역을 우선 노출해 관리자 댓글 작성 영역이 가려지지 않도록 한다.

3. 현재 구현과의 연결 지점

현재 통합 관리페이지는 다음 구조를 사용한다.

• 화면: apps/web/src/pages/main/overview.tsx
• 통합 대시보드 조회: GET /api/admin/dashboard/overview
• 피드백 Todo 목록: 대시보드 API의 todos 응답
• 관리자/담당자 권한 조회: secretary-api의 /api/access/*
• 관리자 설정 화면: apps/web/src/widgets/setting-menu/ui/tenant/admin-permission-setting.ui.tsx
• 현재 리스트에서 담당자와 피드백 상태를 직접 변경하는 UI가 존재한다.
• 현재 리스트에 관리자 댓글 컬럼과 댓글 입력 흐름이 존재한다.
• 현재 피드백의 createdAt, updatedAt은 기본 피드백 데이터 기준이며 관리자 댓글 변경 시각과의 통합 여부를 별도로 보완해야 한다.

4. 데이터 및 API 변경 검토사항

4.1 관리자 기본값

• 프로젝트와 기본 관리자 간 매핑 저장 위치를 결정한다.
• 기본 관리자를 1명으로 제한할지 여러 명 허용할지 결정한다.
• 기본 관리자 지정/변경/해제 API가 필요하다.
• 관리자 설정 응답에 프로젝트별 기본 관리자 정보를 포함해야 한다.

4.2 피드백 읽음 상태

• 피드백별 읽음 상태 저장 테이블 또는 필드가 필요하다.
• “누구든지 한 번이라도 읽음”을 판정할 수 있어야 한다.
• 읽은 사용자, 읽은 시각을 감사 추적용으로 저장할지 결정한다.
• 목록 조회 시 isNew 또는 동등한 필드를 반환하는 방식을 검토한다.

4.3 업데이트일

• 피드백 본문/설정 변경과 관리자 댓글 등록을 하나의 업데이트 시각으로 통합할지 결정한다.
• 기존 feedback.updated_at을 갱신하는 방식과 이벤트/이력 기반 방식 중 하나를 선택한다.
• 외부 ABC 데이터와 내부 Secretary 데이터의 업데이트 시각 기준을 구분해야 한다.

4.4 검색 및 정렬

• Like 검색의 대상 필드를 확정한다.
  • 제목
  • 내용
  • 요청자 정보
  • 카테고리
  • 기타 동적 필드
• 검색을 서버 API 쿼리로 처리할지, 현재 조회 결과의 클라이언트 필터로 처리할지 결정한다.
• 정렬 가능한 필드와 null 값 정렬 규칙을 API에 정의한다.
• 페이지네이션 및 최대 조회 건수 제한을 정렬/검색과 함께 검토한다.

4.5 통합 프로젝트 0번

• 프로젝트 목록 API가 가상 프로젝트 0을 반환할지, 프론트에서 고정 항목으로 삽입할지 결정한다.
• 통합 관리페이지를 일반 프로젝트와 동일한 타입으로 다룰지 별도 타입으로 둘지 결정한다.
• 기존 projectId가 필요한 API 호출과 통합 페이지용 API 호출을 분리한다.
• 향후 4자리 프로젝트 코드 변경을 고려해 projectId, projectCode, displayOrder를 혼용하지 않는다.

5. 우선순위 제안

1순위: 목록 사용성 및 데이터 표시

• 2. 요약 박스 6개 한 줄 표시
• 7. 담당자/상태 읽기 전용 표시 및 상세 팝업 제어
• 8. 관리자 댓글 컬럼 삭제
• 9. 업데이트일 표시
• 14. 리스트 정렬
• 6. Like 검색

2순위: 권한 및 자동화

• 11. 프로젝트별 기본 관리자 지정
• 12. 기본 관리자 자동 담당자 지정
• 13. 읽지 않은 피드백 NEW 표시

3순위: 정보 구조 및 네비게이션

• 3. 언어 설정 이동
• 4. 테넌트/화면 색상 설정 이동
• 5. Setting 아이콘 정렬
• 10. 통합 관리페이지의 프로젝트 편입 및 프로젝트 번호 0

보류

• 1. 관리자 Todo 부연 설명 문구 제거
  • 별도 지시 전까지 보류

6. 완료 기준

• 요구사항별 변경 범위와 API/데이터 변경점이 구현 전에 확정되어야 한다.
• 통합 관리페이지에서 피드백 검색, 정렬, 읽음 상태, 업데이트일이 동일한 기간/프로젝트 범위 기준으로 동작해야 한다.
• 담당자와 피드백 상태는 리스트에서 수정할 수 없고 상세 팝업에서만 수정할 수 있어야 한다.
• 이슈 연결/해제 및 이슈 상태 변경은 피드백 상세 팝업에서 처리할 수 있어야 한다.
• 상세 팝업은 댓글/내부 메모가 없을 때 불필요한 스크롤을 만들지 않아야 한다.
• 상세 팝업의 항목별 보조 설명 문구는 노출하지 않아야 한다.
• 관리자 댓글은 리스트 컬럼에 노출되지 않고 상세 팝업에서만 처리되어야 한다.
• 기본 관리자가 지정된 프로젝트의 미지정 피드백에는 기본 담당자가 표시되어야 한다.
• 프로젝트 통합 관리페이지는 프로젝트 목록 최상단에서 프로젝트 번호 0으로 식별되어야 한다.
• 1번 항목은 별도 지시 전까지 구현하지 않는다.

7. 구현 전 확정이 필요한 질문

1. Like 검색의 대상 필드는 제목/내용만으로 할지, 요청자·카테고리까지 포함할지?
2. 프로젝트별 기본 관리자는 1명만 허용할지, 여러 명을 허용할지?
3. 기본 관리자 자동 지정은 피드백 생성 시 실제 데이터를 저장할지, 조회 시 기본값으로 표시할지?
4. 피드백을 읽은 것으로 처리하는 시점은 리스트 노출 시점인지, 제목 클릭/상세 팝업 진입 시점인지?
5. 읽음 상태를 사용자별로 저장할지, 피드백별 최초 읽음 여부만 저장할지?
6. 업데이트일을 기존 feedback.updated_at으로 통일할지, 댓글까지 포함한 별도 lastActivityAt을 둘지?
7. 리스트 기본 정렬은 최신 업데이트일순인지, 최신 생성일순인지?
8. 통합 관리페이지의 프로젝트 번호 0을 API 프로젝트 목록에도 포함할지, 화면에서만 가상 항목으로 처리할지?

8. 피드백·이슈 자동처리 시퀀스 및 예외 정책

• 작성일: 2026-09-03
• 목적: 현재 수동으로 처리하는 피드백·이슈 상태 변경 중 자동화할 수 있는 범위와 예외 상황을 공유한다.
• 용어 정의:
  • Q&A는 사용자가 Q&A 작성 페이지에서 직접 작성한 원문이다.
  • 피드백은 작성된 Q&A가 관리페이지에 도착해 관리되는 접수 항목이다. 즉, Q&A와 피드백은 같은 내용을 가리키지만 사용되는 화면과 역할이 다르다.
• 표기 규칙: 아래 다이어그램의 S는 관리페이지 시스템, A는 관리자, F는 Q&A 작성자, D는 개발자를 의미한다. NaverWorks(SMS) 알림은 관리페이지 시스템이 직접 처리하며 별도 참여자로 표시하지 않는다.

8.1 공통 상태 정의

관리페이지에서 관리되는 피드백과 이슈는 모두 다음 다섯 단계만 사용한다. Q&A는 작성자가 입력한 원문이므로 별도의 처리 상태를 가지지 않고, 관리페이지에 도착한 뒤 피드백으로 관리된다.

상태	코드 예시	정의	자동 변경 여부
신규	NEW	피드백이나 이슈가 처음 만들어져 아직 누구도 처리하지 않은 상태	생성할 때 관리페이지 시스템이 자동으로 지정
접수	RECEIVED	관리자가 내용을 확인해 처리 대상으로 받아들인 상태	관리자가 피드백을 처음 열면 자동 변경. Gitea 이슈 연결 시 이슈도 자동 변경
진행중	IN_PROGRESS	관리자나 개발자가 실제로 답변·수정 작업을 진행하는 상태	관리자 댓글이나 이슈 연결 뒤 피드백은 자동 변경. 개발자의 이슈 변경은 수동 처리
완료	COMPLETED	처리 결과가 확정되어 추가 조치가 필요하지 않은 상태	Q&A 작성자 확인 또는 확인 기간 만료 뒤 피드백 자동 변경. 이슈 완료는 개발자 수동 처리
보류	ON_HOLD	관리자가 판단해 처리를 잠시 멈춘 상태	관리자가 직접 설정하고 직접 해제

완료 확인을 별도 상태로 추가하지 않는 원칙

• 5단계 상태를 유지하기 위해 완료 대기라는 여섯 번째 상태값은 만들지 않는다.
• 관리자가 처리 완료 안내 댓글을 등록하면 피드백 상태는 진행중을 유지하고, completion_requested=true와 completion_requested_at 메타데이터를 기록한다.
• Q&A 작성자가 완료 확인을 하거나 확인 기간이 만료된 때에만 피드백 상태를 완료로 변경한다.
• 화면에는 진행중 상태와 함께 “Q&A 작성자 확인 대기” 배지를 표시할 수 있다. 이 배지는 상태값이 아니다.
• 완료 확인 대기 중 Q&A 작성자의 재문의가 발생하면 completion_requested를 해제하고 피드백을 진행중으로 유지한다.

8.2 자동 변경의 기본 규칙

피드백

• 생성: 신규
• 관리자가 관리페이지의 피드백 상세 페이지를 처음 열람: 피드백 상태를 신규 → 접수로 자동 변경
• 관리자가 처리 과정에 대한 댓글을 등록: 피드백 상태를 신규/접수 → 진행중으로 자동 변경
• 관리자가 피드백에 이슈를 연결해 처리를 시작: 피드백 상태를 신규/접수 → 진행중으로 자동 변경
• 관리자가 처리 완료 안내 댓글을 등록: completion_requested=true 기록 후 진행중 유지
• 보류 상태에서는 위 자동 변경을 적용하지 않는다. 관리자가 먼저 수동으로 보류를 해제해야 한다.
• 완료 상태에서 단순 열람·댓글·동기화만으로 자동 재오픈하지 않는다. 동일 문제에 대한 Q&A 재문의는 관리자에게 알리고, 관리자가 완료 → 진행중으로 수동 변경한다.
• 완료 확인 대기 중 Q&A 작성자의 재문의는 관리자 확인 없이 피드백을 진행중으로 되돌리고 관리자에게 알린다.

관리자 댓글 유형

• 일반 관리자 댓글은 처리 과정의 안내·질문·추가 확인에 사용한다. 피드백이 신규/접수 상태라면 댓글 등록과 함께 진행중으로 자동 변경한다.
• 처리 완료를 알리는 댓글은 completion_notice=true 메타데이터를 가진 “처리 완료 안내 댓글”로 구분한다.
• 처리 완료 안내 댓글은 별도의 완료 처리 버튼이 아니라, 관리자 댓글 작성 영역에서 완료 안내 유형을 선택해 등록하는 방식으로 정의한다.
• 처리 완료 안내 댓글을 등록하면 Q&A 작성자에게 완료 확인을 표시하고, completion_notice_comment_id를 저장한다.
• 완료 확인 대기 중 일반 댓글은 대기 상태를 유지하지만, Q&A 작성자의 재문의 댓글은 완료 확인 대기를 해제한다.

이슈

• 이슈 생성: 신규
• 관리자가 이슈를 처음 열람하거나 Gitea 이슈를 연결: 이슈 상태를 신규 → 접수로 자동 변경
• 개발자가 Gitea 이슈를 확인한 뒤 이슈 상태를 수동 변경: 접수 → 진행중
• 개발자가 처리를 끝낸 뒤 이슈 상태를 수동 변경: 진행중 → 완료
• 개발자 또는 관리자가 완료된 이슈를 다시 열면 이슈를 진행중으로 수동 변경한다.
• 이슈의 보류 설정·해제는 항상 관리자 수동 처리이며, 외부 Gitea 상태 동기화가 덮어쓰지 않는다.

8.3 보류 상태의 우선 규칙

• 보류는 피드백과 이슈 모두 관리자만 직접 설정하고 해제할 수 있다.
• 자동화 이벤트는 현재 상태가 보류인 피드백·이슈의 상태를 변경하지 않는다.
  • 관리자 댓글 등록
  • 이슈 연결
  • Gitea 상태 동기화
  • Q&A 작성자의 댓글 또는 재문의
  • 기간 만료
• 보류 중 Q&A 작성자의 재문의는 댓글과 NaverWorks(SMS) 알림 이력만 기록하고, 피드백 또는 이슈 상태는 보류로 유지한다.
• 관리자가 보류를 해제할 때 접수 또는 진행중 중 하나를 직접 선택한다.
• 보류 중인 이슈가 포함된 피드백은 모든 이슈가 완료되어도 자동 완료 처리하지 않는다.

8.4 다중 이슈 집계 규칙

하나의 피드백에는 이슈가 여러 개 연결될 수 있으며, 각 이슈는 서로 독립적으로 상태를 가진다.

• 이슈가 하나라도 신규, 접수, 진행중이면 피드백은 진행중으로 유지한다.
• 이슈 하나가 완료가 되어도 다른 이슈가 미완료이면 피드백을 완료 처리하지 않는다.
• 연결된 모든 이슈가 완료여도 관리자가 결과를 확인하고 처리 완료 안내 댓글을 등록해야 한다.
• 관리자가 처리 완료 안내 댓글을 등록한 뒤 이슈를 추가로 연결하면 완료 확인 대기를 해제하고 피드백을 진행중으로 되돌린다.
• 이슈를 모두 연결 해제해도 피드백을 자동으로 완료하지 않는다. 관리자가 피드백 처리 결과를 직접 확인해야 한다.
• 이슈 중 하나라도 보류이면 피드백 자동 완료를 금지한다.
• 이슈별 완료 여부, 완료 시각, 외부 Gitea 이슈 번호·상태를 각각 보존해 감사 추적이 가능해야 한다.

8.5 기본 처리·완료·재문의·재오픈 통합 시퀀스

피드백이 생성된 뒤 접수·처리·완료되는 기본 흐름과, 완료 확인 전후에 재문의가 발생하는 예외 흐름을 하나의 시퀀스로 정리한다. 완료 확인 전 재문의는 기존 완료 절차를 취소하고 진행중으로 유지하며, 완료 확정 후 재문의는 관리자의 검토와 수동 재오픈을 거친다.

sequenceDiagram
    autonumber
    participant F as Q&A 작성자
    participant S as 관리페이지 시스템
    participant A as 관리자

    F->>S: 작성 페이지에서 Q&A 작성
    S->>S: 작성된 Q&A를 관리페이지의 피드백으로 등록
    S->>S: 피드백 상태를 신규로 설정

    A->>S: 관리페이지에서 피드백 상세 페이지를 처음 열람
    S->>S: 피드백 상태를 신규에서 접수로 자동 변경

    A->>S: 피드백 처리 과정에 대한 관리자 댓글 등록
    S->>S: 피드백 상태를 접수에서 진행중으로 자동 변경

    A->>S: 처리 결과를 알리는 관리자 댓글 등록

    alt 완료 확인 대기 중
        S->>S: Q&A 작성자의 완료 확인 대기 정보 저장
        Note over S: 피드백 상태는 진행중으로 유지
        S-->>F: 관리페이지에 완료 확인 요청 표시
        S-->>F: NaverWorks(SMS)로 Q&A 작성자에게 완료 확인 요청 알림 발송

        alt Q&A 작성자가 완료 확인
            F->>S: 처리 결과 확인 버튼 클릭
            S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
            S-->>A: NaverWorks(SMS)로 관리자에게 완료 확정 알림 발송
        else Q&A 작성자가 확인하지 않고 기간 만료
            S->>S: 완료 확인 대기 기간 만료 여부를 자동 확인
            S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
            S-->>F: NaverWorks(SMS)로 Q&A 작성자에게 기간 만료 완료 안내 발송
            S-->>A: NaverWorks(SMS)로 관리자에게 기간 만료 완료 처리 알림 발송
        else 완료 확인 전에 Q&A 작성자가 재문의
            F->>S: 같은 내용에 대한 추가 댓글 또는 재문의
            S->>S: 완료 확인 대기 정보를 해제하고 진행중 상태 유지
            S-->>A: NaverWorks(SMS)로 관리자에게 재문의 알림 발송
            A->>S: 추가 처리 또는 기존 이슈 보완
        end
    else 완료 확정 후 동일 문제 재문의
        S->>F: 피드백이 완료 상태임을 표시
        F->>S: 같은 문제에 대한 추가 댓글 작성
        S->>S: 완료 상태를 자동으로 변경하지 않음
        S-->>A: NaverWorks(SMS)로 관리자에게 재문의 검토 알림 발송
        A->>S: 피드백 상태를 완료에서 진행중으로 직접 변경
        A->>S: 재처리 안내 댓글 작성 또는 이슈 재연결
    else 완료 확정 후 새로운 문제 제기
        F->>S: 새로운 내용으로 추가 Q&A 작성
        S->>S: 기존 완료 피드백과 새 Q&A의 연관 정보 기록
        S-->>A: NaverWorks(SMS)로 관리자에게 새 문의 검토 알림 발송
        A->>S: 필요한 경우 기존 피드백을 완료에서 진행중으로 직접 변경
    end

8.6 이슈 처리 및 피드백 연결 시퀀스

이슈는 피드백과의 연결 여부, Gitea 개발 이슈 연결 여부에 따라 처리 흐름을 구분한다.

• 피드백과 연결되지 않은 내부 이슈는 관리자가 관리페이지에서 직접 처리한다.
• 피드백에 연결됐지만 Gitea와 연결되지 않은 내부 이슈는 관리자가 처리하고, 연결된 피드백의 완료 절차까지 이어진다.
• Gitea와 연결된 이슈는 개발자가 Gitea에서 처리하고, 관리자가 결과를 확인한 뒤 연결된 피드백의 완료 절차를 진행한다.
• 하나의 피드백에는 여러 이슈를 연결할 수 있으며, 모든 이슈가 완료되기 전에는 피드백을 완료하지 않는다.

sequenceDiagram
    autonumber
    participant F as Q&A<br/>작성자
    participant S as 관리페이지<br/>시스템
    participant A as 관리자
    participant I1 as 내부 이슈<br/>A
    participant I2 as 내부 이슈<br/>B
    participant G1 as Gitea 이슈<br/>A
    participant G2 as Gitea 이슈<br/>B
    participant D as 개발자

    alt 피드백 연결 없이 내부 이슈만 발생
        A->>S: 관리페이지에서 내부 이슈 A 등록
        S->>I1: 내부 이슈 A 생성 요청
        I1-->>S: 내부 이슈 A를 신규 상태로 생성
        A->>S: 내부 이슈 A 상세 페이지 열람
        S->>S: 이슈 A 상태를 신규에서 접수로 자동 변경
        A->>S: 내부 이슈 A 처리 시작
        A->>S: 이슈 A 상태를 접수에서 진행중으로 직접 변경
        A->>S: 내부 이슈 A 처리 완료
        A->>S: 이슈 A 상태를 진행중에서 완료로 직접 변경
        Note over S: 피드백 연결이 없어 Q&A 작성자 완료 확인 절차는 없음

    else 피드백과 연결된 내부 이슈<br/>(Gitea 연결 없음)
        F->>S: 작성 페이지에서 Q&A 작성
        S->>S: 작성된 Q&A를 관리페이지의 피드백으로 등록
        S->>S: 피드백 상태를 신규로 설정
        A->>S: 관리페이지에서 피드백 상세 페이지 열람
        S->>S: 피드백 상태를 신규에서 접수로 자동 변경
        A->>S: 내부 이슈 A를 새로 등록하고 피드백에 연결
        S->>I1: 내부 이슈 A 생성 요청
        I1-->>S: 내부 이슈 A를 신규 상태로 생성
        S->>S: 피드백 상태를 접수에서 진행중으로 자동 변경
        A->>S: 내부 이슈 A 상세 페이지 열람
        S->>S: 이슈 A 상태를 신규에서 접수로 자동 변경
        A->>S: 내부 이슈 A 처리 시작
        A->>S: 이슈 A 상태를 접수에서 진행중으로 직접 변경
        A->>S: 내부 이슈 A 처리 완료
        A->>S: 이슈 A 상태를 진행중에서 완료로 직접 변경
        S->>S: 연결된 이슈가 모두 완료되었는지 확인
        A->>S: 처리 결과를 확인하고 완료 안내 댓글 등록
        S->>S: Q&A 작성자의 완료 확인 대기 정보 저장
        S-->>F: Q&A 작성자에게 완료 확인 요청 표시

        alt Q&A 작성자가 완료 확인
            F->>S: 처리 결과 확인 버튼 클릭
            S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
        else Q&A 작성자가 확인하지 않고 기간 만료
            S->>S: 완료 확인 대기 기간 만료 여부를 자동 확인
            S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
        end

    else 피드백과 연결된 Gitea 개발 이슈
        F->>S: 작성 페이지에서 Q&A 작성
        S->>S: 작성된 Q&A를 관리페이지의 피드백으로 등록
        S->>S: 피드백 상태를 신규로 설정
        Note over A,S: 관리자가 댓글을 남기면 피드백은 진행중 상태가 됨

        A->>S: 이슈 A를 새로 등록
        S->>I1: 내부 이슈 A 생성 요청
        I1-->>S: 내부 이슈 A를 신규 상태로 생성
        A->>S: 피드백에 이슈 A 연결
        S->>S: 이슈 A 상태를 신규에서 접수로 자동 변경
        S->>S: 피드백 상태를 신규에서 진행중으로 자동 변경
        A->>S: 이슈 A에 Gitea 이슈 연결
        S->>G1: 내부 이슈와 Gitea 이슈 연결
        S->>S: 외부 이슈 연결 이력 저장

        D->>G1: 개발자가 Gitea 이슈 A의 내용을 확인
        D->>S: 이슈 A 상태를 진행중으로 직접 변경
        D->>G1: 개발자가 이슈 A를 처리
        D->>S: 이슈 A 상태를 완료로 직접 변경

        A->>S: 이슈 B를 새로 등록하고<br/>같은 피드백에 연결
        S->>I2: 내부 이슈 B 생성 요청
        I2-->>S: 내부 이슈 B를 신규 상태로 생성
        A->>S: 이슈 B에 Gitea 이슈 연결
        S->>G2: 내부 이슈와 Gitea 이슈 연결
        S->>S: 이슈 B 상태를 신규에서 접수로 자동 변경

        alt 이슈 A만 완료되고<br/>이슈 B는 아직 처리 중
            S->>S: 다른 이슈가 남아 있으므로 피드백을 진행중으로 유지
            Note over S: 연결된 이슈 일부만 완료되어도 피드백은 완료하지 않음
            D->>G2: 개발자가 Gitea 이슈 B를<br/>확인하고 처리
            D->>S: 이슈 B 상태를 접수에서 진행중으로 직접 변경
            D->>S: 이슈 B 상태를 진행중에서 완료로 직접 변경
        else 연결된 모든 이슈가 완료
            S->>S: 연결된 이슈가 모두 완료되었는지 확인
            A->>S: 처리 결과를 확인하고 완료 안내 댓글 등록
            S->>S: Q&A 작성자의 완료 확인 대기 정보 저장
            S-->>F: Q&A 작성자에게 완료 확인 요청 표시

            alt Q&A 작성자가 완료 확인
                F->>S: 처리 결과 확인 버튼 클릭
                S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
            else Q&A 작성자가 확인하지 않고 기간 만료
                S->>S: 완료 확인 대기 기간 만료 여부를 자동 확인
                S->>S: 피드백 상태를 진행중에서 완료로 자동 변경
            end
        end
    end

8.7 보류·외부 상태 충돌 예외 시퀀스

sequenceDiagram
    autonumber
    participant A as 관리자
    participant S as 관리페이지 시스템
    participant G as Gitea
    participant D as 개발자
    participant F as Q&A 작성자

    A->>S: 피드백 또는 이슈 상태를 보류로 직접 설정
    S->>S: 보류 상태 저장

    par 보류 중 이벤트
        A->>S: 관리자 댓글 작성
        S->>S: 댓글은 저장하고 보류 상태는 유지
    and
        D->>G: 개발자가 Gitea 이슈 상태 변경
        G->>S: Gitea 상태 변경 내용을 전달
        S->>S: 보류 상태는 보호하고 동기화 이력만 저장
    and
        F->>S: Q&A 작성자가 추가 문의
        S->>S: 문의 내용을 저장
        S-->>A: NaverWorks(SMS)로 관리자에게 보류 중 문의 알림 발송
    end

    A->>S: 관리자가 보류를 해제하고 다음 상태 선택
    alt 처리 재개
        A->>S: 접수 또는 진행중 상태 선택
        S->>S: 선택한 상태로 변경
    else 다시 보류
        A->>S: 보류 상태 유지
    end

8.8 전이 우선순위 및 예외 처리표

이벤트	현재 상태	기본 처리	예외
피드백 생성	없음	신규	생성 실패 시 상태 전이 없이 재시도·오류 기록
관리자 최초 열람	신규	접수 자동 변경	보류·완료는 변경하지 않음
관리자 댓글 등록	신규/접수	진행중 자동 변경	보류는 유지. 완료는 재오픈 요청만 생성
이슈 연결	신규/접수	피드백을 진행중으로 자동 변경	보류는 유지하고 관리자 재개 필요
Gitea 이슈 연결	이슈 신규	이슈 접수 자동 변경	이슈 보류/완료는 외부 연결만 기록하고 status 보호
개발자 작업 시작	이슈 접수	이슈 진행중 수동 변경	권한 없는 사용자는 변경 불가
개발자 작업 완료	이슈 진행중	이슈 완료 수동 변경	다른 연결 이슈가 미완료면 피드백은 진행중 유지
처리 완료 안내 댓글 등록	피드백 진행중	완료 확인 대기 메타데이터 기록	미완료 이슈·보류 이슈가 있으면 안내 댓글 등록 전 경고
Q&A 작성자 완료 확인	완료 확인 대기	피드백 완료 자동 변경	재문의가 먼저 발생하면 완료 처리 취소
확인 기간 만료	완료 확인 대기	피드백 완료 자동 변경	보류로 수동 전환된 경우 자동 완료 금지
완료 후 동일 문제 재문의	피드백 완료	재오픈 검토 알림	피드백은 관리자가 수동으로 진행중 전환
보류 설정	모든 상태	관리자 수동으로 보류	자동 이벤트가 덮어쓰지 않음
보류 해제	보류	관리자 수동으로 접수/진행중 선택	자동으로 이전 상태를 추정하지 않음

8.9 자동화 구현 시 필수 데이터

• 피드백 상태, 상태 변경자, 상태 변경 시각
• 이슈별 상태, 상태 변경자, 상태 변경 시각
• 피드백-이슈 연결·해제 이력
• Gitea 이슈 번호, URL, 마지막 외부 상태 동기화 시각
• completion_requested, completion_requested_at, completion_requested_by
• completion_notice_comment_id 및 처리 완료 안내 댓글의 원문
• Q&A 작성자의 완료 확인 시각과 확인 사용자
• 완료 확인 만료 기준 시각 및 자동 완료 처리 시각
• 완료 이후 재문의 여부와 관리자 재오픈 여부
• 보류 설정자, 보류 사유, 보류 시작·해제 시각
• 자동화 이벤트의 원본 이벤트 ID와 처리 결과

8.10 구현 전 합의가 필요한 정책

1. 완료 확인 대기 기간을 며칠로 할지, 프로젝트별로 다르게 둘지 결정한다.
2. 완료 확인 대기 중 작성자 재문의가 발생하면 즉시 진행중으로 되돌릴지 결정한다. 본 문서는 즉시 되돌리는 안을 기준으로 한다.
3. 완료 상태에서 작성자의 추가 댓글을 새 피드백으로 분리할지, 기존 피드백의 재오픈 요청으로 처리할지 결정한다.
4. 여러 이슈 중 하나가 보류일 때 피드백 전체를 보류로 자동 표시할지 결정한다. 본 문서는 피드백 status 자동 변경은 하지 않고 완료만 차단하는 안을 기준으로 한다.
5. 이슈 연결을 피드백 신규/접수에서도 허용할지, 진행중에서만 허용할지 결정한다. 본 문서는 연결 시 진행중으로 자동 승격하는 안을 기준으로 한다.
6. Gitea 웹훅으로 이슈 상태를 자동 반영할 범위와 개발자의 수동 변경을 병행할지 결정한다.
7. 처리 완료 안내 댓글을 일반 댓글과 구분하기 위한 completion_notice 선택 UI를 둘지, 특정 댓글 템플릿으로 제한할지 결정한다. 본 문서는 댓글 작성 영역의 유형 선택 UI를 기준으로 한다.

9. 피드백·이슈 자동화 구현 작업계획

9.1 구현 목표

• 8장의 시퀀스와 전이 우선순위를 실제 관리페이지 처리 흐름에 반영한다.
• 피드백과 이슈의 상태 변경을 화면별 임의 처리에서 공통 상태 전이 규칙으로 통합한다.
• 자동 변경과 관리자 수동 변경을 구분하고, 모든 전이 결과와 실패 원인을 추적한다.
• 기존 피드백 원문·댓글·이슈 연결 데이터는 보존하고, 단계별로 호환성을 확인한다.
• 이번 구현에서는 PDF를 수정하지 않고 MD를 기준 문서로 사용한다.

9.2 현재 구조와 상태값 호환 계획

현재 코드는 피드백·이슈에 각각 6개 상태값을 사용한다. 8장의 업무 상태는 5단계이므로 데이터 마이그레이션과 API/UI 호환 처리가 필요하다.

현재 코드 상태	새 업무 상태	처리 원칙
INIT	NEW	신규 작성·생성 직후 상태
ON_REVIEW	RECEIVED	관리자가 확인하기 전후의 기존 검토 상태를 접수로 통합
DETAILED_REVIEW	RECEIVED	상세 검토 상태를 접수로 통합하고 별도 상태로 유지하지 않음
IN_PROGRESS	IN_PROGRESS	처리 진행 상태 유지
RESOLVED	COMPLETED	완료 상태로 통합
PENDING	ON_HOLD	관리자 보류 상태로 통합

• DB 기존 값은 마이그레이션으로 새 코드로 치환한다.
• API 응답·검색·필터·통계·화면 문구는 새 5단계만 노출한다.
• ON_HOLD의 설정·해제는 관리자 수동 전이만 허용한다.
• COMPLETED는 단순 열람·댓글·외부 동기화로 자동 재오픈하지 않는다.
• 전이 로직은 피드백과 이슈에서 동일한 우선순위와 보호 규칙을 사용한다.

9.3 단계별 작업 목록

현재 진행 상태: 0~5단계 핵심 흐름 구현 완료. 상태 5단계 통합, 최초 열람, 관리자 댓글·이슈 연결에 따른 자동 전환, 완료 안내 댓글, 작성자 완료 확인, 7일 만료 자동 완료, 다중 이슈 완료 조건, 보류 메타데이터, 재문의 처리, 관리자 알림과 상태 이력을 반영. 목록 응답 확장, 자동화 실패 화면, 통합 테스트와 운영 전환 검증은 후속 대상으로 남김.

0단계. 기준선 고정 및 전이 계약 작성

• 현재 피드백/이슈 상태의 저장 위치, 변경 API, 화면별 직접 변경 지점을 목록화
• NEW → RECEIVED → IN_PROGRESS → COMPLETED 기본 전이와 ON_HOLD 보호 규칙을 공통 전이표로 코드화
• 자동 전이와 관리자 수동 전이를 구분하는 입력값 정의
  • actorType: SYSTEM, ADMIN, USER, DEVELOPER
  • trigger: 생성, 최초 열람, 댓글, 이슈 연결, 완료 안내, 완료 확인, 기간 만료, 재문의, 외부 동기화 등
• 같은 이벤트가 반복되어도 결과가 중복 생성되지 않도록 멱등성 기준 정의
• 권한 없는 사용자의 전이·보류 해제·완료 후 재오픈 차단

1단계. 데이터 모델 및 마이그레이션

• 피드백 상태를 새 5단계로 정리하고 기존 6단계 데이터를 매핑
• 이슈 상태를 새 5단계로 정리하고 기존 6단계 데이터를 매핑
• 피드백 자동화 메타데이터 저장 구조 추가
  • 완료 확인 요청 여부·요청 시각·요청 댓글 ID
  • 완료 확인 시각·확인 사용자
  • 완료 확인 만료 기준 시각·자동 완료 시각
  • 재문의 및 수동 재오픈 여부
• 보류 정보 저장 구조 추가
  • 보류 설정자·사유·시작 시각·해제 시각·해제 후 선택 상태
• 피드백-이슈 연결·해제 이력과 이슈별 완료 시각 보존
• 기존 데이터가 손실되지 않는 up/down 마이그레이션 작성
• 상태·메타데이터 변경을 하나의 트랜잭션으로 저장

2단계. 공통 상태 전이 서비스

• 피드백 상태 전이 서비스 구현
• 이슈 상태 전이 서비스 구현
• 현재 상태, 요청 주체, 이벤트, 연결 이슈 상태를 함께 검사하는 guard 구현
• ON_HOLD 자동 변경 차단
• COMPLETED 자동 재오픈 차단 및 관리자 수동 재오픈 지원
• 다중 이슈 집계 구현
  • 미완료 이슈가 하나라도 있으면 피드백 완료 차단
  • 보류 이슈가 하나라도 있으면 피드백 완료 차단
  • 연결 해제만으로 피드백을 완료하지 않음
• 상태 변경 이력과 자동화 이벤트 처리 결과 저장
• 기존 직접 상태 수정 API가 공통 전이 서비스를 거치도록 변경

3단계. 자동 이벤트 연결

• 피드백 생성 시 NEW 자동 설정
• 관리자가 피드백 상세를 최초 열람하면 NEW → RECEIVED 자동 변경
• 관리자가 공개 댓글을 등록하면 NEW/RECEIVED → IN_PROGRESS 자동 변경
• 이슈 연결 시 피드백을 IN_PROGRESS로 자동 변경
• 이슈 생성 시 NEW 설정
• 관리자가 이슈를 최초 열람하거나 Gitea 이슈를 연결하면 NEW → RECEIVED 자동 변경
• 개발자 작업 시작·완료는 개발자 권한의 수동 전이로 처리
• 처리 완료 안내 댓글 등록 시 완료 확인 요청 메타데이터 생성
• 완료 확인 대기 중 재문의 발생 시 대기 정보 해제 및 IN_PROGRESS 유지
• 완료 확정 후 재문의 발생 시 알림만 자동 처리하고 관리자의 수동 재오픈을 요구
• Gitea 상태 동기화가 ON_HOLD 상태를 덮어쓰지 않도록 보호

4단계. 완료 확인 및 만료 처리

• Q&A 작성자 상세 화면에 처리 결과 확인 동작 추가
• 완료 확인 전용 API를 멱등하게 구현
• 완료 확인 시 IN_PROGRESS → COMPLETED 자동 변경
• 완료 확인 대기 기간은 프로젝트 설정값으로 분리하고 초기 기본값은 7일로 적용
• 만료 대상 조회 배치 구현
• 다중 인스턴스 실행을 고려한 스케줄러 락 적용
• 만료 처리 성공·실패·재시도 이력 저장
• 완료 확인 및 만료 시 Q&A 작성자·관리자 알림 처리

5단계. 관리자 처리 화면 반영

• 피드백 상세 팝업에서 상태·담당자·이슈 연결·댓글 유형을 전이 규칙에 맞게 제공
• 처리 완료 버튼은 추가하지 않고, 처리 완료 안내 댓글로 완료 확인 요청 생성
• 완료 확인 대기 중인 피드백에 대기 배지·요청 시각 표시
• 이슈 상세 팝업에서 상태 변경 시 수동/자동 전이 규칙 적용
• 보류 설정 시 사유 입력, 보류 해제 시 접수/진행중 선택 제공
• 완료 상태의 재오픈은 관리자 수동 동작으로만 제공
• 다중 이슈 연결 시 개별 이슈 상태와 피드백 완료 가능 여부 표시
• 자동 전이 실패 시 관리자에게 원인과 재처리 방법 표시

6단계. 목록·통계·알림 반영

• 목록의 상태 필터·정렬·요약 박스를 새 5단계 기준으로 변경
• 기본 목록에서는 완료·보류를 제외하되 검색으로 조회 가능하도록 유지
• 피드백/이슈 상태, 연결 이슈 수, 완료 확인 대기 여부를 목록 응답에 포함
• 상태 변경·댓글·이슈 연결·완료 확인·재문의 알림을 기존 관리페이지 시스템 알림 흐름에 연결
• NaverWorks(SMS)는 별도 시퀀스 참여자가 아닌 관리페이지 시스템의 알림 처리 결과로 기록
• 대시보드 집계와 통계가 상태 매핑 이후에도 기존 데이터와 일관성을 갖는지 검증

7단계. 검증 및 전환

• 상태 전이 단위 테스트 작성
• 다중 이슈·보류·완료 확인 대기·재문의·완료 후 재오픈 통합 테스트 작성
• 댓글 중복 등록, 이슈 연결 중복, 완료 확인 중복 요청의 멱등성 테스트 작성
• 마이그레이션 전후 상태·연결·댓글·이력 건수 비교
• 관리자/개발자/Q&A 작성자 권한별 화면·API 접근 검증
• Gitea 웹훅 지연·중복·실패 상황 검증
• 단계적 적용을 위한 기능 플래그 또는 롤백 기준 정의
• 운영 전환 체크리스트와 장애 시 수동 처리 절차 작성

9.4 우선 구현 순서

1. 상태값 5단계 호환 및 공통 전이 guard
2. 피드백 댓글·이슈 연결·이슈 상태 변경 이벤트 연결
3. 다중 이슈 집계와 보류 보호
4. 완료 안내 댓글·Q&A 작성자 완료 확인·만료 처리
5. 목록·상세 화면과 알림 반영
6. 마이그레이션·통합 테스트·운영 전환

9.5 이번 작업의 완료 기준

• 시퀀스에 정의된 기본 흐름이 실제 API 이벤트와 상태 변경으로 재현됨
• 피드백과 이슈 모두 신규/접수/진행중/완료/보류만 사용함
• 보류 상태는 자동 이벤트가 변경하지 않음
• 한 피드백에 여러 이슈가 연결되어도 모든 이슈 완료 전 피드백이 완료되지 않음
• 관리자의 처리 완료 안내 댓글 이후 Q&A 작성자 확인 또는 기간 만료를 거쳐서만 피드백이 완료됨
• 완료 확인 전 재문의와 완료 후 재문의가 서로 다른 규칙으로 처리됨
• 상태 변경·자동 처리·알림·실패 이력이 조회 가능함
• 기존 데이터와 권한 모델을 유지하면서 단계적 롤백이 가능함