b24014/baron_qa_write

Fork 0

Files

T

root 3c10478482

Deploy EG-BIM QA Gateway / deploy (push) Successful in 2m4s

Details

관리페이지 데이터 전송 구현

2026-09-21 14:46:36 +09:00

16 KiB

Raw Blame History

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
내부 댓글 구분
댓글 첨부파일 업로드·조회·삭제
피드백 첨부 이미지 업로드
카테고리 조회·관리
이슈 생성·조회·검색·수정·삭제

2.2 관리자 API

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

통합 대시보드 API:

GET /api/admin/dashboard/overview

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

2.3 Secretary API

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

3. 현재 Swagger 문서화 상태

완료된 부분

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

보완이 필요한 부분

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

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

사용자용 피드백 API
관리자용 운영 API
내부 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 레벨에서 강제
내부 댓글·내부 메모가 일반 사용자 응답에 포함되지 않도록 보장
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 산출물 및 배포

공개 API OpenAPI JSON 생성
관리자 API OpenAPI JSON 생성
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
오류 응답 형식 검증
페이지네이션·정렬·검색 검증
비밀글 권한 검증
내부 댓글 노출 차단 검증

기능 테스트

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

배포 전 확인

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

8. 권장 작업 순서

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

16 KiB Raw Blame History