diff --git a/docs/development/manual-html-operations.md b/docs/development/manual-html-operations.md index f80b2d24..cfaad1eb 100644 --- a/docs/development/manual-html-operations.md +++ b/docs/development/manual-html-operations.md @@ -76,6 +76,23 @@ scripts/automation/run_pipeline.sh --manual-dir docs/manuals/45th_企画マニ ②〜④だけが回り、出力HTMLは無条件に上書きされる。 +### 承認済みのマニュアルを一部だけ直す（再生成しない） + +部門長が確認して承認したマニュアルを、表の1行や図の1枚を直すために再生成してはいけない。LLM の出力は生成のたびに揺れるので、直したい箇所以外の構造や語句まで変わり、確認をやり直すことになる。 + +表の行と図の差し替えだけなら、公開中の HTML を直接差し替える。 + +- 表：古い `source.html` から組み立てた表の行が、公開中の HTML に一字一句そのまま入っていることを確かめてから、新しい `source.html` の行で置き換える。LLM が表を独自に組み直していて一致しないときは、セルの文字と消す行の数を確かめてから、行（``）ごとに入れ替える +- 図：`images/` の画像は、HTML に base64 の文字列としてそのまま入っているので、その文字列を新しい画像の base64 に置き換える。`--embed-only` は、すでに埋め込まれた画像（`data:`）を飛ばすので、差し替えには使えない + +運用が変わって、表の行の構成や役割分担まで変わるときは、差し替えではなく再生成する。 + +### どれが正しい版かを決める + +手元とサーバーに版が複数あるとき、どれが正しいかをファイルの更新日時で決めない。新しく生成した版でも、LLM の揺れで以前より崩れていることがある。45th では、更新日時が新しい版を上げたところ、構造が崩れていた。さらに、以前に受けた画像の追加の依頼が、どちらの版にも入っていなかった。 + +正しい版は、窓口チャンネルのスレッドにある依頼と承認の履歴で決める。まだ反映していない依頼が見つかったら、版を比べるのではなく、元のドキュメントを取り直して作り直す。 + ## ① Googleドキュメントを取得する 対象のドキュメントを開き、`ファイル > ダウンロード > ウェブページ（.html、zip形式）` を選ぶ。PDFやWordではなくHTMLである点が重要で、これ以外の形式では画像が取り出せない。 @@ -387,7 +404,7 @@ URL文字列をそのまま対応表A列のキーとして使うことも技術 ### 割り当てスプシは対応表に使わない -マニュアルの割り当てスプシ（`1a2pvM1M8NWQNLNaYnsqTzpB_oGE129-ibpbN3Be1Z1Q`）にもマニュアル名の列があるが、こちらは局ごとに命名規則が違い、`配線マニュアル` `物品移動計画書` のような短い形になっている。タスク一覧のM列は `45th_企画マニュアル_縁日` の完全形なので、両者は機械的に突き合わせられない。対応表のキーはタスク一覧M列に揃える。 +マニュアルの割り当てスプシにもマニュアル名の列があるが、こちらは局ごとに命名規則が違い、`配線マニュアル` `物品移動計画書` のような短い形になっている。タスク一覧のM列は `45th_企画マニュアル_縁日` の完全形なので、両者は機械的に突き合わせられない。対応表のキーはタスク一覧M列に揃える。 ## やってはいけないこと @@ -451,12 +468,9 @@ node_modules/.bin/clasp clone <スクリプトID> 名簿タスク送信.js タスク送信本体。TASK_COL_MANUAL_URL = 19（S列） 調査_マニュアルURL.js checkManualUrlMapping（紐付けの点検） / fillManualUrlFormulas / inspectManualUrlLookup -スプレッドシート - 45th_シフト_ver0 1b5FhiuT7M6kcAM_BkFRu1UVLj-Ssbt-VoBjGmEAN3-I - マニュアル割り当て 1a2pvM1M8NWQNLNaYnsqTzpB_oGE129-ibpbN3Be1Z1Q - -Slack - #081_執行部マニュアル窓口 C0B65H5FBQ8（マニュアル1本 = スレッド1本） +スプレッドシート（ID は後任に渡す非公開の別紙にある） + 45th_シフト_ver0 + マニュアル割り当て ``` `docs/proposals/manual-slide-operations.md` は2026-06-18時点の手順書で、GitHub Pagesへの配置とSlackスレッドでの部門長レビューを前提にしている。配信経路が自前APIに移った現在、④以降は本書が正となる。①〜③の生成と検証、および部門長レビューの回し方は同文書がなお詳しい。 diff --git a/docs/development/onboarding.md b/docs/development/onboarding.md index f9bf941c..e977b024 100644 --- a/docs/development/onboarding.md +++ b/docs/development/onboarding.md @@ -506,7 +506,7 @@ cd mobile && fvm flutter test - **Makefile**：よく使う docker compose のコマンドに短い名前を付けたものです。一覧はリポジトリ直下の `Makefile` を開くのが確実です。Mac 用の compose ファイル（`docker-compose.mac.yml`）を使う `mac-` 付きのコマンドもあります。 - **GitHub Actions（CI）**：PR を出すと、変更した場所に応じて次が走ります。 - `api/` を変えたとき：golangci-lint（`go-lint.yml`。PR で新しく増えた指摘だけを見る）と `go test`（`go-test.yml`） - - `mobile/` を変えたとき：`flutter analyze --fatal-infos`（`flutter-lint.yml`。最も軽い info レベルの指摘でも落ちる） + - `mobile/` を変えたとき：`flutter analyze --fatal-infos`（`flutter-lint.yml`。最も軽い info レベルの指摘でも落ちる）。**テスト（`flutter test`）は走りません。** mobile を変えたら、10節のコマンドで手元で実行してください。45th では、別々の PR で変わったボタンの文言とテストが食い違ったまま develop に入り、マージ後に気づきました（#516） - `gas/` を変えたとき：GAS のコードを検査するものは走らない - どの PR でも：ADR（`docs/decisions/`）に書いた前提のファイルや関数がまだあるかの点検（`docs-refcheck.yml`） - **CodeRabbit**：PR に AI がレビューコメントを付けます。指摘は参考です。すべてに従う必要はなく、スコープ外のものは理由を書いて見送って構いません。 @@ -519,6 +519,8 @@ cd mobile && fvm flutter test - workflow ファイルを読める程度の YAML - Git：ブランチ、merge、コンフリクトの解消、1つの PR に1つの目的 +**mobile の lint の違反を `dart fix` で直せるかは、ルール名からは分かりません。** `dart fix` が直せるのは、その指摘に書き換えの手順が用意されているものだけで、Flutter 自身の古い書き方の指摘でも、用意されていないことがあります。45th では「自動で直せる」と分類した違反を新しく入った人に割り振ったところ、`dart fix` が何も直せませんでした（#288）。割り振る前に、`fvm flutter pub get` のあとで `fvm flutter analyze` の件数と `fvm dart fix --dry-run` の件数をルールごとに比べ、どこまで自動で直せるかを確かめてください（#286）。 + --- ## 12. 現実的な学習順序（全員） diff --git a/docs/operations/day-of-support.md b/docs/operations/day-of-support.md index 12e2bfec..8aa2eaf4 100644 --- a/docs/operations/day-of-support.md +++ b/docs/operations/day-of-support.md @@ -146,9 +146,11 @@ docker logs --since nutfes-seeft-api 2>&1 | grep "GAS送信" この文書の SQL はどれも読むだけである。**当日に DB を書き換えることは、原則として避ける。** どうしても直すときは、次を守る。 +- 接続するときは、接続先の URL に `keepalives=1&keepalives_idle=30` を足す。付けずに放置すると、接続が裏で切れていることに気づかないまま次の文を打つことになる。 - 接続が切れていると、`BEGIN` が飲み込まれ、そのあとの `DELETE` や `UPDATE` が即座に確定することがある。45th では、`BEGIN; DELETE …; COMMIT;` をまとめて貼ったときにこれが起きた。 - `BEGIN;` は**単独で**打ち、プロンプトが `=*>` のように `*` 付きになったことを見てから次に進む。 - psql の表示を結果の証拠にしない。45th では `DELETE 0` と表示されたのに、実際には4件消えていた。別の方法で件数を確かめる。 +- tasks の行を消す前に、参照している4つの表（`shifts`・`reviews`・`shorthanded_rescues`・`trouble_rescues`）の件数を数え、**さらにコードの中で id を直接書いている箇所を探す**（`git grep` で id の数字やタスク名を探す）。外部キーだけでは依存が見えない。45th では、どこからも参照されていない「タスク外」（id=3）が、mobile のトラブルの報告から数字の 3 で送られていた。 - タスクの `url` や `manual_url` を SQL で書き換えても、次のタスク送信で上書きされる。直すのはスプシの側である。 ## 説明会で伝えておくと減る問い合わせ diff --git a/docs/operations/seeft-data-contract.md b/docs/operations/seeft-data-contract.md index d720e4e1..32c08fe9 100644 --- a/docs/operations/seeft-data-contract.md +++ b/docs/operations/seeft-data-contract.md @@ -74,6 +74,7 @@ - **GAS が途中で止まっても、DB には途中まで入っている。** 送信が終わらないように見えても、連打しない。GAS が打ち切られても API は処理を続けているので、次の実行を重ねると同じ行を奪い合って、さらに遅くなる。数分空けてから、DB の件数を先に確かめる。 - シフトの**変更**（タスクが変わったとき）と**新規作成**は `action_logs` に記録され、Slack ID が登録されている人には5分おきに DM で届く。一括で空欄にするような編集をして送ると、数百人に通知が飛ぶ。 - 「送信が完了しました」は、DB がシートと同じであることの証明にならない。送信後にシートを編集すれば、DB は古いままである。 +- 送信後にシートと DB を突き合わせるときは、参加不可（背景が黒いセル。`NG` として送られる）も1件として数え、総数ではなくタスクごとの件数で比べる。セルの値だけを数える方法では黒いセルが空に見えるので、DB の方が多く見える。45th では、これを「古い割り当てが DB に残っている」と読み違えた。 ### 送る前に確認するメニュー diff --git a/docs/proposals/manual-proposal-v4-slides/automation-design.md b/docs/proposals/manual-proposal-v4-slides/automation-design.md index 7fe28509..eb04a973 100644 --- a/docs/proposals/manual-proposal-v4-slides/automation-design.md +++ b/docs/proposals/manual-proposal-v4-slides/automation-design.md @@ -252,7 +252,7 @@ dependencies = [ ### スプシ ID -- 環境変数 or 設定ファイル: `SEEFT_STATUS_SHEET_ID=1jz_870-Id89UYS-00F9ozZUNWL92IPntRqtNYYCRF0c` +- 環境変数 or 設定ファイル: `SEEFT_STATUS_SHEET_ID=<ステータス管理スプシの ID>` - ハードコードせず外部から差し替え可能に ## 9. 新 PM 引き継ぎ用クイックスタート