Repository navigation
[Settings] 사업장 설정 조회·수정 API 구현 #16
Description
한 줄 요약
사업장 운영 정책을 안전하게 조회·수정하고, 업무 담당자와 승인자를 선택할 때 사용할 같은 사업장 구성원 목록을 제공합니다.
화면 기준
- 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: 접근 불가
초보자용 구현 순서
- 화면 설정을 사업장 공통 설정과 사용자 개인 설정으로 구분합니다.
CompanySettings기본값과 허용 범위를 먼저 정합니다.- 허용 필드만 받는 PATCH DTO와
expectedVersion을 만듭니다. companyId는 요청값이 아니라 JWT의ActorContext에서 가져옵니다.- 구성원 조회는
UserAccount의 최소 표시 DTO만 반환합니다. - 정책 변경은 이전 값·새 값·actor·requestId를 감사로그에 남깁니다.
- 기본값, 권한, 잘못된 범위, 동시 수정 충돌, 타 사업장 격리 테스트를 작성합니다.
보안·구현 규칙
- LLM API Key, JWT Secret, DB 비밀번호 같은 서버 Secret은 이 API로 조회·수정하지 않습니다.
- 클라이언트가 임의의 설정 키를 추가하지 못하도록 allow-list를 사용합니다.
- Worker Link 만료시간과 보유기간은 안전한 최소·최대 범위를 강제합니다.
- 설정 변경은 AI 결과 자동 승인이나 자동 외부 발송을 허용하지 않습니다.
- 구성원 조회는 반드시 같은 사업장으로 제한합니다.
완료 조건
- 사업장별 설정과 구성원 목록이 분리됩니다.
- 권한 없는 역할의 수정은 403입니다.
- 허용되지 않은 키와 범위 밖 값은 일관된 오류로 거부됩니다.
- 부분 수정 시 보내지 않은 값은 유지됩니다.
- 오래된
expectedVersion으로 수정하면 409를 반환합니다. - 정책 변경 감사로그와 타 사업장 격리 테스트가 있습니다.
- Swagger에 설정·구성원 조회 예시와 역할별 권한을 문서화합니다.
이번 이슈에서 하지 않는 것
- Secret 관리 UI
- 사용자 초대·권한 변경·계정 삭제
- 개인별 모든 화면 환경설정
- 실제 SMS·메신저 발송 설정
Activity