review02: サーバ改修（フェーズ2着手分）の報告と確認事項

作成日: 2026-08-10 対象: zxell-main/zxell_server（ロードマップ 3.6「サーバ実装の改修方針」8 項目に対応）

1. 実施内容

roadmapplanning.md 3.6 の表の全項目、および 3.3 の API 案に沿って zxell_server を全面改修した。

#	3.6 の改修方針	実施内容
1	本文はシャードへ、DB はメタデータのみ	`TrainingData`（記事 1 件＝1 タスク）を廃止。タスクは `type` + `payload`（シャード名・基準重みバージョン・ローカルステップ数 H）を持つ汎用構造に。シャード実体は `ZXELL_STORAGE_DIR/shards/` に置き `GET /api/shards/{name}` で配布
2	リース期限＋自動再キュー	`GET /api/tasks/next` はリース期限付き払い出し（既定 1 時間、`ZXELL_LEASE_SECONDS`）。期限切れは自動で pending に戻り、規定回数（max_attempts、既定 3）超過で failed
3	結果の永続化	`POST /api/results` で `results` テーブルに永続化。metrics（JSON）と成果物ファイル（Δ 等、multipart）を受領。Δ はストレージに保存しパスを記録
4	認証	クライアント登録制（`POST /api/clients/register` で API キー発行）＋全クライアント API で `X-API-Key` 必須。管理系 API（タスク投入・重み登録）は `X-Admin-Key`
5	DB 接続情報の環境変数化	pydantic-settings 導入。`ZXELL_DB_URL` 等の環境変数 / `.env` で設定（メモにあった `ZXELL_DB_URL` がそのまま使える）
6	Pydantic v2 移行	`orm_mode` → `from_attributes`。requirements.txt をサーバ実機（Python 3.8）で動作確認済みの版に固定
7	重み配布	`weight_versions` テーブルでバージョン管理（checksum・サイズ付き）。`POST /api/weights`（管理）で登録、`GET /api/weights/latest` / `GET /api/weights/{version}/download` で配布
8	排他払い出し	`SELECT ... FOR UPDATE SKIP LOCKED` による二重払い出し防止（PostgreSQL 9.5+ で動作。実機の PG10 で問題なし）

その他:

タスク種別を preprocess / train / eval / verify の 4 種で定義（3.3 準拠）。 ?types=train のように希望種別で絞って払い出しを受けられる（GPU/CPU の役割分担用）。
train タスクの結果提出には基準重みバージョン（base_weight_version）を必須化（ステイルネス対策の前提となるデータ）。
GET /api/status でタスク集計・クライアント一覧・最新重みを返す（ダッシュボード v1 のデータ源）。
README.md を刷新（セットアップ手順・環境変数・API 一覧・curl 利用例）。
未使用依存（asyncpg / databases）を削除。

2. 確認事項

旧データの有無: 実機の zxell_db に旧 training_data テーブルへ投入済みのデータはありますか。新コードは旧テーブルを参照しない（残っていても無害）ため、データが無ければ対応不要です。あれば移行スクリプトを用意します。

アーキテクト回答データはありません。

省略: 確認事項 2(作業環境の移行)

クライアント登録の方式: 現状 POST /api/clients/register は誰でも呼べます（同一 LAN・closed 運用前提の最小構成）。登録自体にも管理キーを必須にしますか。 → 当面 LAN 内運用なら現状案で十分と考えますが、外部公開の予定が早まるなら承認制にします。

アーキテクト回答Web自体はLAN外からもアクセスできると思うので、承認制にしてください。

/api/status の公開範囲: ダッシュボード用に認証なしとしています（クライアント名・稼働状況が見える）。LAN 内運用なら問題ないはずですが、認証を掛けるか確認させてください。

アーキテクト回答Web自体はLAN外からもアクセスできると思うので、認証を掛けてください。

省略: 確認事項 5〜7(ストレージの場所、サーバ OS の更新、コーパスの所在と形式)

クライアント実装の置き場所: クライアント（zxell-client、PyTorch ベース）は同一リポジトリ内 zxell_client/ に置く想定でよいですか（別リポジトリにする案もあり）。 → 当面はモノレポ（同一リポジトリ）を推奨します。サーバとスキーマを共有しやすいため。

アーキテクト回答同一リポジトリ内 zxell_client/ に置く想定でよいです。

3. 次の作業予定（確認待ちの間に着手可能なもの）

クライアント v1 の雛形（登録 → タスク取得 → ダミー処理 → 結果提出のループ、リトライ・ベンチマーク自己申告付き）
運用ダッシュボード v1（/api/status を表示する軽量 Web ページ）
前処理パイプラインの骨組み（言語判定・クリーニング・重複除去・トークン化 → シャード化。確認事項 7 の情報が得られ次第、実データ対応）