記録・進捗

プロジェクト準備完了（WBS 0）

検証計画・設計 HTML 資料、WBS・ガントチャート、リポジトリルールを整備。MS-0 達成。

サーバー実装着手・runbook v1.0 作成

server/（FastAPI + PostgreSQL + docker-compose）、 scripts/test-feedback.ps1、 runbook.html#server v1.0 を作成。 当初は Tunnel 新規構築（horse-feedback）を想定。

プライベート PC へ開発環境移行

リポジトリをプライベート PC（Windows 11）へ移行し初回コミット（2c6f420）。 開発の主戦場を自宅 Windows PC とする。

協議: PoC Cloudflare Tunnel の再利用可否

論点: WBS 1.1.1 の Tunnel 構築を一から行うか、 過去 PoC（C:\Dev\PoC_スマート農業環境構築）の資産を活用するか。

• PoC 記録および疎通確認により、https://api.dammy-otoko.com/ping が応答（Tunnel 稼働中）と確認
• Named Tunnel poc-api-tunnel、Public Hostname api.dammy-otoko.com → http://api:8000 が docker-compose と整合
• DNS 移管（Squarespace → Cloudflare）は PoC で完了済み

決定: Tunnel・DNS・Hostname は再利用。作業範囲は「cloudflared の接続先を Pi から Windows PC へ移す」のみ。

参照: Manus 作業記録、 PoC ナレッジ資料（Phase 1-4）

runbook v1.1・開発ログ初版・WBS 更新

PoC Tunnel 再利用を反映し runbook v1.1、 本 開発ログ、WBS を更新。 実施順序: Docker 起動 → ローカル API 疎通 → cloudflared 移行。

Docker Desktop インストール・初回起動

Docker Desktop 4.76.0 をインストール（Per-user）。 初回の Docker Hub サインインはスキップ（ローカル compose のみ利用）。 インストール先: %LOCALAPPDATA%\Programs\DockerDesktop\

WBS 1.1.2 / 1.1.3 ローカル疎通完了

• docker compose up -d --build db api 成功
• GET /api/v1/health → {"status":"ok"}
• POST /api/v1/feedback → HTTP 201、画像は data/storage/ に保存

課題: test-feedback.ps1 の JSON 送信失敗（Windows）

事象: curl.exe -F "inference_result={...}" で inference_result must be valid JSON。

原因: インライン JSON のエスケープ破損、または UTF-8 BOM。

対応: scripts/inference.json を [System.IO.File]::WriteAllText で生成し -F "inference_result=<...json" で送信。

課題: TUNNEL_TOKEN に Tunnel ID（UUID）を設定

事象: cloudflared が Provided Tunnel token is not valid. で Restarting (255)。Tunnel 経由は Cloudflare error 1033。

原因: Tunnel ID（UUID）を設定していた。正しくは Zero Trust の Connector トークン（eyJ...）。

対応: ダッシュボードから正しいトークンを server/.env に設定。 詳細: Phase1 ナレッジ K-03

WBS 1.1.1 完了・MS-1 達成（cloudflared: Pi → Windows）

cloudflared の Windows への置き換えを完了。コミット e4defb5。

• Raspberry Pi（~/poc-api）で sudo docker compose stop cloudflared
• 本 PC で docker compose --profile tunnel up -d cloudflared → Up（precheck 成功、QUIC）
• curl.exe https://api.dammy-otoko.com/api/v1/health → {"status":"ok"}
• test-feedback.ps1 -BaseUrl "https://api.dammy-otoko.com" → HTTP 201

補足: 移行後は /ping（PoC エンドポイント）は 404 となる。 馬体診断 API では /api/v1/health を疎通確認に使用する。

課題: Git push に -m を付けて失敗

事象: git push -m "..." で unknown switch 'm'。

対応: git commit -m "..." → git push の順。 詳細: Phase1 ナレッジ K-14

移行後の再確認（エージェント検証）

ユーザー報告の移行完了後、稼働状態を再確認。

• server-api-1 / server-db-1 / server-cloudflared-1 すべて Up
• localhost・Tunnel 経由とも /api/v1/health が ok
• Tunnel 経由 POST /api/v1/feedback → HTTP 201（ID 発行・Storage 保存）

WBS 1.2.1 / 1.2.2 Flutter スタブ実装

MS-1 完了後、クライアント側スタブの実装に着手。コミット f383eae。

依存: http、image_picker。デフォルト API URL: https://api.dammy-otoko.com（config.dart、UI で変更可）。

• flutter analyze — 問題なし
• flutter test — 成功
• Android INTERNET 権限を AndroidManifest.xml に追加

残: WBS 1.2.3 — 実機検証。 Windows では symlink 警告のため開発者モードの有効化が必要な場合あり。

cd app
        flutter run

WBS 1.2.3 実機検証着手（Pixel 7a）

端末: Pixel 7a（3C261JEHN19182、Android 16 / API 36）。 USB デバッグ初回は is not authorized → 端末の許可ダイアログ承認で解消。

• flutter run -d 3C261JEHN19182 — ビルド・インストール成功（約 161s）
• NDK 26 vs 27 警告あり（ビルドは通過。後日 ndkVersion = "27.0.12077973" 追記可）
• API Base URL https://api.dammy-otoko.com — 確認 OK
• ギャラリー画像選択・ダミー推論表示（F-01 / F-02）— 確認 OK

課題: 実機 FB 送信 — HTTP 530 / error code 1033（Docker Desktop 未起動）

事象: 「フィードバックを送信」→ 送信失敗: Exception: HTTP 530: error code: 1033。

原因: PC 上の Docker Desktop が停止しており、cloudflared が Tunnel に接続していない。 MS-1 達成後に PC を再起動／Docker を終了したため再発（K-06 と同型）。

切り分け: PC から curl.exe https://api.dammy-otoko.com/api/v1/health も同じ 1033。 スマホ側の問題ではない。flutter run を止める必要もない（Docker 操作は別ターミナルで可）。

対応: Docker Desktop を起動 → docker compose --profile tunnel up -d → health 確認。

課題: 実機 FB 送信 — HTTP 400「image must be an image file」

事象: Docker 復旧後、Tunnel 経由で API には到達。 送信時 HTTP 400: {"detail":"image must be an image file"}。

原因: サーバーは multipart の image フィールドの Content-Type が image/* であることを要求（feedback.py）。 Flutter の MultipartFile.fromPath は Android キャッシュパス（拡張子なし）で MIME 推定に失敗し、 PC の test-feedback.ps1（type=image/jpeg 明示）との差分。

対応: image_picker の XFile.mimeType を feedback_client.dart の multipart に渡す。詳細: K-17。

WBS 1.2.3 完了 — 実機から Tunnel 経由 FB 送信成功

Pixel 7a（flutter run）から FB 送信に成功。WBS 1.2 スタブ Android アプリの端末検証を完了とした。

• API URL: https://api.dammy-otoko.com
• 画面: 送信成功 (HTTP 201)、ID: 2cf573f7-1b4b-47a1-a5ce-e1af31915800
• Storage: data/storage/eb29ce87-af85-4159-8a5d-abdc4f5dfd76.png 等に保存を確認
• 経路: スマホ → Cloudflare Tunnel → Windows PC（FastAPI + PostgreSQL + Storage）

次: WBS 1.3 AI Worker スタブ（学習スタブ → repository_dispatch）

WBS 1.3 実装 — AI Worker スタブ

WBS 1.3.1〜1.3.3 のコード実装を完了。実学習は行わずベース stub.tflite を versions/v{N}/ にコピーする。

• F-20: worker/training_stub.py — run_training_stub()
• F-21: worker/github_dispatch.py — trigger_github_dispatch()（event: model-updated）
• 手動起動: scripts/run-training-stub.ps1
• GHA: .github/workflows/android-build.yml（dispatch 受信・プレースホルダビルド）
• ローカル検証: --skip-dispatch で v1 生成を確認

次: WBS 1.4 — APK ビルド本実装。1.3.3 の E2E は worker/.env 設定後に dispatch 実行で確認。

WBS 1.4 / 1.5.1 実装 — GHA APK ビルド・配布手順

• android-build.yml: Flutter セットアップ → モデル同梱 → app-release.apk artifact
• アプリ: assets/models/ 同梱・画面にバージョン表示（ModelBundle）
• scripts/install-apk.ps1: adb インストール用
• runbook: runbook.html#gha

次: リモート push 後、Actions 手動実行または Worker dispatch で artifact 取得 → Pixel 7a 検証。

ナレッジ整理 — GHA / YAML / 月次パイプライン（K-19〜K-21）

WBS 1.4 着手に伴い、GitHub Actions・CI/CD の概念整理を実施。 Phase1 ナレッジ に以下を追記。

• K-19 — YAML の文法とツールごとのスキーマ（Docker Compose vs GHA）
• K-20 — android-build.yml の役割、リモート push、artifact / APK、手動ビルドの実体
• K-21 — 月次モデル更新（学習 → repository_dispatch → GHA → adb 配布、TestFlight は ②）

要点: YAML push だけではビルドは走らない（on: push なし）。 成果物は artifact に一時保存され、端末反映は PC ダウンロード + adb が Phase1 Android の想定。

WBS 1.4.1 / 1.5.1 E2E — GHA 手動ビルド → Pixel 7a 配布（A-2〜A-6）

GHA 操作手順（UI） に沿い、 workflow_dispatch 手動ビルドから実機配布まで完遂。証跡スクショは runbook に掲載。

実機確認（GHA release APK）:

• 画面上部: 同梱モデル: v1 (92 bytes)
• FB 送信: 送信成功 (HTTP 201)（ID: 0710ac54-44f8-41ec-b83b-aca8c12b02af）
• DEBUG リボンなし（release ビルドとして正常）

副次対応: install-apk.ps1 を Android SDK の adb.exe 自動検出に修正（PATH 未設定対策）。

次: WBS 1.4.3 — run-training-stub.ps1 による repository_dispatch 通し検証。

実施内容

1. worker/.env.example を worker/.env にコピー（gitignore 済み、commit しない）
2. Classic PAT をユーザー Settings → Developer settings で発行（repo スコープ）。リポジトリの Actions Secrets ではない — K-22
3. GITHUB_REPOSITORY=makoto55879/github-actions-test を設定
4. .\scripts\run-training-stub.ps1 実行

コンソール結果:

• [1/2] 学習スタブ: models/versions/v2/horse_model.tflite 生成（前回 v1 済みのため v2）
• [2/2] dispatch: event model-updated、status: 204

GitHub Actions: Android Build #2 が Repository dispatch で起動（方法 A の #1「Manually run」とは別トリガー）。

参照: GHA 操作手順 §B、Worker 手順 §3〜5。

実施内容

1. Android Build #2 成功 → Artifacts app-release-apk-v2 を PC にダウンロード・ZIP 解凍
2. Pixel 7a（3C261JEHN19182）へ release APK を install:

.\scripts\install-apk.ps1 `
          -ApkPath "C:\Users\wt2bp\Downloads\app-release-apk-v2\app-release.apk" `
          -DeviceId 3C261JEHN19182

install 時のエラーと対処:

• 初回: INSTALL_FAILED_UPDATE_INCOMPATIBLE（既存 com.horsediagnosis.horse_stub の署名不一致）
• 対処: adb uninstall com.horsediagnosis.horse_stub → 再 install → Success
• 方法 A（v1）でも同症状。デバッグ版（flutter run）残留時や release 上書き時に発生しうる — K-13

方法 B 通し確認（1.5.2）:

実機確認（方法 B release APK）:

• 画面上部: 同梱モデル: v2 (92 bytes)
• API Base URL: https://api.dammy-otoko.com
• FB 送信: 送信成功 (HTTP 201)
• DEBUG リボンなし（release ビルドとして正常）

証跡: GHA 操作手順 図 B-4b（10-app-release-v2.png）

次: WBS 1.5.3 — ① 完了レビュー。

① Android 向け検証 完了レビュー

1.5.2 の方法 B E2E をもって、検証計画 の ① 完了条件 4 項目すべてを満たしたと判定。 成果物: records.html#review。

• MS-0〜MS-3 すべて達成
• runbook 5 体系 + ナレッジ K-19〜K-23 で再現性を確保
• 月次フロー（Worker dispatch → GHA → artifact → adb → FB）確立

次: ② iPhone 向け検証 — Apple Developer Program 加入判断後、WBS 2.1 から。並行して WBS 3.1 本番移行設計。

• integrations/github_actions_client.py — GitHubActionsClient（山梨大 Worker 組み込み用）
• integrations/notifier.py — 開発者 Webhook 通知
• scripts/archive-apk.ps1 / rollback-apk.ps1 — ローカル APK 世代管理
• server/api/sql/001_schema.sql + DB スキーマ
• 山梨大 GHA 連携ガイド
• 本番導入計画（test_plan_draft.html v0.1 を MS-3 実績で同期）

MS-3 後の振り返りで、本番導入計画 はコンポーネント構築までで、 ゴーライブ以降の監視・定常運用が未計画であることを確認。

• プロジェクト振り返り — ギャップ分析・優先度
• 運用・監視計画 v0.1（ドラフト）
• WBS・ガント v2.1 — WBS 3 追加、MS-6 / MS-7 設定
• 本番導入計画 v1.1 — Step 7（ゴーライブ）・Step 8（運用体制）追加

次: WBS 3.1 本番移行設計から着手。3.1.4 セキュリティ（API 認証）は MS-6 前必須。山梨大 Worker 結合（3.2）は並行調整。

基本設計のセキュリティは HTTPS + PII 禁止の 1 行のみ。実装は /api/v1/feedback が無認証のまま。

• セキュリティ設計 v0.1 — 脅威モデル、SEC-01〜08、MS-6 前チェックリスト
• セキュリティ設計 v0.2 — OSI/FW、.env 方針、実測手順 §9
• WBS 3.1.5 セキュリティ実測確認（学習目的）を追加

セキュリティ設計の理解に OSI・HTTPS・FW 等の前提が必要とのフィードバックを受け、 これまでの Q&A を Phase1 ナレッジ に集約。

• K-24 OSI・FW・ネットワーク境界
• K-25 HTTPS・Tunnel（何を守る/守らない）
• K-26 公開 URL・API 認証・アップロード制限
• K-27 シークレット・.env・ローテーション
• K-28 Cloudflare Access・ログ・PII・実測（3.1.5）
• K-29 セキュリティを考える共通の型
• 用語集 v1.5 — セキュリティ用語 14 件追加

設計の正本: セキュリティ設計。推奨読了順は K-24 → K-29。用語は 用語集。

MS-3 後のセキュリティ学習として、Tunnel 経由の FB・DB・Storage・ログ・無認証 POST・localhost 裏口を確認。

• Tunnel: test-feedback.ps1 → 201（id df37d39d-...）
• DB: PII なし（inference JSON + 画像パスのみ）
• ログ: body 全文は出ず（メソッド・パス・ステータスのみ）
• 無認証 POST 可能 → SEC-01（API キー）の必要性を実感
• localhost:8000 で health OK → SEC-03（bind 制限）の必要性を実感

記録: K-28 実測記録。次: WBS 3.1.4（SEC-01〜04 実装）。

• SEC-01: FEEDBACK_API_KEY 設定時に Authorization: Bearer 必須（app/deps/auth.py）
• SEC-02: MAX_UPLOAD_BYTES 超過で HTTP 413
• SEC-03: docker-compose ポートを 127.0.0.1:8000:8000 に変更
• SEC-04: デフォルト DB パスワード検知の起動 WARNING + server/env.example
• クライアント: test-feedback.ps1 -ApiKey、Flutter --dart-define=FEEDBACK_API_KEY=...

検証: 無認証 401 / キーあり 201 / oversized 413 / Tunnel 経由 201（キー未設定時）。

• 誤設定: FEEDBACK_API_KEY を worker/.env に追加してしまった（正しい置き場所は server/.env のみ）。誤記載は削除済み
• 症状: test-feedback.ps1 で health は ok だが POST が 401 invalid api key。プレースホルダ警告あり
• 解消: Remove-Item Env:FEEDBACK_API_KEY → rotate-server-secrets.ps1 -ApiKey -RestartApi → Tunnel 経由で HTTP 201（id 58b80bce-...、2026-06-14）
• ドキュメント: README に「リポジトリ構成とシークレット」、docs/index.html 同セクション、サイドバー「リポジトリ・シークレット」グループを追加
• ナレッジ: K-30 に .env 配置ミスと 401 の整理を追記
• deny 実測: 誤キー → 401 invalid api key、認証なし → 401 missing or invalid authorization header（K-30 deny）

記録: K-30。次: WBS 3.1.1 本番移行設計を継続。Flutter 本番ビルドへ --dart-define=FEEDBACK_API_KEY を渡す手順の整理。

• android-build.yml: secrets.FEEDBACK_API_KEY → --dart-define で APK に同梱
• scripts/build-flutter-apk.ps1: ローカル release ビルド（server/.env 自動読み込み）
• 手順: runbook-phase1-gha §4b

2-B 完了: 2026-06-15 マイルストーン を参照。

• GitHub → Settings → Secrets and variables → Actions → FEEDBACK_API_KEY 登録
• Android Build 手動 run（model_version ラベル付き）→ 成功（約 7m）
• ビルドログ: FEEDBACK_API_KEY is set (length …) を確認

手順・スクショ: runbook §4b-1〜4b-6。注意: Secret 値は = 右のみ。length がローカル（43）と一致するか要確認。

• build-flutter-apk.ps1 → server/.env から鍵同梱（長さ 43）
• 副次修正: feedback_client.dart の import '../config.dart';（release ビルドエラー解消）
• Pixel 7a（3C261JEHN19182）: INSTALL_FAILED_UPDATE_INCOMPATIBLE → uninstall 後 install Success
• 実機 FB: HTTP 201（ID: 77d54315-7fe9-4c82-a48f-4fd628ec9067a）
• 表示: 同梱モデル: local-dev (92 bytes)（ローカル release ビルドのため GHA 版 vN ラベルではない）

証跡: runbook §4c 図 4c-1。SEC-01 経路: サーバー + test-feedback.ps1 + Flutter APK（ローカルビルド）が揃った。

• 初回失敗: Secret に FEEDBACK_API_KEY=... 行全体を貼り付け → ビルドログ length 68 → 実機 FB 401 invalid api key
• 修正: Actions Secret を = 右側のみに更新 → 再ビルド → ログ length 43（2-A と一致）
• Pixel 7a（3C261JEHN19182）: uninstall → GHA artifact install Success
• 実機 FB: HTTP 201（ID: f3119e16-6f20-41d7-915b-15807b25c8fe）
• 表示: 同梱モデル: v2 (Add Secrets) (92 bytes)

証跡: runbook §4c 図 4c-2。SEC-01 クライアント検証（WBS 3.1.4）完了: 2-A（ローカル）・2-B（GHA）の両経路で実機 FB 201。

• 方針: 本番正は パターン A（DB + Storage 直）。B Export API は代替として実装済み
• 環境: 検証は開発者 PC、本番は役場 PC（山梨大コンポーネントは最終的に役場へ）
• FB 想定: 月 100 件以下 — DB レスも可能だが Phase1 は PostgreSQL 維持
• DB: 002_feedback_lifecycle.sql / B 用 API（pending・consume・image）

• 71ff554: 計画 / Runbook / 連携 / 設計 / 参照 / 記録 / ナレッジ + トップの 8 ページ構成
• 旧 HTML はリダイレクトスタブ（例: integration-boundary.html → integration.html#boundary）
• 統合版へリンク統一・パターン A 方針・PC 移設 §5 を追記

• トップ（index §1）: 計画→設計→構築・運用→連携→参照→記録の 6 層 + ナレッジ
• 各ページ冒頭に「この文書について」（目的・読者・標準章との対応表）
• Runbook を「構築・運用手順書」、サイドバーを ①〜⑥ の層番号に統一