ID: key_26_22_05_25_P1_1_4 Created date: 5월 25 2026 월요일
연관 문서
개요
이슈 상태 전이 규칙을 검증하고 적용하는 워크플로우 엔진을 구현한다.
issue_transitions 테이블 기반으로 허용된 전이만 가능하도록 제한한다.
- 예상 소요: 2~3일
- 선행 조건: 1-3_서버-이슈-CRUD-API 완료
- 완료 기준: 허용되지 않은 상태 전이 시 400 에러 반환 확인
기본 상태 전이 규칙
To Do → In Progress → In Review → Done
To Do → Done (허용)
In Progress → To Do (허용 — 되돌리기)
In Review → In Progress (허용 — 재작업)
Done → (전이 불가 — Closed 이슈)
Claude Code 작업 수행서
목표
이슈 상태 변경 API를 구현하고, issue_transitions 테이블에 정의된 규칙에 따라 전이를 검증한다.
작업 지시
CIRA 서버에 워크플로우 상태 전이 API를 구현해줘.
[프로젝트 경로]
- C:\workspace\tsh\boilerplate\be\befw-app-server
[수행 작업]
1. 상태 전이 API 구현
PUT /api/v1/issues/{issueId}/status
Request: { "statusId": "uuid" }
Response: IssueResponse (변경 후 전체 이슈 정보)
2. 전이 검증 로직
WorkflowService.validateTransition(projectId, fromStatusId, toStatusId):
- issue_transitions 테이블에서 해당 프로젝트의 전이 규칙 조회
- 허용되지 않은 전이: CiraException(ErrorCode.ISSUE_INVALID_TRANSITION)
- 조회 결과 캐싱 고려 (동일 프로젝트 내 반복 조회 최적화)
3. 상태 변경 처리 흐름
a. 이슈 존재 확인 + 권한 확인
b. 현재 상태 조회
c. 전이 규칙 검증
d. issues.status_id 업데이트
e. issue_logs에 상태 변경 기록
(field_name: "status", old_value: 이전 상태명, new_value: 새 상태명)
f. issue_positions의 column_id 업데이트 (board_columns와 status 연결)
4. 초기 전이 규칙 데이터 마이그레이션
V130__init_workflow_transitions.sql:
- 각 프로젝트 기본 워크플로우는 프로젝트 생성 시 자동 삽입
- ProjectService.createProject() 에서 기본 상태 4개 + 전이 규칙 삽입
5. 전이 가능 상태 조회 API
GET /api/v1/issues/{issueId}/available-transitions
Response: List<IssueStatusResponse> (현재 상태에서 전이 가능한 상태 목록)
→ UI에서 상태 변경 드롭다운에 활용
6. 단위 테스트
- 허용된 전이: 성공
- 허용되지 않은 전이: ISSUE_INVALID_TRANSITION 에러
- 존재하지 않는 상태 ID: ISSUE_STATUS_NOT_FOUND 에러
[준수 사항]
- 프로젝트별 워크플로우 커스터마이징 가능한 구조로 설계
(미래에 관리자가 전이 규칙을 추가/삭제할 수 있어야 함)
- WorkflowService는 독립 서비스로 분리하여 재사용 가능하도록
완료 기준
| 항목 | 기준 |
|---|---|
| 상태 전이 API | 허용 전이 성공, 비허용 400 반환 |
| issue_logs | 상태 변경 이력 기록 |
| issue_positions | board_columns 연동 업데이트 |
| 전이 가능 상태 API | 현재 상태 기준 목록 반환 |
| 단위 테스트 | 전체 통과 |
후행 작업
- 2-1_칸반-보드-API — board_columns 연동 확장