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

## 1. 문서 목적

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

권한, 테넌트, 로그인 후 페이지 분기 설계는 [architecture_secretary_sso_role_access.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|list|[ticketId]|index` 구현 및 작성->목록->상세 흐름 확인 |
| 승인 목록/운영 목록 연결 | 부분 완료 | `/ops`, `/admin/issues` 라우트와 승인/이슈 생성 스텁 흐름 구현. 실DB/실권한 연동은 남아 있음 |
| ABC 이슈 생성/연결 연동 | 부분 완료 | secretary-api 및 `/admin/issues` 경로에 내부 상태 전이/연결 스텁 구현. 실제 ABC API 연동은 남아 있음 |
| 처리 결과 사용자 노출 동기화 | 부분 완료 | 사용자 상세에 상태 배지 및 댓글 UI 노출. 실제 운영 결과 동기화는 남아 있음 |
| end-to-end 시연 검증 | 진행중 | 역할별 시나리오, 고정 데이터, 실패 케이스 체크리스트 초안 반영 |