#352

開発環境では、**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 回
```

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

Reviewed-on: #381
Co-authored-by: miteruzo <miteruzo@naver.com>
Co-committed-by: miteruzo <miteruzo@naver.com>

backend/app/controllers/posts_controller.rb

@@ -140,10 +140,11 @@ class PostsController < ApplicationController
     original_created_from = params[:original_created_from]
     original_created_before = params[:original_created_before]
     parent_post_ids = parse_parent_post_ids
+    resized_thumbnail = thumbnail.present? ? Post.resized_thumbnail_attachment(thumbnail) : nil
 
     post = Post.new(title:, url:, thumbnail_base: nil, uploaded_user: current_user,
                     original_created_from:, original_created_before:)
-    post.thumbnail.attach(thumbnail) if thumbnail.present?
+    post.thumbnail.attach(resized_thumbnail) if resized_thumbnail
 
     ApplicationRecord.transaction do
       post.save!
@@ -156,8 +157,6 @@ class PostsController < ApplicationController
 
       sync_parent_posts!(post, parent_post_ids)
 
-      post.resized_thumbnail!
-
       PostVersionRecorder.record!(post:, event_type: :create, created_by_user: current_user)
     end
 
@@ -167,6 +166,8 @@ class PostsController < ApplicationController
     render_validation_error fields: { tags: 'ニコニコ・タグは直接指定できません．' }
   rescue Tag::DeprecatedTagNormalisationError
     render_unprocessable_entity '廃止済みタグは付与できません．', field: :tags
+  rescue MiniMagick::Error
+    render_validation_error fields: { thumbnail: ['サムネイル画像の変換に失敗しました．'] }
   rescue ArgumentError => e
     render_validation_error fields: { parent_post_ids: [e.message] }
   rescue ActiveRecord::RecordInvalid => e

backend/app/models/post.rb

@@ -1,5 +1,19 @@
 class Post < ApplicationRecord
   require 'mini_magick'
+  require 'stringio'
+
+  def self.resized_thumbnail_attachment(upload)
+    upload.rewind
+    image = MiniMagick::Image.read(upload.read)
+    image.resize '180x180'
+    image.format 'jpg'
+
+    { io: StringIO.new(image.to_blob),
+      filename: 'resized_thumbnail.jpg',
+      content_type: 'image/jpeg' }
+  ensure
+    upload.rewind
+  end
 
   belongs_to :uploaded_user, class_name: 'User', optional: true
 
@@ -87,12 +101,7 @@ class Post < ApplicationRecord
   def resized_thumbnail!
     return unless thumbnail.attached?
 
-    image = MiniMagick::Image.read(thumbnail.download)
-    image.resize '180x180'
-    thumbnail.purge
-    thumbnail.attach(io:            File.open(image.path),
-                     filename:      'resized_thumbnail.jpg',
-                     content_type:  'image/jpeg')
+    thumbnail.attach(self.class.resized_thumbnail_attachment(StringIO.new(thumbnail.download)))
   end
 
   private

backend/spec/requests/posts_spec.rb

@@ -1,4 +1,5 @@
 require 'rails_helper'
+require 'base64'
 require 'set'
 
 include ActiveSupport::Testing::TimeHelpers
@@ -8,6 +9,11 @@ RSpec.describe 'Posts API', type: :request do
   # resized_thumbnail! が MiniMagick 依存でコケやすいので request spec ではスタブしとくのが無難。
   before do
     allow_any_instance_of(Post).to receive(:resized_thumbnail!).and_return(true)
+    allow(Post).to receive(:resized_thumbnail_attachment).and_return(
+      io: StringIO.new('dummy'),
+      filename: 'resized_thumbnail.jpg',
+      content_type: 'image/jpeg'
+    )
   end
 
   def create_nico_tag!(name)
@@ -19,6 +25,18 @@ RSpec.describe 'Posts API', type: :request do
     Rack::Test::UploadedFile.new(StringIO.new('dummy'), 'image/jpeg', original_filename: 'dummy.jpg')
   end
 
+  def real_thumbnail_upload
+    gif =
+        Base64.decode64(
+            'R0lGODdhAQABAIABAP///wAAACwAAAAAAQABAAACAkQBADs=')
+
+    Rack::Test::UploadedFile.new(
+      StringIO.new(gif),
+      'image/gif',
+      original_filename: 'thumbnail.gif'
+    )
+  end
+
   def post_write_params params = { }
     { parent_post_ids: '' }.merge(params)
   end
@@ -696,6 +714,66 @@ RSpec.describe 'Posts API', type: :request do
       expect(json['tags'][0]).to have_key('name')
     end
 
+    it '201 when posting manually with a thumbnail' do
+      sign_in_as(member)
+      allow(Post).to receive(:resized_thumbnail_attachment).and_call_original
+
+      post '/posts', params: post_write_params(
+        title: 'thumbnail post',
+        url: 'https://example.com/thumbnail-post',
+        tags: 'spec_tag',
+        thumbnail: real_thumbnail_upload
+      )
+
+      expect(response).to have_http_status(:created)
+      post_record = Post.find(json.fetch('id'))
+      expect(post_record.thumbnail).to be_attached
+      expect(post_record.thumbnail.blob.content_type).to eq('image/jpeg')
+      expect { post_record.thumbnail.download }.not_to raise_error
+    end
+
+    it 'resizes the thumbnail before the create transaction begins' do
+      sign_in_as(member)
+
+      open_transactions = []
+      baseline_open_transactions = Post.connection.open_transactions
+      allow(Post).to receive(:resized_thumbnail_attachment) do |_upload|
+        open_transactions << Post.connection.open_transactions
+        { io: StringIO.new('dummy'),
+          filename: 'resized_thumbnail.jpg',
+          content_type: 'image/jpeg' }
+      end
+
+      post '/posts', params: post_write_params(
+        title: 'transaction post',
+        url: 'https://example.com/transaction-post',
+        tags: 'spec_tag',
+        thumbnail: dummy_upload
+      )
+
+      expect(response).to have_http_status(:created)
+      expect(open_transactions).to eq([baseline_open_transactions])
+    end
+
+    it 'returns 422 and does not create a post when thumbnail resize fails' do
+      sign_in_as(member)
+      allow(Post).to receive(:resized_thumbnail_attachment).and_raise(MiniMagick::Error)
+
+      expect {
+        post '/posts', params: post_write_params(
+          title: 'broken thumbnail post',
+          url: 'https://example.com/broken-thumbnail-post',
+          tags: 'spec_tag',
+          thumbnail: dummy_upload
+        )
+      }.not_to change(Post, :count)
+
+      expect(response).to have_http_status(:unprocessable_entity)
+      expect(json.fetch('errors')).to include(
+        'thumbnail' => ['サムネイル画像の変換に失敗しました．']
+      )
+    end
+
     it '201 and creates post + tags when member and tags have aliases' do
       sign_in_as(member)