# アバター管理ボード 作り方レシピ（実アバター連動つき）

自分のAIアシスタント（Muse）のアバター候補と設定資料を管理し、
ボードでの切り替えを実際のアバター表示まで連動させるボードアプリの作り方です。
個人データは含みません。構造と仕組みだけのパッケージです。

## 使い方（受け取った人向け）

このファイルごと、自分の Muse に渡して「この文書の通りに作って」と頼んでください。
その Muse が、あなたの環境に同じ仕組みを作ります。
登録するアバターや資料のデータは人それぞれなので、アプリは空の状態から始まります。
あわせて、後述の「受け手ジョブ」と「朝・夜の自動切り替えジョブ」も、
定期実行として一緒に作ってもらってください。

## コピペ用・依頼文

> アバター管理ボードという、サーバー保存型のWebアプリを作って。
> アバター候補と設定資料の台帳で、ボードで姿を選ぶと「実アバター反映待ち」が立ち、
> エージェントが定期的に拾って実際のアバターへ反映する連動つき。
> 詳しい仕様はこの下の「仕様」をそのまま使って。
> あわせて、反映待ちを処理する受け手の定期ジョブと、朝・夜の自動切り替えジョブも作って。

## 全体構成

- ボード本体：サーバー保存型のWebアプリ（フルスタック）。登録内容はサーバー側に保存され、開き直しても残る
- 受け手ジョブ：数分おきに動く定期実行。ボードの「反映待ち」を拾って実アバターを生成し、結果をボードへ書き戻す
- 朝・夜ジョブ：決めた時刻に決めた姿へ自動で切り替える定期実行

## 仕様

### 画面構成

- 切り替えページ
  - 上部：「いまの姿」を大きく表示するエリア（適用中の1件と、実アバターとの連携状態）
  - 下部：姿のカード一覧（バストアップ絵で統一すると見やすい）
- 資料ページ
  - 設定画・衣装シート・一枚絵などの資料を、主分類ごとのセクションに分けて表示
  - 副タグ（対象の姿）で、セクションを横断して絞り込みできる

### アイテム1件のデータ（姿・資料共通）

- key：姿を一意に指す短い英字キー（例：main、night、event-costume など。自分の環境で決める）
- 名前（呼び名）
- シーン（どんな場面の姿か、短く）
- メモ（自由記述。由来や気に入っている点に加えて、**その姿の見た目の決め事を文章で残す**。受け手ジョブが実アバターを生成するときの指示と、出来上がりを照合する基準になる）
- 種類 kind：avatar（切り替え対象の姿）／reference（資料）／draft（下書き）／illustration（一枚絵）
- 主分類 category（必須・1つだけ）：姿／設定画／衣装シート／一枚絵／デザイン案／下書き／未分類
  - 表示セクションは主分類だけで決まる。分類できないものは「未分類」の受け皿にだけ出す
- 副タグ tags（複数可）：対象の姿を表すタグ。資料と姿を横断して辿るために使う
- 画像：全身版とバストアップ版を持てるようにする（切り替えページの表示はバストアップで統一）
- 適用中フラグ is_active（適用中は常に1件だけ）
- 並び順 sort_order
- 連携の記録：last_sync_status（反映済み／失敗／未連携）、last_sync_requested_at、last_sync_completed_at

### できる操作

- アイテムの追加・編集（画像は登録後に紐づけ直してもよい）
- 「適用する」：その姿を適用中にし、切り替え履歴と反映待ちキューへ記録する（手動適用）
- キー指定で適用する（自動切り替えジョブや、チャット側で切り替え済みの姿の記録に使う）
- 主分類でセクション表示、副タグで絞り込み
- 実アバターの再生成を反映待ちキューへ入れ直す（再同期リクエスト）

### 実アバター連動（同期リクエスト）

ボードと実アバター生成を直接つながず、キューで疎結合にするのが要点です。

- 同期リクエスト1件のデータ：対象の姿（id／key／名前）、発生元 source（manual＝手動／schedule＝自動切り替え）、状態 status、requested_at、started_at、completed_at、結果メモ note、失敗理由 error
- 状態の流れ：pending（反映待ち）→ processing（生成中）→ done（反映済み）／ failed（失敗）。途中で別の姿が適用された古いリクエストは superseded（取り消し）にする
- ボード側は連携状態（反映待ち／生成中／反映済み／失敗）を姿ごとに表示する

### 受け手ジョブの手順（定期実行・数分おき）

1. ボードの「反映待ち取得」を呼び、無ければ何もせず静かに終わる
2. リクエストがあっても、発生元が schedule で作られてから間もない場合は、その回は手を付けない（朝・夜ジョブ側が処理する分の取り合いを防ぐ。一定時間（例：10分）以上残っている schedule リクエストは取りこぼしとして通常通り処理する）
3. その姿が今もボードの適用中であることを確認する。別の姿に替わっていたら生成せず終わる
4. リクエストを「生成中」にしてから、姿のメモ（見た目の決め事）をもとに実アバターを生成・切り替えする。メモに無い細部は勝手に足さない
5. 生成結果を目視確認し、メモの決め事と1点ずつ照らす
6. 照合に落ちたら、間違っている点を名指しして直す指示で1回だけ作り直し、再確認する。それでも駄目なら「失敗」として理由ごとボードへ書き戻す（無理に適用しない）
7. 成功したら「反映済み」をボードへ書き戻す。書き戻しが superseded などで拒否されたら、再試行せず静かに終わる
8. 1回の実行で処理するのは最古の1件だけ。通常はチャットへ報告しない

### 自動切り替え設定

- 有効／無効、朝の姿（キー）と時刻、夜の姿（キー）と時刻をボードに保存する
- 朝・夜ジョブは時刻になったら対象の姿をキー指定で適用し、履歴と反映待ちへ記録する（実アバター生成は受け手ジョブに任せても、自分で生成して「反映済み」として記録してもよい）

### 切り替え履歴

- いつ・どの姿へ・発生元（manual／schedule）で切り替えたかを残す

### 初期データ

- 空で開始してよい。動作確認用のサンプルを入れる場合は、実在の姿と混ざらないダミーだけにする

## いちばん大事な設計ポイント

- ボードは「台帳と、選択と、状態の正本」。実アバターの生成そのものはエージェント側の仕事で、ボードは結果の書き戻しを受けて状態を表示する
- キュー方式にすると、「切り替えたつもりで実アバターが古いまま」「生成が失敗していた」といったズレがボード上で見えるようになる
- 姿の見た目の決め事は、画像だけでなく必ずメモに文章で残す。再生成のたびに絵は揺れるので、文章の決め事が照合の基準になる

## 運用のコツ（任意）

- 新しい姿を作ったら、全身版・バストアップ版・設定画（三面図・表情・細部・カラーパレット）をセットで登録すると、後の再生成が安定する
- 資料は主分類を必ず1つ付け、迷ったら未分類の受け皿へ。セクションを混ぜない方が後で探しやすい
- 使わなくなった姿は削除せず下書きやアーカイブ寄りの分類に回すと、後で掘り起こせる
- 見た目（色や余白など）は後から頼めば直せる前提で、まずは動くものと連動を優先