TeamWorks 宛 共有文書（第1回）の原稿 — これを正とする

2026-09-03 追記: この原稿は一時ディレクトリにしか存在せず、消えると復元できない状態でした。 リポジトリへ移動しています（元: scratchpad/share/CONTENT.md）。 PDF はこの原稿から docs/handoff/pdf/make_ddl_review_pdf.py で生成します。 生成物の検査は docs/handoff/pdf/check_ddl_review_pdf.py。詳細は docs/handoff/pdf/README.md。 第2回の原稿は docs/handoff/TeamWorks確認事項_第2回_20260903.md です。

宛先: TeamWorks（DB開発側） 差出: DFA Robotics 作成日: 2026-09-03 表題: 実DDL照合結果と確認事項

冒頭に置く背景説明

2026-09-02 付でご提供いただいた clean_watch_20260902.sql（CREATE TABLE 39個）を、 こちらで手書きしていた Prisma スキーマと機械的に照合しました。

照合は独立した2つの方法で行い、結果が一致することを確認しています。

1. DDL からローカルに実データベースを構築し、prisma db pull で生成したスキーマと比較
2. DDL を直接パースしてカラム定義を抽出し、比較

差分は49件でした。そのうち 42件はこちらで実DDLに合わせるだけで完結します。 本書には、こちらだけでは判断できない3件と、共有しておきたい3件、 および仕様の確認1件を記載しています。

サマリ表（冒頭に置く）

こちらで完結する42件については本書に記載していません。

A. 合意が必要（3件）

A-1 robot_error_reports の主キーと id の意味

最も影響が大きい項目です。

実DDL の状態:

`id`       varchar(50) NOT NULL,   -- 主キーでも UNIQUE でもない。制約なし
`error_id` varchar(50) NOT NULL,
UNIQUE KEY `robot_error_reports_report_id_unique` (`error_id`)

PRIMARY KEY が定義されておらず、一意制約は error_id のみです。

一方こちらの API 契約と型定義は次のようになっています。

PrecheckItem.id : number
PATCH /prechecks/{id}/status

具体的な帰結です。アラート一覧で担当者が「対応中」を押すと、画面は id を送ります。しかし、

• id は一意でないため、その値で1行を特定できません
• id は文字列なので、number として扱うと不一致が起きます
• 更新できるのは error_id だけです

このため対応状況の更新（PATCH）が設計として成立しません。

伺いたいこと:

1. id に一意制約を付ける予定はありますか。それとも error_id が正式なキーですか
2. こちらの API が画面に返すべき ID は id と error_id のどちらですか
3. id が文字列である前提でよろしいですか（こちらの型を number から string に変更します）

A-2 履歴テーブルの id は誰が採番するのか

clean_status_histories の状態:

`id` bigint unsigned NOT NULL,   -- AUTO_INCREMENT ではない
UNIQUE KEY `clean_status_histories_id_unique` (`id`)

PRIMARY KEY が無く、AUTO_INCREMENT も付いていません。一方で UNIQUE 制約はあります。

これが元テーブル clean_statuses.id を引き継ぐ設計だとすると、 1つの清掃状態につき履歴を1件しか作れません。 履歴テーブルとしては不自然に見えるため、意図を確認したいです。

clean_timetable_histories.id も同様に AUTO_INCREMENT がありません。

伺いたいこと:

1. これらの id は誰が採番しますか（アプリ側で連番を振る想定でしょうか）
2. 元テーブルの id を引き継ぐ設計ですか。その場合、同じ清掃状態の履歴が 複数回作られることはない前提でよろしいですか

こちらが検証用のダミーデータを作る際に、採番方法が決まらないと投入できません。

A-3 先の回答（contact 系の型）はいつ反映されますか

先の確認事項 B-6 について、次のようにご回答いただきました。

typo です。contact_type は unsigned tinyint とします。email は varchar(100) とします。

いただいた DDL（2026-09-02 付）には、まだ反映されていないようです。

顧客側と施設側で型が食い違った状態が残っています。

伺いたいこと:

1. 当面は現行の DDL に合わせて実装してよろしいですか （後で変更が入れば prisma db pull の差分に出るため追随できます）
2. 変更を入れる時期の目安があればお知らせください

なお customer_contacts.contact_type が bigint の場合、 こちらでは JavaScript の bigint 型として受け取ることになり、 JSON へ変換する際に明示的な数値変換が必要になります（実装側で対応します）。

B. 情報共有（3件）

返答は必須ではありません。こちらは現状のまま実装を進められます。

B-1 外部キーが3本欠けています

定義書では fk と記載されているものの、実DDL に制約が見当たりませんでした。

意図的なものか、付け忘れかをご確認いただければ幸いです。 付け忘れであれば DB 側で追加いただくのが適切と考えます。 意図的であれば、こちらは参照先が存在しない行（孤児行）を想定した実装にします。

返答をお待ちせず、孤児行を想定した実装で進めます。

B-2 インデックスが1つ欠けています（DB側でしか対処できません）

robot_task_versions.clean_schedule_id にインデックスがありません。 外部キーも無いため、MySQL による自動作成も行われていません。

この列で絞り込む検索が全件走査になります。 300施設分のタスク履歴が積み上がるテーブルのため、 運用が進むにつれて表示が遅くなることが見込まれます。

こちら側に回避手段がないため、DB 側でのご対応をお願いしたい項目です。

B-3 timestamp NOT NULL に DEFAULT 句がありません

いずれも timestamp NOT NULL ですが DEFAULT 句がなく、 INSERT 時に明示的な値の指定が必要です。

アプリ側で時刻を管理する設計であれば意図的と理解しますが、 created_at に既定値が無いのは珍しい形のため念のため共有します。

こちらは参照のみのため実装への影響はありません。

C. 仕様確認（1件）

C-1 アドバイス規則 R3 の条件に「出発失敗」を含みますか

こちらの実装規約では、行展開アドバイスの規則を次のように定めています。

R3 = 完了率が△以下の状態が2日以上連続
R4 = 出発失敗 または △以下 の状態が3日以上連続

R3 と R4 で条件を書き分けていますが、実装は両方とも 「連続問題日数」という1つの値を見ており、区別できません。

さらに連続問題日数の定義が「△以下 または 出発失敗」であるため、 現状では2日連続の出発失敗で R3 が発火します。

伺いたいこと:

1. R3 の条件に出発失敗を含めるのが正しいですか
2. それとも R3 は完了率の低下のみを対象とし、出発失敗は R4 だけの条件ですか

後者の場合、連続日数を「△以下のみ」と「出発失敗を含む」の2種類に分けて 数える必要があるため、実装方針が変わります。

参考: 照合により解決した事項

いただいた DDL により、こちらで保留していた判断が確定しました。あわせてご報告します。

また、こちらが定義書から手書きしたスキーマは、 28テーブル中12テーブルが実DDLと完全一致していました。 残りの差分も、大半は定義書側の記述と実DDL の食い違いに起因するものでした。

末尾に置く文

本書の A（3件）についてご回答をいただければ、 対応状況の更新機能とダミーデータによる検証に着手できます。 B・C については実装を止めるものではありませんので、お手隙の際にご確認ください。