b24014/Q-A_test

Fork 0

Files

T

SDI 12e4f17b62

CI / typecheck (push) Successful in 1m8s

Details

CI / format (push) Failing after 1m6s

Details

CI / lint (push) Failing after 49s

Details

CI / test (push) Failing after 1m8s

Details

first commit

2026-07-15 18:05:12 +09:00

33 KiB

Raw Blame History

사내 지원 플랫폼 환경 셋업 및 Task 목록

1. 문서 목적

본 문서는 architecture_secretary_sso_user_scenarios.md 에서 정리한 사용자 시나리오와 시스템 역할 분담을 실제 개발 환경으로 옮기기 위한 실행 계획 문서임.

권한, 테넌트, 로그인 후 페이지 분기 설계는 architecture_secretary_sso_role_access.md 에 별도 정리함.

핵심 목적은 다음과 같음.

어떤 순서로 환경을 셋업해야 하는지 명확히 정리함.
개발 착수 전에 필요한 선행 정보와 의존 항목을 체크함.
사용자 화면, 운영 화면, 관리자 기능, 외부 연동까지 단계별로 작업을 분해함.
시연과 운영 전환을 위한 검증 항목을 체크리스트로 관리함.

2. 기본 원칙

먼저 ABC User Feedback 기본 환경을 안정적으로 띄움.
그 다음 BARON-SSO, 우리 시스템 백엔드, 자체 DB를 연결함.
이후 사용자 화면, 운영 화면, 관리자 기능 연계를 붙임.
마지막으로 시연 기준 end-to-end 검증을 수행함.

2.1 현재 작업 기준선

프로젝트/채널 구조 확정과 BARON-SSO tenant_id 기반 권한 분기 정책은 최종 완료의 선행 조건으로 유지함.
다만 현재 주차에서는 위 선행 조건이 아직 확정되지 않았으므로, 우선 범위를 프론트 UI 구성 + 우리 시스템 백엔드/DB 구축까지로 제한함.
다음 주 작업 범위는 BARON-SSO 로그인 연동 + 권한 분기 + 페이지 분기 처리로 계획함.
따라서 현재 문서의 (완료) 표시는 SSO/권한 확정 이전에도 독립적으로 검증 가능한 UI, 라우팅, 스텁 API, DB 스키마, 로컬 실행 항목에만 부여함.

3. 전체 Task 로드맵

단계	작업 묶음	핵심 목표	완료 기준
1	로컬 기본 환경 구성	ABC, DB, 개발 도구를 실행 가능한 상태로 만듦	로컬에서 ABC Web/API 접속 가능
2	ABC 운영 구조 셋업	프로젝트, 채널, 필드, 역할 구조를 준비함	서비스별 채널/필드/권한 정책 초안 반영 완료
3	BARON-SSO 연동 준비	로그인과 사용자 식별 체계를 연결함	`user_id`, `tenant_id`, 역할 정보를 세션에서 읽을 수 있음
4	우리 시스템 백엔드/DB 셋업	내부 티켓/승인/매핑 저장소를 준비함	`support_tickets`, `request_approvals`, `abc_feedback_mappings` 저장 가능
5	사용자 화면 셋업	작성, 목록, 상세 흐름을 연결함	사용자 기준 등록/조회 시연 가능
6	운영/관리 화면 셋업	승인, 이슈 생성, 처리 결과 입력 흐름을 연결함	운영자/관리자 기준 처리 시연 가능
7	외부 연동/알림 준비	알림 및 업무 시스템 연계를 준비함	Mock 또는 실제 연동 경로 확인 완료
8	통합 검증/시연 준비	전체 흐름을 점검하고 시연용 데이터를 고정함	end-to-end 시연 체크리스트 통과

4. 단계별 상세 Task

4.1 로컬 기본 환경 구성

작업 기준 저장소: abcfeedback_test
현재 확인된 로컬 기동 방식: ./start-local.sh 또는 docker compose -f docker/docker-compose.yml up -d
선행 확인 항목
Docker CLI 설치 및 Docker daemon 접근 가능 여부 확인
Node.js / pnpm 설치 여부 확인
로컬 포트 사용 여부 확인: 3001, 4000, 5080, 13306
현재 확인된 기본 접속 URL
Web UI: http://localhost:3001
API Docs: http://localhost:4000/docs
API Health: http://localhost:4000/api/health
SMTP Test Inbox: http://localhost:5080
현재 확인된 기본 DB 접속 정보
DB Engine: MySQL 8.0
Host: localhost
Port: 13306
Database: userfeedback
Username: userfeedback
Password: userfeedback
현재 확인된 핵심 환경 변수
Web: NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
API: JWT_SECRET, MYSQL_PRIMARY_URL, SMTP_HOST, SMTP_PORT, SMTP_SENDER
1차 실행 절차
cd abcfeedback_test
./start-local.sh (완료)
./check-local.sh (완료)
기동 후 첫 진입 절차
테넌트 생성
관리자 계정 생성
로그인
Project 생성
Channel 생성
API Key 생성
첫 피드백 등록
현재 작업 환경 확인 결과
Docker daemon 기동 후 start-local.sh, check-local.sh 기준 로컬 컨테이너 실행과 기본 헬스체크 확인 (완료)
Web 3001, API 4000, SMTP UI 5080, MySQL 13306 포트 매핑 확인 (완료)
산출물
로컬 실행 스크립트 및 접속 URL 문서화 완료
4.2 진행 전 선행 조건: ABC Web/API Health check 성공 확인

4.2 ABC 운영 구조 셋업

설계 기준 문서
docs/architecture_secretary_sso_components_v2.md
docs/architecture_secretary_sso_user_scenarios.md
운영 구조 설계 원칙
ABC Project는 서비스 운영 단위로 생성하고, 세부 신청/문의 유형은 Channel로 분리함
외부 진입 식별자 app_id, service_type_id, 메뉴 코드는 우리 시스템에서 workspace로 해석하고, workspace_channel_mappings로 ABC Channel에 연결함
일반 사용자 입력 스키마는 우리 시스템 동적 폼과 ABC 커스텀 필드를 동시에 맞춰야 하므로 workspace_field_mappings 기준으로 관리함
역할과 화면 권한은 BARON-SSO 세션을 기준으로 판정하되, ABC 프로젝트 접근 권한은 별도로 부여함
1차 운영 구조 초안
Project 단위
INTRANET_SUPPORT: 인트라넷 기반 사내 지원 업무 공통 Project
SOFTWARE_QA: S/W 프로그램별 문의 접수 공통 Project
Channel 단위
INTRA_SUPPLIES_REQUEST: 물품 신청
INTRA_BOOK_REQUEST: 도서 신청
INTRA_VEHICLE_REQUEST: 출장 차량 신청
INTRA_EQUIPMENT_RENTAL: 비품 대여
INTRA_GENERAL_QNA: 사내 문의
SW_APP_<APP_CODE>_QNA: 앱별 전용 Q&A 채널
Field 스키마 초안
공통 필드: request_category, title, description, requester_contact, attachment
승인형 업무 필드: approval_required, approver_org, requested_date, priority
자산/물품형 필드: asset_type, quantity, usage_purpose, delivery_location
도서형 필드: book_title, author, publisher, purchase_reason
차량형 필드: departure_date, return_date, destination, passenger_count
Q&A형 필드: app_version, environment, error_message, expected_result
역할 정의 초안
ROLE_USER: 일반 사용자 작성/본인 조회
ROLE_APPROVER: 승인 대기 조회, 승인/반려 처리
ROLE_OPERATOR: 전체 운영 목록 조회, 상태 변경, 이슈 연결
ROLE_ADMIN: Project/Channel/Field/Member 관리
멤버/권한 부여 정책
Project 멤버는 최소 승인자, 운영 담당자, 관리자 그룹으로 시작함
Channel 단위 운영은 가능하면 Project Role로 통일하고, 예외 채널만 추가 권한을 부여함
운영 화면 접근 권한과 ABC 관리자 권한은 동일 인원 기준으로 시작하되, 이후 분리 가능하게 설계함
1차 실무 작업 순서
INTRANET_SUPPORT, SOFTWARE_QA Project 생성
인트라넷용 기본 Channel 5종 생성
시범 앱 1개를 선정해 SW_APP_<APP_CODE>_QNA Channel 생성
Channel별 필드 스키마 반영
Project Role 생성 및 멤버 배정
workspace_channel_mappings, workspace_field_mappings 초안 작성
seed 데이터 준비 항목
테스트용 일반 사용자 1명, 승인자 1명, 운영 담당자 1명, 관리자 1명
인트라넷 업무 5종에 대한 샘플 Channel/Field 정의서
앱 Q&A 1종에 대한 샘플 Channel/Field 정의서
workspace 매핑 초안 표

workspace_code	진입 구분	ABC Project	ABC Channel	주요 Field 그룹	승인 필요 기본값
`INTRA_SUPPLIES_REQUEST`	인트라넷 물품 신청	`INTRANET_SUPPORT`	`INTRA_SUPPLIES_REQUEST`	공통 + 승인형 + 자산/물품형	예
`INTRA_BOOK_REQUEST`	인트라넷 도서 신청	`INTRANET_SUPPORT`	`INTRA_BOOK_REQUEST`	공통 + 승인형 + 도서형	예
`INTRA_VEHICLE_REQUEST`	인트라넷 차량 신청	`INTRANET_SUPPORT`	`INTRA_VEHICLE_REQUEST`	공통 + 승인형 + 차량형	예
`INTRA_EQUIPMENT_RENTAL`	인트라넷 비품 대여	`INTRANET_SUPPORT`	`INTRA_EQUIPMENT_RENTAL`	공통 + 승인형 + 자산/물품형	예
`INTRA_GENERAL_QNA`	인트라넷 일반 문의	`INTRANET_SUPPORT`	`INTRA_GENERAL_QNA`	공통 + Q&A형	아니오
`SW_APP_<APP_CODE>_QNA`	S/W 프로그램별 문의	`SOFTWARE_QA`	`SW_APP_<APP_CODE>_QNA`	공통 + Q&A형	아니오

workspace_field_mappings 작성 규칙 초안
모든 workspace는 공통 필드 request_category, title, description, requester_contact, attachment를 기본 포함함
승인형 업무는 approval_required=true를 기본값으로 두고, 승인자 조직/우선순위/희망일자를 추가 매핑함
Q&A형 업무는 승인 필드 대신 app_version, environment, error_message, expected_result를 우선 매핑함
ABC 커스텀 필드 키는 가능하면 snake_case로 고정하고, 우리 시스템 local_field_code와 동일한 이름을 사용함
첨부는 ABC 첨부 기능을 기본 저장소로 사용하고, 우리 시스템에는 첨부 메타데이터와 내부 티켓 연결 정보만 저장함
완료 기준
서비스별 Project/Channel/Field/Role 초안이 문서로 정리되어 있어야 함
최소 1개 인트라넷 업무와 1개 S/W 앱 Q&A에 대해 실제 ABC 생성 대상 목록이 확정되어 있어야 함
현재 메모
이 단계는 프론트 UI/백엔드 스텁 완료와 별개로 아직 진행중이며, Project/Channel 구조가 확정되어야 최종 완료 처리 가능함

4.3 BARON-SSO 연동 준비

확인된 전제
ABC User Feedback는 커스텀 OAuth 2.0 / OIDC 제공자 연동을 지원함
현재 ABC Web의 OAuth 콜백 경로는 /auth/oauth-callback 기준으로 동작함
현재 Web 외부 노출 포트는 로컬 기준 3001이므로, ABC 관리자 UI를 그대로 사용할 경우 개발용 콜백 URI 후보는 http://localhost:3001/auth/oauth-callback 임
확보해야 할 BARON-SSO 클라이언트 등록 정보
client_id
client_secret
authorization_endpoint
token_endpoint
userinfo_endpoint
가능하면 jwks_uri
issuer
지원 scope 목록: 최소 openid, 사용자 식별, 이메일, 조직/역할 관련 scope
Redirect / Callback / Logout URI 정리 항목
ABC 관리자 UI OAuth Callback URI: /auth/oauth-callback
우리 시스템 사용자 포털 Callback URI: 별도 Next.js 앱 경로 확정 필요
우리 시스템 운영 포털 Callback URI: 사용자 포털과 분리 여부 확정 필요
Logout Redirect URI: BARON-SSO 로그아웃 후 복귀할 공통 URL 확정 필요
운영 환경별로 local, dev, stg, prod URI를 각각 등록 목록으로 정리해야 함
세션 저장 구조 초안
인증 원본은 BARON-SSO가 담당하고, 우리 시스템은 세션 또는 JWT에 필요한 최소 클레임만 저장함
공통 세션 필드: user_id, tenant_id, display_name, email, role_keys, workspace_scopes, access_token_exp, refresh_token_exp
선택 세션 필드: org_id, org_name, employee_no, position_code
서버 측 권한 판정은 세션에 저장된 역할 문자열만 신뢰하지 않고, tenant_id + workspace + 내부 권한 테이블을 함께 사용함
역할 판정 기준 초안
ROLE_USER: 본인 작성/조회만 가능
ROLE_APPROVER: 승인 대기 목록, 승인/반려 가능
ROLE_OPERATOR: 운영 목록, 상태 변경, 이슈 연결 가능
ROLE_ADMIN: Project/Channel/Field/Member 관리 가능
역할 판정 순서
1차: BARON-SSO 토큰 또는 userinfo에서 조직/그룹/역할 claim 확인
2차: 우리 시스템 user_workspace_access 기준으로 workspace별 실제 권한 확정
3차: ABC 프로젝트 멤버십과 운영 화면 접근 권한 동기화
예외 처리 정책
미로그인: SSO 로그인 페이지로 리다이렉트
세션 만료: 재로그인 유도 후 원래 진입 경로 복귀
권한 부족: 403 화면 + 요청 가능한 담당 조직 안내
workspace 매핑 없음: 일반 오류가 아니라 운영 설정 누락으로 분류하여 관리자 알림 대상에 포함
BARON-SSO userinfo 조회 실패: 재시도 1회 후 실패 로그 적재 및 운영 알림
1차 실무 작업 순서
BARON-SSO 담당자에게 클라이언트 등록 요청 템플릿 전달
환경별 Redirect/Callback/Logout URI 목록 확정
토큰 claim 샘플 수집: user_id, tenant_id, 조직/역할 관련 필드 확인
세션 스키마와 내부 권한 매핑 규칙 정의
테스트 계정 준비: 일반 사용자, 승인자, 운영 담당자, 관리자
로그인 성공/권한 부족/세션 만료/workspace 미매핑 시나리오 검증 항목 작성
완료 기준
BARON-SSO 클라이언트 등록에 필요한 입력값 목록이 문서화되어 있어야 함
세션 저장 필드와 역할 판정 규칙이 문서화되어 있어야 함
개발 환경 기준 Callback URI와 예외 처리 정책이 확정되어 있어야 함
현재 메모
BARON-SSO 로그인과 tenant_id 기반 권한/페이지 분기 처리는 다음 주 구현 범위로 계획함

4.4 우리 시스템 백엔드/DB 셋업

구현 전 정합성 확인
4.4 기준 DB 엔진은 MySQL 8.0으로 고정함
architecture_secretary_sso_components_v2.md의 SQL 초안에는 SERIAL, JSONB 등 PostgreSQL 스타일 표현이 포함되어 있으므로 실제 구현 전 MySQL 문법으로 변환해야 함
FastAPI 기본 구조 초안
실제 생성 경로: apps/secretary-api
apps/secretary-api/app/api: 사용자/운영 API 라우터
apps/secretary-api/app/core: 설정, 보안, 세션, 공통 유틸
apps/secretary-api/app/models: SQLAlchemy 모델 또는 ORM 엔티티
apps/secretary-api/app/schemas: 요청/응답 DTO
apps/secretary-api/app/services: 권한 판정, 티켓 처리, 승인 처리, ABC 브릿지
apps/secretary-api/app/repositories: DB 접근 계층
apps/secretary-api/app/integrations/abc: ABC API 클라이언트
apps/secretary-api/app/integrations/sso: BARON-SSO 토큰 검증 또는 userinfo 연동
apps/secretary-api/alembic: 마이그레이션 파일
apps/secretary-api/app/seeds: 코드성 초기 데이터 및 테스트용 seed 스크립트
현재 저장소 기준 확인 결과
apps/secretary-api/app/main.py에 FastAPI 엔트리포인트가 존재함
apps/secretary-api/app/api/routes/health.py에 /api/health 엔드포인트가 존재함
apps/secretary-api/app/api/routes/tickets.py에 GET /api/workspaces, GET /api/workspaces/{workspace_code}/form-template, POST /api/workspaces/{workspace_code}/tickets, GET /api/workspaces/{workspace_code}/tickets, GET /api/tickets/{ticket_id}, POST /api/tickets/{ticket_id}/approve, POST /api/tickets/{ticket_id}/issue 경로가 존재함 (완료)
apps/secretary-api/alembic/versions/0001_initial_support_schema.py에 P0 기준 1차 MySQL 마이그레이션이 존재함
apps/secretary-api/alembic/versions/0002_support_ticket_content_fields.py에 현재 UI가 사용하는 description, approval_status, sync_status, issue_link_status, extra_fields 컬럼 보강이 반영됨 (완료)
현재 작업 환경에서는 localhost:13306 대신 Docker bridge IP 기준 DATABASE_URL override 로 실제 MySQL 마이그레이션과 티켓 생성/조회 검증을 완료함 (부분 완료)
다만 ABC 연동 클라이언트, seed 스크립트 정리, 환경 공통 DB 접속 방식 정리는 아직 후속 작업으로 남아 있음
DB 구축 순서
1단계: 코드 테이블 및 서비스 마스터 생성
support_status_codes
support_category_codes
software_apps
service_types
workspaces
2단계: 권한 및 채널 매핑 테이블 생성
user_workspace_access
workspace_channel_mappings
workspace_field_mappings
3단계: 핵심 티켓 및 연동 테이블 생성
support_tickets
abc_feedback_mappings
request_approvals
notification_logs
operator_histories 또는 ticket_activity_logs
4단계: 확장 업무 테이블 생성
assets
asset_allocations
vehicle_schedules
remote_support
5단계: 이관 추적 테이블 생성
migration_batches
migration_mappings
핵심 테이블 구현 우선순위
P0: workspaces, workspace_channel_mappings, workspace_field_mappings
P0: support_tickets, abc_feedback_mappings
P0: user_workspace_access, request_approvals
P1: notification_logs, ticket_activity_logs
P1: migration_batches, migration_mappings
P2: assets, asset_allocations, vehicle_schedules, remote_support
MySQL 변환 규칙 초안
SERIAL은 BIGINT AUTO_INCREMENT 또는 INT AUTO_INCREMENT로 변환
JSONB는 MySQL JSON으로 변환
BOOLEAN은 MySQL BOOLEAN 또는 TINYINT(1) 기준으로 통일
TIMESTAMP DEFAULT CURRENT_TIMESTAMP와 updated_at 자동 갱신 규칙을 명시적으로 넣음
코드 테이블과 상태값은 가능하면 ENUM보다 참조 테이블 방식을 우선 적용함
마이그레이션 도구 및 seed 준비
Alembic 기반 버전 관리 적용
최초 마이그레이션은 서비스 마스터, 권한, 채널 매핑, 핵심 티켓 테이블까지 포함
seed 1차 범위: 상태 코드, 카테고리 코드, 기본 workspace, 기본 Project/Channel 매핑, 테스트 사용자 권한
seed 2차 범위: 샘플 티켓, 샘플 승인 데이터, 샘플 알림 이력
ABC API 연동용 서비스 계층 초안
ABCProjectService: Project/Channel 조회 및 캐시
ABCFeedbackService: 피드백 생성, 상세 조회, 첨부 업로드
ABCIssueService: 이슈 생성, 피드백-이슈 연결
ABCMemberSyncService: 운영자/승인자 프로젝트 멤버십 동기화
1차 실무 작업 순서
apps/secretary-api FastAPI 프로젝트 뼈대 생성
MySQL 연결 설정 및 로컬 .env 정의
Alembic 초기화 및 1차 마이그레이션 작성
코드 테이블 및 workspace 관련 테이블 생성
support_tickets, abc_feedback_mappings, request_approvals 생성
상태 코드 및 workspace seed 적재
GET /api/workspaces, POST /api/workspaces/{workspaceCode}/tickets 스텁 API 구현
ABC API 클라이언트 골격 구현
티켓 생성 시 ABC 저장 후 내부 매핑 저장하는 트랜잭션 흐름 설계
완료 기준
MySQL 기준 1차 마이그레이션이 적용 가능해야 함
workspace와 ABC Channel 간 기본 매핑 데이터가 적재 가능해야 함
내부 티켓 생성과 ABC feedback_id 매핑 저장 구조가 확정되어 있어야 함
승인 이력 저장 구조와 운영 이력 저장 구조가 확정되어 있어야 함
현재 메모
baron_support DB에 실제 마이그레이션 적용과 티켓 생성/목록 조회는 검증했으며, 현재 프런트 /support 흐름과 연결되는 최소 실DB 경로는 확보된 상태임
추가 검증 메모
현재 apps/web fallback 경로 기준으로 ABC MySQL userfeedback.feedbacks 저장 및 관리자 Feedback 화면 조회까지 검증했음
workspaceCode별로 ABC Channel 분기 저장되며, 채널 필드 스키마 기준으로 title/contents 또는 message 필드값만 저장되도록 정리했음
다만 이 문서 기준 완료 조건인 내부 support_tickets + abc_feedback_mappings 동시 저장을 현재 fallback 경로가 모두 대체하는 것은 아니므로, ABC DB 기준으로는 Create/Read 검증 완료, 전체 CRUD 완료로 보기는 이름

4.5 사용자 화면 셋업

현재 저장소 기준 확인 결과
실제 서비스 웹앱은 apps/web/src 기준으로 운영되고 있음
현재 apps/web/src/pages/support/[workspaceCode]/new|list|[ticketId]|index 라우트가 존재함 (완료)
사용자 화면은 실제 서비스 라우트 기준으로 운영되며, 로컬 dev 서버 3002에서 시연 가능함 (완료)
단, docker compose만으로는 3002가 열리지 않으며 apps/web를 별도 실행해야 함
예시: cd apps/web && PORT=3002 pnpm dev
라우팅 구조 초안
/support 또는 /portal/support: 공통 진입 라우터
/support/:workspaceCode/new: 사용자 작성 화면 (완료)
/support/:workspaceCode/list: 내 접수 목록 (완료)
/support/:workspaceCode/:ticketId: 접수 상세 (완료)
/support/:workspaceCode: 기본 진입 시 목록으로 리다이렉트 (완료)
승인형 업무와 Q&A형 업무는 같은 라우팅 패턴을 사용하되, workspaceCode에 따라 폼 템플릿과 후처리만 다르게 적용함
공통 로그인 후 화면 분기 규칙
SSO 로그인 완료 후 진입 파라미터 app_id, service_type_id, 메뉴 코드 중 하나를 받아 workspaceCode로 해석함
workspaceCode가 확정되면 GET /api/workspaces/{workspaceCode}/form-template로 필드 구성을 조회함
권한이 없으면 작성 화면으로 보내지 않고 403 또는 접근 안내 화면으로 분기함
사용자 피드백 작성 페이지 구현 항목
공통 입력 필드: 제목, 내용, 첨부 (완료)
workspace별 동적 필드 렌더링: 현재는 최소 Q&A 작성형으로 단순화하여 일부만 사용 (부분 완료)
제출 전 유효성 검사: 필수값, 날짜 범위, 숫자 범위, 첨부 제한
제출 시 처리 순서: 우리 시스템 API 호출 -> ABC 저장 -> 내부 support_tickets 생성 -> abc_feedback_mappings 저장
현재 검증 상태: apps/web fallback 경로에서 ABC feedbacks 저장과 관리자 조회는 확인했으며 (부분 완료), 내부 support_tickets/abc_feedback_mappings까지 같은 요청에서 항상 저장되는 구조는 secretary-api 기준으로 계속 검증 필요
완료 화면에는 ticket_id, feedback_id, 현재 상태값을 함께 보여줌
내 피드백 목록 페이지 구현 항목
로그인 사용자 기준 requester_id + requester_tenant_id 필터 적용 (완료)
목록 컬럼 초안: 제목, 요청 유형, 작성일, 내부 상태 중심 게시판 형태 구현 (완료)
workspace 필터와 상태 필터 제공
상단 우측 검색 입력 및 행 전체 클릭 상세 이동 구현 (완료)
리스트 하단 좌측 작성 페이지 이동 버튼 구현 (완료)
피드백 상세 페이지 구현 항목
ABC 원문 본문/첨부/댓글 조회 영역
우리 시스템 상태 메타데이터 영역: 현재는 최소 상태 배지와 댓글 입력 영역 중심으로 단순화 (부분 완료)
승인형 업무는 승인 이력 타임라인 노출
일반 Q&A형 업무는 이슈 연결 상태와 답변 상태를 노출
workspace별 채널/필드 자동 선택 로직
app_id, service_type_id, 메뉴 코드 -> workspaceCode 해석
workspaceCode -> workspace_channel_mappings로 ABC Channel 결정
workspaceCode -> workspace_field_mappings로 폼 필드와 검증 규칙 로드
채널 매핑이 없으면 작성 화면 진입 전 관리자 설정 누락 오류로 처리
작성 완료 후 매핑 저장 처리
우리 시스템은 ABC API 응답의 feedback_id를 수신한 뒤 같은 요청 컨텍스트에서 내부 티켓과 1:1 매핑 저장
저장 실패 시 사용자에게는 접수 보류 상태를 안내하고, 운영자에게 재처리 대상 알림을 남김
사용자 조회 화면의 상태 노출 원칙
ABC 상태값이 아니라 우리 시스템 support_tickets.status_code를 주 상태값으로 사용함
보조 상태로 approval_status, sync_status, issue_link_status를 함께 노출함
사용자는 본인 데이터만 조회 가능하고, tenant_id 불일치 데이터는 절대 노출하지 않음
1차 실무 작업 순서
사용자 공통 진입 URL 규칙 확정
workspace 해석 API 또는 미들웨어 구현
폼 템플릿 조회 API 구현 (완료 - 스텁 기준)
작성 API와 목록 API 구현 (완료 - 현재 secretary-api 연동 기준)
상세 API 구현: 내부 상태 + ABC 원문 조합 응답 (부분 완료)
샘플 workspace 1종으로 작성 -> 목록 -> 상세 흐름 검증 (완료)
완료 기준
최소 1개 workspace에서 작성, 목록, 상세 흐름이 연결되어 있어야 함
작성 완료 시 support_tickets와 abc_feedback_mappings가 함께 생성되어야 함
현재 확인 범위: ABC feedbacks 저장과 관리자 조회까지는 확인 완료, 내부 매핑 저장은 secretary-api 경로 기준 완료 메모를 유지하되 web fallback 경로는 별도 검증 필요
목록/상세 화면에서 내부 상태값이 ABC 원문과 함께 노출되어야 함

4.6 운영/관리 화면 셋업

현재 저장소 기준 확인 결과
실제 서비스 웹앱 apps/web/src/pages 이하에 /ops, /admin/issues 라우트가 존재함 (완료)
운영/관리 화면은 실제 페이지로 1차 이관되었고 승인/이슈 생성 흐름은 현재 secretary-api 및 내부 DB 경로 기준으로 계속 확장 중임 (부분 완료)
운영 화면 라우팅 구조 초안
/ops/approvals: 승인 대기 목록
/ops/tickets: 운영 전체 목록
/ops/tickets/:ticketId: 운영 상세
/admin/issues: 이슈 생성 대상 목록
/admin/issues/:ticketId: 피드백-이슈 연결 상세
승인 대상 조회 및 승인/반려 처리 구현 항목
조회 조건: request_approvals.approval_status = PENDING 또는 support_tickets.requires_approval = true and status_code = RECEIVED
승인 화면 컬럼 초안: 제목, 요청 유형, 요청자, 요청일시, 현재 상태, 승인 필요 사유
승인 시 처리 순서: 권한 검증 -> request_approvals 기록 -> support_tickets.status_code 갱신 -> 알림 이벤트 발행
반려 시 처리 순서: 반려 사유 저장 -> 사용자 노출 상태 갱신 -> 알림 이벤트 발행
ABC 관리자 UI 진입 링크 또는 연동 포인트
운영 상세에서 대응 ABC 원문 링크와 관리자 UI 바로가기 제공
관리자 화면에서는 abc_feedback_id, abc_channel_id, abc_feedback_url을 함께 노출
필요 시 ABC 기본 목록/상세 UI를 새 탭으로 열고, 우리 시스템은 상태 제어와 처리 이력만 담당함
피드백-이슈 연결 흐름 구현 항목
승인 완료 또는 운영 판단 완료 상태의 티켓만 이슈 생성 가능
이슈 생성 시 ABC 관리자 API 호출 후 issue_id와 연결 시각을 내부 이력에 저장
이미 연결된 티켓은 중복 생성이 아니라 기존 이슈 링크로 유도
연결 실패 시 내부 상태는 유지하고 sync_status 또는 운영 이력에 실패 원인을 저장
담당자 배정, 처리 메모, 상태 전이 로직
상태 전이 초안: RECEIVED -> PENDING_APPROVAL -> APPROVED -> IN_PROGRESS -> RESOLVED -> CLOSED
반려 흐름 초안: PENDING_APPROVAL -> REJECTED
담당자 배정은 current_assignee_id, current_assignee_tenant_id에 기록
처리 메모와 상태 변경 이력은 operator_histories 또는 ticket_activity_logs에 누적 저장
처리 결과/답변 입력 후 사용자 노출 데이터 동기화
내부 상태 변경 시 사용자 상세 화면의 상태 배지와 최근 처리 결과를 즉시 반영
필요 시 ABC 원문 댓글 또는 이슈 상태와 최소 동기화 규칙을 정의
사용자가 보는 최종 상태는 우리 시스템 support_tickets.status_code를 기준으로 유지
역할별 접근 제한 검증 항목
승인자: 승인 대기 목록과 승인/반려만 가능, 전체 운영 설정 변경 불가
운영 담당자: 전체 운영 목록, 상태 변경, 담당자 배정, 처리 메모 가능
관리자: Project/Channel/Member/이슈 연결 관리 가능
일반 사용자: 운영/관리 URL 직접 접근 시 403 처리
1차 실무 작업 순서
승인 대기 목록 API 구현 (완료 - 현재 preview 흐름 기준)
승인/반려 API 구현 및 request_approvals 저장 (부분 완료 - 현재 내부 상태 전이 기준)
운영 상세 API 구현: 내부 상태 + ABC 원문 링크 조합
담당자 배정 및 처리 메모 API 구현
이슈 생성 및 피드백-이슈 연결 API 구현 (부분 완료 - 현재 secretary-api 연동 기준)
운영/관리 화면을 실제 라우트 구조로 정리 (완료)
승인 -> 이슈 생성 -> 사용자 상세 반영 시나리오 검증 (부분 완료)
완료 기준
승인자가 승인/반려를 수행하면 내부 승인 이력과 티켓 상태가 함께 갱신되어야 함
운영 담당자가 상태 변경과 처리 메모를 남길 수 있어야 함
관리자 화면에서 승인 완료 티켓을 이슈 생성 대상으로 식별하고 연결할 수 있어야 함

4.7 외부 연동/알림 준비

대상 연동 범위 초안
메일 알림
사내 메신저 또는 협업 도구 알림
후속 업무 시스템 연계
운영 설정 누락 및 동기화 실패 감지
이벤트 기준 초안
접수 완료: 요청 제목, 접수 번호, 상세 링크
승인 대기: 승인 대상자, 요청 요약, 승인 링크
승인 완료: 요청 제목, 승인 결과, 다음 단계, 상세 링크
반려 완료: 반려 사유, 재작성 또는 문의 안내
처리 완료: 처리 결과 요약, 추가 확인 필요 여부, 상세 링크
RESOLVED: 처리 완료 결과 알림
자산/차량 연동형 업무는 승인 완료 후 후속 처리 이벤트를 별도 발행함
구현 준비 항목
알림 채널별 템플릿 정의
이벤트 발생 시점 정의
재시도 및 실패 로그 정책 정의
민감 정보 마스킹 정책 정의
완료 기준
승인 완료/처리 완료 이벤트 기준 알림 발송 검증
Mock 또는 실제 연동 경로가 최소 1개 이상 확인되어야 함

4.8 통합 검증/시연 준비

시연용 고정 데이터 준비
샘플 접수 데이터 3종: 승인형 1건, 일반 Q&A 1건, 처리완료 1건
테스트 계정: 일반 사용자 1명, 승인자 1명, 운영 담당자 1명, 관리자 1명
체크리스트형 실행 순서
일반 사용자 로그인 또는 진입
작성 페이지 진입
접수 등록
목록 확인
상세 확인
승인자 승인 또는 반려
운영 담당자 상태 갱신
관리자 이슈 연결 확인
사용자 상세 최종 상태 확인
실패 케이스 점검
권한 없는 사용자 진입 차단
workspace 미매핑 처리
세션 만료 후 복귀 흐름
ABC 또는 내부 DB 저장 실패 시 안내 문구
완료 기준
end-to-end 시연 체크리스트가 역할별로 1회 이상 통과되어야 함

5. 우선순위 기준 Task Backlog

P0
workspace, Project, Channel, Field, 권한 구조 확정
support_tickets, abc_feedback_mappings, request_approvals 최소 실DB 경로 검증 유지
사용자 작성 -> 목록 -> 상세 기본 흐름 안정화
P1
승인/반려, 이슈 연결, 댓글, 상태 반영 흐름 고도화
동적 필드, 첨부, 알림, 운영 이력 보강
P2
업무 시스템 연동, 알림 고도화, 확장 업무 테이블, 마이그레이션 추적 체계 보강
2, 3은 최종 완료 판단을 위한 선행 조건으로 유지

6. 실무용 체크리스트

완료: FastAPI 앱 골격, /api/health, /api/workspaces, /api/workspaces/{workspaceCode}/form-template, POST /api/workspaces/{workspaceCode}/tickets 스텁, 1차 Alembic 마이그레이션 파일, apps/web 사용자 /support 라우트, /ops, /admin/issues 실제 페이지 이관 (완료)

항목	상태	메모
ABC Web/API 로컬 실행 확인	완료	`start-local.sh`, `check-local.sh` 실행 및 기본 포트/헬스체크 확인 완료
MySQL 스키마 생성	진행중	`apps/secretary-api` Alembic 1차 마이그레이션 파일 생성 완료. 실제 DB 적용 검증은 남아 있음
MySQL 스키마 생성	부분 완료	`baron_support` DB 생성, Alembic 1차/2차 적용, Docker bridge IP 기준 실DB 검증 완료. 로컬 공통 접속 방식 정리는 남아 있음
`support_tickets` 테이블 생성	완료	실DB 생성 및 `description`, 상태 컬럼, `extra_fields` 포함 티켓 저장/조회 검증 완료
`request_approvals` 테이블 생성	부분 완료	실DB 생성 확인 완료. 실제 승인 저장 흐름 검증은 다음 단계
`abc_feedback_mappings` 테이블 생성	완료	실DB 생성 및 티켓 생성 시 매핑 레코드 저장 검증 완료
ABC DB `feedbacks` 저장/조회	완료	`apps/web` fallback 경로 기준으로 `userfeedback.feedbacks` 생성과 관리자 Feedback 화면 조회 검증 완료. 채널 필드 스키마에 맞춰 `contents`/`message` 본문만 저장되도록 정리 완료
사용자 작성/목록/상세 연결	완료	`apps/web`에 `/support/[workspaceCode]/new
승인 목록/운영 목록 연결	부분 완료	`/ops`, `/admin/issues` 라우트와 승인/이슈 생성 스텁 흐름 구현. 실DB/실권한 연동은 남아 있음
ABC 이슈 생성/연결 연동	부분 완료	secretary-api 및 `/admin/issues` 경로에 내부 상태 전이/연결 스텁 구현. 실제 ABC API 연동은 남아 있음
처리 결과 사용자 노출 동기화	부분 완료	사용자 상세에 상태 배지 및 댓글 UI 노출. 실제 운영 결과 동기화는 남아 있음
end-to-end 시연 검증	진행중	역할별 시나리오, 고정 데이터, 실패 케이스 체크리스트 초안 반영

33 KiB Raw Blame History

사내 지원 플랫폼 환경 셋업 및 Task 목록

1. 문서 목적

2. 기본 원칙

2.1 현재 작업 기준선

3. 전체 Task 로드맵

4. 단계별 상세 Task

4.1 로컬 기본 환경 구성

4.2 ABC 운영 구조 셋업

4.3 BARON-SSO 연동 준비

4.4 우리 시스템 백엔드/DB 셋업

4.5 사용자 화면 셋업

4.6 운영/관리 화면 셋업

4.7 외부 연동/알림 준비

4.8 통합 검증/시연 준비

5. 우선순위 기준 Task Backlog

6. 실무용 체크리스트

33 KiB

Raw Blame History