diff --git a/docs/tdc114plus-api-contract-2026-07-02.md b/docs/tdc114plus-api-contract-2026-07-02.md index 57e07d3..df46acf 100644 --- a/docs/tdc114plus-api-contract-2026-07-02.md +++ b/docs/tdc114plus-api-contract-2026-07-02.md @@ -1,7 +1,7 @@ -# tdc114plus API 계약 초안 +# tdc114plus API 계약 작성일: 2026-07-02 -상태: v0.1 초안 +상태: v1.0 1차 구현 기준 확정 목적: `tdc114plus` Flutter 앱이 Baron SSO backend 및 orgFront 데이터와 연동하기 위해 필요한 API 계약을 정의한다. 본 문서는 구현 전 계약 기준이며, 실제 Baron SSO backend 구현은 `/home/ubuntu/workspace/baron-sso-tdc114plus-api`의 `feature/tdc114plus-api` 브랜치에서 진행한다. @@ -38,7 +38,18 @@ - 미등록 사용자는 앱 사용을 허용하지 않는다. - 공지사항, 전자결재, 수신전화식별, 수신팝업은 1차 API 범위에서 제외한다. -## 3. API namespace +## 3. 1차 구현 확정사항 + +| 항목 | 1차 구현 기준 | 후속 검토 | +| --- | --- | --- | +| 전화번호 로그인 보안 수준 | Baron SSO 등록 사용자 확인, rate limit, 감사 로그, generic error message 적용 | SMS OTP, 기기 등록, 내부망 제한, 추가 인증 | +| token 종류 | 기존 Baron SSO session token 재사용 | 앱 전용 access token 또는 refresh token 분리 | +| 개인정보 마스킹 범위 | Baron SSO 등록 사용자에게 직원 검색/조직도 기본 필드 노출 | 권한별 전화번호/이메일/직급 마스킹 정책 | +| 즐겨찾기 동기화 | 1차는 앱 로컬 저장 | 서버 동기화 API 추가 | + +본 확정사항은 1차 개발 범위를 빠르게 구현하기 위한 기준이다. 운영 배포 전 보안 리뷰에서 전화번호 로그인, token 저장, 개인정보 노출 범위는 재검토한다. + +## 4. API namespace 권장 namespace: @@ -52,9 +63,9 @@ - 앱은 일반 등록 사용자용 직원검색/조직도 기능이므로 별도 namespace가 필요하다. - 향후 감사 로그, 마스킹, 앱별 권한 정책을 독립적으로 적용하기 쉽다. -## 4. 인증 API +## 5. 인증 API -### 4.1 전화번호 로그인 +### 5.1 전화번호 로그인 ```http POST /api/v1/tdc114plus/auth/phone-login @@ -63,7 +74,7 @@ POST /api/v1/tdc114plus/auth/phone-login 설명: - 사용자가 앱 로그인창에 전화번호를 입력하면 Baron SSO 등록 사용자 여부를 확인한다. -- 등록 사용자이면 앱 사용에 필요한 session token 또는 app access token을 반환한다. +- 등록 사용자이면 앱 사용에 필요한 Baron SSO session token을 반환한다. - 기존 Baron SSO의 `/api/v1/auth/phone-login` 흐름을 참고하되, `tdc114plus` 전용 DTO와 오류 정책을 둔다. 요청: @@ -84,7 +95,7 @@ POST /api/v1/tdc114plus/auth/phone-login ```json { "status": "ok", - "token": "session-or-app-token", + "token": "baron-sso-session-token", "expiresAt": "2026-07-02T12:00:00Z", "user": { "id": "user-uuid", @@ -116,7 +127,7 @@ POST /api/v1/tdc114plus/auth/phone-login - 1차 정책상 Baron SSO 등록 인원 확인용으로 사용하되, rate limit, 감사 로그, generic error message를 적용한다. - 운영 전에는 SMS OTP, 기기 등록, 내부망 제한, 추가 인증 중 하나 이상을 후속 검토한다. -### 4.2 내 프로필 +### 5.2 내 프로필 ```http GET /api/v1/tdc114plus/me @@ -146,9 +157,9 @@ Authorization: Bearer {token} } ``` -## 5. 직원검색/전화번호검색 API +## 6. 직원검색/전화번호검색 API -### 5.1 직원 목록 및 검색 +### 6.1 직원 목록 및 검색 ```http GET /api/v1/tdc114plus/directory/employees @@ -205,7 +216,7 @@ Query: - Baron SSO 기준 `active`, `temporary_leave`, `suspended`는 조직도 노출 후보로 볼 수 있다. - `baron_guest`, `extended_leave`, `archived`는 기본 제외한다. -### 5.2 직원 상세 +### 6.2 직원 상세 ```http GET /api/v1/tdc114plus/directory/employees/{employeeId} @@ -247,9 +258,9 @@ Authorization: Bearer {token} } ``` -## 6. 가족사 필터/조직도 API +## 7. 가족사 필터/조직도 API -### 6.1 가족사/조직 필터 목록 +### 7.1 가족사/조직 필터 목록 ```http GET /api/v1/tdc114plus/organization/tenants @@ -275,7 +286,7 @@ Authorization: Bearer {token} } ``` -### 6.2 조직도 snapshot +### 7.2 조직도 snapshot ```http GET /api/v1/tdc114plus/organization/orgchart @@ -335,9 +346,9 @@ Query: - `tdc114plus` 응답은 앱 의미에 맞춰 `users` 대신 `employees`를 사용한다. - 기존 admin/orgFront API를 직접 변경하지 않고 별도 DTO에서 변환한다. -## 7. 즐겨찾기 API +## 8. 즐겨찾기 API -1차 구현은 로컬 저장을 기본으로 한다. +1차 구현은 앱 로컬 저장을 기본으로 한다. 서버 동기화는 후속 단계에서 검토한다. @@ -348,7 +359,7 @@ GET /api/v1/tdc114plus/favorites PUT /api/v1/tdc114plus/favorites ``` -## 8. 오류 응답 공통 형식 +## 9. 오류 응답 공통 형식 Baron SSO API 설계 정책에 맞춰 신규 API는 `code`를 기본 포함한다. @@ -371,15 +382,16 @@ Baron SSO API 설계 정책에 맞춰 신규 API는 `code`를 기본 포함한 | 429 | `rate_limited` | 과도한 요청 | | 503 | `dependency_unavailable` | Kratos, Redis, DB 등 의존성 장애 | -## 9. 개인정보/보안 정책 +## 10. 개인정보/보안 정책 - 전화번호 원문은 로그에 남기지 않고 마스킹 또는 정규화 값 일부만 기록한다. - 직원 검색/상세 조회는 감사 로그 대상으로 둔다. - 대량 조회, 짧은 시간 내 반복 조회는 이상 조회 탐지 후보로 기록한다. -- 권한 없는 사용자의 민감정보 마스킹은 후속 정책에서 확정한다. +- 1차 구현에서는 Baron SSO 등록 사용자에게 직원 검색/조직도 기본 필드를 노출한다. +- 권한별 민감정보 마스킹은 후속 정책에서 확정한다. - 1차 앱에서는 `call`, `sms` 액션을 제공하되, 앱 내부에서 수신전화식별/수신팝업 기능은 구현하지 않는다. -## 10. Baron SSO 구현 후보 +## 11. Baron SSO 구현 후보 신규 패키지/파일 후보: @@ -403,20 +415,22 @@ tdc114plus.Get("/organization/tenants", requireAnyUser, tdc114plusHandler.ListTe tdc114plus.Get("/organization/orgchart", requireAnyUser, tdc114plusHandler.GetOrgChart) ``` -## 11. 구현 전 확인사항 +## 12. 구현 전 확인사항 -문서 기준으로 우선 진행 가능한 항목: +확정되어 바로 진행 가능한 항목: - 전용 namespace `/api/v1/tdc114plus` - 전용 DTO - 기존 admin/user/orgchart API는 변경하지 않음 - 직원/조직 데이터는 기존 orgchart snapshot 및 identity mirror/read model 기반으로 변환 +- 전화번호 로그인은 1차에서 등록자 확인 + rate limit + audit + generic error message 기준으로 구현 +- token은 1차에서 기존 Baron SSO session token 재사용 +- 개인정보는 1차에서 Baron SSO 등록 사용자에게 기본 필드 노출 +- 즐겨찾기는 1차에서 앱 로컬 저장 -추가 확인이 필요한 항목: +운영 배포 전 재검토 항목: -| 항목 | 확인 필요 이유 | 기본 권장안 | -| --- | --- | --- | -| 전화번호 로그인 보안 수준 | 전화번호 단독 로그인은 표준 인증이 아님 | 1차는 등록자 확인 + rate limit + audit, 후속 기기 등록/OTP 검토 | -| token 종류 | 기존 session JWT를 그대로 앱에 줄지, app token을 별도로 둘지 결정 필요 | 초기에는 기존 session token 재사용, 후속 app token 검토 | -| 개인정보 마스킹 범위 | 직급/전화번호/이메일 노출 정책 필요 | 1차는 등록 사용자 전체 공개, 후속 권한별 마스킹 | -| 서버 즐겨찾기 동기화 | 1차 요구사항은 즐겨찾기이나 서버 동기화 여부 미정 | 1차 로컬 저장 | +- SMS OTP, 기기 등록, 내부망 제한, 추가 인증 중 하나 이상 도입 여부 +- 앱 전용 access token 또는 refresh token 분리 여부 +- 권한별 개인정보 마스킹 범위 +- 즐겨찾기 서버 동기화 API 추가 여부 diff --git a/docs/tdc114plus-work-progress-timetable-2026-07-02.md b/docs/tdc114plus-work-progress-timetable-2026-07-02.md index d2f40ff..ac8bc4c 100644 --- a/docs/tdc114plus-work-progress-timetable-2026-07-02.md +++ b/docs/tdc114plus-work-progress-timetable-2026-07-02.md @@ -43,9 +43,9 @@ | 9 | Baron SSO 참조 소스 기준 정리 | 완료 | tdc114plus 개발 시 참조할 Baron SSO 원격/브랜치/업데이트 정책 정리 | `docs/baron-sso-reference-source-policy-2026-07-02.md` | | 10 | 최신 Baron SSO API 개발 worktree 생성 | 완료 | `origin/dev` 기준 `feature/tdc114plus-api` worktree를 생성해 orgFront/backend 확인 및 API 개발 준비 | `/home/ubuntu/workspace/baron-sso-tdc114plus-api` | | 11 | tdc114plus 개발 정책 정리 | 완료 | Baron SSO API 생성 우선 원칙, VS Code 기반 AI 개발 방식, Flutter/플랫폼 구현 원칙 정리 | `docs/tdc114plus-development-policy-2026-07-02.md` | -| 12 | API 계약 정리 | 초안 완료 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | `docs/tdc114plus-api-contract-2026-07-02.md` | -| 13 | API 계약 검토 및 확정 | 다음 작업 | API 계약 초안의 추가 확인사항 검토 후 확정 | API 계약 확정본 | -| 14 | 데이터 모델 설계 | 대기 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model | +| 12 | API 계약 정리 | 완료 | Baron SSO 로그인 API, orgFront 직원/조직 API 계약 정리 | `docs/tdc114plus-api-contract-2026-07-02.md` | +| 13 | API 계약 검토 및 확정 | 완료 | API 계약 초안의 추가 확인사항 검토 후 1차 구현 기준 확정 | `docs/tdc114plus-api-contract-2026-07-02.md` | +| 14 | 데이터 모델 설계 | 다음 작업 | 직원, 조직, 가족사, 즐겨찾기 모델 정의 | Dart model | | 15 | Mock 데이터 기반 화면 확장 | 대기 | 직원목록, 검색, 가족사 필터, 조직도 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI | | 16 | Baron SSO 로그인 연동 | 대기 | 전화번호 입력 후 SSO 등록 인원 여부 확인 연동 | 로그인 client/repository | | 17 | orgFront 데이터 연동 | 대기 | 직원/조직 데이터 API 연동 | directory/organization client | @@ -60,8 +60,9 @@ | Phase 0 | 완료 | 저장소와 개발환경 출발점 확보 | clone, 문서 이관, README, scripts 구성 | Gitea `main` push 완료 | | Phase 1 | 완료 | Flutter 앱 실행 골격 확보 | Flutter create, 라우터, 로그인/직원검색 화면 초안 | analyze/test 통과 | | Phase 2 | 완료 | Baron SSO 참조 기준 확정 및 API 계약 준비 | 공식 `origin/dev` 기준 확인, API 개발 worktree 생성, Baron Safe 참고 정책 확인 | `feature/tdc114plus-api` worktree 생성 | -| Phase 2-1 | 초안 완료 | API 계약 초안 작성 | 개발 정책 확인 후 SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 초안 작성 완료 | -| Phase 2-2 | 다음 | API 계약 검토 및 확정 | token 종류, 전화번호 로그인 보안 수준, 개인정보 마스킹 범위, 즐겨찾기 동기화 여부 확인 | API 계약 확정본 | +| Phase 2-1 | 완료 | API 계약 초안 작성 | 개발 정책 확인 후 SSO 로그인 API, orgFront 직원/조직 API, 응답 필드, 오류 정책 정리 | API 계약 초안 작성 완료 | +| Phase 2-2 | 완료 | API 계약 검토 및 확정 | token 종류, 전화번호 로그인 보안 수준, 개인정보 마스킹 범위, 즐겨찾기 동기화 여부 확인 | API 계약 확정본 | +| Phase 2-3 | 다음 | Dart 데이터 모델 설계 | 확정된 API 계약 기준으로 직원, 조직, 로그인, 즐겨찾기 model 정의 | model 초안 | | Phase 3 | 이후 | Mock 기반 1차 UI 완성 | 직원목록, 검색, 가족사 필터, 조직도, 상세 화면 구성 | API 없이 화면 흐름 확인 가능 | | Phase 4 | 이후 | 실제 API 연동 | SSO 로그인, orgFront 직원/조직 데이터 연동 | 등록 사용자 로그인 및 직원목록 조회 | | Phase 5 | 이후 | 핵심 액션 완성 | 전화걸기, 문자보내기, 즐겨찾기 저장 | 1차 기본 기능 수동 검증 | @@ -69,7 +70,7 @@ ## 4. 다음 작업 판단 -현재 다음 작업은 **Phase 2-2: API 계약 검토 및 확정**이다. +현재 다음 작업은 **Phase 2-3: Dart 데이터 모델 설계**이다. 공식 Baron SSO `origin/dev` 기준의 API 개발용 worktree는 `/home/ubuntu/workspace/baron-sso-tdc114plus-api`에 생성 완료했다. 기존 `baron-sso` 작업 브랜치는 수정/미추적 파일이 많으므로 직접 merge/rebase하지 않는다. @@ -92,16 +93,16 @@ API 계약 정리 시 아래 문서를 우선 참고한다. 7. 개인정보 마스킹 또는 권한 필드 필요 여부 8. API 실패/네트워크 오류 시 앱 표시 정책 -API 계약 초안: +API 계약 확정본: - `docs/tdc114plus-api-contract-2026-07-02.md` -계약 확정 전 확인할 항목: +1차 구현 기준 확정사항: -1. 전화번호 로그인 보안 수준 -2. token 종류 -3. 개인정보 마스킹 범위 -4. 즐겨찾기 서버 동기화 여부 +1. 전화번호 로그인은 등록자 확인, rate limit, 감사 로그, generic error message 기준으로 구현한다. +2. token은 기존 Baron SSO session token을 1차 재사용한다. +3. 개인정보는 Baron SSO 등록 사용자에게 기본 필드를 노출한다. +4. 즐겨찾기는 1차 앱 로컬 저장으로 구현한다. ## 5. 신규 작업 추가 규칙 @@ -132,4 +133,4 @@ git -C /home/ubuntu/workspace/tdc114plus log --oneline origin/main -n 10 git -C /home/ubuntu/workspace/tdc114plus status --short --branch ``` -현재 문서 기준 다음 작업은 `Phase 2-2: API 계약 검토 및 확정`이다. +현재 문서 기준 다음 작업은 `Phase 2-3: Dart 데이터 모델 설계`이다.