SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c637dd38ebd65cb2d80e98ab10bd2f4935282ac2
sam-api/app/Swagger/v1/DepartmentApi.php
hskwon a27b1b2091 feat: Phase 5.1-1 사용자 초대 + Phase 5.2 알림 설정 API 연동 
- 사용자 초대 API: role 문자열 지원 추가 (React 호환)
- 알림 설정 API: 그룹 기반 계층 구조 구현
  - notification_setting_groups 테이블 추가
  - notification_setting_group_items 테이블 추가
  - notification_setting_group_states 테이블 추가
  - GET/PUT /api/v1/settings/notifications 엔드포인트 추가
- Pint 코드 스타일 정리
2025-12-22 17:42:59 +09:00

559 lines
23 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(
* name="Department",
* description="부서 관리(목록/조회/등록/수정/삭제) + 부서원 관리 + 부서 권한 매핑"
* )
*/
/**
* =========================
* Domain 스키마
* =========================
*/
/**
* @OA\Schema(
* schema="Department",
* type="object",
* description="부서 상세",
* required={"id","name"},
*
* @OA\Property(property="id", type="integer", example=7),
* @OA\Property(property="tenant_id", type="integer", example=1),
* @OA\Property(property="code", type="string", nullable=true, example="OPS"),
* @OA\Property(property="name", type="string", example="운영팀"),
* @OA\Property(property="description", type="string", nullable=true, example="서비스 운영 총괄"),
* @OA\Property(property="is_active", type="integer", example=1),
* @OA\Property(property="sort_order", type="integer", example=10),
* @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-16 10:00:00"),
* @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-16 10:00:00")
* )
*
* @OA\Schema(
* schema="DepartmentBrief",
* type="object",
* description="부서 요약",
* required={"id","name"},
*
* @OA\Property(property="id", type="integer", example=7),
* @OA\Property(property="code", type="string", nullable=true, example="OPS"),
* @OA\Property(property="name", type="string", example="운영팀"),
* @OA\Property(property="is_active", type="integer", example=1),
* @OA\Property(property="sort_order", type="integer", example=10)
* )
*
* @OA\Schema(
* schema="DepartmentList",
* type="array",
*
* @OA\Items(ref="#/components/schemas/DepartmentBrief")
* )
*
* @OA\Schema(
* schema="DepartmentCreateRequest",
* type="object",
* required={"name"},
*
* @OA\Property(property="code", type="string", nullable=true, example="OPS"),
* @OA\Property(property="name", type="string", example="운영팀"),
* @OA\Property(property="description", type="string", nullable=true, example="서비스 운영 총괄"),
* @OA\Property(property="is_active", type="integer", enum={0,1}, example=1),
* @OA\Property(property="sort_order", type="integer", example=0)
* )
*
* @OA\Schema(
* schema="DepartmentUpdateRequest",
* type="object",
*
* @OA\Property(property="code", type="string", nullable=true, example="OPS2"),
* @OA\Property(property="name", type="string", example="운영기획팀"),
* @OA\Property(property="description", type="string", nullable=true, example="운영 기획/성과 관리"),
* @OA\Property(property="is_active", type="integer", enum={0,1}, example=1),
* @OA\Property(property="sort_order", type="integer", example=5)
* )
*
* @OA\Schema(
* schema="DepartmentUserAttachRequest",
* type="object",
* required={"user_id"},
*
* @OA\Property(property="user_id", type="integer", example=12),
* @OA\Property(property="is_primary", type="integer", enum={0,1}, nullable=true, example=0),
* @OA\Property(property="joined_at", type="string", format="date-time", nullable=true, example="2025-08-21 10:00:00")
* )
*
* @OA\Schema(
* schema="UserBrief",
* type="object",
* description="부서원 요약",
* required={"id","name","email"},
*
* @OA\Property(property="id", type="integer", example=12),
* @OA\Property(property="name", type="string", example="홍길동"),
* @OA\Property(property="email", type="string", format="email", example="hong@example.com"),
* @OA\Property(property="phone", type="string", nullable=true, example="010-1234-5678"),
* @OA\Property(property="is_active", type="integer", example=1)
* )
*
* @OA\Schema(
* schema="DepartmentPermissionUpsertSingle",
* type="object",
* required={"permission_id"},
*
* @OA\Property(property="permission_id", type="integer", example=25),
* @OA\Property(property="is_allowed", type="integer", enum={0,1}, example=1, description="1=ALLOW, 0=DENY(차단)")
* )
*
* @OA\Schema(
* schema="DepartmentPermissionUpsertMany",
* type="object",
* required={"items"},
*
* @OA\Property(
* property="items",
* type="array",
*
* @OA\Items(ref="#/components/schemas/DepartmentPermissionUpsertSingle")
* )
* )
*
* @OA\Schema(
* schema="DepartmentPermissionRevokeSingle",
* type="object",
* required={"permission_id"},
*
* @OA\Property(property="permission_id", type="integer", example=25)
* )
*
* @OA\Schema(
* schema="DepartmentPermissionRevokeMany",
* type="object",
* required={"items"},
*
* @OA\Property(
* property="items",
* type="array",
*
* @OA\Items(ref="#/components/schemas/DepartmentPermissionRevokeSingle")
* )
* )
*/
class DepartmentApi
{
/**
* @OA\Get(
* path="/api/v1/departments",
* summary="부서 목록 조회",
* description="테넌트 범위 내 부서 목록을 페이징으로 반환합니다. (q로 이름/코드 검색)",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
* @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=10)),
* @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string", example="운영")),
* @OA\Parameter(name="is_active", in="query", required=false, @OA\Schema(type="integer", enum={0,1}, example=1)),
*
* @OA\Response(response=200, description="부서 목록 조회 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 목록 조회 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="per_page", type="integer", example=10),
* @OA\Property(property="total", type="integer", example=2),
* @OA\Property(property="data", ref="#/components/schemas/DepartmentList")
* )
* )
* ),
*
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function index() {}
/**
* @OA\Get(
* path="/api/v1/departments/tree",
* summary="부서 트리 조회",
* description="부서를 계층 구조(트리)로 조회합니다. with_users=1 시 각 부서의 소속 사용자도 포함됩니다.",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="with_users", in="query", required=false, description="사용자 포함 여부", @OA\Schema(type="integer", enum={0,1}, example=0)),
*
* @OA\Response(response=200, description="부서 트리 조회 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 트리 조회"),
* @OA\Property(property="data", type="array",
*
* @OA\Items(
* type="object",
*
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="name", type="string", example="본사"),
* @OA\Property(property="code", type="string", nullable=true, example="HQ"),
* @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
* @OA\Property(property="sort_order", type="integer", example=1),
* @OA\Property(property="is_active", type="integer", example=1),
* @OA\Property(property="children", type="array", @OA\Items(ref="#/components/schemas/DepartmentBrief")),
* @OA\Property(property="users", type="array", nullable=true, @OA\Items(ref="#/components/schemas/UserBrief"))
* )
* )
* )
* )
* )
*/
public function tree() {}
/**
* @OA\Get(
* path="/api/v1/departments/{id}",
* summary="부서 단건 조회",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
*
* @OA\Response(response=200, description="부서 조회 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 조회 성공"),
* @OA\Property(property="data", ref="#/components/schemas/Department")
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function show() {}
/**
* @OA\Post(
* path="/api/v1/departments",
* summary="부서 생성",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentCreateRequest")),
*
* @OA\Response(response=200, description="부서 생성 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 생성 성공"),
* @OA\Property(property="data", ref="#/components/schemas/Department")
* )
* ),
*
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function store() {}
/**
* @OA\Patch(
* path="/api/v1/departments/{id}",
* summary="부서 수정",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
*
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentUpdateRequest")),
*
* @OA\Response(response=200, description="부서 수정 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 수정 성공"),
* @OA\Property(property="data", ref="#/components/schemas/Department")
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function update() {}
/**
* @OA\Delete(
* path="/api/v1/departments/{id}",
* summary="부서 삭제(소프트)",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
*
* @OA\Response(response=200, description="부서 삭제 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 삭제 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="id", type="integer", example=7),
* @OA\Property(property="deleted_at", type="string", format="date-time", example="2025-08-21 11:00:00")
* )
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function destroy() {}
/**
* @OA\Get(
* path="/api/v1/departments/{id}/users",
* summary="부서 사용자 목록",
* description="해당 부서에 속한 사용자 목록을 페이징으로 반환합니다.",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
* @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
* @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=20)),
*
* @OA\Response(response=200, description="부서 사용자 목록 조회 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 사용자 목록 조회 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="per_page", type="integer", example=20),
* @OA\Property(property="total", type="integer", example=1),
* @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/UserBrief"))
* )
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function users() {}
/**
* @OA\Post(
* path="/api/v1/departments/{id}/users",
* summary="부서 사용자 배정(단건)",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
*
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/DepartmentUserAttachRequest")),
*
* @OA\Response(response=200, description="부서 사용자 배정 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 사용자 배정 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="department_id", type="integer", example=7),
* @OA\Property(property="user_id", type="integer", example=12)
* )
* )
* ),
*
* @OA\Response(response=409, description="이미 배정됨", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function attachUser() {}
/**
* @OA\Delete(
* path="/api/v1/departments/{id}/users/{user}",
* summary="부서 사용자 해제(단건)",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
* @OA\Parameter(name="user", in="path", required=true, @OA\Schema(type="integer", example=12)),
*
* @OA\Response(response=200, description="부서 사용자 해제 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 사용자 해제 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="user_id", type="integer", example=12),
* @OA\Property(property="deleted_at", type="string", format="date-time", example="2025-08-21 11:00:00")
* )
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function detachUser() {}
/**
* @OA\Patch(
* path="/api/v1/departments/{id}/users/{user}/primary",
* summary="주부서 설정/해제",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
* @OA\Parameter(name="user", in="path", required=true, @OA\Schema(type="integer", example=12)),
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(
*
* @OA\Property(property="is_primary", type="integer", enum={0,1}, example=1)
* )
* ),
*
* @OA\Response(response=200, description="주부서 설정 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="주부서 설정 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="user_id", type="integer", example=12),
* @OA\Property(property="department_id", type="integer", example=7),
* @OA\Property(property="is_primary", type="integer", example=1)
* )
* )
* ),
*
* @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function setPrimary() {}
/**
* @OA\Get(
* path="/api/v1/departments/{id}/permissions",
* summary="부서 권한 목록",
* description="부서에 설정된 ALLOW/DENY 목록을 조회합니다. (is_allowed=1|0, menu_id 필터 지원)",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
* @OA\Parameter(name="menu_id", in="query", required=false, @OA\Schema(type="integer", example=101)),
* @OA\Parameter(name="is_allowed", in="query", required=false, @OA\Schema(type="integer", enum={0,1}, example=1)),
* @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
* @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", example=20)),
*
* @OA\Response(response=200, description="부서 권한 목록 조회 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 권한 목록 조회 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="current_page", type="integer", example=1),
* @OA\Property(property="per_page", type="integer", example=20),
* @OA\Property(property="total", type="integer", example=3),
* @OA\Property(property="data", type="array",
*
* @OA\Items(type="object",
*
* @OA\Property(property="permission_id", type="integer", example=25),
* @OA\Property(property="permission_code", type="string", example="menu.101.read"),
* @OA\Property(property="is_allowed", type="integer", example=1),
* @OA\Property(property="reason", type="string", nullable=true, example="보안 이슈"),
* @OA\Property(property="effective_from", type="string", format="date-time", nullable=true),
* @OA\Property(property="effective_to", type="string", format="date-time", nullable=true)
* )
* )
* )
* )
* ),
*
* @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function listPermissions() {}
/**
* @OA\Post(
* path="/api/v1/departments/{id}/permissions",
* summary="부서 권한 부여/차단(Upsert: 단건/배치)",
* description="permission_id 기준으로 ALLOW(1) 또는 DENY(0) 처리합니다. 단건 또는 items 배열을 모두 지원합니다.",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=7)),
*
* @OA\RequestBody(
* required=true,
*
* @OA\JsonContent(oneOf={
*
* @OA\Schema(ref="#/components/schemas/DepartmentPermissionUpsertSingle"),
* @OA\Schema(ref="#/components/schemas/DepartmentPermissionUpsertMany")
* })
* ),
*
* @OA\Response(response=200, description="부서 권한 적용 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 권한 적용 성공"),
* @OA\Property(property="data", type="object",
* @OA\Property(property="processed", type="integer", example=2),
* @OA\Property(property="succeeded", type="integer", example=2),
* @OA\Property(property="failed", type="array", @OA\Items(type="object"))
* )
* )
* ),
*
* @OA\Response(response=404, description="부서 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function upsertPermission() {}
/**
* @OA\Delete(
* path="/api/v1/departments/{id}/permissions/{permission}",
* summary="부서 권한 해제",
* description="지정 권한을 부서 매핑에서 제거합니다.",
* tags={"Department"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, description="부서 ID", @OA\Schema(type="integer", example=7)),
* @OA\Parameter(name="permission", in="path", required=true, description="권한 ID", @OA\Schema(type="integer", example=15)),
*
* @OA\Response(response=200, description="부서 권한 해제 성공",
*
* @OA\JsonContent(
*
* @OA\Property(property="success", type="boolean", example=true),
* @OA\Property(property="message", type="string", example="부서 권한 제거")
* )
* ),
*
* @OA\Response(response=404, description="부서 또는 권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function revokePermission() {}
}
Reference in New Issue View Git Blame Copy Permalink