docs: オンボーディング資料の論の筋を「黙って壊れるところ」に通し、コードと食い違う記述を直す

[taminororo]

対応Issue

resolve #592

概要

docs/development/onboarding.md の論の筋を1本にし、今のコードと食い違う記述を直しました。

論の筋

• 冒頭で約束していたのは「技術ごとに何を学ぶか」でした。一方、0節の「最初に理解してほしい」と 13節の「完了」の問いが測っていたのは、「コンパイラや CI が気づかず、黙って壊れる場所」でした。冒頭に「この資料でいちばん伝えたいこと」の節を足し、この軸をはっきり書きました。
• 各節の該当する段落は「黙って壊れるところ。」で書き出してそろえ、13節の問いには答えがある節の番号を添えました。
• 「前の節の言葉を後の節で使う」という説明を、実際の書き方（前の節が後ろの節を参照している）に合わせました。
• 5節「DI でテストがしやすい」と 10節「偽の repository は作れない」の食い違いを直し、どこまで差し替えられるかを書き分けました。
• 13節で mobile だけの担当が作るものを、自分のアプリを http://localhost:45029 で開いて SeeFT のローカルの api を呼ぶ形にしました（CORS の許可リストに入っているオリジンなので）。

担当の種類（判断したこと）

元の本文は、冒頭で担当を api・mobile・GAS の3種類と書きながら、12節・13節は2種類を前提にしていました。担当は api と mobile の2種類にそろえ、GAS（8節）は GAS に関わる issue を持ったときに読む扱いにしました。3種類に戻す場合は、13節に GAS の担当向けの課題を足す必要があります。

コードと食い違っていた記述

直す前	実際（確かめた場所）
JSON のキー名が食い違っても、動かせば分かる	Echo の c.Bind は知らないキーを捨て、ゼロ値のまま進む。型の食い違いなら 400（review_controller.go の CreateReview）。9節に comment → comments の例を足した
Slack のトークン・レスキューの送り先の URL が無い	api/env/dev.env にダミーの値が入っている
make down なら DB は残る	docker-compose.yml の db にボリュームの指定が無く、次の起動では空になる。残すなら docker compose stop
widget テストは --platform chrome が必須	指定なしで通る（VM で 38 件成功。落ちるのは既知の test/widget_test.dart の1件）
LockService は、2回目が1回目の後に普通に動く	waitLock(30000) で、30 秒を過ぎるとエラーになる
clasp push の説明	公開中の Web アプリは clasp deploy -i <デプロイID> をしないと変わらない（gas/README.md）
マイシフトは日付・天気ごとに表示	mobile は天気を晴れに固定している（my_shift_page.dart）
gas/ を変えたときは CI が何も走らない	すべての PR で docs-refcheck.yml が走る
repository も usecase も go-sqlmock でテストする	今のテストはそのとおり。ただし test-roadmap.md が計画する実際の DB を使うテスト（フェーズ2）はまだ無い、と書き足した
ブランチ名は feat/... の形だけ	fix・docs もある。スカッシュマージで、マージするのは PM（workflow.md）
errors.Wrap は古いコードで使っている	api/lib/ ではこちらが多数派
repository は *sql.Rows を返す	1件なら *sql.Row。GORM を使う shift_card_repository.go は struct を返す

このほか、15節に「セキュリティの問題は公開の issue に書かない」（workflow.md「2. issue」）を足しました。新入生向けには、0節の図の描き直し（矢印の向きの意味と、番号付きの流れ）、早見表への語の追加、5節と 10節のコード片へのコメントを足しています。

テスト項目

確かめたこと

• 上の表の各記述を、develop のコードと文書で確かめた
• cd mobile && fvm flutter test を手元で実行した（chrome の指定なしで通る）
• node --check で、function どうしの重複はエラーにならないことを確かめた
• python3 scripts/refcheck/refcheck.py --worktree docs/development/onboarding.md で、パスとシンボルの参照が通った
• 0節の図の縦線の位置が、日本語の文字幅を含めてそろっていることを確かめた

確かめていないこと

• make down のあと DB が空になることは、Docker を起動して試してはいない（compose の定義と Docker の仕様から判断した）
• xcode-select --install で git と make が入ることは、この環境では実行していない

備考

• PR docs: 45th の運用で踏んだことのうち、手順書にないものを足す #574 も 11節の CI の一覧を変えています。後からマージするほうで、衝突の解消が要ります。

[coderabbitai]

Warning

Review limit reached

Next included review available in 52 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: NUTFes/SeeFT/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 6ece22b1-8385-4ba2-a0d6-e70de1e3e9f0

📥 Commits

Reviewing files that changed from the base of the PR and between b183503 and 1c8b1c3.

📒 Files selected for processing (1)

• docs/development/onboarding.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}