Finalize tdc114plus API contract

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 추가 여부