ABC User Feedback는 BARON-SSO로 인증한 사용자가 피드백을 등록하고, 관리자가 피드백·이슈·댓글·첨부파일을 처리하는 통합 지원 플랫폼입니다. 이 저장소는 ABC User Feedback를 기반으로 한 관리자 콘솔과 Secretary 업무 API를 함께 관리합니다.

이 문서는 저장소의 시작점입니다. 상세 설계와 작업 이력은 docs/ 아래에 보존하고, 여기에는 실제 실행·검증·배포 순서와 문서 선택 기준을 정리합니다.

1. 빠른 시작

로컬 실행

필요 조건:

Node.js와 pnpm@10.32.1
Docker 및 Docker Compose
apps/secretary-api/.venv와 Secretary API 의존성

권장 실행 명령은 루트의 start-local.sh입니다. 이 스크립트가 로컬 MySQL 2개와 smtp4dev를 올린 뒤 Web, ABC API, Secretary API를 함께 실행합니다.

pnpm install
./start-local.sh

접속 주소:

Web: http://127.0.0.1:3100
ABC API: http://127.0.0.1:4000
ABC Swagger: http://127.0.0.1:4000/docs
ABC 관리자 Swagger: http://127.0.0.1:4000/admin-docs
Secretary API: http://127.0.0.1:8010
Secretary Swagger: http://127.0.0.1:8010/docs
SMTP 테스트함: http://127.0.0.1:5080

이미 인프라를 실행한 상태에서 개발 서버만 시작하려면 다음을 사용할 수 있습니다.

pnpm dev:local

포트 3100, 4000, 8010을 사용하는 프로세스가 있으면 스크립트가 임의로 종료하지 않고 중단합니다. 먼저 사용 중인 프로세스를 확인한 뒤 종료하고 다시 실행합니다.

lsof -nP -iTCP:3100 -sTCP:LISTEN
lsof -nP -iTCP:4000 -sTCP:LISTEN
lsof -nP -iTCP:8010 -sTCP:LISTEN

로컬 검증

pnpm lint
pnpm typecheck
pnpm build

E2E는 테스트용 데이터베이스를 초기화할 수 있으므로 로컬 개발 데이터와 분리된 환경에서 실행합니다.

pnpm test:e2e

2. 서비스 구조

브라우저
  │
  ▼
apps/web                Next.js 화면 및 내부 BFF
  ├─▶ apps/api           NestJS, ABC 피드백·이슈 API
  │      └─▶ ABC MySQL
  └─▶ apps/secretary-api FastAPI, SSO 접근·워크스페이스·업무 보조 API
         └─▶ Secretary MySQL

외부 연동: BARON-SSO · Gitea · SMTP · R2/S3 호환 스토리지 · OpenSearch(선택)

구성요소	책임	기본 포트
`apps/web`	관리자 콘솔, 사용자 피드백 화면, Secretary 내부 BFF	`3100` 로컬 / `3030` Docker
`apps/api`	ABC 프로젝트·채널·피드백·이슈·댓글·필드·통계 API	`4000`
`apps/secretary-api`	SSO 접근권한, 워크스페이스, 지원 업무 API	`8010`
ABC MySQL	피드백과 이슈 원본 데이터	`13306` 로컬
Secretary MySQL	접근권한과 업무 보조 데이터	`13308` 로컬

3. 데이터와 SSOT 원칙

피드백의 원본은 관리자 화면이 아니라 ABC API/ABC DB입니다. 관리자 콘솔과 사용자 페이지 모두 같은 ABC API를 조회·작성·수정·삭제에 사용해야 합니다.

ABC가 보유하는 원본:

피드백 ID, 제목, 내용, 생성일, 수정일
작성자 이름·이메일·부서·연락처와 SSO 식별자
카테고리, 비밀글 여부, IP 주소, MAC 주소
중요도와 피드백 처리 상태
첨부파일, 댓글, 내부 메모
ABC 이슈 연결 관계

Secretary가 보유하는 데이터:

SSO 접근권한과 역할
프로젝트/워크스페이스 접근 설정
업무용 담당자·승인·알림·매핑 메타데이터

Secretary DB에 피드백 제목·내용·상태를 별도로 복제하지 않습니다. 연결이 필요하면 abc_feedback_id 같은 식별자만 보조 데이터로 사용합니다. 피드백 상태와 이슈 상태도 서로 독립적으로 관리합니다.

4. 인증과 권한 흐름

사용자가 BARON-SSO OAuth/OIDC 로그인 화면으로 이동합니다.
Web의 callback이 인증 코드를 ABC API에 전달합니다.
ABC API가 SSO 프로필을 조회하고 사용자·테넌트 정보를 반영한 JWT를 발급합니다.
Web은 세션 쿠키로 JWT를 유지합니다.
접근 가능한 프로젝트와 워크스페이스를 조회한 뒤 관리자 통합 대시보드 또는 사용자 피드백 화면으로 분기합니다.

5. 주요 기능 사용 가이드

사용자 피드백

사용자는 프로젝트/채널의 필드 설정에 따라 피드백을 등록합니다. 현재 확장 필드에는 구분, 중요도, IP, MAC 주소 등이 포함될 수 있으며, 비밀글과 첨부파일을 지원합니다. 사용자 목록은 제목·내용·작성자 검색, 작성자 본인 글 필터, 구분 필터, 정렬, 10건 단위 페이지 이동을 제공합니다.

관리자 피드백 처리

관리자는 피드백 상태, 중요도, 피드백 담당자를 관리하고 댓글과 내부 메모를 구분해 기록합니다. 내부 메모는 관리자에게만 노출되며 일반 댓글과 동시에 저장되지 않아야 합니다. 피드백을 이슈에 연결해도 피드백 상태와 이슈 상태는 각각 별도로 처리합니다.

이슈와 Gitea

이슈를 연결한 뒤 이슈 담당자를 지정하고 Gitea 이슈를 생성·연결·동기화할 수 있습니다. 하나의 이슈에 여러 피드백을 연결할 수 있으며, 연결된 피드백 목록과 Gitea 상태를 확인합니다.

통합 관리자 대시보드

여러 프로젝트의 관리자에게 지정된 사용자는 홈 버튼을 통해 통합 대시보드로 이동합니다. 피드백 처리 탭에서는 담당자 지정·댓글·피드백 상태를, 이슈 처리 탭에서는 Gitea 연결·이슈 상태·연결 피드백을 프로젝트별로 처리합니다. 대시보드의 집계와 Todo는 권한이 있는 프로젝트만 대상으로 합니다.

6. API와 Swagger

ABC API 문서는 공개 연동 API와 관리자 API를 분리합니다.

구분	로컬 경로	주요 인증
공개 API Swagger	`/docs`	API Key가 필요한 엔드포인트는 API Key
관리자 API Swagger	`/admin-docs`	JWT 및 권한
공개 OpenAPI JSON	`/docs-json`	환경 설정에 따름
관리자 OpenAPI JSON	`/admin-docs-json`	환경 설정에 따름
Secretary Swagger	`:8010/docs`	FastAPI 설정에 따름

로컬에서는 API 포트로 직접 확인합니다. Docker 스테이징에서는 API 컨테이너 포트를 외부에 별도로 열지 않고 Web reverse proxy를 통해 다음 경로를 사용합니다. 최신 Web 이미지가 배포된 뒤 동작합니다.

https://feedback.hmac.kr/docs
https://feedback.hmac.kr/admin-docs
https://feedback.hmac.kr/secretary-docs
Secretary OpenAPI JSON: https://feedback.hmac.kr/secretary-docs/openapi.json

API 패키징 시에는 화면용 Next.js /api/support/* BFF를 외부 계약으로 사용하지 않고, NestJS 공개/관리자 API와 Secretary API를 공식 경계로 취급합니다. API 버전, 페이지네이션, 동적 필드, 오류 형식, 댓글 공개 범위는 docs/api-packaging-tasks.md를 기준으로 확정합니다.

7. 환경변수와 비밀값

환경별 값을 코드와 문서에 하드코딩하지 않습니다. 스테이징에서는 Gitea Actions 변수/Secret 또는 서버의 실제 환경 주입 방식을 사용합니다.

주요 변수 그룹:

실행: APP_ENV, WEB_PORT, APP_PORT, SECRETARY_API_PORT
Web/API 주소: NEXT_PUBLIC_API_BASE_URL, ADMIN_WEB_URL, BASE_URL
인증: JWT_SECRET, MASTER_API_KEY, SSO_ISSUER, SSO_CLIENT_ID, SSO_CLIENT_SECRET
연동: GITEA_API_URL, GITEA_API_TOKEN, SMTP 변수, SECRETARY_ABC_API_KEY
운영: AUTO_MIGRATION, OPENSEARCH_USE 및 OpenSearch 변수

Docker 내부 서비스는 api:4000, secretary-api:8010, mysql:3306, mysql-secretary:3306으로 통신합니다. 브라우저에 노출되는 외부 포트는 Web 포트 하나로 제한합니다. 환경변수 전체 목록과 Gitea 등록 규칙은 GITEA_VARIABLES.md를 확인합니다.

R2/S3 호환 첨부파일은 버킷과 endpoint를 환경 또는 관리자 설정으로 주입합니다. Access Key, Secret Key, API Token은 절대 커밋하지 않습니다. 이미지·첨부파일 저장 원칙은 GUIDE.md를 참고합니다.

8. 스테이징 배포

배포 전 로컬:

git status
pnpm lint
pnpm typecheck
pnpm build

스테이징 서버에서는 실제 환경 파일 또는 배포 시스템이 제공하는 환경을 사용해 Compose 설정을 먼저 검증합니다.

cd ~/baron_qa
docker compose --env-file <실제-환경파일> \
  -f docker/docker-compose.prod.yml config

docker compose --env-file <실제-환경파일> \
  -f docker/docker-compose.prod.yml up -d --build

docker compose --env-file <실제-환경파일> \
  -f docker/docker-compose.prod.yml ps

기존 데이터가 있는 서버에서 docker compose down -v를 실행하지 않습니다. -v는 DB 볼륨을 삭제할 수 있습니다. 최초 배포나 스키마 변경 시 백업, AUTO_MIGRATION, 로그, health check를 확인합니다.

상세 순서는 STAGING_DEPLOYMENT_CHECKLIST.md를 따릅니다.

9. 문제 해결 순서

브라우저 주소가 localhost/127.0.0.1인지, 스테이징 도메인인지 확인합니다.
Network에서 요청 URL과 응답 코드, 특히 401, 404, 500을 확인합니다.
Web이 API를 localhost가 아닌 Docker 내부 api:4000으로 호출하는지 확인합니다.
SSO callback URL의 host, scheme, path가 BARON-SSO 등록값과 같은지 확인합니다.
프로젝트/채널/워크스페이스 이름과 ABC 매핑을 확인합니다.
서버 로그를 확인합니다.

docker compose --env-file <실제-환경파일> \
  -f docker/docker-compose.prod.yml logs --tail=200 web api secretary-api

데이터가 보이지 않는다고 DB를 초기화하거나 볼륨을 삭제하지 않습니다. 먼저 API 응답의 프로젝트 ID, 채널 ID, 테넌트, 권한을 확인합니다.

10. 상세 문서 목차

운영·배포

STAGING_DEPLOYMENT_CHECKLIST.md: 정적 검사, 환경변수, Compose 배포, 배포 후 검증
GITEA_VARIABLES.md: Gitea Actions 변수/Secret 및 스테이징 매핑
GUIDE.md: S3/S3 호환 스토리지와 Webhook 관련 기본 가이드

API·SSOT·기능 작업

api-packaging-tasks.md: 외부 패키지용 API 경계, Swagger, DTO, 버전 정책
ssot-feedback-rearchitecture-tasks.md: ABC DB를 피드백 SSOT로 통일한 단계별 작업
qna-platform-prototype-2-feedback-tasks.md: Q&A 관리자 콘솔 기능과 API 작업 이력

통합 아키텍처

architecture_secretary_sso_components_v2.md: 현재 통합 구조를 설명하는 우선 참고 문서
architecture_secretary_sso_role_access.md: 역할, 테넌트, 로그인 후 접근 분기
architecture_secretary_sso_user_scenarios.md: 사용자 유형별 업무 시나리오
architecture.md: 초기 통합 지원 플랫폼 설계
architecture_secretary_sso_components.md: 통합 컴포넌트 설계 초안

SSO

BARON-SSO server-side-app guide.md: 서버 애플리케이션의 BARON-SSO 연동 예시
Back-Channel Logout.md: Back-Channel Logout 처리 순서와 구현 위치
architecture_secretary_sso_setup_tasks_v2.md: 최신 SSO 연계 셋업 및 남은 작업

데이터 이관·통합 대시보드

egbim_to_secretary_staging_migration_tasks.md: EGBIM/Secretary 데이터 이관 범위와 검증
multi-project-admin-dashboard-design.md: 다중 프로젝트 관리자 통합 대시보드 설계

이전 버전·참고 문서

다음 문서는 앞선 설계 버전 또는 중복된 셋업 문서입니다. 현재 구현과 충돌할 경우 코드와 위의 v2/SSOT 문서를 우선합니다.

문서의 작업 완료 표시는 당시 기준의 기록입니다. 배포 전에는 반드시 현재 코드, Compose 파일, 환경변수와 함께 대조합니다.

11. 저장소 구조

apps/
  api/             NestJS ABC API
  web/             Next.js Web/BFF
  secretary-api/   FastAPI Secretary API
  e2e/             Playwright E2E
  docs/            Docusaurus 기반 일반 제품 문서
docs/              프로젝트 설계·작업·운영 보조 문서
docker/            로컬/스테이징 Compose 및 Dockerfile
scripts/           로컬 실행·이관·개발 보조 스크립트
uploads/           로컬 첨부파일 마운트 경로

기여 방법은 CONTRIBUTING.md, 라이선스는 LICENSE를 확인합니다.