egbim_homepage/FEEDBACK_CUSTOM_QNA_API_TASKS.md

feedback.mac.kr 커스텀 Q&A API 연동 작업 목록

목표

• 현재 사이트의 커스텀 Q&A 데이터를 feedback.mac.kr 관리 서버로 전송한다.
• 기존 egbim/ 및 eng/ Q&A 기능은 계속 사용할 수 있어야 한다.
• 기존 데이터는 1회 백필하고, 이후 신규 등록·수정·댓글·상태 변경·삭제를 증분 동기화한다.
• 첨부파일과 댓글 이미지는 Cloudflare R2에 저장하고, 관리 서버에는 R2 객체 정보만 전달한다.
• 관리 서버에서 Q&A 본문, 답변/댓글, 첨부파일, 작성자 정보, 상태를 일관되게 조회할 수 있도록 한다.

범위

포함

• 커스텀 Q&A 게시글: qa_posts
• 게시글 첨부파일: qa_attachments
• 댓글/답변: qa_comments
• 댓글 이미지와 썸네일: qa_comment_images
• 댓글 이미지 원본과 썸네일: R2 저장 대상
• 에디터 본문에 삽입된 이미지: R2 저장 대상
• 국문 경로: egbim/bbs/descope_qa_*.php
• 영문 경로: eng/bbs/descope_qa_*.php

제외

• 그누보드 기본 1:1 문의: g5_qa_content, g5_qa_config
• 쇼핑몰 상품 Q&A: g5_shop_item_qa
• 일반 게시판의 Q&A성 글
• FAQ 및 기타 관리자 데이터

현재 코드 기준 데이터 흐름

기능	현재 엔드포인트	저장 데이터
목록 조회	bbs/descope_qa_list.php	qa_posts, 댓글 수, 첨부 수
상세 조회	bbs/descope_qa_detail.php	qa_posts, qa_comments, qa_attachments, qa_comment_images
글 등록/수정	bbs/descope_qa_write.php	qa_posts, qa_attachments
댓글 등록	bbs/descope_qa_comment.php	qa_comments, qa_comment_images
댓글 수정	bbs/descope_qa_comment_update.php	qa_comments
댓글 삭제	bbs/descope_qa_comment_delete.php	qa_comments
글 상태 변경	bbs/descope_qa_status.php	qa_posts.status
글 삭제	bbs/descope_qa_delete.php	게시글·댓글·첨부 삭제
본문 이미지 업로드	bbs/descope_qa_img_upload.php	파일 시스템, 본문 URL

1. 연동 정책 확정

• feedback.mac.kr가 데이터를 받는 방식 확정: Push API 또는 관리 서버의 Pull API
• 운영 API Base URL 및 환경별 URL 확정
• 인증 방식 확정: API Key, HMAC 서명, OAuth2 등
• API 버전과 리소스 경로 확정
• 전송 대상 사이트 구분값 확정: ko, en 또는 egbim, eng
• 관리 서버가 원본 데이터를 저장하는지, 단순 조회 프록시인지 확정
• 삭제 데이터를 실제 삭제할지 deleted 상태로 보존할지 확정
• 비밀글의 본문·R2 첨부파일을 관리자 서버에서 어떻게 표시할지 확정
• 개인정보 보관 기간 및 마스킹 정책 확정

권장 동기화 방식

• 최초 1회: 커스텀 Q&A 전체 백필
• 이후: 변경 이벤트를 동기화 큐에 기록한 뒤 API로 재시도 전송
• API 전송 성공 여부는 원본 트랜잭션과 분리해 관리
• 동일 데이터 재전송이 가능하도록 source, source_id, event_id 기반 멱등성 보장

2. 원본 데이터 구조 확인

저장소에는 커스텀 테이블의 정식 DDL이 없으므로 실제 운영 DB에서 컬럼, 타입, 인덱스, 기본값을 확인해야 한다.

• SHOW CREATE TABLE qa_posts 확보
• SHOW CREATE TABLE qa_comments 확보
• SHOW CREATE TABLE qa_attachments 확보
• SHOW CREATE TABLE qa_comment_images 확보
• 국문/영문 사이트가 동일 DB와 동일 테이블을 사용하는지 확인
• 각 테이블의 건수와 최대 ID 확인
• 고아 레코드 확인: 게시글 없는 댓글/첨부, 댓글 없는 이미지
• 실제 파일이 없는 첨부 레코드 확인
• DB의 시간대와 API 전송 시간 포맷을 Asia/Seoul 기준으로 통일

3. API 데이터 계약 설계

게시글 기본 필드

• source: egbim 또는 eng
• source_id: 원본 qa_posts.post_id
• category: general, improvement, error, notice, admin
• title
• content
• is_secret
• status: new, review, deep, patch, done
• is_read_admin
• created_at, updated_at

작성자 필드

• user_id
• login_id
• user_name
• phone 전송 여부 및 마스킹 방식
• is_internal
• company
• family_company
• department
• 관리자 표시명 변환 전 원본과 변환 후 표시명 중 무엇을 저장할지 결정

댓글/답변 필드

• comment_id
• 원본 게시글 ID
• commenter
• user_name
• content
• created_at, updated_at
• 댓글 수정·삭제 여부와 삭제 시각을 보낼 수 있도록 컬럼 또는 이벤트 구조 보완

첨부파일 필드

• id 또는 image_id
• 원본 게시글/댓글 ID
• ori_name 또는 file_name
• 저장 경로
• 공개 URL 또는 관리 서버용 다운로드 URL
• 파일 크기
• MIME 타입 및 확장자
• 썸네일 URL
• uploaded_at
• 파일 삭제 여부와 삭제 시각
• 파일 저장소는 Cloudflare R2로 사용
• API에는 파일 자체를 보내지 않고 R2 객체 키·메타데이터를 보낼지 확정
• R2 공개 URL, 커스텀 도메인, presigned URL 중 접근 방식 확정
• 관리 서버가 R2에서 파일을 가져갈 수 있도록 할지, 원본 서버가 임시 URL을 발급할지 결정

4. API 엔드포인트 구현

공통 API 클라이언트

• feedback.mac.kr 전용 API 클라이언트 작성
• Base URL, 인증키, timeout을 환경변수로 분리
• TLS 인증서 검증 활성화
• 요청 ID와 원본 ID를 모든 요청 헤더/본문에 포함
• 연결 실패, 4xx, 5xx, timeout을 구분해 기록
• 재시도 가능한 오류와 즉시 실패해야 하는 오류 구분
• 응답 JSON 스키마 검증
• API 인증키와 개인정보가 로그에 남지 않도록 마스킹

권장 리소스 API

• POST /api/v1/qna/sync — 게시글 전체 snapshot upsert
• POST /api/v1/qna/events — 등록·수정·댓글·상태·삭제 이벤트 전송
• POST /api/v1/qna/assets — R2 객체 키와 첨부파일 메타데이터 등록
• GET /api/v1/qna/sync/status — 백필/증분 동기화 상태 확인
• 관리 서버의 실제 계약에 맞춰 경로와 payload 확정

5. 동기화 기록 및 재처리 구조

원본 저장 성공 후 API가 실패해도 사용자 작업이 실패하지 않도록 별도 동기화 기록이 필요하다.

• qna_sync_events 테이블 설계
• 이벤트 종류 정의: post.created, post.updated, post.deleted, comment.created, comment.updated, comment.deleted, status.changed, attachment.created, attachment.deleted
• 원본 테이블명과 원본 ID 저장
• payload 또는 payload 생성에 필요한 snapshot 저장
• event_id unique 제약으로 중복 전송 방지
• 상태 정의: pending, sending, sent, failed, dead_letter
• 시도 횟수, 마지막 오류, 다음 재시도 시각 저장
• 재처리용 CLI 또는 관리자 실행 도구 작성
• 일정 시간 sending 상태로 남은 이벤트 복구 처리
• 삭제 이벤트가 누락되지 않도록 soft-delete 또는 삭제 이력 보존

6. 기존 기능에 이벤트 연결

국문과 영문 코드에 같은 정책을 적용해야 한다.

• egbim/bbs/descope_qa_write.php 신규 등록 후 이벤트 생성
• egbim/bbs/descope_qa_write.php 수정 후 이벤트 생성
• eng/bbs/descope_qa_write.php 신규 등록 후 이벤트 생성
• eng/bbs/descope_qa_write.php 수정 후 이벤트 생성
• 댓글 등록 시 게시글과 댓글 이미지 이벤트 생성
• 댓글 수정 시 수정 이벤트 생성
• 댓글 삭제 시 삭제 이벤트 생성
• 게시글 상태 변경 시 상태 이벤트 생성
• 게시글 삭제 시 게시글·댓글·첨부 삭제 이벤트 순서 정의
• 에디터 이미지 업로드 시 이미지 자산 동기화 정책 적용
• 기존 화면의 저장/리다이렉트/JSON 응답 형식을 깨뜨리지 않는지 확인

트랜잭션 처리 원칙

• 게시글/댓글/첨부 DB 저장과 동기화 이벤트 기록은 동일 DB 트랜잭션으로 처리
• R2 업로드 성공 후 원본 DB에 객체 키를 저장
• 외부 API 호출은 원본 DB 트랜잭션 안에서 직접 실행하지 않음
• 이벤트 기록 성공 후 사용자에게 정상 응답
• 외부 API 실패는 백그라운드 재처리 대상으로 남김
• DB 저장 실패 시 이미 업로드된 R2 객체를 삭제하거나 orphan 정리 큐에 등록

7. 기존 데이터 백필

• 백필 기준 시각과 대상 ID 범위 확정
• qa_posts 전체를 페이지 단위로 추출
• 게시글별 qa_comments 추출
• 게시글별 qa_attachments 추출
• 댓글별 qa_comment_images 추출
• 본문 HTML에 포함된 이미지 URL 추출
• 파일 존재 여부와 파일 크기 검증
• 파일이 없는 레코드는 오류 목록으로 분리
• 원본 ID 보존형 upsert 적용
• 기존 로컬 파일을 R2로 대량 이전
• 대량 R2 업로드 속도 제한 및 실패 재시도 적용
• 백필 중 신규 변경분을 놓치지 않도록 기준 시각 이후 이벤트 재전송
• 백필 종료 후 원본 건수와 관리 서버 건수 대조

8. R2 첨부파일·이미지 처리

게시글 첨부파일, 댓글 이미지 원본·썸네일, 에디터 이미지를 모두 R2에 저장한다. feedback.mac.kr API에는 파일 바이너리 대신 R2 객체 식별자와 메타데이터를 전달하는 방향을 우선한다.

R2 저장 구조

• R2 버킷명과 환경별 버킷 분리 여부 확정
• R2 객체 prefix 확정: 예) qna/{source}/{post_id}/attachments/
• 댓글 이미지 prefix 확정: 예) qna/{source}/{post_id}/comments/{comment_id}/images/
• 댓글 썸네일 prefix 확정: 예) qna/{source}/{post_id}/comments/{comment_id}/thumbs/
• 에디터 이미지 prefix 확정: 예) qna/{source}/{post_id}/content/
• 동일 파일 재업로드 방지를 위한 object key 또는 content hash 정책 확정
• R2 객체에 원본 파일명, MIME, 크기, source ID를 metadata로 저장
• egbim과 eng 파일의 prefix가 충돌하지 않는지 확인

대상별 이전·저장

• 게시글 첨부 원본 이전: /egbim/uploads/qa/
• 영문 게시글 첨부 원본 이전: /eng/uploads/qa/
• 댓글 이미지 원본 이전: /egbim/uploads/comment/, /eng/uploads/comment/
• 댓글 이미지 썸네일 이전: 각 comment/thumb/ 경로
• 에디터 이미지 이전: /egbim/uploads/img/, /eng/uploads/img/
• 기존 DB의 save_path, file_path, thumb_path를 R2 object key와 연결
• 이전 완료 후에도 기존 URL을 일정 기간 유지하거나 redirect 처리
• 실제 파일이 없는 DB 레코드는 오류 목록으로 분리
• R2에만 존재하거나 DB에만 존재하는 orphan 파일 정리

업로드 흐름

• 신규 게시글 첨부는 R2 업로드 성공 후 qa_attachments 저장
• 댓글 이미지 원본과 썸네일 생성 후 R2 업로드
• qa_comment_images에는 R2 object key와 접근 URL 정보를 저장
• 에디터 이미지도 R2 업로드 후 본문에 최종 URL 저장
• R2 업로드 실패 시 Q&A 저장을 실패시키거나 임시 업로드로 분리할지 결정
• DB 저장 실패 시 R2 orphan 정리 작업 등록
• 파일 삭제 시 DB 삭제와 R2 객체 삭제 순서 및 재처리 정책 정의

접근 방식

• 공개 이미지와 비공개 첨부파일의 접근 정책 분리
• 권장안: 비밀글 첨부는 R2 비공개 저장 + 관리 서버 요청 시 짧은 presigned URL 발급
• 공개 가능한 공지 이미지 등은 R2 custom domain/CDN URL 사용 여부 결정
• API payload에는 bucket, object_key, mime_type, file_size, original_name, url 또는 download_token 전달
• presigned URL 만료시간과 재발급 API 정의
• 관리 서버가 원본 사이트 세션 없이도 권한 검사를 통과하는 구조인지 확인
• R2 CORS 정책에 실제 사용 Origin만 등록
• R2 lifecycle 정책: orphan 파일, 임시 업로드, 삭제 보류 파일 정리

코드 정리

• R2 SDK 또는 S3 호환 클라이언트 공통 모듈 작성
• R2 endpoint, access key, secret key, bucket을 환경변수로 분리
• 게시글 첨부·댓글 이미지·에디터 이미지가 같은 업로드 모듈을 사용하도록 통합
• 상대경로와 로컬 절대경로를 R2 object key로 변환하는 마이그레이션 유틸리티 작성
• 파일명 인코딩, 한글 파일명, 특수문자 처리 확인
• 허용 확장자와 MIME 타입을 원본 서버와 R2 업로드 단계에서 검증

9. 보안 및 개인정보

• API 인증정보를 코드에 하드코딩하지 않음
• 운영/개발/로컬 API 키 분리
• API 수신 서버 allowlist 또는 IP 제한 검토
• HMAC 사용 시 timestamp와 nonce 검증
• 재전송 공격 방지
• phone, login_id, 이메일 등 개인정보의 전송 범위 확정
• IP 주소는 기본적으로 전송하지 않거나 별도 마스킹
• 비밀글 본문과 첨부파일이 공개 URL로 노출되지 않도록 확인
• R2 access key/secret key를 코드와 API payload에 노출하지 않음
• presigned URL이 로그·DB·브라우저에 필요 이상으로 남지 않도록 만료시간 설정
• HTML 본문을 관리 서버에서 출력할 때 XSS 정화 정책 통일
• API 요청/응답 로그에서 본문·첨부 내용·개인정보를 최소화
• API 키 교체 절차와 유출 시 폐기 절차 문서화

10. 관측성 및 운영

• 동기화 성공/실패 건수 모니터링
• 대기 이벤트 수와 가장 오래된 대기 시간을 모니터링
• 연속 실패 시 알림 기준 설정
• source_id, event_id, request_id로 양쪽 로그 추적
• 백필 진행률과 실패 목록 조회 기능 제공
• API 응답 지연 및 오류율 기록
• 개인정보가 포함된 원문 로그 보관 금지
• 재처리 작업의 중복 실행 방지

11. 테스트 시나리오

기능

• 신규 게시글 등록 → 관리 서버 생성 확인
• 게시글 수정 → 관리 서버 동일 레코드 갱신 확인
• 게시글 상태 변경 → 관리 서버 상태 갱신 확인
• 댓글 등록 → 관리 서버 댓글 생성 확인
• 댓글 수정 → 관리 서버 댓글 갱신 확인
• 댓글 삭제 → 관리 서버 댓글 삭제/숨김 확인
• 게시글 첨부 등록 → 파일과 메타데이터 확인
• 댓글 이미지 등록 → 원본과 썸네일 확인
• 에디터 이미지 등록 → 본문 링크와 파일 확인
• 게시글 삭제 → 관리 서버 삭제 정책 확인
• 비밀글의 본문·첨부 권한 확인

장애·재처리

• 관리 서버 timeout 후 원본 저장 성공 확인
• 500 응답 후 자동 재시도 확인
• 400 응답이 무한 재시도되지 않는지 확인
• 동일 이벤트를 여러 번 보내도 중복 레코드가 생기지 않는지 확인
• API 키 오류 시 사용자 기능과 동기화 실패가 분리되는지 확인
• 이벤트 큐가 쌓인 뒤 정상 복구되는지 확인
• 삭제 직후 재전송 시 최종 상태가 일관적인지 확인

국문/영문

• egbim 신규/수정/댓글/삭제 흐름 검증
• eng 신규/수정/댓글/삭제 흐름 검증
• 관리 서버에서 사이트 구분이 정확한지 확인
• 같은 DB를 공유하는 경우 중복 전송이 발생하지 않는지 확인

12. 완료 기준

• 커스텀 Q&A 전체 데이터의 게시글·댓글·첨부·이미지가 관리 서버에서 조회됨
• 최초 백필 누락 건수가 0건이거나 승인된 예외 목록으로 관리됨
• 신규 등록·수정·댓글·상태 변경·삭제가 정해진 지연시간 내 반영됨
• API 장애가 원본 Q&A 사용을 막지 않음
• 실패 이벤트를 재처리할 수 있음
• 중복 전송에도 관리 서버 데이터가 중복되지 않음
• 비밀글과 개인정보가 정책에 맞게 보호됨
• 국문/영문 양쪽의 테스트가 완료됨
• 운영 배포 및 장애 대응 절차가 문서화됨

우선순위 제안

1. 관리 서버 API 계약과 인증 방식 확정
2. 네 개 커스텀 테이블의 실제 DDL/건수/파일 현황 확인
3. 동기화 이벤트 테이블과 공통 API 클라이언트 구현
4. 게시글·댓글 저장 흐름에 이벤트 기록 연결
5. R2 업로드 모듈 및 첨부파일/댓글 이미지 이전 구현
6. 기존 데이터 백필
7. 장애 재처리·모니터링·운영 배포

결정이 필요한 항목

• feedback.mac.kr API 명세 또는 수신 엔드포인트
• Push와 Pull 중 최종 방식
• API 인증 방식 및 키 발급 방법
• 게시글·댓글·첨부 삭제 보존 정책
• 개인정보 전송 필드와 마스킹 기준
• R2 버킷, prefix, public/custom domain 정책
• R2 공개 URL과 presigned URL 사용 범위
• R2 첨부파일 전송·삭제·보존 정책
• 국문/영문 데이터가 관리 서버에서 분리되어야 하는지 여부
• API 장애 시 허용 가능한 동기화 지연시간