egbim_qa_platform/docs/api-packaging-tasks.md

# API 패키징 작업 계획

- 작성일: 2026-08-25
- 목적: 현재 ABC User Feedback와 커스터마이징 기능을 다른 서비스에서 사용할 수 있는 공식 API 패키지로 정리한다.
- 현재 상태: 기능별 API는 대부분 존재하고 Swagger도 연결되어 있으나, 외부 배포용 API 계약과 스키마는 아직 정리되지 않았다.

## 1. 현재 구조

### 1.1 NestJS API

| 구분 | 현재 주소 | 인증 | Swagger |
|---|---|---|---|
| 공개 연동 API | /api/... | x-api-key | /docs |
| 관리자 API | /api/admin/... | JWT + 권한 | /admin-docs |
| Swagger JSON | /docs-json, /admin-docs-json | 서버 설정에 따름 | 생성 가능 |

현재 로컬 확인 주소:

- 공개 API 문서: http://127.0.0.1:4000/docs
- 관리자 API 문서: http://127.0.0.1:4000/admin-docs
- 공개 OpenAPI JSON: http://127.0.0.1:4000/docs-json
- 관리자 OpenAPI JSON: http://127.0.0.1:4000/admin-docs-json

Swagger 설정은 apps/api/src/main.ts에 있으며, 공개 문서 생성 스크립트는 apps/api/src/scripts/build-swagger-docs.ts에 있다.

### 1.2 Secretary API

Secretary API는 FastAPI 자동 문서를 사용한다.

- Swagger UI: :8010/docs
- OpenAPI JSON: :8010/openapi.json

현재 Secretary API에는 SSO 기반 접근 정보, workspace, ticket, 댓글, 내부 메모, 첨부파일, 담당자 관련 API가 포함되어 있다.

### 1.3 Next.js API Route

apps/web/src/pages/api/support/* 아래의 API는 화면과 Secretary API 사이를 연결하는 내부 프록시다.

이 경로들은 NestJS Swagger 문서에는 포함되지 않는다. 외부 패키지에서 직접 사용할 공식 API로 제공하려면 NestJS 또는 Secretary API의 공개 계약으로 승격해야 한다.

## 2. 현재 구현된 API 범위

### 2.1 공개 피드백 API

- 프로젝트·채널 조회
- 채널 필드 조회
- 피드백 생성
- 피드백 목록 조회
- 피드백 검색
- 피드백 상세 조회
- 피드백 수정·삭제
- 피드백과 이슈 연결·해제
- 댓글 CRUD
- 내부 댓글 구분
- 댓글 첨부파일 업로드·조회·삭제
- 피드백 첨부 이미지 업로드
- 카테고리 조회·관리
- 이슈 생성·조회·검색·수정·삭제

관련 컨트롤러:

- apps/api/src/domains/api/feedback.controller.ts
- apps/api/src/domains/api/v2/feedback.controller.ts
- apps/api/src/domains/api/issue.controller.ts
- apps/api/src/domains/api/channel.controller.ts
- apps/api/src/domains/api/project.controller.ts

### 2.2 관리자 API

- 프로젝트·채널·필드 관리
- 피드백 관리자 검색·수정·삭제
- 피드백 상태 처리
- 피드백 담당자 지정
- 이슈 관리자 지정
- 이슈 상태 처리
- Gitea 이슈 생성·연결·동기화
- 댓글·내부 메모 관리
- 통계 조회
- 다중 프로젝트 통합 대시보드
- 관리자 권한·역할 관리

통합 대시보드 API:

    GET /api/admin/dashboard/overview

현재 대시보드 API는 사용자의 프로젝트 권한을 기준으로 프로젝트별 피드백·이슈 요약과 Todo 항목을 집계한다.

### 2.3 Secretary API

- SSO 사용자 접근 정보
- workspace 목록 및 폼 템플릿
- ticket 생성·조회·상세 조회
- 댓글 CRUD
- 내부 메모 CRUD
- 담당자 후보 조회 및 지정
- 이슈 연결
- 승인 처리
- 첨부파일 저장·조회
- R2 기반 파일 저장

## 3. 현재 Swagger 문서화 상태

### 완료된 부분

- [x] NestJS Swagger 모듈 연결
- [x] 공개 API 문서와 관리자 API 문서 분리
- [x] 공개 API Key 인증 정의
- [x] 관리자 JWT 인증 정의
- [x] 주요 피드백·이슈 API의 ApiTags, ApiParam, ApiOperation 일부 적용
- [x] 일부 요청·응답 DTO에 ApiProperty 적용
- [x] FastAPI 자동 OpenAPI 문서 제공
- [x] 공개 Swagger JSON 생성 스크립트 존재

### 보완이 필요한 부분

- [x] 통합 대시보드 응답 DTO 정의
- [x] 통합 대시보드 날짜·프로젝트 필터 파라미터 문서화
- [x] 관리자 피드백 컨트롤러에 ApiTags와 상세 operation 문서 추가
- [x] 댓글 CRUD 요청·응답 DTO 정의
- [x] 내부 메모와 일반 댓글의 공개 범위 문서화
- [x] 첨부파일 multipart 요청 스키마 정의
- [x] 담당자·상태·우선순위 enum 문서화
- [x] 오류 응답 형식 표준화
- [x] 동적 필드의 요청·응답 계약 정의
- [x] 내부 workspace mapping API의 Swagger 공개 범위 재검토
- [x] Next.js 내부 프록시 API와 공식 API의 역할 분리

### 1차 보완 완료 기록

- `DashboardOverviewResponseDto`와 하위 통계·Todo·상태 스키마를 추가했다.
- `GET /api/admin/dashboard/overview`의 날짜 범위와 쉼표 구분 프로젝트 필터를 Swagger에 명시했다.
- 관리자 피드백 API에 `admin-feedbacks` 태그, 경로 파라미터, operation 설명, 동적 body 예시, 생성·수정·삭제 응답 설명을 추가했다.
- 공개 OpenAPI JSON과 관리자 OpenAPI JSON을 함께 생성하도록 `apps/api/src/scripts/build-swagger-docs.ts`를 보완했다.
- 공통 오류 응답, enum 문서화, 동적 필드 계약은 다음 보완 작업으로 남겨두었다.

### 2차 보완 완료 기록

- Secretary 댓글 요청·응답 모델에 작성자, 공개 범위, 첨부파일 메타데이터, 수정·삭제 가능 여부의 설명을 추가했다.
- `GET/POST/PUT/DELETE /api/tickets/{ticketId}/comments...`를 공개 댓글 계약으로 명시하고, `GET/POST/PUT/DELETE /api/tickets/{ticketId}/internal-memos...`를 관리자 전용 계약으로 분리했다.
- 공개 댓글 API는 관리자 권한으로 호출하더라도 `is_internal=false`로 저장되며, 내부 메모는 전용 API에서만 생성되도록 경계를 고정했다.
- 지원 요청 생성 API에 JSON과 multipart/form-data 계약을 모두 문서화하고, 반복 가능한 `attachments` binary 필드와 JSON 문자열 `extra_fields`를 명시했다.
- 첨부파일 댓글 API도 `content`와 반복 가능한 `attachments` 입력을 OpenAPI에 노출하도록 명시적인 multipart 파라미터로 변경했다.
- 삭제 응답을 `TicketDeleteResponse` DTO로 고정해 `deleted`, `ticket_id`, `comment_id`, `feedback_id`를 문서화했다.
- Secretary API는 FastAPI 자동 OpenAPI 엔드포인트(`/openapi.json`)에서 위 계약을 산출하며, 실행 환경에 의존성 설치 후 `/docs`에서 확인한다.

### 3차 보완 완료 기록

- 피드백 상태 enum을 `INIT`, `ON_REVIEW`, `DETAILED_REVIEW`, `IN_PROGRESS`, `RESOLVED`, `PENDING`으로 고정하고, 이슈 상태와 동일한 6단계 값임을 Swagger에 명시했다.
- 피드백 우선순위 enum을 `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`로 문서화했다.
- 관리자 피드백 수정 API에 상태, 우선순위, 담당자 ID·tenant ID·이름·이메일 필드의 요청 예시와 enum을 추가했다.
- 통합 대시보드 Todo 응답에 담당자 정보를 포함하고, 피드백 상태·우선순위 타입을 enum으로 제한했다.
- NestJS와 Secretary API의 오류 응답을 `code`, `message`, `error`, `statusCode`, `path` 공통 구조로 표준화했다. 추가 오류 정보는 `details`에 담는다.
- NestJS 관리자 피드백·통합 대시보드 API와 Secretary API OpenAPI에 공통 오류 응답 스키마를 노출했다.

### 4차 보완 완료 기록

- 채널 필드 조회 API(`/projects/{projectId}/channels/{channelId}/fields`)를 동적 피드백 계약의 기준점으로 명시했다. 클라이언트는 이 응답으로 필드 키, format, property, status, select 옵션을 먼저 확인한다.
- 공개·관리자 피드백 생성 API에 동적 JSON 요청 스키마를 연결했다. `title`, `contents`, `Category`, `IP`, `MAC_address`는 대표 예시이며 실제 입력 키는 채널 설정을 따른다.
- `issueNames`는 피드백 필드로 저장되지 않는 이슈 연결용 제어 필드임을 문서화했다.
- 이미지 첨부 생성 API에 multipart 스키마를 연결하고, 동적 비파일 필드와 반복 가능한 `images` binary 파일 입력을 구분했다.
- 피드백 검색 응답은 실제 구현처럼 동적 필드가 최상위에 펼쳐지는 `items`와 페이지네이션 `meta` 구조로 문서화했다.
- 동적 검색 `query` 값에 문자열·숫자·배열·`gte/lt` 범위 조건을 문서화했다.
- 관리자 피드백 수정 API는 공통 관리 필드(상태·우선순위·담당자)를 명시하면서, 나머지 허용 필드는 채널 필드 설정에서 발견하도록 설명했다.

### 5차 보완 완료 기록

- Secretary API가 ABC API의 `GET /api/internal/support/workspace-mappings`를 서비스 간 동기화에만 사용하도록 확인했다.
- workspace mapping endpoint는 `MASTER_API_KEY` 서비스 인증을 사용하므로 공개·관리자 Swagger에서 제외했다. 이 키는 외부 패키지 소비자에게 제공하는 API Key가 아니다.
- Next.js의 `/api/support/*` 경로는 브라우저 세션과 Secretary API 사이의 내부 BFF(proxy)로 분류하고, 외부 패키지용 공식 API는 Secretary API와 NestJS 공개·관리자 API로 한정했다.
- Next.js proxy 경로는 Swagger 산출 대상이 아니며, 외부 연동 문서와 SDK 계약에 포함하지 않는다는 경계를 명시했다.

## 4. 외부 패키지용 API 계약 설계

### 4.1 API 영역 분리

외부 패키지에서는 다음 세 영역을 분리한다.

1. 사용자용 피드백 API
2. 관리자용 운영 API
3. 내부 Secretary 업무 API

외부 사용자에게 관리자 API나 내부 API 권한이 노출되지 않도록 인증 체계와 문서도 분리한다.

### 4.2 권장 버전 정책

    /api/v1/projects/{projectId}/channels/{channelId}/feedbacks
    /api/v1/projects/{projectId}/issues
    /api/v1/admin/...

기존 경로는 호환성을 위해 유지하고, 패키지용 공식 계약은 v1 버전으로 고정하는 것을 권장한다.

### 4.3 공통 응답 형식

성공 응답과 오류 응답을 모든 API에서 일관되게 정의한다.

    {
      "data": {},
      "meta": {
        "requestId": "..."
      }
    }

오류 예시:

    {
      "code": "NOT_FOUND",
      "message": "Feedback was not found.",
      "error": "NOT_FOUND",
      "statusCode": 404,
      "path": "/api/feedbacks/34",
      "details": {}
    }

### 4.4 페이지네이션·검색·정렬

- page, limit 또는 cursor 방식 중 하나로 표준화
- 최대 limit 제한
- 정렬 가능 필드 화이트리스트 적용
- 제목·내용·작성자 검색의 검색 범위 명시
- 비밀글 접근 시 작성자·관리자 권한 검증
- 응답에 total, page, limit, hasNext 포함

### 4.5 동적 필드

현재 피드백 데이터는 채널 필드 설정에 따라 동적으로 구성된다.

현재 API 계약:

    {
      "title": "...",
      "contents": "...",
      "Category": "ERROR_QNA",
      "IP": "...",
      "MAC_address": "...",
      "issueNames": ["Login error"]
    }

- 실제 필드 키와 허용 값은 `GET /projects/{projectId}/channels/{channelId}/fields`에서 확인한다.
- `text`, `keyword`, `aiField`는 문자열, `number`는 숫자, `select`는 옵션 key 또는 null, `multiSelect`와 `images`는 배열, `date`는 날짜 문자열 또는 null을 사용한다.
- 응답에서도 채널 필드 값은 최상위 동적 속성으로 반환되며, `id`, `createdAt`, `updatedAt`, `issues`가 함께 제공된다.
- `issueNames`는 생성 요청에서만 사용하는 이슈 연결 제어 필드다.
- 장기적으로 SDK 호환성을 위해 `customFields` 래퍼를 도입할 수 있지만, 기존 클라이언트 호환성을 깨지 않도록 별도 버전 계약으로 진행한다.

## 5. 인증·권한·보안

- [ ] 공개 API Key를 프로젝트·채널 단위로 제한
- [ ] 관리자 JWT와 공개 API Key의 권한 차이 문서화
- [ ] Secretary API는 SSO JWT 검증을 필수화
- [ ] workspace·tenant·project 접근 범위 검증
- [ ] 비밀글 조회 권한을 API 레벨에서 강제
- [x] 내부 댓글·내부 메모가 일반 사용자 응답에 포함되지 않도록 보장
- [ ] R2 presigned URL 만료 시간 문서화
- [ ] API Key·JWT·R2 credential 로그 마스킹 확인
- [ ] rate limit과 업로드 용량 제한 추가
- [ ] CORS와 외부 패키지 허용 origin 정책 정의

### 보안 검증 기록

- 공개 API의 일반 댓글 목록·생성·첨부파일 접근은 내부 메모를 포함하지 않도록 고정했다. `is_internal` 입력과 `includeInternal` 조회 플래그는 공개 API에서 무시하며, 내부 메모는 관리자 전용 API에서만 처리한다.
- 공개 API Key는 `projectId` 기준으로 검증하고, `MASTER_API_KEY`는 서비스 간 내부 호출을 위한 전역 키로 구분했다.
- 관리자 API는 JWT guard와 권한 guard를 사용하고, Secretary API는 SSO JWT의 서명·만료·`sso_sub`·`tenant_id`를 검증한다.

## 6. Swagger/OpenAPI 산출물 및 배포

- [x] 공개 API OpenAPI JSON 생성
- [x] 관리자 API OpenAPI JSON 생성
- [x] Secretary API OpenAPI JSON export (`/openapi.json` 자동 산출)
- [ ] OpenAPI 파일을 패키지에 포함할지 결정
- [ ] Swagger UI를 staging에서만 노출할지 결정
- [ ] production에서는 인증된 관리자만 Swagger 접근 가능하도록 제한
- [ ] API 버전별 문서 URL 제공
- [ ] Postman collection 또는 SDK 생성 여부 결정
- [ ] 외부 패키지 배포 시 changelog와 breaking change 정책 추가

생성 산출물 후보:

    packages/api-contract/openapi/public.json
    packages/api-contract/openapi/admin.json
    packages/api-contract/openapi/secretary.json

## 7. 테스트 계획

### 계약 테스트

- [ ] OpenAPI schema validation
- [ ] 요청 DTO validation
- [ ] 응답 DTO serialization
- [x] 오류 응답 형식 검증
- [ ] 페이지네이션·정렬·검색 검증
- [ ] 비밀글 권한 검증
- [ ] 내부 댓글 노출 차단 검증

### 기능 테스트

- [ ] 사용자 피드백 생성
- [ ] 피드백 목록·상세·수정·삭제
- [ ] 댓글 CRUD
- [ ] 내부 메모 CRUD
- [ ] 첨부파일 R2 업로드·다운로드·삭제
- [ ] 피드백 담당자 지정
- [ ] 상태 변경
- [ ] 이슈 연결·해제
- [ ] Gitea 이슈 생성·동기화
- [ ] 통합 대시보드 조회
- [ ] 다중 프로젝트 권한 필터링
- [ ] SSO 재로그인 후 사용자 정보 유지

### 배포 전 확인

- [ ] pnpm typecheck
- [ ] pnpm lint
- [ ] API 단위 테스트
- [ ] Secretary API 테스트
- [ ] E2E 테스트
- [ ] staging에서 OpenAPI JSON 확인
- [ ] 실제 외부 클라이언트 샘플 호출
- [ ] 마이그레이션 및 기존 데이터 호환성 확인

## 8. 권장 작업 순서

1. 공개 API와 관리자 API의 패키징 범위 확정
2. API 버전과 인증 정책 확정
3. 통합 대시보드 응답 DTO 작성
4. 피드백·댓글·내부메모·첨부파일 DTO 작성
5. 상태·우선순위·담당자 enum 정리
6. Swagger decorator 보완
7. Next.js 내부 프록시와 공식 API 경계 정리
8. OpenAPI JSON을 별도 계약 패키지로 export
9. 계약 테스트와 권한 테스트 추가
10. staging 배포 및 외부 호출 검증
11. SDK 또는 Postman collection 생성
12. API 패키지 버전 태그 및 배포

## 9. 완료 기준

- 외부 시스템이 Swagger 문서만 보고 피드백을 생성·조회·수정할 수 있다.
- 관리자 시스템이 피드백 상태·담당자·댓글·내부 메모·이슈·Gitea를 API로 처리할 수 있다.
- 사용자·관리자·내부 API의 권한이 분리되어 있다.
- 동적 필드와 비밀글 정책이 문서화되어 있다.
- 모든 주요 API의 요청·응답·오류 스키마가 OpenAPI에 표시된다.
- Swagger JSON이 CI에서 생성되고 버전 관리 또는 패키지 산출물로 배포된다.
- 기존 화면과 API 소비처의 호환성이 깨지지 않는다.

## 참고 문서

- SSOT 피드백 재구성 작업: docs/ssot-feedback-rearchitecture-tasks.md
- 다중 프로젝트 관리자 통합 대시보드 설계: docs/multi-project-admin-dashboard-design.md
- Secretary SSO 구성 설계: docs/architecture_secretary_sso_components_v2.md
- Q&A 플랫폼 작업 목록: docs/qna-platform-prototype-2-feedback-tasks.md
- NestJS API README: apps/api/README.md