feat(api): 최소 인원 조건 API 구현

[ehlung]

개요

최소 인원 조건 관리 화면에서 사용할 staffing-rules API를 구현합니다.

Closes #78

---

변경 사항

• GET/POST/PATCH/DELETE /staffing-rules 라우트 추가
• 인증 사용자 조직 기준 최소 인원 조건 조회·생성·수정·삭제 구현
• ruleId 검증, 요청 body 검증, 조직 범위 접근 제한 적용

---

변경 유형

• feat — 새로운 기능
• fix — 버그 수정
• refactor — 리팩터링 (기능 변경 없음)
• test — 테스트 코드
• perf — 성능 개선
• docs — 문서 수정
• chore — 빌드·설정 변경

---

영향 범위

• web — apps/web
• api — apps/api
• db — packages/database
• shared — packages/shared
• repo — 루트 설정·CI/CD·문서

---

테스트 방법

1. pnpm format:check
2. pnpm --filter @fragment/shared build
3. pnpm --filter @fragment/database db:generate
4. pnpm --filter @fragment/database build
5. pnpm --filter @fragment/web lint
6. pnpm --filter @fragment/web typecheck
7. pnpm --filter @fragment/web test
8. pnpm --filter @fragment/api lint
9. pnpm --filter @fragment/api typecheck
10. pnpm --filter @fragment/api test

---

체크리스트

• CI (테스트 + 린트) 통과 확인
• 관련 테스트 코드 작성 또는 업데이트
• 상태 분류 규칙(서버/전역/로컬/폼 상태) 준수
• 에러 처리 및 Fallback UI 확인 (해당 시)
• Swagger 문서 업데이트 (API 변경 시)
• 공유 타입·스키마(packages/shared) 업데이트 (타입 변경 시)

---

스크린샷 / 영상

API 변경만 있어 없음

---

리뷰 포인트

• 수정/삭제 시 다른 조직의 최소 인원 조건에 접근할 수 없는지
• DB 시간 값과 API HH:mm 응답 변환이 적절한지
• docs/API.md와 기존 shared schema의 필드명 기준을 그대로 따르는지

[coderabbitai]

Warning

Review limit reached

@ehlung, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 56 minutes and 29 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 442761af-28a7-4945-b409-fb7b744c8261

📥 Commits

Reviewing files that changed from the base of the PR and between 631822e and 020c26c.

📒 Files selected for processing (15)

• .coderabbit.yaml
• .github/pull_request_template.md
• CLAUDE.md
• apps/api/CLAUDE.md
• apps/api/src/modules/organization/organization.service.ts
• apps/api/src/modules/staffing-rules/staffing-rules.service.spec.ts
• apps/api/src/modules/staffing-rules/staffing-rules.service.ts
• apps/api/src/utils/date-time.ts
• apps/api/test/helpers/fake-prisma.ts
• apps/api/test/staffing-rules.routes.test.ts
• apps/web/CLAUDE.md
• docs/API.md
• docs/ERD.md
• docs/SWAGGER.md
• docs/stack.md

Walkthrough

/staffing-rules 라우트가 추가되고, 인증된 사용자만 최소 인력 규칙을 조회·생성·수정·삭제하도록 핸들러와 Prisma 서비스가 연결됐다. 시간 값은 HH:mm 문자열과 UTC Date 사이에서 변환된다.

Changes

최소 인력 규칙 API

Layer / File(s)	Summary
라우트와 핸들러 배선 apps/api/src/routes/index.ts, apps/api/src/routes/staffing-rules.routes.ts, apps/api/src/modules/staffing-rules/staffing-rules.handlers.ts	/staffing-rules가 apiRoutes에 등록되고, 각 CRUD 엔드포인트가 인증과 입력 검증을 거친 뒤 대응하는 핸들러로 연결된다.
변환과 공용 조회 apps/api/src/modules/staffing-rules/staffing-rules.service.ts	HH:mm 시간 변환, 조직 ID 조회, 404 오류 생성, Prisma 레코드와 요청 입력을 오가게 하는 매핑 함수가 추가된다.
규칙 CRUD 서비스 apps/api/src/modules/staffing-rules/staffing-rules.service.ts	조직 범위의 규칙 목록 조회, 생성, 수정, 삭제가 Prisma로 구현되고, 규칙이나 조직이 없을 때 403/404 오류가 반환된다.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	핵심 API는 구현됐지만 docs/API.md와 shared 스키마 업데이트가 보이지 않아 링크된 이슈의 완료 조건이 부족합니다.	Swagger 문서(docs/API.md)와 shared schema를 실제 요청/응답 필드와 맞게 추가·정리하고, 누락된 타입 변경도 반영하세요.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	주요 변경인 staffing-rules API 구현을 짧고 명확하게 요약합니다.
Out of Scope Changes check	✅ Passed	변경은 모두 staffing-rules API 범위에 머물러 있으며 무관한 수정은 확인되지 않습니다.
Description check	✅ Passed	개요, 변경 사항, 변경 유형, 영향 범위, 테스트 방법, 체크리스트, 리뷰 포인트가 모두 갖춰져 있어 템플릿 요구사항을 대체로 충족합니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/78-staffing-rules-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/src/modules/staffing-rules/staffing-rules.service.ts`:
- Around line 17-26: The HH:mm ↔ Date conversion helpers are duplicated in
staffing-rules.service and organization.service, so extract the shared logic
into a common utility (for example a time helper under a shared utils path) and
reuse it from both places. Move the existing timeStringToDate and
dateToTimeString behavior into the shared module, then update
staffing-rules.service and organization.service to import the same helper
symbols instead of keeping local copies.
- Around line 69-77: `createMinimumStaffingRuleUpdateData` in
`staffing-rules.service.ts` allows partial PATCH updates to change `endsNextDay`
without rechecking the existing `startTime`/`endTime` range, so invalid time
combinations can be persisted. Fix this by having the update flow load the
current rule values, merge them with the incoming
`UpdateMinimumStaffingRuleRequest`, and run the same staffing-rule time-range
validation before saving; alternatively, update
`addMinimumStaffingRuleTimeRangeIssues` to validate in partial-update contexts
using existing values. Make sure the `endsNextDay`-only path is covered so
`startTime < endTime` cannot be stored with `endsNextDay = true`.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b69b7fef-bfb7-4a89-9292-2db5038180d3

📥 Commits

Reviewing files that changed from the base of the PR and between 80565cc and 631822e.

📒 Files selected for processing (4)

• apps/api/src/modules/staffing-rules/staffing-rules.handlers.ts
• apps/api/src/modules/staffing-rules/staffing-rules.service.ts
• apps/api/src/routes/index.ts
• apps/api/src/routes/staffing-rules.routes.ts

[ehlung]

CodeRabbit 리뷰 반영 사항입니다.

• PATCH에서 endsNextDay만 수정할 때 기존 startTime/endTime과 합친 최종 시간 범위가 검증되지 않을 수 있던 문제를 수정했습니다.
  • 기존 rule 값을 조회한 뒤 요청 값과 병합해 최종 상태 기준으로 시간 범위를 재검증하도록 변경했습니다.
• HH:mm 문자열과 DB Time Date 변환 로직이 organization/staffing-rules service에 중복되어 있던 부분을 공통 유틸로 정리했습니다.
  • apps/api/src/utils/date-time.ts에서 재사용하도록 변경했습니다.
• endsNextDay 단독 수정 회귀 케이스를 service 단위 테스트로 추가했습니다.
  • 잘못된 최종 시간 범위에서는 update가 실행되지 않도록 검증합니다.

[ehlung]

추가 반영 사항입니다.

• 테스트 작성 기준을 문서에 정리했습니다.
  • API service는 권한, DB 접근 조건, 비즈니스 규칙 중심으로 테스트합니다.
  • API route는 인증, 요청 검증, 성공 흐름 중 대표 케이스만 테스트합니다.
  • Web은 typecheck/lint를 우선하고, 복잡한 유틸 또는 hook 추가 시 테스트합니다.
• 현재 프로젝트 구조에 맞게 문서 기준을 정리했습니다.
  • API 구조를 routes/modules/middlewares/errors/common 기준으로 맞췄습니다.
  • API 명세는 docs/API.md 우선, docs/openapi.yaml은 포함된 endpoint 변경 시 갱신하는 기준으로 정리했습니다.
  • PATCH /staffing-rules/:ruleId의 부분 수정 request 예시를 보강했습니다.
• 최소 인원 조건 API 테스트를 보강했습니다.
  • service 테스트: 조직 없음, 조직 범위 조회, 시간 매핑, 생성 data 변환, 다른 조직 수정/삭제 차단, PATCH 시간 재검증
  • route 테스트: 미인증 401, 잘못된 생성 요청 400, 조회 성공 200
• develop 최신 변경사항을 병합해 PR 브랜치를 최신화했습니다.

검증 완료:

• pnpm format:check
• pnpm --filter @fragment/shared build
• pnpm --filter @fragment/database db:generate
• pnpm --filter @fragment/database build
• pnpm --filter @fragment/web lint
• pnpm --filter @fragment/web typecheck
• pnpm --filter @fragment/web test
• pnpm --filter @fragment/api lint
• pnpm --filter @fragment/api typecheck
• pnpm --filter @fragment/api test