CLIN

API開発シリーズ③CLIN開発日記 #016｜清掃業務の進行履歴を残す「Job Timeline基盤」を実装

2026年7月24日

こんにちは。

清掃業務プラットフォーム「CLIN」の開発を進めています。

今回のSprintでは、清掃業務の進行状況を時系列で記録するための、Job Timeline基盤を実装しました。

これまでCLINでは、清掃ジョブの現在ステータスを更新するAPIを整備してきました。

今回の開発では、単に現在の状態を保存するだけではなく、

未開始
↓
移動中
↓
清掃中
↓
撮影
↓
AI確認
↓
管理者確認
↓
修正
↓
完了

といった一連の流れを、履歴として残せる仕組みへ拡張しています。

現在の状態だけでなく、変化の履歴を残す

清掃現場では、「現在どの状態なのか」だけでは十分ではありません。

例えば、管理者が確認したいのは次のような情報です。

何時に現場へ向かったか
何時に清掃を開始したか
清掃にどのくらい時間がかかったか
写真確認はいつ始まったか
修正依頼が何回発生したか
最終的に何時に完了したか

そこでCLINでは、清掃ジョブの状態が変わるたびにイベントを記録する仕組みを追加しました。

今回のテストでは、以下の履歴が正しく保存されることを確認しています。

not_started → moving
moving → cleaning
cleaning → completed

それぞれの変更時刻も保存されるため、将来的には管理者画面で清掃業務の流れをタイムライン形式で表示できます。

開始時刻と完了時刻を自動記録

今回、清掃ジョブへ次の日時情報を追加しました。

statusUpdatedAt
startedAt
completedAt
updatedAt

startedAtは、未開始状態から初めて業務が動き出した時刻を記録します。

その後、清掃中や撮影中へステータスが変わっても、最初の開始時刻は維持されます。

completedAtは、ジョブが完了状態になった時点で記録されます。

これにより、

業務開始時刻
業務完了時刻
実際にかかった時間

を正確に計測できるようになります。

今後は、予定時間との差や、物件ごとの平均清掃時間なども分析できるようになります。

同じ操作が繰り返されても履歴を増やさない

スマートフォンの通信環境やボタンの連続操作によって、同じ更新リクエストが複数回送信される可能性があります。

例えば、すでに「移動中」になっているジョブへ、もう一度「移動中」の更新が届くケースです。

今回の実装では、

moving → moving

のように状態が変わっていない場合は、日時を更新せず、履歴も追加しないようにしました。

これにより、同じ操作が複数回送信されても、タイムラインに不要な履歴が増えません。

データ更新をトランザクション化

Job Timelineでは、次の2つを同時に処理しています。

清掃ジョブの現在ステータスを更新
清掃ジョブの変更履歴を保存

どちらか片方だけが成功すると、現在の状態と履歴が一致しなくなります。

そこで今回は、PostgreSQLのトランザクションを導入しました。

BEGIN
↓
現在ステータスを取得・ロック
↓
清掃ジョブを更新
↓
履歴を保存
↓
COMMIT

途中でエラーが発生した場合は、

ROLLBACK

によって、すべての変更を元に戻します。

開発中にはSQLの型判定エラーも発生しましたが、その際にも清掃ジョブの状態や履歴が中途半端に更新されないことを確認できました。

今後の管理者画面につながる基盤

Job Timelineは、単なる履歴保存機能ではありません。

今後、管理者画面では次のような表示を予定しています。

08:01　現場へ移動開始
08:15　現場到着
08:18　清掃開始
08:52　写真撮影
08:55　AI写真チェック
08:57　管理者レビュー待ち
09:01　修正依頼
09:08　修正完了
09:10　清掃完了

この履歴を使うことで、

  • 現場の遅れ
  • 作業時間
  • レビュー時間
  • 修正回数
  • 完了までの所要時間

を把握できるようになります。

AI分析にも活用予定

将来的には、Job Timelineの履歴をAI分析にも使用します。

例えば、

この物件は予定より清掃時間が長い
写真確認後の修正が多い
特定の曜日に遅延が発生している
同じ設備で作業が止まりやすい

といった傾向を自動で検出できるようになります。

現在は履歴を正確に保存する基盤を整備した段階ですが、今後のAI機能やダッシュボード機能にとって重要なデータになります。

今回のSprintで実装した内容

今回の開発では、主に以下を実装しました。

Jobステータス更新のトランザクション化
Job Timeline履歴の保存
業務開始時刻の記録
業務完了時刻の記録
ステータス更新時刻の記録
同一ステータス更新の重複防止
APIレスポンスへの日時追加
エラー時のロールバック確認

これでCLINは、清掃ジョブの現在状態だけでなく、業務がどのように進んだかを記録できるようになりました。

次のSprintでは、この進行履歴をスタッフ画面や管理者画面へどのようにつなげるかを検討していきます。

CLINは、ホテル、宿泊施設、アパート定期清掃、退去清掃、就労支援事業所など、さまざまな清掃現場で利用できるプラットフォームを目指して開発を続けています。