[Settings] 사업장 설정 조회·수정 API 구현

[hywznn]

한 줄 요약

사업장 운영 정책을 안전하게 조회·수정하고, 업무 담당자와 승인자를 선택할 때 사용할 같은 사업장 구성원 목록을 제공합니다.

화면 기준

• Figma [PWF] Prototype-WireFrame-3rd의 05_Desktop Core Product > SETTINGS
• Task 담당자·승인자 선택 컴포넌트
• 세부 요청·응답 필드는 Notion API 명세를 기준으로 합니다.

소유 API

• GET /api/v1/settings
• PATCH /api/v1/settings
• GET /api/v1/company-members

설정 범위

• 승인 정책
• 근로자 보안 링크 기본 만료시간
• 업무 유형별 완료 증빙 규칙
• 파일·AI 품질 로그 보유기간
• 감사로그 조회 범위
• 동시 수정을 막기 위한 version

법정 기한·필수 서류·승인 필요 여부와 개인정보 Guardrail은 knowledge 및 서버 보안 정책의 기준이며, 사업장 설정으로 완화할 수 없습니다.

구성원 조회 범위

GET /api/v1/company-members는 담당자·승인자 선택에 필요한 최소 정보만 반환합니다.

• userId, displayName, roles, 활성 여부
• 승인 권한 보유 여부
• 선택 필터: role, approvalCapable, activeOnly
• 이메일·비밀번호·Refresh Token 등 인증 정보는 반환하지 않음

권한 원칙

• ADMIN: 설정 조회·수정, 구성원 조회 가능
• HR: 업무에 필요한 설정과 구성원 조회 가능, 설정 수정은 허용 필드만 가능
• VIEWER: 화면 표시에 필요한 최소 설정과 구성원 표시명만 조회 가능
• Worker Link: 접근 불가

초보자용 구현 순서

1. 화면 설정을 사업장 공통 설정과 사용자 개인 설정으로 구분합니다.
2. CompanySettings 기본값과 허용 범위를 먼저 정합니다.
3. 허용 필드만 받는 PATCH DTO와 expectedVersion을 만듭니다.
4. companyId는 요청값이 아니라 JWT의 ActorContext에서 가져옵니다.
5. 구성원 조회는 UserAccount의 최소 표시 DTO만 반환합니다.
6. 정책 변경은 이전 값·새 값·actor·requestId를 감사로그에 남깁니다.
7. 기본값, 권한, 잘못된 범위, 동시 수정 충돌, 타 사업장 격리 테스트를 작성합니다.

보안·구현 규칙

• LLM API Key, JWT Secret, DB 비밀번호 같은 서버 Secret은 이 API로 조회·수정하지 않습니다.
• 클라이언트가 임의의 설정 키를 추가하지 못하도록 allow-list를 사용합니다.
• Worker Link 만료시간과 보유기간은 안전한 최소·최대 범위를 강제합니다.
• 설정 변경은 AI 결과 자동 승인이나 자동 외부 발송을 허용하지 않습니다.
• 구성원 조회는 반드시 같은 사업장으로 제한합니다.

완료 조건

• 사업장별 설정과 구성원 목록이 분리됩니다.
• 권한 없는 역할의 수정은 403입니다.
• 허용되지 않은 키와 범위 밖 값은 일관된 오류로 거부됩니다.
• 부분 수정 시 보내지 않은 값은 유지됩니다.
• 오래된 expectedVersion으로 수정하면 409를 반환합니다.
• 정책 변경 감사로그와 타 사업장 격리 테스트가 있습니다.
• Swagger에 설정·구성원 조회 예시와 역할별 권한을 문서화합니다.

이번 이슈에서 하지 않는 것

• Secret 관리 UI
• 사용자 초대·권한 변경·계정 삭제
• 개인별 모든 화면 환경설정
• 실제 SMS·메신저 발송 설정

선행/후속 관계

• 선행: [Foundation] Spring Boot 개발·검증 기반 정리 #3, [Auth & Security] JWT 인증·사업장 권한·멀티테넌시 구현 #4, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11
• 연결: [Worker Link] 로그인 없는 근로자 보안 링크와 응답 구현 #7, [Dashboard] 오늘 업무 대시보드 요약 API 구현 #15
• 상위 목표: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2