first commit

docs/architecture_secretary_sso_setup_tasks_v2.md

@@ -0,0 +1,209 @@
+# BARON-SSO 연계 Task 정리
+
+## 1. 문서 목적
+
+본 문서는 현재 저장소 기준으로 이미 완료된 작업, 부분 완료 상태인 작업, 앞으로 진행해야 할 작업을 다시 정리한 실행 문서임.
+
+특히 다음 두 문서를 하나의 실행 기준으로 연결하는 목적을 가짐.
+
+- 사용자/운영 흐름 기준: `docs/architecture_secretary_sso_user_scenarios.md`
+- 권한/테넌트/분기 기준: `docs/architecture_secretary_sso_role_access.md`
+
+이 문서에서는 기존 초안 중 현재 방향과 맞지 않는 항목은 정리하고, 실제 구현 상태와 다음 작업 순서를 우선으로 기록함.
+
+## 2. 현재 기준선
+
+### 2.1 운영 구조 기준
+
+- 인증 원본은 BARON-SSO 임.
+- 1차 사용자 분기는 `Q&A 관리자 테넌트` 소속 여부로 판단함.
+- 일반 사용자는 `/support/[workspaceCode]/**` 경로로 진입함.
+- 관리자/담당자는 `/main/project/[projectId]/feedback?channelId=[channelId]` 중심 관리자 콘솔로 진입함.
+- 초기 프로젝트 기준은 `EGBIM`, `TOVA`, `GAIA`, `KNGIL`, `INTRANET_QNA` 임.
+- 초기에는 프로젝트당 기본 채널 1개로 시작하고, 이후 문의 구분 기반 다중 채널로 확장함.
+
+### 2.2 상태 표기 기준
+
+- `완료`: 현재 저장소와 로컬 검증 기준으로 동작 경로가 확인된 작업
+- `부분 완료`: 일부 구현 또는 연결은 되었지만, 최종 운영 기준으로는 비어 있는 작업
+- `대기`: 설계만 있고 아직 구현 또는 운영 반영이 시작되지 않은 작업
+
+## 3. 완료된 작업 정리
+
+### 3.1 로컬 실행 기반
+
+| 항목 | 상태 | 정리 |
+| --- | --- | --- |
+| 로컬 ABC/연관 서비스 실행 스크립트 | 완료 | `start-local.sh`, `check-local.sh` 기준 로컬 기동 경로가 정리되어 있음 |
+| 기본 개발 저장소 구조 | 완료 | `apps/web`, `apps/api`, `apps/secretary-api`, `apps/e2e` 등 작업 단위가 분리되어 있음 |
+| secretary-api 기본 앱 구조 | 완료 | FastAPI 엔트리포인트, health, tickets 라우트, Alembic 구조가 존재함 |
+
+### 3.2 사용자 지원 포털
+
+| 항목 | 상태 | 정리 |
+| --- | --- | --- |
+| 사용자 작성 페이지 | 완료 | `/support/[workspaceCode]/new` 구현 완료 |
+| 사용자 목록 페이지 | 완료 | `/support/[workspaceCode]/list` 구현 완료 |
+| 사용자 상세 페이지 | 완료 | `/support/[workspaceCode]/[ticketId]` 구현 완료 |
+| 기본 진입 리다이렉트 | 완료 | `/support/[workspaceCode]` 진입 시 목록 흐름 존재 |
+| 폼 템플릿 조회 | 완료 | workspace 기반 작성 폼 템플릿 조회 API 연결 완료 |
+| 작성/목록/상세 기본 흐름 | 완료 | 최소 1개 workspace 기준 작성 -> 목록 -> 상세 흐름 구현 완료 |
+| 댓글 CRUD | 완료 | 사용자 상세와 관리자 상세 시트에서 댓글 생성/수정/삭제 흐름 존재 |
+| 상세 상태 반영 | 완료 | 사용자 상세에서 내부 상태와 ABC 이슈 연결 상태를 함께 반영함 |
+
+### 3.3 secretary-api 및 내부 DB
+
+| 항목 | 상태 | 정리 |
+| --- | --- | --- |
+| support ticket 기본 API | 완료 | workspaces, tickets, ticket detail, comments, approve, issue 관련 기본 라우트 존재 |
+| 핵심 마이그레이션 1차/2차 | 완료 | `support_tickets`, 상태 컬럼, `extra_fields` 등 현재 UI 기준 컬럼 반영 완료 |
+| 내부 티켓 저장 | 완료 | `support_tickets` 생성 흐름 구현 완료 |
+| ABC 피드백 매핑 저장 | 완료 | 내부 티켓 생성 후 `abc_feedback_mappings` 저장 흐름 구현 완료 |
+| 승인/이슈 상태 컬럼 | 완료 | `approval_status`, `sync_status`, `issue_link_status` 관리 구조 존재 |
+| 코멘트 저장 구조 | 완료 | `ticket_comments` 및 관련 API 흐름 구현 완료 |
+| 첨부 메타데이터 테이블 | 완료 | `attachments` 테이블과 ORM 모델 존재 |
+
+### 3.4 첨부파일 업로드 현재 완료 범위
+
+| 항목 | 상태 | 정리 |
+| --- | --- | --- |
+| 작성 페이지 파일 선택 UI | 완료 | 작성 화면에서 다중 첨부 선택 가능 |
+| multipart 프록시 처리 | 완료 | `apps/web` API route 에서 multipart 파싱 후 secretary-api 로 전달함 |
+| secretary-api 업로드 수신 | 완료 | multipart 요청에서 `attachments` 수신 가능 |
+| 로컬 파일 저장 | 완료 | 업로드 파일을 로컬 디렉터리에 저장하고 메타데이터를 `attachments` 테이블에 기록함 |
+| 파일 크기 제한 | 완료 | 30MB 제한 설정 존재 |
+
+### 3.5 운영 보조 화면
+
+| 항목 | 상태 | 정리 |
+| --- | --- | --- |
+| `/ops` 페이지 | 완료 | 승인 대기/처리 흐름용 운영 보조 화면 존재 |
+| `/admin/issues` 페이지 | 완료 | 이슈 연결 대상 확인용 운영 보조 화면 존재 |
+| 관리자 상세 시트 댓글 연계 | 완료 | 관리자 피드백 상세 시트에서 support ticket 댓글 흐름 사용 가능 |
+
+## 4. 부분 완료 작업 정리
+
+### 4.1 role_access 기준 운영 구조 반영
+
+| 항목 | 상태 | 남은 내용 |
+| --- | --- | --- |
+| 프로젝트 구조 문서화 | 부분 완료 | 새 기준 프로젝트 목록은 role_access 에 정리됐지만 실제 운영 seed/매핑 반영은 남아 있음 |
+| 프로젝트/채널 실제 생성 | 대기 | `EGBIM`, `TOVA`, `GAIA`, `KNGIL`, `INTRANET_QNA` 프로젝트와 동일명 기본 채널 생성 필요 |
+| 관리자 접근 정책 | 대기 | 프로젝트/채널별 운영자 접근 범위와 내부 권한 테이블 반영 필요 |
+| 문의 구분 기반 확장 전략 | 부분 완료 | 문서 초안은 있으나 실제 필드/라우팅/큐 분기 규칙은 미구현 |
+
+### 4.2 BARON-SSO 및 권한 분기
+
+| 항목 | 상태 | 남은 내용 |
+| --- | --- | --- |
+| BARON-SSO 로그인 연동 | 대기 | 실제 OIDC/OAuth 연동 구현 필요 |
+| 세션의 `user_id`, `tenant_id`, `role_keys` 처리 | 대기 | 현재 테스트 사용자 상수 기반 흐름을 실제 세션 기반으로 전환해야 함 |
+| 관리자 테넌트 여부 판정 | 대기 | `Q&A 관리자 테넌트` 기준 1차 분기 로직 미구현 |
+| 사용자/관리자 페이지 분기 | 대기 | 로그인 후 `/support/...` 와 관리자 콘솔 자동 분기 미구현 |
+| 프로젝트/채널별 세부 권한 제한 | 대기 | 관리자 콘솔 진입 후 재검증 로직 미구현 |
+
+### 4.3 사용자 지원 포털 보강
+
+| 항목 | 상태 | 남은 내용 |
+| --- | --- | --- |
+| 동적 필드 전체 사용 | 부분 완료 | 현재 title/description 중심 최소 렌더링만 사용 중 |
+| 문의 구분 필드 반영 | 대기 | role_access 기준 문의 구분 저장 및 운영 큐 분기 연결 필요 |
+| 첨부파일 상세 조회/다운로드 | 대기 | 업로드 저장은 되지만 목록/상세 응답과 다운로드 경로는 없음 |
+| 첨부파일 ABC 연동 | 대기 | 현재 ABC 생성 시 제목/본문만 전송하고 첨부는 내부 로컬 저장만 수행함 |
+| 작성 완료 결과 표준화 | 부분 완료 | 현재 ticket 상태는 보이지만 운영 기준 완료 UX 는 추가 정리 필요 |
+
+### 4.4 운영/관리 기능 보강
+
+| 항목 | 상태 | 남은 내용 |
+| --- | --- | --- |
+| 승인 이력 정교화 | 부분 완료 | 승인 상태 전이와 기본 API 는 있으나 실제 운영 권한/사유/이력 정책 보강 필요 |
+| 이슈 생성/연결 운영 흐름 | 부분 완료 | 상태 동기화와 보조 화면은 있으나 실제 운영 정책/권한 제어는 추가 필요 |
+| 담당자 배정/처리 메모 | 대기 | 전담 운영 테이블/화면/이력 흐름 미구현 |
+| 관리자 콘솔 프로젝트 단위 제한 | 대기 | role_access 기준 프로젝트/채널별 접근 제한 미구현 |
+
+### 4.5 데이터 및 운영 자동화
+
+| 항목 | 상태 | 남은 내용 |
+| --- | --- | --- |
+| seed 데이터 정리 | 부분 완료 | 테스트 흐름은 있으나 새 프로젝트 기준 seed 재정리 필요 |
+| 공통 권한 테이블 | 대기 | `tenant + project + channel + role` 조합 저장 구조 구체화 필요 |
+| 알림/후속 연계 | 대기 | 승인 완료, 처리 완료, 설정 누락 알림 등 운영 이벤트 미구현 |
+| E2E 시나리오 고정 | 부분 완료 | 화면 시연은 가능하나 role_access 기준 사용자/관리자 분기 시나리오 정리는 부족함 |
+
+## 5. 앞으로 해야 할 작업
+
+### 5.1 P0: role_access 기준 운영 구조 확정
+
+- BARON-SSO `Q&A 관리자 테넌트` 식별값 확정
+- 관리자 대상 계정 배정 기준 확정
+- 프로젝트 `EGBIM`, `TOVA`, `GAIA`, `KNGIL`, `INTRANET_QNA` 실제 생성
+- 각 프로젝트 기본 채널 1개 생성
+- 사용자 Q&A 이동 URL과 `workspaceCode` 매핑 표 확정
+- 프로젝트/채널별 관리자 접근 정책 확정
+
+### 5.2 P0: 로그인 후 분기와 권한 처리 구현
+
+- BARON-SSO 로그인 연동 구현
+- 세션에서 `user_id`, `tenant_id`, `role_keys` 읽는 공통 계층 추가
+- 관리자 테넌트 여부에 따른 1차 분기 구현
+- 일반 사용자 -> `/support/[workspaceCode]/new` 이동 구현
+- 관리자/담당자 -> 관리자 콘솔 기본 진입 경로 이동 구현
+- 관리자 콘솔 진입 후 프로젝트/채널별 재검증 구현
+
+### 5.3 P1: 사용자 포털 기능 마감
+
+- 문의 구분 필드 추가 및 저장
+- `workspace`별 동적 필드 전체 렌더링 정리
+- 첨부파일 응답 스키마 추가
+- 사용자 상세 첨부 목록 및 다운로드 구현
+- 필요 시 첨부 ABC 저장 전략 확정 후 브릿지 구현
+- 업로드 실패/부분 저장 실패 시 사용자 안내 문구 표준화
+
+### 5.4 P1: 운영/관리 기능 마감
+
+- 승인/반려 사유와 승인 이력 화면 정리
+- 담당자 배정, 처리 메모, 상태 변경 이력 구현
+- 이슈 생성 후 사용자 상세 상태 반영 규칙 정리
+- 관리자 콘솔에서 프로젝트/채널/문의구분 기반 큐 분리
+- 운영 보조 화면 `/ops`, `/admin/issues` 와 실제 관리자 콘솔 역할 분담 정리
+
+### 5.5 P2: 운영 안정화 및 검증
+
+- role_access 기준 테스트 계정 3종 이상 준비
+- 일반 사용자/담당자/시스템 관리자 시나리오별 E2E 체크리스트 작성
+- 프로젝트 미매핑, 권한 부족, 세션 만료 예외 처리 검증
+- 알림 및 운영 설정 누락 감지 체계 추가
+- 문서 간 용어 통일: tenant, workspace, project, channel, 문의 구분
+
+## 6. 바로 실행할 다음 작업 제안
+
+### 6.1 1차 묶음
+
+- `workspaceCode -> project/channel` 새 매핑표 확정
+- `Q&A 관리자 테넌트` 식별 규칙 확정
+- 로그인 후 사용자/관리자 분기 미들웨어 또는 라우터 초안 작성
+
+### 6.2 2차 묶음
+
+- 첨부파일 조회/다운로드 API 추가
+- 사용자 상세 첨부 표시 추가
+- 문의 구분 필드 저장 및 관리자 큐 표시 초안 추가
+
+### 6.3 3차 묶음
+
+- 프로젝트/채널별 관리자 접근 제어 테이블 설계
+- 운영 보조 화면과 실제 관리자 콘솔 권한 경계 정리
+- role_access 기준 E2E 시나리오 문서화
+
+## 7. 이번 정리에서 제거한 구버전 가정
+
+- `INTRANET_SUPPORT`, `SOFTWARE_QA` 중심 Project 초안은 현재 우선 기준에서 제외함.
+- 기존 task 문서에 있던 인트라넷 신청형 업무 중심 Channel 목록은 role_access 기준 Q&A 프로젝트 구조가 확정될 때까지 보조 아이디어로만 취급함.
+- 테스트 상수 사용자 기준 흐름은 임시 검증 수단으로 유지하되, 운영 기준 완료 항목으로 보지 않음.
+
+## 8. 최종 요약
+
+- 현재 구현은 사용자 지원 포털, 내부 티켓 저장, 댓글, 일부 운영 보조 화면까지는 갖춰져 있음.
+- 새 기준선은 role_access 문서의 테넌트 분기, 프로젝트 구조, 관리자 권한 모델임.
+- 지금 가장 큰 공백은 SSO 실연동, 로그인 후 분기, 프로젝트/채널별 접근 제어, 첨부 조회/다운로드, 문의 구분 기반 운영 큐 분리임.
+- 이후 작업은 기존 범용 초안 확장보다 role_access 기준 운영 구조를 코드와 데이터에 반영하는 순서로 진행해야 함.