CLIN

API開発シリーズ②CLIN開発日記 #015｜Job Workflow API完成。清掃品質をつなぐステータス管理基盤

2026年7月24日

清掃作業の「今」を管理するAPIを実装しました

清掃業務プラットフォーム「CLIN」の開発では、予約情報や清掃予定を登録するだけではなく、現場の作業が現在どの段階にあるのかを正確に把握できる仕組みが必要です。

今回のSprint6では、清掃作業の進行状態を更新するJob Workflow APIを実装しました。

これにより、スタッフが現場へ移動している段階から、清掃、写真撮影、AI解析、管理者レビュー、修正対応、作業完了までを、一連のワークフローとして管理できる基盤が整いました。

今回実装したAPI

今回追加したエンドポイントは、次のAPIです。

PATCH /api/jobs/:id/status

リクエスト例：

{
  "status": "cleaning"
}

このAPIを利用することで、指定した清掃作業のステータスを更新できます。

更新後は、物件情報、部屋情報、担当スタッフ情報を含む最新のJobデータを返します。

CLINの清掃ワークフロー

CLINでは、清掃作業を単純な「未開始・作業中・完了」だけでは管理しません。

今回、以下の8段階を正式なJob Statusとして定義しました。

not_started
未開始

moving
現場へ移動中

cleaning
清掃中

shooting
完了写真を撮影中

ai_review
AIによる写真解析中

review_waiting
管理者レビュー待ち

repairing
修正対応中

completed
作業完了

清掃後の写真確認や修正対応まで含めて管理することで、清掃品質を継続的に維持できる設計になっています。

なぜ細かなステータスが必要なのか

一般的な作業管理システムでは、作業状態が次の3段階程度で管理されることがあります。

未開始
↓
作業中
↓
完了

しかし、実際の清掃現場では、作業が終わっただけで業務完了とは限りません。

清掃後には、次のような工程があります。

  • 完了写真の撮影
  • 写真のアップロード
  • AIによる品質確認
  • 管理者によるレビュー
  • 不備があった場合の修正依頼
  • 修正後の再確認

CLINでは、これらの工程をワークフローとして管理します。

これにより、管理者は「清掃が終わったか」だけでなく、「現在どの工程で止まっているのか」まで把握できるようになります。

DTOとバリデーションを導入

今回の開発から、APIリクエストを安全に受け取るためにDTOを導入しました。

NestJSのclass-validatorとclass-transformerを使用し、許可されていないステータスが送信された場合は、HTTP 400を返します。

例えば、次のような未定義のステータスは登録できません。

{
  "status": "abc"
}

エラー例：

{
  "message": [
    "status must be one of: not_started, moving, cleaning, shooting, ai_review, review_waiting, repairing, completed"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

余分なリクエスト項目も拒否

CLIN APIでは、DTOに定義されていない余分な項目も受け付けない設定にしました。

例えば、次のリクエストはエラーになります。

{
  "status": "cleaning",
  "admin": true
}

レスポンス：

{
  "message": [
    "property admin should not exist"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

意図しないデータや不正なパラメータをAPIへ送信できないようにすることで、安全性と保守性を高めています。

存在しないJobや不正IDにも対応

今回のAPIでは、次のエラー処理も確認しました。

存在しないJob ID

PATCH /api/jobs/999/status
{
  "message": "Cleaning job with ID 999 was not found",
  "error": "Not Found",
  "statusCode": 404
}

数値ではないJob ID

PATCH /api/jobs/abc/status
{
  "message": "Validation failed (numeric string is expected)",
  "error": "Bad Request",
  "statusCode": 400
}

今回行った動作確認

Sprint6では、以下を確認しました。

正常なステータス更新
データベースへの反映
未定義ステータスの拒否
存在しないJobの404
不正なJob IDの400
余分なパラメータの拒否
NestJS Build
APIコンテナ再起動
Git Commit

テストで変更したデータは、確認後に元の状態へ戻しています。

今回追加した主なファイル

backend/src/jobs/job-status.enum.ts
backend/src/jobs/dto/update-job-status.dto.ts

既存ファイルでは、次の箇所を更新しました。

backend/src/main.ts
backend/src/jobs/jobs.controller.ts
backend/src/jobs/jobs.service.ts
backend/package.json
backend/package-lock.json

Git Commit

今回の変更は、次のCommitとして記録しました。

28933cf feat(api): add job workflow status endpoint

Sprint6とは関係のないフロントエンドやRealtime関連の変更はCommitに含めず、Job Workflow APIに必要なファイルだけを分離しています。

Job Workflow APIが今後つなぐ機能

今回実装したステータス管理は、今後のCLINのさまざまな機能につながります。

スタッフ画面
作業開始・写真撮影・完了操作

管理者画面
作業進捗・停滞状況の把握

リアルタイム画面
ステータス変更の即時反映

AI写真チェック
解析開始・解析完了の管理

レビュー画面
確認待ち・修正対応・完了管理

スタッフ実績
作業時間・完了件数・品質評価

今回のAPIは、CLINの現場画面と管理者画面をつなぐ中核となる基盤です。

次回予告

次の開発では、各ステータスへ移行した時刻を記録する仕組みを検討します。

例えば、

清掃を開始した時刻
写真撮影を開始した時刻
レビュー待ちになった時刻
作業が完了した時刻

を保存できるようにすることで、作業時間分析、遅延検知、スタッフ実績、AI分析に活用できるようになります。

次回は、清掃ワークフローの時間データを蓄積する基盤を構築していきます。