海運の運航会社が、代理店から届く英文の荷役記録（Statement of Facts）を読み取り、着岸・荷役・中断の時刻を並べて、停泊期間の超過（デマレージ）と早出料の試算に回す

処理の起点を決める

航海ごとの受け取りの場所（S3 のフォルダ）にPDFが保存されたことを起点にします。 フォルダは sof/<航海番号>/<港の区分：load|disch>/ の形にし、どの航海・どの港の荷役記録かを、保存した場所で決めます。 荷役記録の本船名と港名から航海を探すと、同じ本船の前後の航海や、同じ港に続けて寄った航海と取り違えます。

読み取りを始めるとき、ClientRequestToken に「航海番号＋港の区分＋受領日」を入れます。 公式のページでは、同じトークンで StartDocumentAnalysis を呼ぶと同じ JobId が返り、同じジョブを誤って二度始めるのを防げるとされています。代理店が同じ荷役記録を2回送ってきても、読み取りは1回で済みます。

完了は Amazon SNS の通知で受け、JobTag に入れた航海番号でどの航海かを知ります。 JobId は7日間だけ有効なので、結果は受け取ったその場で S3 に保存します。

船長の署名のある版と、署名の無い速報の版が別々に届くことがあります。 速報の版でも下書きは作りますが、署名のある版が届いたら作り直し、2つの版の違いを確認事項に出します。

入力データを集める

質を決めるのは、傭船契約の条件の一覧です。 「天候の悪い日を除く」とだけ書かれていると、計算の規則を選べません。定義集のどの定義に当たるか（たとえば Weather Working Day、Weather Working Day of 24 Consecutive Hours、Weather Working Day of 24 Hours のどれか）まで、傭船の担当者が契約から書き出します。 書き出せない契約は、自動の計算を止めて人が計算します。

港の暦は、日曜・祝日を除く契約で使います。 定義集では、祝日を「現地の法律や慣行で通常の労働時間に通常は働かない日」としており、国や港で日が違うので、自社の暦では代わりになりません。

データの取得方法を決める

表は、TABLE のブロックから CELL を行の番号・列の番号の順に並べて組み立てます。 公式のページでは、セルには行と列の位置が付き、列の見出しのセルには COLUMN_HEADER の印が付くとされています。見出しのセルの文字から、どの列が日付・開始・終了・内容・備考かを決めます。見出しの言い方は代理店ごとに違う（Date／Day、From／Commenced、To／Completed など）ので、言い換えの一覧を持ちます。

結合されたセルにも気を付けます。 同じ日の行が続くとき、日付の列が1つのセルに結合されていることがあります。公式のページでは、結合されたセルは MERGED_CELL として、どのセルを結合したかと一緒に返るとされています。結合されたセルの日付を、結合の範囲の行すべてに配ります。

問い合わせは、表の外にある項目だけに使います。

結果は NextToken が返る限り GetDocumentAnalysis を呼び続け、全ページ分をそろえてから組み立てます。 公式のページでは、1回で返るブロックは最大1,000件とされ、数ページの荷役記録でも複数回に分かれます。

AIへ渡す前に整形する

1. 形式の確認 … JPEG、PNG、PDF、TIFF のどれかであることを確かめます。XFA の形式のPDFとパスワードで保護されたPDFは扱えないとされています
2. ページをまたぐ表のつなぎ … 次のページの表の列の見出しが同じなら、1つの表としてつなぎます
3. 日時の組み立て … 日付の列が空の行には直前の日付を引き継ぎます。「2400」は翌日の「0000」に直し、終了が開始より前なら日をまたいだとみなして印を付けます
4. 日付の順の決め方 … 月の名前で書かれたものはそのまま読み、数字だけの日付は代理店ごとの設定（日月年か月日年か）で読みます。設定の無い代理店で日が12以下のものは人に回します
5. 現地時刻の確かめ … 荷役記録の時刻は現地時刻として扱い、港の表の時差を持たせます。「LT」「UTC」「GMT」と書かれた行があれば、そのとおりに印を付けます
6. 手書きの追記の印 … 単語の TextType が手書きのものに印を付け、確認事項に出します

3番目と4番目を軽く見ないでください。 停泊期間は時間単位、デマレージは1日あたりの額を時間で按分することが多く、日付を1日取り違えると、請求額が1日分ずれます。 定義集でも、1日を24時間とし、1日に満たない部分は按分すると定めています。

AIに処理させる

させるのは、行ごとの出来事を区分に当てはめることだけです。 読み取りは Textract、日時と計算はプログラムが行います。

中断の理由の区分は、停泊期間から差し引くかの判断ではありません。 「本船のクレーンの故障」を ship に分けても、それを差し引くかは傭船契約の条項で決まります。AIの出力には「差し引く」「数える」という言葉を入れさせません。

3行目がいちばん起きやすい失敗です。 「awaiting cargo」をAIは荷主側の責任と書きがちですが、貨物が来ないのが陸側の設備の問題か、荷主の手配の問題かは、文だけでは決まりません。 指示で「文に書かれた理由の言葉で分け、責任を推し量らない」と縛り、迷えば unclear にさせます。

指示内容を固定する

あなたは不定期船の運航会社で、代理店から届いた荷役記録（Statement of Facts）の
行を整理する担当者を手伝います。
渡された「行の一覧（行番号・日付・開始・終了・内容・備考）」と「区分の表」だけを見てください。

【やること】
- 行ごとに、event_code を区分の表の中から1つ選んでください。
- event_code が stoppage の行には、stop_cause を次のどれかで付けてください。
  weather ........ 雨・風・波など天候が理由と書かれている
  ship ........... 本船の設備・乗組員が理由と書かれている
  shore .......... 岸壁・荷役の設備・作業員など陸側が理由と書かれている
  shifting ....... 別の岸壁や錨地への移動
  holiday ........ 日曜・祝日・休みのため作業しないと書かれている
  cargo_docs ..... 貨物や書類の到着を待っていると書かれている
  unclear ........ 上のどれに当たるかを文から決められない
- evidence には、判断に使った内容と備考の文をそのまま写してください。

【厳守事項】
- 時刻を計算しないでください。開始と終了は渡された値のまま返してください。
- 終了の時刻が空の行を、次の行の時刻で埋めないでください。
- 差し引く・数える・請求できる、といった判断を書かないでください。
- 誰の責任かを推し量らないでください。
  「awaiting cargo」は cargo_docs、理由の書かれていない「stopped」は unclear です。
- 迷ったときに weather や ship を選ばないでください。unclear にしてください。
- 備考に「under protest」「without prejudice」「not agreed」などがあれば、
  remarks_flag に true を入れ、文をそのまま evidence に写してください。

「理由の書かれていない stopped は unclear」を例として書くのは、AIが前後の行から理由を補いがちだからです。 直前の行が雨なら、次の「stopped」も雨と書きます。前後から補った区分は、相手のタイムシートと合わなかったときに根拠を示せません。

cargo_docs を独立の区分にしているのは、ここが精算の交渉でいちばん争われるところだからです。 天候や本船の故障と混ぜると、後で行を探し直すことになります。

出力形式を固定する

区分は、Claude API の構造化出力で形を決めて受けます。 公式のページでは、output_config.format に JSON スキーマを渡すと、スキーマに合う JSON が返るとされ、正式提供の機能です。ただし、数値の minimum／maximum などの制約はスキーマに書けないとされているので、値の範囲はプログラムで確かめます。

{
  "voyage_no": "V-2611",
  "port_type": "disch",
  "rows": [
    { "row_no": 14, "date": "2026-09-18", "from": "08:00", "to": "11:30",
      "event_code": "stoppage", "stop_cause": "weather",
      "evidence": "Stopped loading due to heavy rain", "remarks_flag": false },
    { "row_no": 15, "date": "2026-09-18", "from": "11:30", "to": "",
      "event_code": "stoppage", "stop_cause": "unclear",
      "evidence": "Stopped", "remarks_flag": false }
  ]
}

プログラムは、これに計算の結果を足してタイムシートの下書きにします。

{
  "laytime_allowed_hours": 96.0,
  "time_used_hours": 118.5,
  "excluded": [ { "row_no": 14, "hours": 3.5, "rule": "weather_wwd24c" } ],
  "result": "demurrage", "excess_hours": 22.5, "amount_usd": 0,
  "checks": [ "row_15_missing_to", "nor_accepted_missing" ],
  "rule_set": "CP-2611：SHEX／WWD24C／notice 6h"
}

1つ目の理由は、区分と計算を別の層に置けることです。 rows はAIが埋め、excluded はプログラムが傭船契約の条件で決めます。区分を1行直せば、計算はやり直すだけで済みます。

2つ目は、rule と rule_set で計算の根拠が残ることです。 どの行をどの規則で差し引いたかがタイムシートに残り、半年後の交渉でも説明できます。

システムへ連携する

傭船契約の条件の一覧には書き込みません。 条件を直すのは傭船の担当者で、運航担当が計算の都合で条件を書き換えると、契約と計算が食い違います。

運航管理の仕組みへの登録も人が行います。 下書きの数字がそのまま精算の金額になると、区分の誤りがそのまま請求に進みます。

人が確認する

運航担当が全件の下書きを見ます。 見る順を決めておきます。

1. checks のあるものを先に見る … 抜け・重なり・日付の取り違えを原本で確かめます
2. unclear と cargo_docs の行を読む … 原本の文と備考を読み、必要なら代理店に問い合わせて区分を直します
3. remarks の行を読む … 但し書きの付いた行は、相手が争う意思を示した行です。 交渉の材料として印を残します
4. 計算の規則が契約と合っているかを見る … rule_set が傭船契約の条件と合っているかを確かめます
5. 精算の記録に登録する … 請求や支払の連絡は運航担当と傭船の担当者が行います

例外に対処する

5行目が、この構成で最も守りたいことです。 条件が分からないまま計算すると、それらしい数字が出て、そのまま交渉に使われます。 条件が無いときは数字を出しません。

記録を残す

• 荷役記録の原本と、保存した場所（航海・港・受領日・版）
• Textract が返した結果の全文と、組み立てた行の一覧
• AIの区分の結果（rows）と根拠の文
• 運航担当が直した区分 … どの行を、どの区分から、どの区分に、なぜ直したか
• 計算に使った傭船契約の条件（rule_set）と計算の結果
• 相手のタイムシートと、行ごとの違い

4つ目の直した記録は、指示と区分の表の改善に使います。 直しが多い代理店や言い回しが分かれば、区分の表の説明に足せます。