[Settings] 회사 설정 조회·수정 및 사업장 구성원 조회 API 구현`

[krestar]

왜 필요한가요?

사업장별 운영 정책을 조회·수정하고, 같은 사업장의 구성원을 역할·활성 상태·승인 가능 여부로 조회할 수 있는 Server 계약이 필요합니다.

기존에는 Worker Link 만료시간, 승인·반려 권한, 업무 완료 증빙, 감사 조회 범위를 회사 단위 설정으로 관리하거나 일관되게 소비할 수 없었습니다. 또한 구성원 선택 UI가 사용할 tenant-safe 조회 API가 없었습니다.

• Closes [Settings] 사업장 설정 조회·수정 API 구현 #16

무엇이 바뀌나요?

• API·도메인·DB 변경:
  • GET /api/v1/settings 회사 설정 조회 API를 추가했습니다.
  • PATCH /api/v1/settings ADMIN 전용 부분 수정 API를 추가했습니다.
  • PATCH에서 omitted field와 explicit null을 구분하고, expected_version 기반 낙관적 잠금을 적용했습니다.
  • GET /api/v1/company-members 사업장 구성원 조회 API와 role, approval_capable, active_only query를 추가했습니다.
  • 단일 UserAccount.role을 응답의 singleton roles로 매핑하고 active와 approval_permission을 파생 값으로 제공합니다.
  • company_settings 테이블, 기존 회사 기본 설정 backfill, PostgreSQL RLS 준비 migration(V35·V36)을 추가했습니다.
  • 신규 회사와 Demo Seed 회사 생성 시 기본 설정 row를 같은 transaction에서 생성합니다.
• 권한·Workflow 변경:
  • 설정 조회는 ADMIN·HR·VIEWER, 설정 수정은 ADMIN만 허용합니다.
  • VIEWER의 구성원 응답은 user_id, display_name만 제공하며 제한 query 사용을 거부합니다.
  • approval_policy를 승인·반려 권한에 적용했습니다.
  • evidence_rules를 기존 업무 완료 증빙 baseline에 추가되는 회사 규칙으로 적용했습니다.
  • audit_visibility를 회사 전체 Audit 검색 권한에 적용했습니다.
  • 설정 변경 필드별 before/after compact diff를 Audit Event로 기록합니다.
• AI·외부 연동 변경:
  • link_expiry_hours를 Worker Link 기본 만료시간으로 적용하며 요청의 expires_in_hours가 있으면 요청값을 우선합니다.
  • 기존 발급 링크에는 설정 변경을 소급 적용하지 않습니다.
  • ai_log_retention_days는 ai_attempt 상세 데이터 보유 계약만 저장하며 이번 PR에서 삭제 job이나 Provider 연동은 추가하지 않습니다.
  • file_retention_days도 이번 PR에서는 설정 계약과 영속화만 제공하며 파일 삭제 job은 추가하지 않습니다.
• 문서·배포 변경:
  • 설정 조회·수정과 구성원 조회의 Swagger/OpenAPI schema, 권한 설명, 오류 응답, 실제 요청·응답 예시를 추가했습니다.
  • Notion의 관련 API 계약 3개를 frozen 후보 기준으로 갱신했습니다.
  • 새 환경변수는 없습니다.

어떻게 검증했나요?

• ./gradlew clean test
• ./gradlew build
• /health와 Swagger UI 확인
• 정상 요청
• 잘못된 입력
• 권한 부족
• 다른 사업장 접근 차단
• 필요한 상태 전이·Idempotency

검증 결과:

• ./gradlew clean test: 성공
• 설정·구성원 API security integration test와 OpenAPI contract test: 성공
• PATCH omitted/explicit null, unknown field, 범위, no-op, stale/concurrent version을 검증했습니다.
• ADMIN·HR·VIEWER 권한과 다른 사업장 데이터 비노출을 검증했습니다.
• PostgreSQL RLS 전용 테스트는 관련 환경변수가 없는 실행에서는 조건부 skip되며, 별도 PostgreSQL test fixture에서 실행할 수 있습니다.
• Demo Seed 기동 중 발견된 DemoCaseSeeder의 PostgreSQL Instant 바인딩 문제는 Issue [Settings] 사업장 설정 조회·수정 API 구현 #16 변경과 무관하며, 별도 브랜치 fix/94-demo-seed-golden-flow의 7665c2a에서 수정되어 있습니다. 해당 수정의 main 병합 후 Demo Seed smoke를 다시 수행합니다.

보안·개인정보

• DTO·로그·AI 입력에 불필요한 개인정보가 없습니다.
• JWT, Worker Link 원본 토큰, API Key, 비밀번호가 없습니다.
• 모든 사업장 데이터 접근에 company_id 범위를 검사합니다.
• AI 결과가 자동 승인·발송되지 않습니다.
• 중요한 변경이 AuditLog와 request_id로 추적됩니다.
• 관련 Accepted ADR을 지켰거나 필요한 새 ADR을 이 PR에서 Proposed로 작성했습니다.
• Server에 Prompt Builder·Provider SDK·모델 routing을 추가하지 않았습니다.

구성원 응답에는 이메일·계정 상태 원문·비밀번호·토큰을 포함하지 않습니다.
active는 AccountStatus에서, approval_permission은 role·active 상태·회사 승인 정책에서 계산합니다.
Repository query와 PostgreSQL RLS가 모두 tenant 경계를 적용합니다.

API·DB·운영 영향

• Swagger/OpenAPI와 Notion 계약을 갱신했습니다.
• Client에 알려야 할 호환성 변경을 적었습니다.
• DB 변경에 Flyway migration이 있습니다.
• migration 번호와 소유 Issue를 확인했고 다른 기능의 테이블을 미리 만들지 않았습니다.
• 환경변수는 이름만 .env.example에 적었습니다.
• 배포 후 Smoke Test와 롤백 방법을 적었습니다.

Client 전달 사항:

• 외부 JSON과 query 이름은 snake_case입니다.
• 구성원 조회 query는 approval_capable, 상세 응답 필드는 approval_permission입니다.
• roles는 현재 단일 role의 singleton 배열입니다.
• VIEWER에게는 구성원 최소 projection만 반환됩니다.
• PATCH는 ADMIN만 사용할 수 있고 항상 expected_version이 필요합니다.
• 설정 변경 충돌 시 최신 설정을 다시 조회한 후 재시도해야 합니다.

배포 후 Smoke Test:

1. GET /health가 200 OK인지 확인합니다.
2. ADMIN으로 로그인해 설정 GET·PATCH와 구성원 조회를 확인합니다.
3. HR·VIEWER의 설정 GET 성공과 PATCH 403을 확인합니다.
4. VIEWER 구성원 최소 projection과 제한 query 403을 확인합니다.
5. Test Company 계정으로 조회해 Demo Company 구성원이 노출되지 않는지 확인합니다.
6. 설정 변경 후 SETTINGS_UPDATED Audit Event와 request ID를 확인합니다.

롤백:

• 애플리케이션은 이전 버전으로 되돌릴 수 있으며, 추가된 company_settings 테이블은 이전 버전이 참조하지 않아 그대로 두어도 됩니다.
• Flyway migration은 자동 downgrade하지 않습니다.
• DB 구조 제거가 반드시 필요하면 백업과 별도 승인된 forward migration으로 처리합니다.

화면 또는 응답 예시

개인정보를 제거한 예시입니다.

{
  "approval_policy": "ADMIN_OR_HR",
  "link_expiry_hours": 72,
  "evidence_rules": {},
  "file_retention_days": 365,
  "ai_log_retention_days": 90,
  "audit_visibility": "ADMIN_ONLY",
  "version": 0
}

{
  "expected_version": 0,
  "link_expiry_hours": 48,
  "audit_visibility": "ADMIN_AND_HR"
}

{
  "items": [
    {
      "user_id": "7e2722bb-3c72-4aa0-b37c-28931c4f8e53",
      "display_name": "구성원 예시",
      "roles": ["HR"],
      "active": true,
      "approval_permission": true
    }
  ]
}

---

주의점

• Demo 시드 fix가 fix(seed): 응웬반A Golden Flow 시작 상태와 PostgreSQL 호환성 보강 #111 에서 구현되어, Demo 시드 환경에서의 검증은 하지 못했습니다.
• Swagger 상에서는 HR 가입 구현이 안되어 있는걸로 파악되어, HR 계정으로 회사 설정 조회가 가능한지 검증은 fix(seed): 응웬반A Golden Flow 시작 상태와 PostgreSQL 호환성 보강 #111 이 Merge된 후 추가 검증이 필요합니다.
• [Settings] 사업장 설정 조회·수정 API 구현 #16 에 명시된 HR: 설정 수정은 허용 필드만 가능 의 합의가 이루어지지 않아서 현재 설정 수정은 Admin Only로 구현된 상태입니다.

[hywznn]

ㅇㅣㅅㅏㅇㅇㅓㅂㅅㅅㅡㅂㄴㅣㄷㅏ ㅇㅣㅓㄱ ㅋㅣㅂㅗㄷㅡㄱㅏ ㅇㅣㄹㄷㅏㄴ ㅇㅣㅅㅏㅇㅎㅐㅅㅓ ㅇㅣㄹㅓㅎㄱㅔ ㅂㅗㄴㅐㄷㅗ ㄷㅗㅣㄹㄲㅏㅇㅛ