# アバターRP管理ボード 設計図

この文書は、「キャラクター／アバターの画像と設定をカードで管理するボード」を他の人（またはAI）が再現して作れるようにするための仕様書です。
組み立てるときは、まず **第5章の質問リスト** に答えて機能の取捨選択をしてから、第2〜4章の該当モジュールを実装してください。

---

## 1. 設計思想

1. **ボードは「参照と保管」の場所**。実際のアバター切り替えやRPの演技は、ボードの外（チャット側・AI側）が行い、ボードは正本の台帳として機能する。
2. **カード1枚で完結**。生成やRPで参照するとき、そのキャラの情報はカード1枚だけ見れば足りるようにする。長い履歴や経緯はカードに書かず、外部の記録に置く。
3. **項目は汎用に保つ**。特定用途専用の項目（例：撮影用NG欄）は作らず、自由記述のメモに集約する。どんなキャラにも使えるボードにするため。
4. **状態は2つに分ける**。「ボード上で使いたいもの（使用中）」と「実際に適用されているもの（適用済み）」を別々に持ち、ズレを「予約」として扱う。

---

## 2. 全体構成

- フロントエンド＋DBを持つWebアプリ（カードとボード状態をサーバー側に保存）。
- 画面は「一覧（タイル）／詳細（シート）／作成・編集フォーム」の3つが基本。
- 画像は外部URLではなく **アプリに同梱したアセット** として保持する（第4章 M8 が重要）。
- （任意）AIエージェントから操作するためのアクションAPI（第4章 M11）。

---

## 3. データモデル

### 3.1 カード（Card）

| 項目 | 型 | 必須 | 説明 |
|---|---|---|---|
| id | 数値 | ○ | 一意ID |
| name | 文字列 | ○ | キャラ／衣装の名前。同名は不可 |
| subtitle | 文字列 | | 名前の下の1行（例：フルネーム ・ 種族 ・ 年齢） |
| description | 文字列 | | 短い要約（2文程度） |
| category | 文字列 | ○ | 分類（例：日常／イベント／キャスト） |
| palette | 色コード | | 画像が無いときのタイルの色 |
| image_key / image_hash | 文字列 | | メイン画像のアセットキーとSHA-256 |
| images | 配列 | | 複数画像 [{image_key, image_hash}]。先頭がメイン画像 |
| status | held / archived | ○ | 手持ち／アーカイブ |
| is_default | 真偽 | | デフォルトカード（1枚だけ） |
| is_favorite | 真偽 | | お気に入り |
| queue_rank | 数値 or null | | 「次に使いたい」キューの順位 |
| sort_order | 数値 | ○ | 一覧の並び順 |
| use_case | 文字列 | | 用途メモ |
| prompt_memo | 文字列 | | 画像生成用のメモ（短い英語タグ等） |
| profile_body | 文字列 | | 体格（身長・スリーサイズ等） |
| profile_hair | 文字列 | | 髪 |
| profile_eyes | 文字列 | | 目 |
| profile_outfit | 文字列 | | 衣装 |
| profile_role | 文字列 | | 職業・役割 |
| rp_personality | 文字列 | | RP：性格・演じ方 |
| rp_speech | 文字列 | | RP：セリフの癖・口調 |
| rp_situation | 文字列 | | RP：想定シチュエーション |
| rp_hook | 文字列 | | RP：導線・フック（そのキャラとの関わり方） |
| rp_tags | 文字列 | | RPタグ（空白区切り） |
| memo | 文字列 | | 自由メモ。安全情報（NG・ストップ合図等）もここに集約する運用を推奨 |

### 3.2 ボード状態（BoardState、1件だけ）

| 項目 | 説明 |
|---|---|
| board_active_id | ボード上で「使用中」のカード |
| applied_id | 実際に適用済みのカード |
| current_avatar | 現在の表示アバターのスナップショット（識別情報・image_key・image_hash） |

- board_active ≠ applied の状態が「予約あり」。両方を揃える操作で解消する。
- キューは各カードの queue_rank で表現する（付け直すと最後尾）。

---

## 4. 機能モジュール

各モジュールは独立に採否を選べます。第5章の質問と対応しています。

### M1 カードCRUD・並び替え（必須）
- 作成／編集／削除（削除はアーカイブ済みのみ可、デフォルトは不可）、一覧の並び替え。

### M2 ステータス管理（必須）
- 手持ち／アーカイブの切り替え、デフォルト指定、お気に入り。

### M3 着替えモデル（使用中／適用済み／予約／キュー）
- 「このアバターを使う」＝使用中だけを変更し、予約を発生させる。
- 実際に切り替えた後、使用中と適用済みを揃える。
- 予約の解消は「適用済みに合わせる」「使用中に合わせる（取消）」の2方向。
- 「次に使いたい」キュー（複数可、順位つき）。キュー先頭を予約・適用する操作。

### M4 検索・フィルタ
- テキスト検索は name／description／memo／プロフィール各行／RP項目／prompt_memo を対象にする。
- rp_tags のチップによる絞り込み。

### M5 プロフィール構造化表示
- 詳細では説明文の塊ではなく、体格／髪／目／衣装／役割のラベル付き行で表示する。性格は rp_personality をそのブロックに表示。

### M6 RP項目
- 性格／口調／シチュエーション／導線／タグの5項目。フォームと詳細に「RP設定」セクションを作る。

### M7 複数画像ギャラリー
- 詳細の画像エリアは縦長 **4:5・横幅いっぱい**。横スワイプ／ドット／前後ボタン／「画像N枚 ・ n/N」カウンタで切り替え。
- 一覧タイルには「画像N枚」バッジ。編集フォームでは画像キーを1行1つで複数指定し、先頭がメイン。

### M8 画像アセットの同梱（最重要の落とし穴）
- **image_key とハッシュをDBに登録しただけでは画像は表示されない。** 実ファイルをアプリのアセットとして同梱し、キーで引けるようにする工程が必須。
- 登録手順は2段構え：①カードにキーとハッシュ（元ファイルのSHA-256）を登録 → ②実ファイルをアセットとして同梱し、ハッシュ一致を確認。
- 画像が表示されないトラブルの大半は②の欠落。

### M9 詳細UIの操作性
- 詳細シートの外側（背景）クリック／タップで閉じる。中側のクリックや画像スワイプでは閉じないようにする（`e.target === e.currentTarget` 判定）。作成モーダルも同じ挙動に揃える。

### M10 キャラカードエクスポート
- 詳細のアクションエリアに「キャラカードをエクスポート」ボタンを置く。
- そのカードのメイン画像に、Character Card V2形式のJSONをBase64化してPNGの tEXt チャンク（キー `chara`）に埋め込み、「<カード名>_chara-card.png」をダウンロードさせる。
- **埋め込むのは、そのカードの詳細に表示されている項目だけ**。外部データの参照や、項目に無い内容の創作はしない（例：挨拶文 first_mes はボードに項目が無いので空）。
- name ← name
- description ← description ＋ 空でないプロフィール行を「体格：／髪：／目：／衣装：／役割：」で連結
- personality ← rp_personality、scenario ← rp_situation、creator_notes ← memo
- tags ← rp_tags を空白で分割
- extensions に subtitle／プロフィール各行／rp_speech／rp_hook／prompt_memo／category／use_case／memo を格納
- 元画像にあるテキストチャンク（生成ツールの prompt／workflow 等）は全て除去し、出力のテキストチャンクは `chara` だけにする。ピクセルデータは変更しない（チャンクのCRC32を正しく計算する）。
- **プライバシー保護（必須）**：エクスポートにマスター（利用者）の名前などの個人情報を含めない仕組みを、機能として組み込むこと。
  - data.creator は常に空にする（作成者名を入れない）。
  - JSON内のすべての文字列値を再帰的に走査し、「個人情報リスト」に登録した語（本名・呼び名・住所・連絡先など）を汎用語（例：「マスター」）へ置換してから埋め込む。
  - 個人情報リストは利用者ごとに設定する（組み立て時の Q11 で聞く）。
  - スクラブはエクスポート時の出力だけに適用し、ボードに保存されているカードデータ自体は変更しない。
- アセットがPNGでない場合は canvas でPNG化してから埋め込む。画像が無いカードではボタンを無効化し理由を表示する。

### M11 エージェント用アクションAPI
AIがチャット側からボードを操作するためのAPI。参考実装のアクション一覧：

| アクション | 役割 |
|---|---|
| getBoard | ボード全体（全カード・使用中・適用済み・予約・キュー・現在の登録状況）を返す |
| listCards | 全カードを並び順で返す |
| getSyncStatus | 使用中と適用済みのズレを確認する |
| createCard / updateCard / deleteCard | カードの作成／編集／削除 |
| importCards | 一括登録（同名・同一画像はスキップ） |
| seedBoard | 初期投入 |
| reorderCards | 並び順の設定 |
| archiveCard / restoreCard | アーカイブ／復帰 |
| setFavorite | お気に入りの切り替え |
| setCardImages | 複数画像の一括設定（先頭がメイン） |
| requestActive | ボード側の「使う」（使用中だけ変更＝予約発生） |
| setActive | 実際に切り替えた後、使用中と適用済みを揃える |
| requestApplyNext / applyNext | キュー先頭の予約／適用後の後始末 |
| toggleQueue | キューへの追加／解除 |
| syncAppliedToBoard / syncBoardToApplied | 予約の解消（2方向） |
| registerCurrentAvatar | 現在のアバターを名前を付けて登録 |
| setCurrentAvatar | 現在の表示アバターのスナップショットを報告 |

---

## 5. 組み立て時の質問リスト（取捨選択）

作り始める前に、この順で質問し、回答に応じてモジュールをON/OFFしてください。各質問に推奨（迷ったらこれ）を示します。

- **Q1. 用途は？**
- a) 自分のアバター衣装管理だけ → M3（着替えモデル）が中心
- b) キャラクター／キャストの台帳も兼ねる → M5・M6 も推奨
- c) RP専用のキャラ台帳 → M6 中心、M3 は不要なことが多い
- **Q2. 着替えモデル（使用中／適用済み／予約／キュー）は要りますか？**（M3）
- 推奨：アバター運用をするなら「要る」。台帳だけなら「要らない」
- **Q3. RP項目は要りますか？**（M6）要る場合、性格／口調／シチュエーション／導線／タグの全部？ 一部？
- 推奨：全部（空欄でも害はない）
- **Q4. プロフィールはラベル行（体格／髪／目／衣装／役割）に分けますか？**（M5）
- 推奨：分ける。文章の塊より検索・参照が速い
- **Q5. 画像は複数枚対応にしますか？**（M7）
- 推奨：する（衣装＋素顔など基準ペアの置き場になる）
- **Q6. 画像の持ち方は？**（M8）
- a) アプリ同梱アセット（推奨：表示が確実）
- b) 外部URL参照（手軽だがリンク切れ・表示不安定のリスク）
- **Q7. キャラカードエクスポートは要りますか？**（M10）
- 推奨：キャラを他の人／他のツールと交換する予定があるなら「要る」
- **Q8. AIエージェントから操作するアクションAPIは要りますか？**（M11）
- 推奨：AIと一緒に運用するなら「要る」
- **Q9. 安全情報（NG・ストップ合図など）の置き場所は？**
- a) メモに集約（推奨：ボードが汎用のまま保てる。メモ先頭にの見出しブロックで書く運用ルールを添える）
- b) 専用項目を作る（用途が固定されている場合のみ）
- **Q10. 初期データは？**
- a) 空で始める
- b) 既存のアバター／キャラを初期カードとして登録して始める（デフォルトカードを1枚決める）
- **Q11. エクスポート時に除去する個人情報は？**（M10採用時は必須）
  - 本名・呼び名・住所・連絡先など、他人に渡すファイルへ入れたくない語をリストアップしてもらう。置換先の汎用語（例：「マスター」）も一緒に決める

### プリセット

| 構成 | 内容 |
|---|---|
| 最小構成 | M1＋M2（＋画像1枚表示）。とにかく台帳だけ欲しい人向け |
| 標準構成（現行仕様） | M1〜M11 の全部。アバター運用＋RP台帳＋交換まで |
| 交換特化 | M1＋M2＋M5＋M6＋M10。キャラカードの作成・配布が目的の人向け |

---

## 6. 実装上の注意

1. **画像が出ない大半は M8 の②（アセット同梱）漏れ**。キーとハッシュの登録だけで終わらせない。
2. エクスポート時は生成ツールのメタデータ（prompt／workflow）を残さない。残すとプロンプトやシードまで相手に渡ってしまう。
3. エクスポートで項目に無い内容を創作しない。「詳細に書いてあるデータだけ」が原則。
3b. エクスポートにマスターの名前などの個人情報を含めない。creator は空にし、個人情報リストの語は汎用語へ置換する処理を必ず通す（M10 のプライバシー保護）。
4. デフォルトカードは削除不可・名前変更不可にする。同名カードは作れないようにする。
5. 使用中／適用済みのズレ（予約）は必ず画面で見えるようにする。ズレたまま放置が一番の混乱源。

---

## 7. 受け入れチェックリスト

- [] カードの作成・編集・削除・並び替えができる
- [] 画像が実際に表示される（キー登録だけでなくアセット同梱まで確認）
- [] 複数画像がスワイプで切り替わり、枚数表示が出る
- [] 検索とタグ絞り込みで目的のカードに届く
- [] 使用中／適用済み／予約の状態が正しく表示・解消できる（M3採用時）
- [] エクスポートしたPNGから chara チャンクを取り出して復号し、カード項目と一致する（M10採用時）
- [] エクスポートしたPNGに生成ツールのメタデータが残っていない
- [] エクスポートしたPNGにマスターの名前などの個人情報が残っていない（creator が空で、個人情報リストの語が置換済み）