b24014/baron_qa_write
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c10478482e7894773288f98d7e8f0cc523e2d95
baron_qa_write/docs/관리페이지 md 파일/README.md
T
root 3c10478482
Deploy EG-BIM QA Gateway / deploy (push) Successful in 2m4s
Details
관리페이지 데이터 전송 구현
2026-09-21 14:46:36 +09:00

19 KiB
Raw Blame History

ABC User Feedback

프로젝트 개요

회사 내 여러 RP(Request Point, 요청 접수 서비스)의 Q&A를 한곳에서 확인·처리하는 Q&A 통합 관리 플랫폼.

주요 기능:

  • 사용자의 Q&A 작성
  • 여러 프로젝트·RP의 Q&A를 모아 보는 관리자 콘솔
  • 피드백, 댓글, 내부 메모, 첨부파일 관리
  • 이슈 등록 및 Gitea 이슈 연결
  • BARON-SSO 기반 로그인·권한 관리
  • 관리자 업무를 보조하는 Secretary API

통합 관리가 필요한 이유

기존 운영 방식

사내 S/W 홈페이지, 인트라넷, 총무 관련 요청 게시판 등 RP별로 회원 관리와 Q&A 관리가 분리된 구조.

기존 문제

  • 서비스마다 별도 계정·권한 관리 필요
  • 관리자가 여러 페이지를 각각 확인해야 함
  • 답변, 담당자, 첨부파일, 이슈 처리 이력이 서비스별로 분산
  • 서비스마다 상태·관리 방식이 달라 통합 현황과 통계 확인 어려움

통합 필요성

BARON-SSO 도입으로 여러 서비스의 회원 인증과 사용자 정보를 하나의 기준으로 통합 가능.

회원 관리가 통합된 시점에서 Q&A 관리도 통합 필요. 여러 RP에서 들어오는 Q&A를 하나의 관리자 콘솔에서 관리하고, 답변·담당자·이슈·처리 상태를 동일한 기준으로 연결.

기대 효과

  • 관리자의 여러 페이지 이동 감소
  • 문의 누락 방지 및 처리 현황 실시간 확인
  • Q&A부터 이슈 처리까지 단일 업무 흐름으로 관리
  • RP별 권한은 유지하면서 전체 현황은 통합 조회
  • 사용자 인증과 문의 처리 경험의 일관성 확보

핵심 용어

용어 의미
RP 사내 S/W 홈페이지, 인트라넷, 총무 요청 게시판 등 Q&A를 접수하는 각각의 서비스·요청 창구
Q&A 사용자가 작성 페이지에서 직접 등록한 질문·요청·불편 사항
피드백 Q&A가 관리자 콘솔에 도착한 뒤 관리 대상이 된 항목. 같은 요청을 사용자 관점에서는 Q&A, 관리자 관점에서는 피드백으로 구분
관리자 콘솔 여러 프로젝트·RP의 피드백을 확인하고 처리하는 화면. 통합 관리와 프로젝트별 관리 제공
프로젝트 서비스 또는 업무 단위를 구분하는 관리 단위
채널 프로젝트 안에서 Q&A를 접수하는 세부 창구. 입력 항목과 화면 설정을 채널별로 지정
이슈 피드백 처리를 위해 등록하는 작업 항목. 하나의 피드백에 여러 이슈 연결 가능
Gitea 이슈 개발자가 소스 코드 수정·개발 작업을 진행하는 외부 이슈. 관리자 콘솔의 이슈와 연결 가능
BARON-SSO 여러 사내 서비스의 로그인과 사용자 정보를 통합하는 인증 시스템
Secretary API BARON-SSO 접근 권한, 워크스페이스, 담당자·알림 등 관리 업무를 보조하는 API

프로젝트 목표와 처리 흐름

여러 RP의 Q&A 작성부터 관리자 처리와 개발 이슈 연결까지 하나의 기준으로 연결.

사용자가 RP에서 Q&A 작성
        ↓
ABC API에 Q&A 저장
        ↓
관리자 콘솔에 피드백으로 표시
        ↓
관리자가 확인·답변·담당자 지정
        ↓
필요하면 관리자 이슈 또는 Gitea 이슈로 연결
        ↓
처리 결과를 기록하고 Q&A 작성자에게 안내

핵심 목표:

  1. BARON-SSO 기반 로그인·사용자 식별 통합
  2. 여러 RP의 Q&A를 관리자 콘솔에서 통합 관리
  3. 피드백, 댓글, 내부 메모, 첨부파일, 이슈 처리 이력 연결
  4. 프로젝트별 권한 유지와 전체 현황 통합 조회
  5. ABC API/ABC DB를 피드백 원본으로 사용하고 보조 시스템에는 식별자·업무 메타데이터만 저장

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

1. 빠른 시작

로컬 실행

필요 조건:

  • Node.js 24.14.1 (.nvmrc)과 pnpm@10.32.1
  • Docker 및 Docker Compose
  • apps/secretary-api/.venv와 Secretary API 의존성

권장 실행 명령은 루트의 start-local.sh입니다. 이 스크립트가 로컬 MySQL·Redis·smtp4dev를 올린 뒤 Web, ABC API, Secretary API를 함께 실행합니다. 현재 셸의 Node 버전이 다르면 설치된 nvm에서 .nvmrc 버전을 자동 선택합니다.

pnpm install
./start-local.sh

접속 주소:

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

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
         └─▶ ABC 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 피드백·이슈·사용자·권한·Secretary 보조 데이터 13306 로컬

3. 데이터와 SSOT 원칙

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

ABC가 보유하는 원본:

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

Secretary가 보유하는 데이터:

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

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

4. 인증과 권한 흐름

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

관련 구현 위치:

SSO 프로필의 name, email, phones, employee_id, status 등의 필드를 사용할 때는 BARON-SSO의 profile scope와 실제 callback 응답을 함께 확인합니다. 토큰, client secret, API key는 코드나 README에 기록하지 않습니다.

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 이미지가 배포된 뒤 동작합니다.

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으로 통신합니다. ABC와 Secretary는 같은 userfeedback 스키마를 사용합니다. 브라우저에 노출되는 외부 포트는 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. 문제 해결 순서

  1. 브라우저 주소가 localhost/127.0.0.1인지, 스테이징 도메인인지 확인합니다.
  2. Network에서 요청 URL과 응답 코드, 특히 401, 404, 500을 확인합니다.
  3. Web이 API를 localhost가 아닌 Docker 내부 api:4000으로 호출하는지 확인합니다.
  4. SSO callback URL의 host, scheme, path가 BARON-SSO 등록값과 같은지 확인합니다.
  5. 프로젝트/채널/워크스페이스 이름과 ABC 매핑을 확인합니다.
  6. 서버 로그를 확인합니다.
docker compose --env-file <실제-환경파일> \
  -f docker/docker-compose.prod.yml logs --tail=200 web api secretary-api

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

10. 상세 문서 목차

운영팀 사용 안내

운영·배포

API·SSOT·기능 작업

통합 아키텍처

SSO

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

이전 버전·참고 문서

다음 문서는 앞선 설계 버전 또는 중복된 셋업 문서입니다. 현재 구현과 충돌할 경우 코드와 위의 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를 확인합니다.

Reference in New Issue View Git Blame Copy Permalink