素材管理 (#306) (#381)

開発環境では、**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>
2026-06-28 06:35:53 +09:00
@@ -1,6 +1,9 @@
 class Material < ApplicationRecord
  include MyDiscard

+  SOURCE_KINDS = ['uri', 'google_drive_path', 'google_drive_file',
+                  'legacy_drive_path'].freeze
+
  default_scope -> { kept }

  belongs_to :parent, class_name: 'Material', optional: true
@@ -10,9 +13,18 @@ class Material < ApplicationRecord
  belongs_to :created_by_user, class_name: 'User', optional: true
  belongs_to :updated_by_user, class_name: 'User', optional: true

-  has_one_attached :file, dependent: :purge
+  has_many :material_versions, dependent: :destroy
+  has_many :material_export_items, dependent: :destroy

-  validates :tag_id, presence: true, uniqueness: true
+  has_one_attached :file, dependent: :purge
+  has_one_attached :thumbnail, dependent: :purge
+
+  before_validation :assign_normalized_source_key
+
+  validates :tag_id, uniqueness: true, allow_nil: true
+  validates :source_kind,
+            inclusion: { in: SOURCE_KINDS },
+            allow_blank: true

  validate :file_must_be_attached
  validate :tag_must_be_material_category
@@ -23,8 +35,37 @@ class Material < ApplicationRecord
    file.blob.content_type
  end

+  def file_byte_size
+    return nil unless file&.attached?
+
+    file.blob.byte_size
+  end
+
+  def file_filename
+    return nil unless file&.attached?
+
+    file.blob.filename.to_s
+  end
+
+  def snapshot_export_paths
+    material_export_items.order(:profile).pluck(:profile, :export_path).to_h
+  end
+
  private

+  def assign_normalized_source_key
+    if source_kind.blank?
+      self.normalized_source_key = nil
+      return
+    end
+
+    self.normalized_source_key =
+        MaterialSyncSuppression.normalize_source_key(source_kind:,
+                                                     source_uri:,
+                                                     drive_path: source_path,
+                                                     drive_file_id: source_file_id)
+  end
+
  def file_must_be_attached
    return if url.present? || file.attached?

@@ -0,0 +1,48 @@
+class MaterialExportItem < ApplicationRecord
+  VALID_PROFILES = ['legacy_drive'].freeze
+
+  belongs_to :material
+  belongs_to :created_by_user, class_name: 'User', optional: true
+
+  validates :profile, presence: true, inclusion: { in: VALID_PROFILES }
+  validates :export_path, presence: true, uniqueness: { scope: :profile }
+  validates :material_id, uniqueness: { scope: :profile }
+  validate :export_path_must_be_relative_safe_path
+
+  scope :enabled, -> { where(enabled: true) }
+
+  private
+
+  def export_path_must_be_relative_safe_path
+    return if export_path.blank?
+
+    if export_path.start_with?('/')
+      errors.add(:export_path, '絶対パスは使へません．')
+    end
+
+    if export_path.match?(/\A[A-Za-z]:\//)
+      errors.add(:export_path, '絶対パスは使へません．')
+    end
+
+    if export_path.include?('\\')
+      errors.add(:export_path, '/ 区切りで指定してください．')
+    end
+
+    if export_path.include?("\0")
+      errors.add(:export_path, 'NUL は使へません．')
+    end
+
+    parts = export_path.split('/')
+    if export_path.include?('//')
+      errors.add(:export_path, '空の path segment は使へません．')
+    end
+
+    if parts.any? { |part| part.in?(['.', '..']) }
+      errors.add(:export_path, '.. は使へません．')
+    end
+
+    if export_path.end_with?('/')
+      errors.add(:export_path, 'directory path は使へません．')
+    end
+  end
+end
@@ -0,0 +1,29 @@
+class MaterialImportBlock < ApplicationRecord
+  MATCH_KINDS = ['sha256', 'exact_path', 'path_prefix', 'manual'].freeze
+  REASONS = [
+    'copyright_high_risk',
+    'copyright_takedown',
+    'adult_or_sensitive',
+    'personal_information',
+    'malware_or_dangerous_file',
+    'duplicate_or_low_quality',
+    'source_owner_request',
+    'other'
+  ].freeze
+
+  belongs_to :created_by_user, class_name: 'User', optional: true
+
+  validates :match_kind, presence: true, inclusion: { in: MATCH_KINDS }
+  validates :reason, presence: true, inclusion: { in: REASONS }
+  validates :sha256, length: { is: 64 }, allow_blank: true
+  validate :match_value_must_be_present
+
+  private
+
+  def match_value_must_be_present
+    return if match_kind == 'manual'
+    return if sha256.present? || external_path_pattern.present?
+
+    errors.add(:base, 'sha256 または external_path_pattern は必須です．')
+  end
+end
@@ -0,0 +1,45 @@
+class MaterialSyncSource < ApplicationRecord
+  SOURCE_KINDS = ['uri', 'google_drive_path', 'google_drive_file', 'legacy_drive_path'].freeze
+
+  belongs_to :created_by_user, class_name: 'User', optional: true
+  belongs_to :updated_by_user, class_name: 'User', optional: true
+
+  validates :name, presence: true
+  validates :source_kind,
+            presence: true,
+            inclusion: { in: SOURCE_KINDS }
+  validates :profile, presence: true, inclusion: { in: MaterialExportItem::VALID_PROFILES }
+  validate :source_value_must_be_present
+
+  scope :enabled, -> { where(enabled: true) }
+
+  def normalized_source_key
+    MaterialSyncSuppression.normalize_source_key(source_kind:,
+                                                 source_uri:,
+                                                 source_path:,
+                                                 source_file_id:)
+  end
+
+  private
+
+  def source_value_must_be_present
+    return if source_value_present?
+
+    errors.add(:base, '同期元を指定してください．')
+  end
+
+  def source_value_present?
+    case source_kind
+    when 'uri'
+      source_uri.present?
+    when 'google_drive_file'
+      source_file_id.present? || source_uri.present?
+    when 'google_drive_path'
+      source_file_id.present? || source_uri.present?
+    when 'legacy_drive_path'
+      source_path.present?
+    else
+      normalized_source_key.present?
+    end
+  end
+end
@@ -0,0 +1,105 @@
+class MaterialSyncSuppression < ApplicationRecord
+  SOURCE_KINDS = [
+    'uri',
+    'google_drive_path',
+    'google_drive_path_prefix',
+    'google_drive_file',
+    'legacy_drive_path',
+    'legacy_drive_path_prefix'
+  ].freeze
+
+  REASONS = [
+    'copyright_high_risk',
+    'copyright_takedown',
+    'adult_or_sensitive',
+    'personal_information',
+    'malware_or_dangerous_file',
+    'duplicate_or_low_quality',
+    'source_owner_request',
+    'other'
+  ].freeze
+
+  belongs_to :created_by_user, class_name: 'User', optional: true
+
+  before_validation :assign_normalized_source_key
+
+  validates :source_kind, presence: true, inclusion: { in: SOURCE_KINDS }
+  validates :reason, presence: true, inclusion: { in: REASONS }
+  validates :normalized_source_key, presence: true, uniqueness: true
+  validate :source_value_must_be_present
+  validate :drive_path_must_be_safe_relative_path
+
+  def self.normalize_source_key source_kind:,
+                                source_uri: nil,
+                                drive_path: nil,
+                                drive_file_id: nil,
+                                source_path: nil,
+                                source_file_id: nil
+    kind = source_kind.to_s
+    value =
+        case kind
+        when 'uri'
+          source_uri.to_s.strip
+        when 'google_drive_path', 'google_drive_path_prefix',
+             'legacy_drive_path', 'legacy_drive_path_prefix'
+          (source_path || drive_path).to_s.strip.gsub(%r{/+}, '/')
+        when 'google_drive_file'
+          (source_file_id || drive_file_id).to_s.strip
+        else
+          ''
+        end
+
+    return nil if kind.blank? || value.blank?
+
+    "#{ kind }:#{ value }"
+  end
+
+  private
+
+  def assign_normalized_source_key
+    normalize_path_fields!
+    self.normalized_source_key =
+        self.class.normalize_source_key(source_kind:,
+                                        source_uri:,
+                                        drive_path:,
+                                        drive_file_id:)
+  end
+
+  def source_value_must_be_present
+    return if normalized_source_key.present?
+
+    errors.add(:base, '同期元を指定してください．')
+  end
+
+  def drive_path_must_be_safe_relative_path
+    return unless source_kind.in?(
+        ['google_drive_path', 'google_drive_path_prefix',
+         'legacy_drive_path', 'legacy_drive_path_prefix'])
+
+    value = drive_path.to_s
+    return if value.blank?
+
+    if value.start_with?('/') || value.match?(/\A[A-Za-z]:\//)
+      errors.add(:drive_path, '相対 path を指定してください．')
+    end
+    if value.start_with?('My Drive/', 'マイドライブ/')
+      errors.add(:drive_path, '同期元フォルダからの相対 path を指定してください．')
+    end
+    errors.add(:drive_path, 'NUL は使へません．') if value.include?("\0")
+    errors.add(:drive_path, '連続スラッシュは使へません．') if value.include?('//')
+    errors.add(:drive_path, '末尾スラッシュは使へません．') if value.end_with?('/')
+
+    parts = value.split('/')
+    if parts.any? { |part| part.in?(['.', '..']) }
+      errors.add(:drive_path, '. や .. は使へません．')
+    end
+  end
+
+  def normalize_path_fields!
+    return unless source_kind.in?(
+        ['google_drive_path', 'google_drive_path_prefix',
+         'legacy_drive_path', 'legacy_drive_path_prefix'])
+
+    self.drive_path = drive_path.to_s.tr('\\', '/').strip.presence
+  end
+end
@@ -0,0 +1,17 @@
+class MaterialVersion < ApplicationRecord
+  EVENT_TYPE_MAP = { create: 'create',
+                     update: 'update',
+                     discard: 'discard',
+                     restore: 'restore' }.freeze
+
+  include VersionRecord
+
+  belongs_to :material
+  belongs_to :tag, optional: true
+  belongs_to :parent, class_name: 'Material', optional: true
+  belongs_to :updated_by_user, class_name: 'User', optional: true
+
+  def export_paths_hash
+    export_paths_json || {}
+  end
+end
@@ -1,15 +1,23 @@
 module VersionRecord
  extend ActiveSupport::Concern

+  DEFAULT_EVENT_TYPE_MAP = { create: 'create',
+                             update: 'update',
+                             discard: 'discard',
+                             restore: 'restore' }.freeze
+
  def readonly? = persisted?

  included do
+    event_type_map = if const_defined?(:EVENT_TYPE_MAP, false)
+                       const_get(:EVENT_TYPE_MAP)
+                     else
+                       DEFAULT_EVENT_TYPE_MAP
+                     end
+
    belongs_to :created_by_user, class_name: 'User', optional: true

-    enum :event_type, { create: 'create',
-                        update: 'update',
-                        discard: 'discard',
-                        restore: 'restore' }, prefix: true, validate: true
+    enum :event_type, event_type_map, prefix: true, validate: true

    validates :version_no, presence: true, numericality: { only_integer: true, greater_than: 0 }
    validates :event_type, presence: true