kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d89089396695054af4cea89b485dd48890ef0ee6
tdc114plus/docs/tdc114plus-api-contract-2026-07-02.md
T

12 KiB
Raw Blame History

tdc114plus API 계약

작성일: 2026-07-02 상태: v1.0 1차 구현 기준 확정

목적: tdc114plus Flutter 앱이 Baron SSO backend 및 orgFront 데이터와 연동하기 위해 필요한 API 계약을 정의한다. 본 문서는 구현 전 계약 기준이며, 실제 Baron SSO backend 구현은 /home/ubuntu/workspace/baron-sso-tdc114plus-api의 feature/tdc114plus-api 브랜치에서 진행한다.

1. 설계 기준

확인한 기준 문서:

  • docs/tdc114plus-development-decision-brief-2026-07-01.md
  • docs/tdc114plus-development-policy-2026-07-02.md
  • docs/baron-sso-reference-source-policy-2026-07-02.md
  • docs/references/baron-safe-policies/api-contract.md
  • Baron SSO docs/API_DESIGN_POLICY.md
  • Baron SSO docs/identity-redis-mirror-policy-2026-06-09.md
  • Baron SSO docs/references/baron-safe-policies/nonstandard-phone-only-login-technical-review-2026-06-23.md

확인한 기존 Baron SSO 코드:

  • backend/cmd/server/main.go
  • backend/internal/handler/auth_handler.go
  • backend/internal/handler/tenant_handler.go
  • backend/internal/handler/user_handler.go
  • backend/internal/domain/user.go
  • backend/internal/domain/tenant.go
  • orgfront/src/lib/adminApi.ts

2. 핵심 원칙

  • 기존 Baron SSO API 응답을 tdc114plus 요구사항에 맞게 직접 변경하지 않는다.
  • tdc114plus 전용 endpoint와 response DTO를 둔다.
  • JSON field는 camelCase를 사용한다.
  • 목록 응답은 items, limit, offset, total, nextCursor 형식을 따른다.
  • 직원/조직 데이터는 Baron SSO orgFront 및 backend read model을 기준으로 제공한다.
  • 앱 자체 회원가입은 제공하지 않는다.
  • 미등록 사용자는 앱 사용을 허용하지 않는다.
  • 공지사항, 전자결재, 수신전화식별, 수신팝업은 1차 API 범위에서 제외한다.

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:

/api/v1/tdc114plus

이유:

  • 기존 /api/v1/admin/users, /api/v1/admin/orgchart/snapshot은 관리자/orgFront 성격이 강하다.
  • 앱은 일반 등록 사용자용 직원검색/조직도 기능이므로 별도 namespace가 필요하다.
  • 향후 감사 로그, 마스킹, 앱별 권한 정책을 독립적으로 적용하기 쉽다.

5. 인증 API

5.1 전화번호 로그인

POST /api/v1/tdc114plus/auth/phone-login

설명:

  • 사용자가 앱 로그인창에 전화번호를 입력하면 Baron SSO 등록 사용자 여부를 확인한다.
  • 등록 사용자이면 앱 사용에 필요한 Baron SSO session token을 반환한다.
  • 기존 Baron SSO의 /api/v1/auth/phone-login 흐름을 참고하되, tdc114plus 전용 DTO와 오류 정책을 둔다.

요청:

{
  "phoneNumber": "01012345678",
  "device": {
    "platform": "android",
    "appVersion": "0.1.0",
    "deviceName": "Pixel 8"
  }
}

응답:

{
  "status": "ok",
  "token": "baron-sso-session-token",
  "expiresAt": "2026-07-02T12:00:00Z",
  "user": {
    "id": "user-uuid",
    "name": "홍길동",
    "phoneNumber": "+821012345678",
    "tenantId": "tenant-uuid",
    "tenantName": "한맥",
    "tenantSlug": "hanmac",
    "department": "기술연구소",
    "grade": "책임",
    "position": "팀장",
    "jobTitle": "개발"
  }
}

오류:

HTTP code 설명
400 invalid_phone_number 전화번호 형식 오류
401 login_failed 등록 사용자 확인 실패. 사용자 존재 여부를 과도하게 드러내지 않는다.
429 rate_limited 반복 시도 제한
503 identity_provider_unavailable Kratos/SSO 조회 실패

보안 메모:

  • 전화번호 단독 로그인은 표준 인증으로 보기 어렵다.
  • 1차 정책상 Baron SSO 등록 인원 확인용으로 사용하되, rate limit, 감사 로그, generic error message를 적용한다.
  • 운영 전에는 SMS OTP, 기기 등록, 내부망 제한, 추가 인증 중 하나 이상을 후속 검토한다.

5.2 내 프로필

GET /api/v1/tdc114plus/me
Authorization: Bearer {token}

응답:

{
  "id": "user-uuid",
  "name": "홍길동",
  "phoneNumber": "+821012345678",
  "email": "user@example.com",
  "tenantId": "tenant-uuid",
  "tenantName": "한맥",
  "tenantSlug": "hanmac",
  "department": "기술연구소",
  "grade": "책임",
  "position": "팀장",
  "jobTitle": "개발",
  "permissions": {
    "directory": true,
    "organization": true,
    "favoritesSync": false
  }
}

6. 직원검색/전화번호검색 API

6.1 직원 목록 및 검색

GET /api/v1/tdc114plus/directory/employees
Authorization: Bearer {token}

Query:

이름 필수 설명
q N 이름, 전화번호, 부서, 직위, 직무 검색어
tenantId N 가족사/회사/조직 필터
tenantSlug N 가족사 slug 필터
department N 부서명 필터
limit N 기본 50
offset N 기본 0
cursor N cursor pagination 사용 시

응답:

{
  "items": [
    {
      "id": "user-uuid",
      "name": "홍길동",
      "phoneNumber": "+821012345678",
      "phoneDisplay": "010-1234-5678",
      "email": "user@example.com",
      "tenantId": "tenant-uuid",
      "tenantName": "한맥",
      "tenantSlug": "hanmac",
      "department": "기술연구소",
      "grade": "책임",
      "position": "팀장",
      "jobTitle": "개발",
      "status": "active",
      "profileImageUrl": null,
      "sortOrder": 100
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1,
  "nextCursor": ""
}

검색 규칙:

  • q는 이름, 전화번호, 부서, 직위, 직책, 직무, 이메일 일부를 대상으로 한다.
  • 전화번호 검색은 숫자만 입력해도 매칭되도록 서버에서 정규화한다.
  • 기본 노출 대상은 조직도 표시 가능한 사용자 상태로 제한한다.
  • Baron SSO 기준 active, temporary_leave, suspended는 조직도 노출 후보로 볼 수 있다.
  • baron_guest, extended_leave, archived는 기본 제외한다.

6.2 직원 상세

GET /api/v1/tdc114plus/directory/employees/{employeeId}
Authorization: Bearer {token}

응답:

{
  "id": "user-uuid",
  "name": "홍길동",
  "phoneNumber": "+821012345678",
  "phoneDisplay": "010-1234-5678",
  "email": "user@example.com",
  "tenantId": "tenant-uuid",
  "tenantName": "한맥",
  "tenantSlug": "hanmac",
  "joinedTenants": [
    {
      "id": "tenant-uuid",
      "name": "한맥",
      "slug": "hanmac",
      "type": "COMPANY",
      "parentId": "parent-tenant-uuid"
    }
  ],
  "department": "기술연구소",
  "grade": "책임",
  "position": "팀장",
  "jobTitle": "개발",
  "status": "active",
  "profileImageUrl": null,
  "actions": {
    "call": true,
    "sms": true,
    "email": true
  }
}

7. 가족사 필터/조직도 API

7.1 가족사/조직 필터 목록

GET /api/v1/tdc114plus/organization/tenants
Authorization: Bearer {token}

응답:

{
  "items": [
    {
      "id": "tenant-uuid",
      "name": "한맥",
      "slug": "hanmac",
      "type": "COMPANY",
      "parentId": "hanmac-family-root",
      "memberCount": 120,
      "totalMemberCount": 350
    }
  ],
  "generatedAt": "2026-07-02T12:00:00Z"
}

7.2 조직도 snapshot

GET /api/v1/tdc114plus/organization/orgchart
Authorization: Bearer {token}

Query:

이름 필수 설명
tenantId N 특정 가족사/조직 하위만 조회
refresh N 서버 캐시 refresh 요청. 기본 false

응답:

{
  "tenants": [
    {
      "id": "tenant-uuid",
      "name": "기술연구소",
      "slug": "rnd",
      "type": "ORGANIZATION",
      "parentId": "company-tenant-uuid",
      "memberCount": 12,
      "totalMemberCount": 38
    }
  ],
  "employees": [
    {
      "id": "user-uuid",
      "name": "홍길동",
      "phoneNumber": "+821012345678",
      "phoneDisplay": "010-1234-5678",
      "tenantId": "tenant-uuid",
      "tenantName": "기술연구소",
      "tenantSlug": "rnd",
      "department": "기술연구소",
      "grade": "책임",
      "position": "팀장",
      "jobTitle": "개발",
      "status": "active"
    }
  ],
  "generatedAt": "2026-07-02T12:00:00Z",
  "cache": {
    "source": "redis",
    "hit": true,
    "ttlSeconds": 300
  }
}

구현 참고:

  • 기존 GET /api/v1/admin/orgchart/snapshot은 tenants, users, generatedAt, cache 구조를 가진다.
  • tdc114plus 응답은 앱 의미에 맞춰 users 대신 employees를 사용한다.
  • 기존 admin/orgFront API를 직접 변경하지 않고 별도 DTO에서 변환한다.

8. 즐겨찾기 API

1차 구현은 앱 로컬 저장을 기본으로 한다.

서버 동기화는 후속 단계에서 검토한다.

후속 후보:

GET /api/v1/tdc114plus/favorites
PUT /api/v1/tdc114plus/favorites

9. 오류 응답 공통 형식

Baron SSO API 설계 정책에 맞춰 신규 API는 code를 기본 포함한다.

{
  "error": "사람이 읽을 수 있는 메시지",
  "code": "machine_readable_code",
  "details": {}
}

공통 오류:

HTTP code 설명
400 invalid_request 요청 형식 오류
401 unauthorized 토큰 없음/만료
403 forbidden tdc114plus 사용 권한 없음
404 not_found 직원/조직 없음
429 rate_limited 과도한 요청
503 dependency_unavailable Kratos, Redis, DB 등 의존성 장애

10. 개인정보/보안 정책

  • 전화번호 원문은 로그에 남기지 않고 마스킹 또는 정규화 값 일부만 기록한다.
  • 직원 검색/상세 조회는 감사 로그 대상으로 둔다.
  • 대량 조회, 짧은 시간 내 반복 조회는 이상 조회 탐지 후보로 기록한다.
  • 1차 구현에서는 Baron SSO 등록 사용자에게 직원 검색/조직도 기본 필드를 노출한다.
  • 권한별 민감정보 마스킹은 후속 정책에서 확정한다.
  • 1차 앱에서는 call, sms 액션을 제공하되, 앱 내부에서 수신전화식별/수신팝업 기능은 구현하지 않는다.

11. Baron SSO 구현 후보

신규 패키지/파일 후보:

backend/internal/domain/tdc114plus_models.go
backend/internal/handler/tdc114plus_handler.go
backend/internal/service/tdc114plus_service.go
backend/internal/service/tdc114plus_service_test.go
backend/internal/handler/tdc114plus_handler_test.go

라우트 후보:

tdc114plus := api.Group("/tdc114plus")
tdc114plus.Post("/auth/phone-login", tdc114plusHandler.PhoneLogin)
tdc114plus.Get("/me", requireAnyUser, tdc114plusHandler.GetMe)
tdc114plus.Get("/directory/employees", requireAnyUser, tdc114plusHandler.ListEmployees)
tdc114plus.Get("/directory/employees/:id", requireAnyUser, tdc114plusHandler.GetEmployee)
tdc114plus.Get("/organization/tenants", requireAnyUser, tdc114plusHandler.ListTenants)
tdc114plus.Get("/organization/orgchart", requireAnyUser, tdc114plusHandler.GetOrgChart)

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차에서 앱 로컬 저장

운영 배포 전 재검토 항목:

  • SMS OTP, 기기 등록, 내부망 제한, 추가 인증 중 하나 이상 도입 여부
  • 앱 전용 access token 또는 refresh token 분리 여부
  • 권한별 개인정보 마스킹 범위
  • 즐겨찾기 서버 동기화 API 추가 여부
Reference in New Issue View Git Blame Copy Permalink