版数: 1.2 | 更新日: 2026-06-15 | 層: ⑤ 参照

参照資料

この文書について（標準付録・リファレンスの構成）

目的	本文を読まずに用語・スキーマを引ける辞書として機能する
想定読者	全担当者（必要なときだけ開く）
いつ読むか	不明な用語、DB テーブル・カラムの確認時

設計の説明は設計資料、手順は Runbook。本ページは定義の正本として使います。

§1 用語集

インフラ・セキュリティ関連の詳しい説明は Phase1 ナレッジ（K-24〜K-29）、設計はセキュリティ設計を参照。

アプリ・インフラ（既存）

用語	英語	説明
FB / フィードバック	Feedback	アプリ利用者が送信する診断結果・画像・修正情報。本プロジェクトでは個人情報を含まない
オンデバイス推論	On-device Inference	端末内の ML モデル（TFLite / CoreML）で推論を行う方式。クラウド API 不要
Cloudflare Tunnel	—	CGNAT 環境の自宅 PC をインターネットから安全にアクセス可能にするトンネルサービス。詳細は Phase1 ナレッジ
Connector Token	—	cloudflared が Tunnel に接続するための認証文字列（`eyJ...` 形式）。`TUNNEL_TOKEN` に設定。Tunnel ID（UUID）とは別物
cloudflared	—	Cloudflare Tunnel のクライアント。自宅 PC から Cloudflare へ外向き接続し、Edge からのリクエストをローカル API へ中継
AI Worker	—	FB データを用いてモデルを再学習し、新モデルファイルを生成するバッチ処理コンポーネント
repository_dispatch	—	GitHub REST API 経由でワークフローを起動するトリガー。Worker の `model-updated` で Android Build を自動起動（PAT 要）。詳細: K-22
スタブ	Stub	本番機能の代替となる最小実装。インフラ検証用にダミー処理で構成する
YAML	—	設定を人間が読みやすい形式で書くファイル形式（`.yml`）。文法は共通だが、キーの意味はツールごとに異なる。詳細: K-19
GitHub Actions	—	GitHub 上で CI/CD ワークフローを実行するサービス。本プロジェクトでは APK ビルドに使用
workflow_dispatch	—	GitHub Actions を Web UI から手動起動するトリガー。Actions → Run workflow
PAT	Personal Access Token	PC から GitHub API を叩くためのトークン。Worker dispatch 用は `worker/.env` に置く（Actions Secrets とは別）。詳細: K-22
adb	Android Debug Bridge	PC から Android 端末を操作する公式ツール。APK インストール（`adb install`）等。本体は Android SDK `platform-tools\adb.exe`。`install-apk.ps1` は PATH 未設定でも自動検出
APK	Android Package	Android アプリのインストール用ファイル。GHA ビルド成果物は `app-release.apk`
artifact	—	GitHub Actions の1実行ごとの成果物保管。ブラウザから ZIP ダウンロード可能（本プロジェクトは 30 日保持）。リポジトリには commit されない。詳細: K-20
TFLite	TensorFlow Lite	Android 向けオンデバイス ML モデル形式。①検証で使用
CoreML	—	iOS 向けオンデバイス ML モデル形式。②検証で使用
TestFlight	—	Apple 公式のベータ配布サービス。Apple Developer Program 加入が必要（追加料金なし）
CGNAT	Carrier-Grade NAT	キャリア側 NAT により自宅回線にグローバル IP が無い環境。Tunnel が必要な理由
runbook	—	運用手順書。障害対応・定期更新の手順を記載し、属人化を防ぐ

セキュリティ・ネットワーク（2026-06-12 追加）

用語	英語	説明
OSI 参照モデル	OSI Reference Model	ネットワーク通信を 7 層に分けた整理の枠組み。本プロジェクトでは層 3〜4（IP・ポート）と層 7（HTTP/API）が重要。詳細: K-24
ゾーン	Zone	信頼度や到達範囲が違うネットワーク領域の区切り（例: インターネット、LAN、役場 PC 内）。境界をまたぐたびに門番があるか確認する。詳細: K-24
ネットワーク境界	Network Boundary	ゾーンとゾーンの境目。「誰がどこから何に届くか」が変わる線。FW・API 認証は境界に置く。詳細: K-24
ファイアウォール	Firewall (FW)	主に IP・ポート単位で通信の通過を許可/拒否する門番（多くはソフトウェア）。HTTP の内容や利用者認証は別層の役割。詳細: K-24
HTTPS / TLS	HTTPS / TLS	通信路上の盗み見・改ざんを困難にする暗号化（層 6）。「正規アプリだけが使える」ことは保証しない。詳細: K-25
公開 URL	Public URL	インターネットから到達できる入口の住所（例: `https://api.dammy-otoko.com/api/v1/feedback`）。Cloudflare 経由で PC 内 API に転送される。詳細: K-26
API 認証	API Authentication	リクエスト送信者が正当かを層 7 で確認すること。本番案は `Authorization: Bearer` の API キー（SEC-01）。詳細: K-26
API キー	API Key	クライアントが API を叩く際に付ける共有秘密。サーバー `.env` とアプリに配布。HTTPS と併用。詳細: セキュリティ設計 SEC-01
シークレット	Secret	漏洩するとなりすまし・不正操作につながる文字列（DB パスワード、PAT、`TUNNEL_TOKEN`、API キー等）。`.env` + gitignore で管理。詳細: K-27
多層防御	Defense in Depth	HTTPS・FW・API 認証・DB 非公開など、層の違う対策を重ねる考え方。一つだけでは不十分。詳細: K-29
Cloudflare Access	—	URL にアクセスする前に人の認証（メール等）を挟む Zero Trust 機能。Pages のメール認証と概念は近いが、モバイルアプリの自動 API POST には API キーが向く。詳細: K-28
PII	Personally Identifiable Information	個人を特定できる情報。本プロジェクトでは FB に含めない方針。実際の保存内容は WBS 3.1.5 で実測確認。詳細: K-28
`.env`	—	環境変数・シークレットを置くローカル設定ファイル。git に含めない。DB パスワードもここに置く（DB テーブルに秘密を入れるのは一般的でない）。詳細: K-27
ローテーション	Rotation	シークレットを計画的に取り替えること。漏洩リスクの保険。PAT は四半期が目安。詳細: K-23・K-27

§2 DB スキーマ

本番構築に向けた DB 設計です。DDL は server/api/sql/001_schema.sql に格納しています。

1. 実装済み（Phase 1）

feedbacks

クライアントからのフィードバック（画像パス + 端末内推論 JSON）。

カラム	型	説明
`id`	VARCHAR(36) PK	UUID
`image_path`	VARCHAR(512)	Storage 内パス
`inference_result`	TEXT	JSON 文字列（label, score 等）
`created_at`	TIMESTAMPTZ	受信日時
`consumed_at`	TIMESTAMPTZ NULL	Worker 取込済み（`002_feedback_lifecycle.sql`）
`archived_at`	TIMESTAMPTZ NULL	アーカイブ移動日（将来ジョブ）

SQLAlchemy モデル: server/api/app/models.py の Feedback。

2. 計画（Phase 2 — 山梨大 Worker / 運用連携）

training_jobs

再学習ジョブ 1 回分のメタデータ。

カラム	型	説明
`id`	VARCHAR(36) PK	ジョブ ID
`status`	VARCHAR(32)	pending / running / completed / failed
`triggered_by`	VARCHAR(128)	manual / cron / webhook 等
`started_at`	TIMESTAMPTZ	開始
`completed_at`	TIMESTAMPTZ	完了
`model_version`	VARCHAR(32)	出力バージョン（v3 等）
`model_path`	VARCHAR(512)	出力ファイルパス
`feedback_count`	INTEGER	学習に使用した FB 件数（任意）
`error_message`	TEXT	失敗時
`created_at`	TIMESTAMPTZ	レコード作成

model_versions

公開モデル一覧（Android: TFLite / iOS: CoreML）。

カラム	型	説明
`version`	VARCHAR(32) PK	v1, v2, …
`format`	VARCHAR(16)	tflite / coreml
`file_path`	VARCHAR(512)	ストレージ上のパス
`training_job_id`	VARCHAR(36) FK	生成元ジョブ
`is_active`	BOOLEAN	現行配布版フラグ
`created_at`	TIMESTAMPTZ	登録日時

deployments

GHA ビルド・端末インストール履歴（ロールバック参照用）。

カラム	型	説明
`id`	VARCHAR(36) PK	デプロイ ID
`platform`	VARCHAR(16)	android / ios
`model_version`	VARCHAR(32) FK	同梱モデル
`artifact_name`	VARCHAR(256)	例: app-release-apk-v2
`github_run_id`	VARCHAR(64)	Actions run ID
`github_run_url`	VARCHAR(512)	実行 URL
`status`	VARCHAR(32)	built / installed / rolled_back / failed
`installed_at`	TIMESTAMPTZ	adb install 日時
`device_id`	VARCHAR(64)	adb デバイス ID
`created_at`	TIMESTAMPTZ	レコード作成

notification_log

開発者通知の監査ログ（Webhook 送信の成否を記録）。

Phase 2 テーブルと Worker のデータ取得・削除ポリシーの合意たたき案は外部連携 §1 連携境界（会議用質問表付き）を参照。

3. ER 概要

        erDiagram
          feedbacks ||--o{ training_jobs : "feeds"
          training_jobs ||--o| model_versions : produces
          model_versions ||--o{ deployments : bundled_in

feedbacks と training_jobs の関連は将来 M:N 中間テーブル化する可能性があります（現 DDL はシンプル化）。

4. APK ローカルアーカイブ（DB 外）

ロールバック用 APK は PostgreSQL ではなく data/apk-archive/manifest.json + ローカルファイルで管理します（K-23 方針）。

スクリプト	用途
`scripts/archive-apk.ps1`	artifact 取得後にバージョン付きで保存
`scripts/rollback-apk.ps1`	`-Previous` または `-Version` で再 install

5. 適用方法（参考）

# 計画テーブルは未適用。必要時に:
        docker compose -f server/docker-compose.yml exec db \
          psql -U app -d feedback_db -f /path/to/001_schema.sql

現行 API 起動時は SQLAlchemy が feedbacks のみ自動作成します。