素材管理 (#306)

みてるぞがコメント

2026-06-27 20:29:22 +09:00

オーナー

開発環境では、DB を壊さない前提で、migration → API → 画面 → 同期 → ZIP → 履歴の順に見るのがよいです。今回の差分は素材管理全体に触っているので、単体でチョンチョン見るより、素材の一生を通すのが早いです。

0. 先に方針

やらないこと:

rails db:drop
rails db:reset
rails db:setup
DISABLE_DATABASE_ENVIRONMENT_CHECK=1 ...

これは禁止。
開発 DB に本番データを入れているなら、床板を剥がして耐震確認するようなものです。

1. migration 確認

まず現在の状態を見る。

cd backend
RAILS_ENV=development bundle exec rails db:migrate:status

その後、通常 migration。

RAILS_ENV=development bundle exec rails db:migrate

見るポイント:

materials に source_* / normalized_source_key / version_no がある
material_versions に event_type / file snapshot / source snapshot がある
material_export_items がある
material_sync_suppressions がある
material_sync_sources がある
既存 materials に material_versions version_no=1 create が backfill されている

確認用:

RAILS_ENV=development bundle exec rails runner '
puts "materials=#{Material.count}"
puts "versions=#{MaterialVersion.count}"
puts "materials without versions=#{Material.left_joins(:material_versions).where(material_versions: { id: nil }).count}"
puts "sync suppressions table=#{ActiveRecord::Base.connection.table_exists?(:material_sync_suppressions)}"
'

ここで materials without versions=0 になれば、backfill は通っています。

2. 既存素材一覧の画面確認

フロントを起動して /materials を見る。

cd frontend
npm run dev

見る観点:

初期表示で素材が出る
初期表示ではグルーピングがオフ
タグなし素材も出る
カード表示でサムネまたは代替テキストが出る
一覧表示に切り替えられる
q / tag_state / media_kind / sort / direction が効く

ここでまず、普通の素材一覧が壊れていないことを確認します。

3. 左タグバーの確認

/materials を開いて左タグバーからタグを選ぶ。

見る観点:

URL が tag_id=...&include_descendants=1&group_by=parent_tag になる
選択中タグが左バーで強調される
一覧上部に「選択中」の表示が出る
「タグ選択を解除」で通常表示に戻れる
解除後、tag_id / include_descendants / group_by / page が消える
子タグ・孫タグの素材も一覧に出る
親タググルーピングされる

特に重要なのはこれ。

親タグ A を選択
  A に直接紐づく素材
  A > B に紐づく素材
  A > B > C に紐づく素材
が同じ一覧に出ること

4. 選択タグから素材追加

左タグからタグを選択した状態で、一覧上部の このタグに素材を追加 を押す。

見る観点:

素材追加画面の tag 欄に選択中タグ名が初期入力されている
file または url を指定して保存できる
保存後 return_to で元のタグ選択済み一覧に戻る
戻った一覧に追加した素材が出る
material_versions に create が 1 件できる

Rails console でも確認できます。

RAILS_ENV=development bundle exec rails runner '
m = Material.order(id: :desc).first
puts({ id: m.id, tag: m.tag&.name, versions: m.material_versions.count, version_no: m.version_no }.inspect)
'

5. グループ見出しから素材追加

親タググルーピング表示中に、各グループ見出しの このタグに素材を追加 を押す。

見る観点:

グループタグ名が tag 欄に初期入力される
保存後、元の一覧に戻る
追加素材がそのグループ内に出る

ここは今回の導線の肝です。棚の見出しから直接その棚へ素材を置けるかを見る。

6. 素材更新と履歴

既存素材の詳細または編集導線から、タグ・URL・ファイル・export path を更新する。

見る観点:

更新前 snapshot が無ければ create が補われる
更新後 update version ができる
file_blob_id / file_filename / file_sha256 が material_versions に入る
export_paths_json が履歴に残る
/materials/changes または /materials/versions で履歴が見える

console:

RAILS_ENV=development bundle exec rails runner '
m = Material.order(updated_at: :desc).first
puts m.material_versions.order(:version_no).map { |v|
  [v.version_no, v.event_type, v.tag_name, v.file_filename, v.file_sha256, v.export_paths_hash]
}.inspect
'

7. サムネイル

画像素材を追加して、一覧にサムネイルが出るか確認。

動画素材があるなら、ffmpeg が入っている環境で backfill。

cd backend
RAILS_ENV=development bundle exec rails materials:thumbnails:backfill

見る観点:

画像は 180x180 のサムネが付く
動画はフレームからサムネが作られる
非対応ファイルは代替テキスト表示になる
ログに result が出る

8. ZIP export

export path がある素材を用意して、ブラウザで確認。

/materials/download.zip?profile=legacy_drive

見る観点:

ZIP が落ちる
entry path が material_export_items.export_path になる
disabled な export item は入らない
ファイル実体が欠けている場合は 422 と missing_files が返る

9. 抑止

/materials/suppressions で path prefix 抑止を追加する。

見る観点:

member で作成できる
guest は forbidden / unauthorized
google_drive_path_prefix で既存素材が discard される
discard 履歴が material_versions に残る
同期時に同じ source_path 配下が再作成されない

10. Google Drive 同期

開発環境では、まず小さいフォルダでやるのがよいです。
いきなり本番素材集フォルダを食わせると、ログが藪になります 🌿

必要な ENV:

GOOGLE_DRIVE_SERVICE_ACCOUNT_EMAIL=...
GOOGLE_DRIVE_PRIVATE_KEY_PATH=...
MATERIAL_SYNC_SOURCE_KIND=google_drive_path
MATERIAL_SYNC_SOURCE_FILE_ID=<folder_id>
MATERIAL_SYNC_SOURCE_NAME=dev-small-folder
MATERIAL_SYNC_SOURCE_PROFILE=legacy_drive

seed で source 作成、または console で作成。

RAILS_ENV=development bundle exec rails db:seed
RAILS_ENV=development bundle exec rails materials:sync

見る観点:

imported / updated / unchanged / suppressed / failed がログに出る
2 回目実行で unchanged が増える
tag は nil のままでも保存できる
人手で tag / url を付けた既存同期素材が、再同期で消えない
Google native file は skip される
download 後 sha256 block が効く

11. schema.rb は別途確認

これはテストというより merge gate です。
今回まだ怪しいので、差分に以下が混ざっていないことを確認します。

wiki_assets 削除
wiki_pages.next_asset_no 削除
素材管理と無関係な CHECK constraint 削除
素材管理と無関係な index order 消失

ここが残るなら、機能テストが通っても merge は止めた方がいいです。

最小テスト順

時間がないなら、この順で十分です。

1. db:migrate
2. materials without versions = 0 を確認
3. /materials 初期表示
4. 左タグ選択 → 子孫込み表示 → グルーピング
5. タグ選択解除
6. 選択タグから素材追加 → return_to で戻る
7. グループ見出しから素材追加
8. 更新して material_versions を確認
9. ZIP export
10. 小さい Drive folder で materials:sync を 2 回

これで、今回の差分の主要な導線はほぼ踏めます。

開発環境では、**DB を壊さない前提で、migration → API → 画面 → 同期 → ZIP → 履歴**の順に見るのがよいです。今回の差分は素材管理全体に触っているので、単体でチョンチョン見るより、素材の一生を通すのが早いです。 ## 0. 先に方針 **やらないこと:** ```sh id="snb3i6" rails db:drop rails db:reset rails db:setup DISABLE_DATABASE_ENVIRONMENT_CHECK=1 ... ``` これは禁止。開発 DB に本番データを入れているなら、床板を剥がして耐震確認するようなものです。 --- ## 1. migration 確認まず現在の状態を見る。 ```sh id="qsdfpt" cd backend RAILS_ENV=development bundle exec rails db:migrate:status ``` その後、通常 migration。 ```sh id="a89fir" RAILS_ENV=development bundle exec rails db:migrate ``` 見るポイント: ```txt id="c1u57a" materials に source_* / normalized_source_key / version_no がある material_versions に event_type / file snapshot / source snapshot がある material_export_items がある material_sync_suppressions がある material_sync_sources がある既存 materials に material_versions version_no=1 create が backfill されている ``` 確認用: ```sh id="g4vd4m" RAILS_ENV=development bundle exec rails runner ' puts "materials=#{Material.count}" puts "versions=#{MaterialVersion.count}" puts "materials without versions=#{Material.left_joins(:material_versions).where(material_versions: { id: nil }).count}" puts "sync suppressions table=#{ActiveRecord::Base.connection.table_exists?(:material_sync_suppressions)}" ' ``` ここで `materials without versions=0` になれば、backfill は通っています。 --- ## 2. 既存素材一覧の画面確認フロントを起動して `/materials` を見る。 ```sh id="vl28jd" cd frontend npm run dev ``` 見る観点: ```txt id="i2ovxw" 初期表示で素材が出る初期表示ではグルーピングがオフタグなし素材も出るカード表示でサムネまたは代替テキストが出る一覧表示に切り替えられる q / tag_state / media_kind / sort / direction が効く ``` ここでまず、普通の素材一覧が壊れていないことを確認します。 --- ## 3. 左タグバーの確認 `/materials` を開いて左タグバーからタグを選ぶ。見る観点: ```txt id="n6udul" URL が tag_id=...&include_descendants=1&group_by=parent_tag になる選択中タグが左バーで強調される一覧上部に「選択中」の表示が出る「タグ選択を解除」で通常表示に戻れる解除後、tag_id / include_descendants / group_by / page が消える子タグ・孫タグの素材も一覧に出る親タググルーピングされる ``` 特に重要なのはこれ。 ```txt id="d33os0" 親タグ A を選択 A に直接紐づく素材 A > B に紐づく素材 A > B > C に紐づく素材が同じ一覧に出ること ``` --- ## 4. 選択タグから素材追加左タグからタグを選択した状態で、一覧上部の **このタグに素材を追加** を押す。見る観点: ```txt id="qdd5uw" 素材追加画面の tag 欄に選択中タグ名が初期入力されている file または url を指定して保存できる保存後 return_to で元のタグ選択済み一覧に戻る戻った一覧に追加した素材が出る material_versions に create が 1 件できる ``` Rails console でも確認できます。 ```sh id="i07rrb" RAILS_ENV=development bundle exec rails runner ' m = Material.order(id: :desc).first puts({ id: m.id, tag: m.tag&.name, versions: m.material_versions.count, version_no: m.version_no }.inspect) ' ``` --- ## 5. グループ見出しから素材追加親タググルーピング表示中に、各グループ見出しの **このタグに素材を追加** を押す。見る観点: ```txt id="fpx8w4" グループタグ名が tag 欄に初期入力される保存後、元の一覧に戻る追加素材がそのグループ内に出る ``` ここは今回の導線の肝です。棚の見出しから直接その棚へ素材を置けるかを見る。 --- ## 6. 素材更新と履歴既存素材の詳細または編集導線から、タグ・URL・ファイル・export path を更新する。見る観点: ```txt id="w36i61" 更新前 snapshot が無ければ create が補われる更新後 update version ができる file_blob_id / file_filename / file_sha256 が material_versions に入る export_paths_json が履歴に残る /materials/changes または /materials/versions で履歴が見える ``` console: ```sh id="a3okhv" RAILS_ENV=development bundle exec rails runner ' m = Material.order(updated_at: :desc).first puts m.material_versions.order(:version_no).map { |v| [v.version_no, v.event_type, v.tag_name, v.file_filename, v.file_sha256, v.export_paths_hash] }.inspect ' ``` --- ## 7. サムネイル画像素材を追加して、一覧にサムネイルが出るか確認。動画素材があるなら、`ffmpeg` が入っている環境で backfill。 ```sh id="qxm8fj" cd backend RAILS_ENV=development bundle exec rails materials:thumbnails:backfill ``` 見る観点: ```txt id="s9a1vf" 画像は 180x180 のサムネが付く動画はフレームからサムネが作られる非対応ファイルは代替テキスト表示になるログに result が出る ``` --- ## 8. ZIP export export path がある素材を用意して、ブラウザで確認。 ```txt id="aq7f7o" /materials/download.zip?profile=legacy_drive ``` 見る観点: ```txt id="h4rve5" ZIP が落ちる entry path が material_export_items.export_path になる disabled な export item は入らないファイル実体が欠けている場合は 422 と missing_files が返る ``` --- ## 9. 抑止 `/materials/suppressions` で path prefix 抑止を追加する。見る観点: ```txt id="w80jbu" member で作成できる guest は forbidden / unauthorized google_drive_path_prefix で既存素材が discard される discard 履歴が material_versions に残る同期時に同じ source_path 配下が再作成されない ``` --- ## 10. Google Drive 同期開発環境では、まず小さいフォルダでやるのがよいです。いきなり本番素材集フォルダを食わせると、ログが藪になります 🌿 必要な ENV: ```sh id="kzbb7f" GOOGLE_DRIVE_SERVICE_ACCOUNT_EMAIL=... GOOGLE_DRIVE_PRIVATE_KEY_PATH=... MATERIAL_SYNC_SOURCE_KIND=google_drive_path MATERIAL_SYNC_SOURCE_FILE_ID=<folder_id> MATERIAL_SYNC_SOURCE_NAME=dev-small-folder MATERIAL_SYNC_SOURCE_PROFILE=legacy_drive ``` seed で source 作成、または console で作成。 ```sh id="sec40c" RAILS_ENV=development bundle exec rails db:seed RAILS_ENV=development bundle exec rails materials:sync ``` 見る観点: ```txt id="a5ltqu" imported / updated / unchanged / suppressed / failed がログに出る 2 回目実行で unchanged が増える tag は nil のままでも保存できる人手で tag / url を付けた既存同期素材が、再同期で消えない Google native file は skip される download 後 sha256 block が効く ``` --- ## 11. schema.rb は別途確認これはテストというより merge gate です。今回まだ怪しいので、差分に以下が混ざっていないことを確認します。 ```txt id="s3k6da" wiki_assets 削除 wiki_pages.next_asset_no 削除素材管理と無関係な CHECK constraint 削除素材管理と無関係な index order 消失 ``` ここが残るなら、機能テストが通っても merge は止めた方がいいです。 --- ## 最小テスト順時間がないなら、この順で十分です。 ```txt id="c1k2pw" 1. db:migrate 2. materials without versions = 0 を確認 3. /materials 初期表示 4. 左タグ選択 → 子孫込み表示 → グルーピング 5. タグ選択解除 6. 選択タグから素材追加 → return_to で戻る 7. グループ見出しから素材追加 8. 更新して material_versions を確認 9. ZIP export 10. 小さい Drive folder で materials:sync を 2 回 ``` これで、今回の差分の主要な導線はほぼ踏めます。

みてるぞが 20 コミット追加 2026-06-27 20:29:22 +09:00

#306 507ce1680e

#306 事故が起きたので，エージェントへの指示を追加 a820ce4c3e

#306 510cbb0d78

#306 c2102c8f96

#306 dbc654f346

#306 fa6c547cc9

#306 c10ba7a698

#306 377a09ed70

#306 8304909c8c

#306 daf9e7e6fa

#306 4da3f0afba

#306 d7b136c198

#306 ce28661271

#306 363146c219

#306 c836369dfc

#306 41a98ff725

#306 4c0a4f5d9b

#306 27aa5321a1

#306 0eb45372c3

#306 d721a64e33

みてるぞがラベル

P

0

を追加 2026-06-27 20:29:32 +09:00

みてるぞが 1 コミット追加 2026-06-28 03:40:46 +09:00

#306 ec98c6b756

みてるぞが 2 コミット追加 2026-06-28 06:35:17 +09:00

#306 283c20b9da

#306 c9b22d346b

みてるぞがコミット 776dea87d9 を main にマージ 2026-06-28 06:35:53 +09:00

みてるぞがラベル

P

0

を除去 2026-06-30 01:18:58 +09:00

素材管理 (#306) #381

0. 先に方針

1. migration 確認

2. 既存素材一覧の画面確認

3. 左タグバーの確認

4. 選択タグから素材追加

5. グループ見出しから素材追加

6. 素材更新と履歴

7. サムネイル

8. ZIP export

9. 抑止

10. Google Drive 同期

11. schema.rb は別途確認

最小テスト順