第3部 画面と機能の完全ガイド

1. MOTKの一文説明候補

MOTKは、映像・アニメーション・VFX・ストップモーション制作のために、ショット、アセット、タスク、メンバー、スケジュール、素材フォルダ、プロキシ、レビュー状態を一つのブラウザUIで扱えるようにする制作管理ツールである。

MOTKは、Google Sheets上の制作データをそのまま使いながら、制作現場で必要な「探す」「並べる」「見る」「編集する」「関連をたどる」「スケジュールに置く」「Driveフォルダを開く」「診断する」を行うためのアプリである。

MOTKは、ShotGridのような制作管理思想をGoogle Sheets/Driveベースで軽量に実装し、制作規模に応じてローカル・社内・クラウド運用へ拡張できるようにするための基盤である。

2. 利用者別の使い方

2.1 Producer / Production Manager

Producerは、Tableで全体の進捗を見て、Status、Due Date、Assignee、Task Link、Asset Linkを更新し、Schedulerでメンバーごとの作業量や詰まりを見る。

Producerは、TableのSort/Filterを使って「未着手」「レビュー待ち」「締切が近い」「担当未設定」「アセットリンクが空」「素材が未アップロード」などを抽出する。

Producerは、Detailで1ショットまたは1タスクを開き、関連アセット、関連タスク、Drive Originals、プロキシ、ノート、履歴を確認する。

Producerは、SchedViewのDailyまたはSlotで作業配置を確認し、編集が必要な場合はSchedulerへ移動する。SchedulerではSave Asで別案を作り、カードを調整し、Publishで確定版として扱う。

2.2 Director / Supervisor

DirectorやSupervisorは、Detailでショット単位・アセット単位の情報を確認し、ShotView、AssetView、Comp、Versions、Producer Note、Artist Noteなどを見る。

Supervisorは、Tableでレビュー対象だけを絞り込み、DetailのPrev/Nextで連続チェックする。

Supervisorは、プロキシやサムネイルがある場合、直接Driveを探さずにMOTK上から最新ビューやバージョンを開ける。

2.3 Artist / Animator

Artistは、自分に割り当てられたTaskをTasks Table、Member DetailのAssigned Tasks、またはSchedViewから探す。

Artistは、Task Detailで必要なShot Link、Asset Link、Materials、Originals、Version、Due Date、Statusを確認する。

Artistは、作業したファイルをDetailのVersions Uploadなどから追加し、必要に応じてProxyJobs/UploadInboxの処理に乗せる。

Artistは、Statusを進行中、レビュー待ち、完了などに更新し、必要なノートを残す。

2.4 Admin / Pipeline / Technical Director

Adminは、Settingsでproject_meta、PNAVI、Theme、Drive folders、Proxy Ops、Proxy Audit、User Access、Sharing、Hydrate Originals、Task Est Recalculateを管理する。

Adminは、DebugPanelでPerformance Snapshot、Viewer State、Regression Coverage、Console、Schema/Meta Health、FieldTypes Health、Column Contract、Binding Integrity、Originals diagnostics、Link replacer diagnosticsを確認する。

Adminは、問題があった場合、まずDebugPanelとConsoleを見て、Fields定義、PageConfig、ServerFields、CommonRenderer、Router、Table/Detailの解釈を追う。

3. 全体画面構造

3.1 GLOBAL NAV

GLOBAL NAVはアプリ全体の固定ナビゲーション。基本的にはプロジェクトやページの種類に関係なく同じ位置に出る。

主な項目:

• MOTKロゴ
• Dashboard
• Settings
• Guide
• Debug

Dashboardはプロジェクトの入口。

Settingsは管理者・編集者向けの設定画面。別タブで開くことが多い。

GuideはUserGuideを開く。

Debugは診断コンソールを開く。通常ユーザーは毎日使う必要はないが、問題報告時には重要。

3.2 PROJECT NAV / PNAVI

PNAVIはプロジェクト固有のナビゲーション。project_metaの pnavi.config.json によって設定できる。

主な項目:

• Shots
• Assets
• Tasks
• Members
• Users
• Schedule
• Forum

PNAVIはプロジェクトごとに出す項目を変えられる。たとえば小規模制作ではUsersを隠し、大規模制作ではScheduleやForumを強く見せるなどが可能。

Scheduleは現在、基本的に ?p=schedview のSchedViewへ移動する。Daily/Slotの表示確認はSchedViewで行い、編集が必要なときはInteractionをEditにして ?p=schedule のSchedulerへ移動する。

Forumは制作上の議論、ショットやタスクに紐づくやりとり、または軽い連絡用として位置付ける。

3.3 Page Toolbar

Page Toolbarは現在開いている画面だけに関係する操作領域。

Tableなら Page selector, Save, Sort, Filter, Fields, New, Server search, pager。

Detailなら Prev, Next, Discuss, Cards, Save Menu, View/Edit mode, Preset selector。

SchedViewなら schedule switch, Daily/Slot, Lane, Interaction, Zoom, Card List検索, display fields, lane visibility, status。

Schedulerなら Save As, Publish, Undo, Settings, Inspector, slot editing controls。Schedulerは編集用で、読み取り表示はSchedViewが担当する。

Settingsなら Reload, Save, maintenance buttons。

DebugPanelなら Run all checks, Copy report, Export TXT/JSON, local runner generation。

4. Dashboard

Dashboardは、MOTKを開いたときの入口。全体状況、最近の更新、主要エンティティへの導線、プロキシやスケジュールへの導線を置く場所。

Dashboardで説明すべきこと:

• 現在のプロジェクトを確認する場所。
• Shots, Assets, Tasks, Membersなどに移動する入口。
• 最近更新されたレコードを見る場所。
• スケジュールやプロキシ状況の要約を見る場所。
• 作業開始時に最初に見る画面。

Dashboardは「編集する画面」よりも「状況を見る画面」として説明するのがよい。

5. Table Page

5.1 Table Pageの役割

Table Pageは、ショット、アセット、タスク、メンバー、ユーザーなどのレコードを一覧で見る画面。

大量のレコードを検索、フィルタ、並び替え、ページングしながら見るための画面。

複数レコードを比較する、進捗をまとめて確認する、担当者別に見る、ステータス別に見る、締切順に見る、といった作業に向いている。

Detail Pageは1件を見る画面。Table Pageは多数を見る画面。

5.2 Table Pageでできること

• entityごとの一覧表示
• ページレイアウトの選択
• 表示列の変更
• ソート
• フィルタ
• サーバー検索
• ページング
• 1ページあたりの行数変更
• ALL表示
• 新規レコード作成
• インライン編集
• Link fieldから関連レコードへ移動
• Originals/Versions/Thumbnailsなどの特殊フィールド表示
• 状態のローカル保存
• 2回目表示時の復元
• DebugPanelへの状態共有

5.3 Table Toolbar

Preset Selectは、保存されたTableレイアウトを選ぶ。プロジェクトやユーザーごとに、レビュー用、編集用、制作進行用、アーティスト用などの列構成を切り替えるために使う。

Save menuは、列構成やページ設定を保存するためのメニュー。セルの値を保存するものではない。セルの値はインライン編集時に保存される。

Sortは、現在のTable表示を指定フィールドで並べ替える。

Filterは、条件に合うレコードだけを表示する。

Fieldsは、表示列を選ぶ。必要な列だけを出して表示を軽くするためにも使う。

Newは、新規レコードを作成する。作成時には必須フィールド、ID、自動生成項目、初期値の扱いを説明する必要がある。

Server Searchは、ブラウザ内ではなくサーバー側に問い合わせる検索。大量行のときに重要。

Pagerは、行数が多い場合にページを切り替える。50/100/200/500/ALLのような選択肢がある。

5.4 Tableの読み込みとキャッシュ

Tableは初回表示時にサーバーからデータを取得する。

2回目以降は、前回のViewer State、rows cache、bootpack、column manifestなどを使って、できるだけ早く画面を復元する。

ユーザー向けには「2回目の表示は前回状態を使って先に画面を出し、その後サーバーの最新データで更新されることがある」と説明できる。

ただし、空状態が一瞬表示される場合は、キャッシュ復元の前に空表示が走っている可能性がある。これはユーザーガイドのトラブルシュートに書ける。

5.5 Tableのステータス表示

画面下部またはstatus areaには、loading、saving、applying page、rows count、errorなどが出る。

以前の問題として 0 of 0 のような誤解を招く表示があった。UserGuideでは「読み込み中やキャッシュ復元中は、実データが0件という意味ではない」と明記できる。

5.6 Tableの列固定・列マニフェスト

MOTKはTableの列構成を保存し、ページ再表示時に同じ列順を復元しようとする。

Column Manifestは、ページIDごとの表示列リスト。古い列や別エンティティの列が混ざった場合は、コード側がエンティティに合わないfield_idを除外する。

ユーザー向け説明では「表示列が変になったときは、Fieldsメニューやページ設定の保存状態が原因の可能性がある。データそのものが壊れたとは限らない」とする。

5.7 TableのSearchとFilterの違い

Searchは、サーバー側に問い合わせて検索する。大量行の中から文字列を探す場合に使う。

Filterは、現在のTable表示に対して条件をかける。Statusがreview、Due Dateが今日以前、Assigneeが空などの絞り込みに使う。

Sortは、表示対象を並べる。フィルタ後に並べることもできる。

5.8 TableのInline Editing

Inline EditingはTable上でセルを直接編集する機能。

編集できるかどうかはFieldsのeditable設定とfield typeによる。

編集対象:

• text
• date
• select
• checkbox
• entity_name
• link field
• 一部URL/metadata fields

編集しない対象:

• id
• originals
• generated fields
• system-managed fields
• read-only json

idは機械用の一意識別子。通常ユーザーは編集しない。

entity_nameは人間が見る名前。ShotCode, Asset Name, Task Name, Role, User Nameなど。

Inline Editingは、短い修正に向いている。長い説明文や複雑なリンク修正はDetailの方が安全な場合がある。

5.9 Link fieldの表示

Link fieldには asset_link, shot_link, task_link, member_link, user_link がある。

シート上にはIDが保存されるが、UIでは可能な限りentity_nameとして表示される。

たとえば as_0001 はAsset Nameで表示され、クリックするとAsset Detailに移動できる。

複数IDが入る場合はチップ、ピル、リストとして表示する。

リンク先の解決にはLINK_MAPSが使われる。LINK_MAPSが未取得または古い場合、ID表示のままになることがある。

5.10 Tableの日常ワークフロー例

Production Managerが朝に使う:

1. Dashboardを開く。
2. Tasks Tableへ移動。
3. FilterでStatusがcompleted以外のタスクを表示。
4. SortでDue Date順に並べる。
5. Assigneeが空のものを探す。
6. 必要に応じてインラインでAssigneeやDue Dateを更新。
7. 気になるタスクをDetailで開く。
8. Shot LinkやAsset Linkから関連先を確認。
9. Schedulerで日程上の詰まりを確認。

Supervisorがレビューに使う:

1. Shots Tableへ移動。
2. FilterでStatusがreviewのショットだけ表示。
3. ShotViewまたはCompのある列を表示。
4. 1件目をDetailで開く。
5. Prev/Nextで連続確認。
6. Producer NoteまたはStatusを更新。
7. 必要ならTask Linkから担当タスクへ移動。

Artistが自分の作業を探す:

1. Tasks Tableへ移動。
2. Assigneeで自分のメンバーをFilter。
3. Statusがnot_started/in_progressのものを見る。
4. Due Date順に並べる。
5. Task Detailで関連Shot/Asset/Originalsを開く。
6. 作業後にStatusをreviewへ変更。

6. Detail Page

6.1 Detail Pageの役割

Detail Pageは1つのレコードを深く見るための画面。

Tableは一覧、Detailは個別確認。

ショット、アセット、タスク、メンバー、ユーザーのそれぞれにDetailがある。

Detailは、関連レコード、リンク、Driveフォルダ、サムネイル、バージョン、ノート、ステータス、日付、カードレイアウトをまとめて見せる。

6.2 Detail Toolbar

Titleは現在のレコード名。ShotならShotCode、AssetならAsset Name、TaskならTask Nameのように、人間が識別しやすいentity_nameを優先する。

Prev/Nextは、同じTable内の前後レコードに移動するためのボタン。レビューやチェック作業で重要。

DiscussはForumまたは議論ページを開く。

CardsはDetail内のカード構成を編集する機能。

Save MenuはDetailカードレイアウトやプリセットを保存する機能。

View mode / Edit modeは、レイアウト編集や誤編集を防ぐための切り替え。

Preset SelectはDetailの表示構成を切り替える。

6.3 DetailのCard

Detailは、フィールドをカードとして配置して見せる。

カードにはTable型とSingle Field型がある。

Table型カードは複数フィールドをまとめる。

Single Fieldカードはサムネイル、バージョン、ノート、リンクなど、重要な1フィールドを大きく見せる。

カードはレビュー用、編集用、素材確認用、スケジュール確認用などに分けるとよい。

6.4 Detail Preset

Detail Presetは、カード構成を保存したもの。

例:

• Shot Review Preset
• Asset Review Preset
• Task Edit Preset
• Producer Notes Preset
• Media Check Preset
• Minimal Preset

Save Asで新しいプリセットを作る。

Revertで保存状態に戻す。

6.5 DetailのVersions Upload

DetailにはUpload Versionsのモーダルがある。

Upload Versionsでは、現在のentity、record_id、field_idに対してファイルをアップロードする。

複数ファイルを選べる。

アップロードされたファイルはVersions folderまたはOriginals/Proxies連携に入る。

アップロード後、UploadInboxやProxyJobsに記録され、Workerによるプロキシ生成対象になる場合がある。

ユーザー向けには「ファイルを直接Driveに置くより、MOTKのUploadから入れた方がVersionsやProxyと結びつきやすい」と説明できる。

6.6 DetailのSoft Navigation

Shell内ではDetailが静的に埋め込まれており、SoftNavでTableとDetailを切り替える。

通常ユーザーにSoftNavという言葉は不要だが、ユーザーガイドのトラブルシュートでは「画面が切り替わったように見えてもブラウザ全体は再読み込みされないことがある」と説明できる。

DetailのPrev/Nextは、Tableから引き継いだrowsまたはサーバーから取得したrowsを使って移動する。

6.7 Detailの日常ワークフロー例

Shotのレビュー:

1. Shots Tableでレビュー対象をFilter。
2. 1件目のShot IDまたはShotCodeをクリック。
3. DetailでShotView、Comp、Versions、Notesを確認。
4. 必要ならOriginalsを開く。
5. Statusをreviewからapprovedへ変更。
6. Prevで前、Nextで次へ移動。

Assetの確認:

1. Assets Tableを開く。
2. Asset Typeでcharacter/prop/environmentを絞る。
3. Asset Detailを開く。
4. AssetView、AssetView Versions、Linked Shots、Linked Tasksを確認。
5. アセットが使われるショットへ移動。

Taskの作業確認:

1. Tasks TableまたはSchedulerからTask Detailへ移動。
2. Assignee、Due Date、Status、Shot Link、Asset Linkを確認。
3. 必要素材をOriginalsまたはLinked Shot/Assetから開く。
4. 作業後にVersionをUpload。
5. Statusを更新。

7. CommonRenderer / 表示タイプ

CommonRendererは、field typeに応じて値の見せ方を変える共通レンダラー。

UserGuideでは、フィールドタイプごとに「表示」「編集」「保存される値」を説明するとよい。

7.1 id

idは機械用の一意識別子。

例:

• sh_0001
• as_0001
• tk_0001
• pm_0001
• us_0001

idは原則編集しない。

リンク、Driveフォルダ、タスク、スケジュール、プロキシ、Versionsなどの内部処理はidを基準にする。

7.2 entity_name

entity_nameは人間が見る名前。

例:

• ShotCode
• Asset Name
• Task Name
• Role
• User Name

DetailタイトルやLink chipの表示名に使う。

idとentity_nameは別物。名前が変わってもidは変わらない。

7.3 text

自由入力テキスト。

ノート、説明、メモ、補足、短い値に使う。

長文の場合はDetailのカードで見る方がよい。

7.4 select

選択式の値。

Status、Asset Type、Task Type、Departmentなどに使う。

選択肢はFields.optionsまたは過去入力値から生成されることがある。

新しい値を許可する設計の場合、入力値がoptionsに蓄積される。

7.5 checkbox

true/falseを扱う。

project_metaのEpisode/Act/Sequence/Scene/Shot表示設定や、UI設定に使われる。

7.6 date

日付を扱う。

Due Date、Schedule関連日付、作成日、更新日などに使う。

Timezoneと表示形式に注意する。制作管理では日付の1日ズレが大きな問題になるため、SettingsやSchedulerではTZも表示する。

7.7 json

機械用設定やページ設定を保存する。

UserGuideでは通常ユーザー向けには「編集しないフィールド」と説明する。

Admin向けには、PAGESやproject_metaに保存されるレイアウト・表示設定・PNAVIなどがJSONであると説明する。

7.8 originals

OriginalsはGoogle Drive上のオリジナル素材フォルダへのリンク。

MOTK_ORIGINALS内の対応フォルダを開く。

ユーザーはこのリンクから素材フォルダへ移動できる。

Originalsの中のファイルはアプリから勝手にリネーム・削除しない方針。

7.9 file_list

複数ファイルのリスト。

Materials、Refs、資料、撮影素材、コンセプトアートなどに使う。

UIではファイル名、数、タグ、リンクなどとして表示する。

7.10 thumbnails

サムネイルグリッド。

ShotView、AssetView、TaskView、Compなどの視覚確認に使う。

プロキシやDriveプレビューから表示する。

7.11 versions

バージョン管理用フィールド。

Latest versionを1枚だけ見せたり、version historyを選べるようにしたりする。

ファイルアップロード、プロキシ、Originals/Proxiesフォルダと結びつく。

7.12 link fields

link fieldsは他のentityへの関係を表す。

• asset_link: Assetへリンク
• shot_link: Shotへリンク
• task_link: Taskへリンク
• member_link: ProjectMemberへリンク
• user_link: Userへリンク

シートにはIDが保存される。UIでは名前を表示する。

Link Pickerで検索・選択できる。

リンクが解決されない場合、表示名ではなくIDが出ることがある。

8. Entities

8.1 Shots

Shotsは制作の最小または主要な映像単位。

代表フィールド:

• Shot ID
• ShotCode
• Episode
• Act
• Sequence
• Scene
• Shot
• Status
• TC @fps
• Artist Note
• Producer Note
• Frames
• ShotView
• ShotView Versions
• Materials
• Comp
• Comp Versions
• Asset Link
• Task Link
• Due Date

Shotsはレビュー、進捗管理、素材確認、タスク連携、アセット連携、スケジュール連携の中心。

8.2 Assets

Assetsは制作で使う再利用可能な要素。

代表フィールド:

• Asset ID
• Asset Name
• Asset Type
• Status
• AssetView
• AssetView Versions
• Shot Link
• Task Link

Assetsは、キャラクター、プロップ、背景、環境、衣装、小道具、モデル、リグ、素材などを扱う。

8.3 Tasks

Tasksは作業単位。

代表フィールド:

• Task ID
• Task Name
• Task Type
• Assignee
• Status
• Due Date
• Shot Link
• TaskView
• TaskView Versions
• Asset Link

Schedulerは主にTasksをカードとして扱う。

タスクはShotまたはAssetと結びつく。

8.4 ProjectMembers

ProjectMembersは制作上の役割または参加メンバー。

代表フィールド:

• Member ID
• Role
• Department
• User Link
• Task Link

Schedulerのlaneに出る場合がある。

Member Detailでは、member側のtask_linkフィールドを使ってAssigned Tasksカードを表示できる。Assigned TasksはTasks側Assigneeの逆引きを通常経路にせず、Member行に保存されたTask IDを元にTask Table presetの列順・表示非表示・sort/filter・列幅を引き継いで表示する。

UserとMemberを分けることで、Googleアカウントと制作上の役割を分離できる。

Task Linkは、担当者に紐づくTask一覧をMember Detail内で確認するためにも使える。

8.5 Users

UsersはGoogleアカウントや実ユーザー情報。

代表フィールド:

• User ID
• User Name
• Email
• Department
• Notes

SettingsのUser Access/Sharingと関係する。

8.6 Pages

PagesはTableやDetailなどの表示設定を保存するためのentity。

代表フィールド:

• Page ID
• Page Name
• Page Type
• Entity
• Config JSON
• Created By

Table presetやDetail presetやSchedView viewの保存に使われる。

9. Scheduler / SchedView

9.1 Schedule系の全体像

MOTKにはSchedule表示が2系統ある。

SchedViewは読み取り中心の表示画面。

Schedulerは編集中心の画面。

SchedViewはDailyとSlotの両方を表示できる。

SchedulerはSlot編集を行う。現在のモデルでは、Daily/SlotのView表示はSchedView、Slot編集はSchedulerに分かれている。

UserGuideでは「見るならSchedView、動かすならScheduler」と説明すると分かりやすい。

9.2 SchedView

SchedViewはスケジュールを読む画面。

できること:

• scheduleの切り替え
• Daily表示
• Slot表示
• Lane axis切り替え
• Interaction切り替え
• Zoom調整
• Inspector確認
• Card List検索
• Settings表示
• Lane visibility調整
• Task Display設定
• Fit
• Apply
• Save view

Dailyは日単位のトークン表示。日ごとに何があるかを大まかに見るのに向く。

Slotは時間・スロット単位のバー表示。作業時間、占有、流れを見るのに向く。

Lane axisは、縦または横のlaneをMember基準にするかAsset基準にするかの切り替え。

InteractionがViewならSchedView内で読み取り。EditにするとSchedulerへ移動し、Slot編集用の画面になる。

ZoomはDailyではday height、Slotではslot pixelに関係する。

9.3 Scheduler

Schedulerは編集画面。

できること:

• Slot上でカードを動かす
• カードをリサイズする
• 複数カード選択
• Undo
• Save As
• Publish
• Inspector編集
• Task Assetsのインラインリンク編集
• Lane width調整
• Inspector width調整
• Work hours設定
• Origin date設定
• Slot minutes設定
• Display field設定
• Asset conflict表示
• Taskless card表示
• Camera move badge表示

9.4 Schedulerのカード

カードはTaskを表すことが多い。

カードにはTask ID、Main field、Sub field、extra fields、status、assignee、duration、asset link、shot linkなどが表示される。

ステータスによりカード色が変わる。

未割り当てやtasklessは別色になる。

Asset conflictがある場合、警告的な表示になる。

Camera moveがある場合、カード内にbandやaccentが出る。

9.5 Scheduler Inspector

Inspectorは右側パネル。

タブ:

• INSPECTOR
• CARD LIST
• SETTINGS

INSPECTORは選択したカードの詳細や編集欄を表示する。

CARD LISTはカード一覧と検索。クリックで該当カードへジャンプ。

SETTINGSはschedule表示・lane・zoom・display fields・lane visibility・幅・fit/saveなどを扱う。

9.6 Save As / Publish

Save Asは、現在のscheduleを別名で複製して実験用または別案として保存する。

Publishは、作業中のscheduleを確定版として扱うための操作。

Publishは段階的な操作として説明する必要がある。

例:

• draft scheduleを作る
• reviewする
• snapshotとしてlockする
• locked snapshotをTasksへ反映する

現在のモデルでは、最初のPublishでSchedsのpublished timestampを設定してsnapshotをlockする。lock済みのscheduleでは編集が制限され、次のPublish操作でTasks側の予定フィールドへ反映する。

UserGuideでは、Publishの意味を慎重に書く必要がある。誤ってTasksに反映する操作は制作に影響が大きい。

9.7 Schedulerの日常ワークフロー例

制作進行が翌週の作業を組む:

1. SchedViewを開く。
2. Dailyで全体の作業密度を見る。
3. LaneをMemberにする。
4. 問題のありそうな日を見つける。
5. InteractionをEditにしてSchedulerへ移動。
6. Save Asで新しい案を作る。
7. Slot上でカードを動かす。
8. Card Listで未割り当てや締切近いカードを探す。
9. InspectorでAssigneeやTask Assetsを確認。
10. 問題なければPublishする。

SupervisorがAsset負荷を見る:

1. SchedViewを開く。
2. LaneをAssetにする。
3. Slot表示にする。
4. 同じAssetに作業が集中していないか確認する。
5. Asset conflict表示があれば該当カードを選択。
6. 関連Task/Shotへ移動して調整する。

Artistが自分の予定を見る:

1. SchedViewを開く。
2. LaneをMemberにする。
3. 自分のlaneだけ表示する。必要に応じてMember DetailのAssigned Tasksも確認する。
4. Dailyで今日・明日の作業を確認。
5. カードをクリックしてTask detailを開く。

10. Settings

10.1 Settingsの役割

SettingsはMOTKの管理画面。

通常作業者ではなく、Admin、Editor、Pipeline担当者が使う。

Settingsはプロジェクトメタ、テーマ、PNAVI、Originals URL水和、Task計算式、Driveフォルダ、User Access、Sharing、Proxy Ops、Proxy Auditを扱う。

10.2 project_meta

project_metaはプロジェクト単位の設定を保存する。

Settingsではmeta_key、meta_value、meta_type、note、updated_atを一覧で見る。

updated_atは読み取り専用。

meta_typeはtext、number、checkboxなど。

project_metaには、ui_theme、pnavi.config.json、drive originals/proxies root id、proxy preset、schedule settingsなどが入る。

10.3 Theme

Themeはsystem/dark/lightを選べる。

保存先はproject_metaのui_theme。

次回ページロード時に反映される。

一部ではlocalStorageにも保存され、初期ちらつきを減らす。

10.4 PNAVI Config

PNAVI Configはproject_metaのpnavi.config.jsonに保存される。

プロジェクトナビゲーションの項目、ラベル、リンク、page、entity、enabled、targetなどを制御する。

Reset DefaultでShots, Assets, Tasks, Members, Users, Scheduleなどの標準構成に戻す。

ユーザー向けには「PNAVIはプロジェクトの入口を決める設定」と説明する。

10.5 Hydrate Originals URLs

Hydrate Originals URLsは、Drive上のOriginalsフォルダとシート上のOriginals URLを同期する操作。

対象はall/shot/asset/task。

これはデータ修正というより、アプリ管理用のリンクキャッシュを補完する処理として説明する。

実行すると、MOTK_ORIGINALS内の対応フォルダを見て、該当レコードのOriginals URLを埋める。

既存の有効リンクは維持する。

無効なリンクはクリアまたは更新されることがある。

10.6 Task Est Recalculate

Task Est Recalculateは、Tasksの推定日数・推定時間・計算式などを現在のproject_meta設定に基づいて再計算する。

対象例:

• 推定日数
• 推定時間
• 計算結果フィールド

内部的には sv_task_recalculate_v1 が使われる。完了済みタスクを含めるかどうかのオプションがあるため、運用時は対象範囲を確認してから実行する。

10.7 Drive Folders - Ensure Missing

Ensure All Foldersは、Shots/Assets/Tasksに対応するOriginalsフォルダが存在しない場合に作成する。

既存フォルダやファイルは動かさない。

これは安全な補完処理として説明できる。

10.8 Drive Folders Diff / Fix

Diffは、指定entityのデータとDriveフォルダの対応を比較する。

Fix Missingは、足りないフォルダだけを作成する。

既存ファイルの削除・移動・リネームは行わない方針。

10.9 User Access / Sharing

User Access / Sharingは、Users.permissionに基づき、DriveやSpreadsheetの共有状態を同期する。

役割:

• viewer
• editor
• admin

Admin listは管理用workbookのADMIN_USERS sheetに関係する。Users.permissionのeditor/viewerとは別に、ADMIN_USERSでis_admin=TRUEのユーザーが管理者として扱われる。

Sync Checkedは選択したユーザーを同期する。

Sync Mismatchesは、権限設定と実際の共有状態が合っていないものを同期する。

UserGuideでは「MOTK内の権限表示」と「Google Drive/Sheetsの実共有」がズレることがあるため、同期機能があると説明する。

10.10 Proxy Ops

Proxy Opsは、OriginalsとProxiesのroot id、proxy preset default、アップロード、ProxyJobs、UploadInbox、ProxyWorkersを管理する。

できること:

• originals root idを設定
• proxies root idを設定
• default proxy presetを設定
• Originalsへファイルアップロード
• Recent Proxy Jobsを確認
• Recent Uploadsを確認
• Workersを確認

Proxy Worker Kitとの連携説明もここに置ける。

10.11 Proxy Audit

Proxy Auditは、OriginalsはあるがProxyがないレコードを検出する。

Daily ScanをONにできる。

Hour、Limit、対象entityを設定できる。

Run Audit Nowで即時実行できる。

Latest Missing Proxiesで不足プロキシ一覧を見る。

Proxy Auditは、レビュー用サムネイルや軽量プレビューが足りない箇所を見つけるための機能。

10.12 Settingsの運用注意

Settingsは制作全体に影響する。

PNAVIやThemeは比較的安全。

Hydrate OriginalsやEnsure Missingは補完系。

Sharing Sync、Proxy Config、Task Recalculate、Publish系は影響範囲が大きい。

Admin以外は不用意に触らない方がよい。

11. DebugPanel

11.1 DebugPanelの役割

DebugPanelは、MOTKの状態を調べるための診断画面。

通常作業者向けではなく、問題報告、開発確認、回帰テスト、パフォーマンス確認、スキーマ確認に使う。

11.2 DebugPanelの主要カード

Performance Snapshot:

• route open
• paint speed
• first paint
• table paint
• cache restore
• raw timing

Viewer State:

• 現在のtable/entity/page/fieldIds/rowsLength/cache keyなど
• 2回目表示や復元問題の調査に使う

Regression Coverage:

• 受け入れ済みレポート
• live checks
• 現在の診断結果

Console:

• アプリのconsole buffer
• Panel側のlog
• Copy console可能

Runtime:

• google.script.runが使えるか
• server ping
• location
• URL params

Data Maps / Page:

• FIELD_TYPES
• LINK_MAPS counts
• Layout presets

Schema/Meta Health:

• project_meta-firstの健全性
• Fields/metadataの解釈

SchemaMeta / FieldTypes Health:

• field typesの検出
• entity_name fid検出

Last callFirst Trace:

• API fallbackや呼び出し順の調査

Scheduler Load Diagnostics:

• Scheduler読み込み状態の調査

FieldTypes diagnostics:

• shot/asset/task/member/userのentity_name fid検出

Originals resolver:

• Originals URL解決経路の確認

Entity samples:

• 各entityのid/name sample

Originals diagnostics:

• DriveBuilder、ServerAPIs、ProjectMetaRoot、Final URLの確認

Link replacer diagnostics:

• router detected
• gNav anchors replaced
• sample diff
• dry-run task link

Column Contract / No Index Binding:

• field_idに基づいて列を扱えているか
• column indexに依存していないか

Binding Integrity:

• fidからcell valueへの対応が壊れていないか

11.3 DebugPanelを使う場面

• Tableが遅い
• 2回目表示でも空になる
• Link chipがIDのまま
• Detailが違うrecordを開く
• Inline editが違う列に入る
• Scheduleが表示されない
• Cardが違うlaneに出る
• Originalsが開けない
• Proxyが表示されない
• Settingsが保存できない
• 権限同期がおかしい
• ThemeやPNAVIが反映されない

11.4 問題報告時にコピーすべきもの

• Copy report
• Copy console
• Viewer State JSON
• Performance raw JSON
• Column Contract結果
• Binding Integrity結果
• URL
• 操作手順
• 期待した結果
• 実際の結果

12. File / Drive / Originals / Proxies

12.1 MOTK Drive構造

MOTKはGoogle Driveにプロジェクトフォルダを持つ。

基本構造:

• MOTK[Project:...]
• MOTK_ORIGINALS
• MOTK_PROXIES

Originalsはオリジナルファイルを保持する。

Proxiesは軽量表示・レビュー用ファイルを保持する。

12.2 Originals

Originalsは元素材の保管場所。

MOTKはOriginals内の既存ファイルを勝手にリネーム・削除しない。

Originalsは制作上の信頼できる素材置き場として扱う。

Shot/Asset/Taskごとにフォルダが作られる。

例:

• 01shots/sh_0001__501A
• 02assets/as_0012__Sword100
• 03tasks/tk_0017__Lighting

12.3 Proxies

Proxiesはレビュー・サムネイル・軽量再生用の派生ファイル。

命名にはrecord id、timestamp、field_id、proxyが入る。

例:

• sh_0001_20250815-041700_fi_0013_proxy.mp4
• as_0012_20250815-041700_fi_0023_proxy.png
• tk_0017_20250815-041700_fi_0032_proxy.jpg

12.4 Proxy Workflow

1. ユーザーがDetailまたはSettingsからファイルをアップロード。
2. Originalsにファイルが置かれる。
3. UploadInboxとProxyJobsに処理対象として記録される。
4. Workerがプロキシを生成する。
5. MOTK_PROXIESに保存される。
6. Table/Detail/SchedViewでサムネイルやプレビューとして表示される。

12.5 Proxyが出ないときの説明

Proxyが出ない理由:

• Originalsにファイルがない
• Proxy jobがqueuedのまま
• Workerが動いていない
• Proxies root idが未設定
• Proxy Auditでmissingになっている
• field_idとproxy filenameの対応が合っていない
• Drive権限が足りない
• キャッシュが古い

ユーザー向けには、まずSettingsのProxy OpsとProxy Auditを確認するよう説明する。

13. Forum / Discussion

Forumは、MOTK内の議論・連絡・メモを扱う入口。

DetailのDiscussボタンからForumを開ける。

ForumはForumThreads、ForumPosts、ForumRecentを使って、record単位またはgeneralな会話を保存する。

主な用途:

• ショット単位の議論
• タスク単位の質問
• アセット単位の確認
• レビューコメント
• 制作進行メモ
• 決定事項の記録

レコードに紐づくthreadは、entityとrecord idの組み合わせで扱われる。一般連絡はgeneralなthreadとして扱う。

14. WorkerKit

WorkerKitはローカルまたは外部ワーカーでプロキシ生成などを行うためのキット。

基本的な流れ:

• WorkerKitをダウンロードする
• SettingsのProxy Configを確認する
• worker-bootstrapでspreadsheetIdやwebapp urlを取得する
• ローカルでWorkerを起動する
• ProxyJobsとUploadInboxを見る
• 生成済みProxyがMOTK_PROXIESへ入る
• Workerが止まっている場合はProxy Jobsがqueuedのままになる

15. Routing / URL

MOTKはURLパラメータで画面を切り替える。

代表例:

• Dashboard: ?page=Dashboard またはShell内のDashboard
• Table: ?p=table&e=shots
• Assets Table: ?p=table&e=assets
• Tasks Table: ?p=table&e=tasks
• Members Table: ?p=table&e=members
• Users Table: ?p=table&e=users
• Detail: ?page=DetailShot&entity=shot&id=sh_0001
• SchedView: ?p=schedview
• Scheduler: ?p=schedule
• Settings: ?page=Settings
• UserGuide: ?page=UserGuide
• DebugPanel: ?page=DebugPanelPage

ShellではDashboard/Table/DetailがSoft Navigationで切り替わる。

Settings、Debug、Guide、Schedule系は別ページまたは別タブになることがある。Schedule navは通常SchedViewを開き、Schedulerは編集導線から開く。

16. Page / Preset / Config

MOTKでは表示設定をPagesとして保存する。

Pagesはユーザーが見る画面ではなく、表示構成を保存するためのデータ。

Table preset:

• 表示列
• 列順
• sort/filter状態
• page type
• entity

Detail preset:

• card layout
• card title
• field set
• view/edit permission

SchedView view:

• view mode
• lane axis
• zoom
• visible lanes
• display fields
• lane width
• inspector width
• date range

UserGuideでは「データそのもの」と「見え方の保存」を明確に分ける必要がある。

セル編集はデータ変更。

Save/Save As/Revertは、主にページ設定やレイアウト保存。

17. キャッシュと復元

MOTKは速度向上のため複数のキャッシュを使う。

ユーザー向けに完全な技術名は不要だが、トラブルシュートでは役立つ。

主なキャッシュ:

• Viewer State
• Table rows cache
• Link maps cache
• AppData cache
• Versions context cache
• Bootpack
• Column Manifest
• Detail rows cache
• localStorage theme cache
• console buffer

キャッシュがあるため、画面が先に表示され、その後最新データに更新されることがある。

キャッシュが古いと、表示名、列順、リンク名、状態が一時的に古く見える場合がある。

問題が続く場合はDebugPanelのViewer StateとConsoleを確認する。

18. 権限と共有

MOTKには内部ロールとGoogle側共有がある。

内部ロール:

• admin
• editor
• viewer

Google側共有:

• Spreadsheetアクセス
• Drive folderアクセス
• Originals folderアクセス
• Proxies folderアクセス

SettingsのUser Access / Sharingは、内部設定とGoogle共有を合わせるための機能。

ユーザーが画面を開けない場合、MOTKのUsers設定とGoogle Drive/Sheets共有の両方を見る必要がある。

19. 典型的な作業シナリオ

19.1 新しいショットを作る

1. Shots Tableを開く。
2. Newを押す。
3. 必須項目を入力する。
4. Shot IDは自動生成される。
5. ShotCodeはEpisode/Act/Sequence/Scene/Shot設定から生成または編集される。
6. Statusをnot_startedにする。
7. 必要ならDue Dateを入れる。
8. Asset LinkまたはTask Linkを追加する。
9. Detailを開いてOriginalsやVersionsを確認する。

19.2 ショットにアセットを紐づける

1. Shots TableまたはShot Detailを開く。
2. Asset Linkを編集する。
3. Link PickerでAssetを検索する。
4. 対象Assetを選択する。
5. 保存する。
6. Asset Detailから逆方向にShot Linkを確認する。

19.3 タスクを担当者へ割り当てる

1. Tasks Tableを開く。
2. FilterでAssigneeが空のものを出す。
3. Assigneeをクリック。
4. member_link pickerで担当Memberを選ぶ。
5. Due DateとStatusを更新する。
6. SchedViewで配置を確認し、編集が必要ならSchedulerへ移動する。

19.4 プロキシを作るために素材をアップロードする

1. Detailを開く。
2. Upload Versionsを開く。
3. Filesを選ぶ。
4. Uploadする。
5. UploadInboxとProxyJobsに処理対象が作られる。
6. SettingsのProxy Opsでjobを確認する。
7. Worker実行後、Table/Detailでサムネイルを確認する。

19.5 スケジュール案を作る

1. SchedViewで現在のscheduleを見る。
2. Dailyで大まかな日付を確認。
3. Slotで時間密度を確認。
4. InteractionをEditにする。
5. SchedulerでSave Asを押す。
6. カードを移動・調整する。
7. Inspectorで詳細を確認。
8. 問題なければPublishする。

19.6 表示列を制作会議用に保存する

1. Tableを開く。
2. Fieldsで必要な列だけを表示。
3. Sort/Filterを設定する。
4. Save Asで「Production Meeting」などの名前をつける。
5. 次回会議ではPresetから選ぶ。

19.7 Detailレビュー用レイアウトを作る

1. Detailを開く。
2. View/Edit modeを切り替えてカード編集を可能にする。
3. Cardsを開く。
4. ShotView、Comp、Status、Producer Note、Artist Note、Due Dateなどを配置する。
5. Save AsでReview用Presetとして保存する。

20. トラブルシュート

20.1 Tableが遅い

確認するもの:

• 初回表示か2回目表示か
• row count
• selected entity
• page preset
• displayed fields count
• server search中か
• ALL表示か
• DebugPanel Performance Snapshot
• Viewer State
• Console

説明候補:

Tableは大量行を扱うため、初回表示はサーバー取得が入る。2回目はキャッシュ復元により速くなる想定。2回目でも遅い場合、キャッシュが使われていない、page/entityが一致していない、列構成が再計算されている、またはサーバー取得を待ってから描画している可能性がある。

20.2 一瞬空のTableが出る

原因候補:

• cached rowsを適用する前にempty stateが描画されている
• bootpack復元前にfull network load待ちになっている
• entity/page mismatchでcacheが無効化されている
• rowsLengthが0のsnapshotを読んでいる
• fieldIdsのreconcile中

ユーザー向け説明:

空表示が一瞬出ても、実データが0件という意味ではない場合がある。読み込み中やキャッシュ復元中の中間表示の可能性がある。

20.3 Linkが名前ではなくIDで出る

原因候補:

• LINK_MAPS未取得
• link map cacheが空または古い
• field typeが正しくlink typeとして解釈されていない
• target entityが解決できていない
• CommonRendererのlink target推定が失敗

確認:

• DebugPanelのLINK_MAPS counts
• Fields type
• Entity samples
• Console

20.4 Detailが開かない

原因候補:

• URLのentity/idが不足
• Routerのentity mapping問題
• record idがrowsにない
• sv_getRecordが返っていない
• google.script.runが使えない
• Shell SoftNavがDetail containerを表示していない

確認:

• URL
• DebugPanel Runtime
• Console
• Detail smoke diag

20.5 Inline editが保存されない

原因候補:

• field editableがfalse
• id/originals/system fieldを編集しようとしている
• API failure
• permission不足
• date/select/link value validation
• network/GAS error

説明:

保存されない場合、まずstatus areaとConsoleを見る。idやOriginalsはユーザー編集対象ではない。

20.6 Originalsが開けない

原因候補:

• Originals URLが未水和
• Drive folderがまだ作られていない
• Drive権限がない
• project_metaのoriginals root idがない
• Folder IDが無効

対処:

• SettingsのHydrate Originals URLs
• Drive Folders Diff
• Ensure Missing
• Originals diagnostics

20.7 Proxyが出ない

原因候補:

• OriginalsだけでProxyがない
• Proxy job未処理
• Worker停止
• Proxies root未設定
• Auditでmissing
• field_idとfilenameの対応不一致

確認:

• Settings Proxy Ops
• Proxy Audit
• Worker status
• Recent Proxy Jobs

20.8 Schedulerが空

原因候補:

• date range外
• lane visibilityで全lane非表示
• schedule idが違う
• task cardsがない
• view modeが違う
• display filters
• Scheduler load API failure

確認:

• Fit
• Lane visibility
• Card List
• Scheduler Load Diagnostics
• Console

20.9 Settingsが保存できない

原因候補:

• 管理権限がない
• project_metaがread-only mode
• invalid JSON
• missing required field
• API timeout

説明:

Settingsの保存は制作全体に影響するため、エラーが出た場合はLogとDebugPanelをコピーする。

21. この部の主要用語

MOTK: 制作管理アプリ本体。

Entity: Shot, Asset, Shot, Asset, Task, Member, User, Pageなどのデータ種別。

Record: Entity内の1行。たとえば1つのShot、1つのTask。

Field: 1つの列または属性。Status、Due Date、ShotCodeなど。

Field ID: fi_0001のような機械用フィールドID。

Field Name: 人間向けの列名。

Type: text, select, date, thumbnails, versions, asset_linkなどの表示・編集種別。

entity_name: 人間が見る名前。

id: 機械が使う一意ID。

Originals: 元ファイルのDriveフォルダ。

Proxies: 軽量プレビュー・サムネイル用ファイル。

Page: 表示設定や画面プリセット。

Preset: 保存されたTable/Detail/View設定。

PNAVI: Project Navigation。プロジェクトごとの上部ナビ。

GNAVI: Global Navigation。アプリ全体の上部ナビ。

DebugPanel: 診断コンソール。

SchedView: 読み取り用スケジュール表示。

Scheduler: 編集用スケジュール画面。

Lane: スケジュール上の行または列。MemberまたはAsset基準。

Card: Scheduler上の作業単位。多くはTask。

Publish: スケジュール変更を確定し、Tasks等へ反映する操作。

Save As: 表示設定やschedule案を別名保存する操作。

Hydrate: Driveやメタ情報から不足しているリンクやキャッシュを補完すること。

LINK_MAPS: IDを人間向けの名前へ変換するためのマップ。

FIELD_TYPES: Fields定義から作られるfield typeのマップ。

Viewer State: Tableの現在状態を保存したもの。

Column Manifest: 表示列の順序・構成を保存したもの。

25. Pages / PageConfig / Preset 詳細

25.1 Pagesの基本

Pagesは、MOTKの「見え方」を保存するためのデータである。

Tableで表示列を変える、Detailでカード配置を変える、SchedViewでlaneやzoomを変えるといった操作は、制作データではなくPages側のView Configとして保存される。

説明では、次の区別を明確にする。

• Shots/Assets/Tasks = 制作データ
• Pages = 表示設定
• project_meta/SystemConfig = プロジェクト設定
• Drive = ファイル実体

25.2 Pagesの保存対象

Pagesに保存される主な項目:

• pageId
• entity
• pageType
• pageName
• sharedWith
• config JSON
• createdBy
• createdAt
• modifiedBy
• modifiedAt

config JSONに入る主な項目:

• order
• widths
• hidden
• group
• filterGroups
• sort
• display fields
• lane visibility
• zoom
• mode
• column order
• detail card layout
• scheduler view settings

25.3 PageType

PageTypeは、Pagesの設定がどの画面のものかを示す。

想定されるPageType:

• table
• detail
• schedule
• editor
• view

Table presetはTable用、Detail presetはDetail用、SchedView viewはSchedule表示用である。

同じPageNameでも、entityやpageTypeが違えば別の設定として扱う。

現在のMOTKでは、View表示はSchedView、Slot編集はSchedulerが担当する。

25.4 pageId

pageIdはPages内の一意識別子である。

例:

• pg_default_shot
• pg_default_asset
• pg_...

通常ユーザーはpageIdを意識しないが、DebugPanel、URL、トラブルシュートでは重要になる。

25.5 Default Page

Pagesが空の場合や該当設定がない場合、MOTKはFields metadataからDefault Pageを合成することがある。

Default Pageは、id、entity_name、status、episode/act/sequence/scene/shotなどの基本列を選んで作る。

ユーザー向けには「初期表示はFields定義から自動で作られる。必要に応じてSave Asで自分の見え方を保存する」と説明する。

25.6 PageConfigの読み込み

TableやDetailは、現在のentityとpageIdに合うPageConfigを読み込む。

失敗例:

• not_found
• header_unrecognized
• pages_sheet_not_found

Presetが表示されない、保存したViewが見えない、Page selectorが空の場合の原因候補:

• Pagesシートがない
• Pagesシートのヘッダが想定と違う
• pageTypeが違う
• entityが違う
• pageIdが違う
• config JSONが壊れている
• Pagesのキャッシュが古い

25.7 PageConfigの保存

Save / Save As / Revertは、基本的にPageConfigを保存・復元する操作である。

Table上のセル値保存とは別である。

• セルを編集する = 制作データの変更
• Save menuで保存する = 見え方・レイアウト設定の変更

25.8 Pages Cache

Pages一覧は短時間キャッシュされる。

保存・削除時にはキャッシュが無効化される。

保存直後にリストが古い場合はRefreshまたは再読み込みで更新される。

25.9 Page Presetの日常例

制作進行用Table preset:

• ShotCode
• Status
• Due Date
• Assignee
• Task Link
• Asset Link
• Producer Note

レビュー用Table preset:

• ShotCode
• Status
• ShotView
• Comp
• Versions
• Artist Note
• Producer Note

アーティスト用Task preset:

• Task Name
• Status
• Due Date
• Shot Link
• Asset Link
• TaskView
• Notes

Schedule view preset:

• Lane = Member
• Mode = DailyまたはSlot
• Visible lanes = 自分の部署
• Display field = Task Name / ShotCode / Status

編集が必要な場合は、SchedViewのInteractionをEditにしてSchedulerへ移動する。

26. Fields / ServerFields / Schema 詳細

26.1 Fieldsの基本

Fieldsは、MOTKが各列をどう読むかを決める定義である。

Google Sheetsの1行目のfield_idと、Fieldsシートのmetadataを使って、MOTKは列の意味を判断する。

MOTKは列番号ではなくfield_idを基準に動く。Admin向けには「列を移動してもfield_idが正しければMOTKは読める。ただしfield_idが欠けると壊れる」と説明する。

26.2 field_idとlabel

field_idは機械用、labelは人間用である。

例:

• fi_0001 = Shot ID
• fi_0002 = ShotCode
• fi_0013 = ShotView

実際の番号はプロジェクト定義による。UserGuideでは、番号を固定例として断定せず、「例」と明記する。

26.3 SchemaResolver

SchemaResolverは、entityごとにid field、entity_name field、type別field、field_name別fieldを探す共通解決器である。

SchemaResolverが見つけるもの:

• id field
• entity_name field
• field nameからfid
• fidからfield meta
• fidからentity
• typeからfid一覧

26.4 entity_name

entity_nameは、IDを人間向けに見せるための基準である。

Link chip、Detail title、Dashboard feed、Forum entity link、Scheduler card labelなどで使われる。

entity_nameが正しく設定されていないと、IDだけが表示されたり、カード名が分かりにくくなったりする。

26.5 LinkMaps

LinkMapsは、IDから表示名へ変換するための辞書である。

例:

• sh_0001 -> 501A
• as_0003 -> Robot Arm
• tk_0012 -> Animation Block
• pm_0004 -> Animator A
• us_0002 -> user name

LinkMapsはShots, Assets, Tasks, Users, Membersから作られる。

LinkMapsがない、古い、または対象recordが存在しない場合はIDがそのまま出る。

26.6 Originals URL resolver

ServerFieldsにはOriginals URL resolverがある。

優先順位:

1. Sheet上の保存済みOriginals URLを読む。
2. allowFallbackがtrueならDrive scanを試す。
3. 見つからなければDriveBuilderのensureEntityFolderでフォルダを自動作成する。
4. URLを返す。

Open Originalsを押したとき、フォルダがまだなければ作成される場合がある。ただし通常操作として強調しすぎず、Admin/トラブルシュートで扱う。

26.7 Originals URLの保存値

Originals URLは、以下の形式から正規化される可能性がある。

• Google Drive folder URL
• Drive open?id形式
• folder id単体

UIでは最終的に https://drive.google.com/drive/folders/... 形式で開く。

26.8 ServerFieldsのトラブルシュート

Originalsが開けない原因候補:

• idがない
• entityが不明
• sheetがない
• id fieldが解決できない
• originals columnが解決できない
• Sheet上のOriginals URLが空
• DriveBuilderがない
• originals_root_urlがない
• Drive権限がない

LinkMapが解決しない原因候補:

• 対象entity sheetがない
• 2段ヘッダを正しく読めていない
• entity_name列がない
• LINK_MAPS cacheが古い
• record idが存在しない

27. DriveBuilder 詳細

27.1 DriveBuilderの役割

DriveBuilderは、MOTKプロジェクトのGoogle Driveフォルダ構造を保証・監査するためのサーバー側ヘルパーである。

目的:

• Originals rootを確認する
• entity rootを作る
• record folderを作る
• id__code形式にリネーム・統合する
• Versions field folderを作る
• 不足フォルダを検出する
• 不足フォルダを作る
• Soft delete用のdeleted folderへ移動する

27.2 基本フォルダ構造

Originals rootの下にentity rootを作る。

標準構造:

• 01shots
• 02assets
• 03tasks
• 04misc
• 05deleted

プロジェクトセットアップ時に必ず作るのは主に01shotsと02assetsである。03tasks、04misc、05deletedはオンデマンド作成される。

27.3 Entity root

entityとrootの対応:

• shot / shots -> 01shots
• asset / assets -> 02assets
• task / tasks -> 03tasks
• user / users -> 04misc
• member / members -> 04misc
• page / pages -> 04misc
• sched / card / misc -> 04misc
• deleted -> 05deleted

Admin向けには「Task foldersは必要になった時点で作られる」と説明する。

27.4 Record folder naming

record folderは基本的に以下の形である。

• id
• id__code

codeが分かる場合は id__code にする。

例:

• sh_0001__501A
• as_0002__RobotArm
• tk_0012__Lighting

codeが後から設定された場合、bare idフォルダをid__codeへ統合・リネームする処理がある。

27.5 Folder consolidation

DriveBuilderは、bare idフォルダとid__codeフォルダが両方ある場合、内容を統合し、重複フォルダをtrashへ送ることがある。

通常ユーザー向けには詳しく書かず、Admin向けに「重複フォルダがある場合は統合される可能性がある」と書く。

27.6 Versions folder

Versions fieldごとに、record folder内にversions用サブフォルダを作る。

命名規則:

• field_id__label

例:

• fi_0013__shotview
• fi_0023__assetview
• fi_0032__versions

古い shotview や assetview だけのフォルダがある場合、field_id付きの命名へ移行される可能性がある。

27.7 Versions folder repair

SettingsまたはDebug系から、versions field folderを修復する処理がある。

指定entity、field_id、label、limitをもとに、各recordにVersions folderを作る。

対象entity:

• shot
• asset
• task

Admin向けには「Versions fieldを追加した後、既存recordsに対応フォルダを作るための修復処理」と説明する。

27.8 Drive Diff / Fix Missing / Ensure All Folders

Drive Diffは、Sheets上のrecord IDとDrive上のrecord foldersを比較する。

出力:

• missing
• existing
• hubTotal
• driveTotal

Fix Missingは、Drive Diffでmissingになったrecord folderだけを作る。

Ensure All Foldersは、すべての主要entityに対して不足フォルダを作る。

UserGuideでは「既存フォルダや既存ファイルは削除しない」と明記する。

27.9 Soft Delete

Soft deleteはrecord folderを05deletedへ移動する。

削除ではなく移動である。

管理・保守寄りの操作として扱い、通常ユーザー向けには「削除ではなく退避」と説明する。

28. Settings詳細補足

28.1 Settingsの構成

Settingsは、複数の管理機能が同じ画面に集約されている。

大分類:

• project_meta editor
• Theme
• PNAVI Config
• Hydrate Originals URLs
• Task Est Recalculate
• Drive Folders Ensure Missing
• Drive Folders Diff / Fix
• User Access / Sharing
• Proxy Ops
• Proxy Audit
• Log

Settingsは日常作業画面ではなく、管理・保守・初期設定の画面として説明する。

28.2 project_meta editor

project_meta editorでは、meta_key、meta_value、meta_type、note、updated_atを管理する。

新規行はmeta_key、meta_value、meta_type、noteが必須。

updated_atはread-only。

project_metaが外部SpreadsheetからIMPORTRANGEされている場合、ローカル側ではread-onlyになる。この場合、Settings上では保存ボタンを押しても書き込めない。

28.3 project_meta管理モード

想定されるモード:

• local_sheet
• external_importrange_mirror
• formula_managed_local_sheet
• external_source_only
• missing

local_sheet: このSpreadsheet内のproject_metaを直接編集する。

external_importrange_mirror: 外部Spreadsheetからproject_metaをミラーしている。ローカルでは読み取り専用。

formula_managed_local_sheet: ローカルsheetだが数式管理されているため読み取り専用。

external_source_only: admin workbook側のproject_metaを参照している。

missing: project_metaが見つからない。

28.4 SystemConfig

SystemConfigは、ProxyやAuditなどのシステム設定を保存する別系統の設定である。

主なキー:

• drive.originals.root_id
• drive.proxies.root_id
• proxy.preset.default
• proxy.audit.enabled
• proxy.audit.hour
• proxy.audit.limit
• proxy.audit.entities
• proxy.audit.last_run_at
• proxy.audit.last_missing_count
• proxy.audit.last_error

project_metaはプロジェクト全体の意味設定。SystemConfigはシステム運用やProxy/Auditのための設定。

28.5 Access / Write Access

Settingsの読み取りと書き込みには権限チェックがある。

読むだけならaccess。

書き込みはwrite access。

Admin/Editor/Viewerの関係は権限章でまとめる。

28.6 Admin users

SettingsにはAdmin listがあり、管理用workbookのADMIN_USERS sheetと関係する。

Admin追加モーダルでは、ユーザーを選んでAdmin権限を付与する。

初期セットアップ時の「最初のAdminをどう作るか」は別途詳しく書く。

28.7 Sharing sync

Users.permissionを基準に、Google Drive/Sheetsの実共有と同期する。

Valid roles:

• viewer
• editor

AdminはUsers.permissionとは別に、管理用workbookのADMIN_USERS sheetで管理される。

Sync Checked: 選択したユーザーだけ同期。

Sync Mismatches: 設定と実共有がズレているユーザーを同期。

Refresh: 現状を読み直す。

28.8 Settings Log

SettingsのLogは、保守操作の結果やエラーを表示する。

保守操作を実行したらLogを確認する。

問題報告時はSettings Logをコピーする。

29. Upload / Versions / ProxyJobs 詳細

29.1 Uploadの全体像

MOTKのUploadは、単にDriveへファイルを置くだけではない。

Uploadすると、以下が同時に進む。

1. 対象entity/record_id/field_idを決定する。
2. record folderを解決または作成する。
3. versions field folderを解決または作成する。
4. Drive fileを作成する。
5. UploadInboxへ行を追加する。
6. ProxyJobsへpending jobを追加する。
7. versions latest pointerを書き込む。
8. Originals URLをtouch/updateする。

現行MOTKでは、独立したUpload専用ページを前提にせず、DetailのVersions UploadやSettingsのProxy Ops upload導線から入るものとして説明する。

29.2 UploadInbox

UploadInboxは、アップロードされたファイルの記録である。

主な列:

• upload_id
• ts
• entity
• record_id
• originals_folder_id
• drive_file_id
• drive_file_name
• uploaded_by
• proxy_job_id
• status
• field_id
• latest_pointer_json

29.3 ProxyJobs

ProxyJobsは、プロキシ生成ジョブを管理するシートである。

現行MOTKでは、Proxy Queueという別シートではなく、ProxyJobsとUploadInboxを分けて説明する。

主な列:

• job_id
• status
• source_file_id
• source_file_name
• entity
• record_id
• originals_folder_id
• proxies_folder_id
• output_file_name
• preset
• claimed_by
• claimed_at
• heartbeat_at
• finished_at
• error_message
• field_id
• source_updated_at
• output_file_id
• output_updated_at

status候補:

• pending
• claimed
• processing
• done
• error

Worker側の状態は、ProxyJobsのstatus、claimed_by、claimed_at、heartbeat_at、finished_at、error_messageなどで確認する。

29.4 latest_pointer_json

versions fieldは、最新ファイルへのpointerをJSONで保持する。

pointerには、source、fileId、name、mimeType、updatedAt、url、openUrl、previewUrl、thumb、fieldId、recordIdなどが含まれる。

通常ユーザーには「Latest Versionの参照情報」と説明する。Admin向けには「versions fieldが空に見える場合はlatest_pointer_jsonやfield_idを確認する」と書く。

29.5 Default versions field

Upload時にfield_idが指定されない場合、entity内のversions type fieldを探してdefaultにする。

優先候補:

• ShotView
• AssetView
• Versions

ただし、実際にはFields定義次第である。フィールド名やfield_idを固定前提にせず、versions typeのFields metadataから解決されるものとして説明する。

29.6 Requeue

Proxy Audit rowからProxy jobを再作成する機能がある。

OriginalsはあるがProxyがない場合に、再度ProxyJobsへ入れるための操作である。

29.7 Upload失敗時

原因候補:

• write accessがない
• entityがない
• record_idがない
• versions fieldが見つからない
• field_idがversions typeではない
• field_id entity mismatch
• upload fileがない
• drive.proxies.root_idが未設定
• originals folderが作れない
• Drive権限がない

報告時に必要な情報:

• entity
• record_id
• field_id
• file name
• Settings Log
• ProxyJobs row
• UploadInbox row
• Console

30. Proxy Ops / Proxy Audit / WorkerKit 詳細

30.1 Proxy Ops

Proxy Opsは、MOTKの軽量プレビュー生成パイプラインの管理画面である。

Originalsは素材の元ファイル。

Proxiesは表示・レビュー用の軽いファイル。

Proxy WorkerはProxyJobsを読み、ffmpegなどで変換し、Proxies folderへ出力する。

30.2 Proxy Config

必要設定:

• drive.originals.root_id
• drive.proxies.root_id
• proxy.preset.default

proxy.preset.defaultは通常 proxy_h264 のような変換presetである。

30.3 Proxy Overview

SettingsのProxy Opsでは以下を表示する。

• Recent Proxy Jobs
• Recent Uploads
• Workers
• Summary pills

Summaryはstatusごとの件数。

Proxyが出ない場合はここを最初に確認する。

30.4 WorkerKit画面

WorkerKit画面は、MOTK Proxy Worker Kitをダウンロードし、ローカルワーカーを動かすための入口である。

画面にある導線:

• Download Worker Kit
• Open GitHub Repo
• Setup手順
• MOTK Proxy Worker.bat
• 04_run_worker_once.bat

30.5 WorkerKit setup

1. Worker Kitをダウンロードする。
2. zipを展開する。
3. MOTK Proxy Worker.bat を起動する。
4. MOTKのpublic URLを貼る。
5. Detectを押す。
6. Google sign-inを行う。
7. ffmpeg、OAuth token、Spreadsheet accessを確認する。
8. WorkerをStartする。
9. SettingsのProxy OpsでWorkersとProxyJobsを見る。

30.6 Worker behavior

Workerはpending proxy jobを1件ずつ取得する。

処理中はjob statusを更新する。

完了すると、output file idやoutput updated atをProxyJobsに書き戻す。

Versions pointerも更新される。

複数Workerを使えば、処理スループットが上がる。

30.7 Media behavior

WorkerKit画面のmedia behavior:

• Video becomes MP4 proxy.
• Images become image proxy without resizing.
• PDFs pass through as original.

30.8 Run one job only

04_run_worker_once.bat は1件だけjobを処理する用途。

本番連続運用の前に1件だけ動かして確認する。

30.9 Proxy Audit

Proxy Auditは、OriginalsとProxiesの対応を検査する。

ProxyAudit sheetの主な列:

• scanned_at
• entity
• record_id
• display_name
• originals_folder_id
• originals_folder_url
• originals_file_count
• latest_original_file_name
• latest_original_file_id
• latest_original_modified
• proxy_status
• proxy_file_name
• proxy_file_id
• latest_job_status
• latest_job_id
• latest_upload_status
• note

30.10 Proxy Audit config

設定:

• enabled
• hour
• limit
• entities
• last_run_at
• last_missing_count
• last_error
• trigger state

対象entity:

• shot
• asset
• task

Daily ScanをONにすると、時間指定で定期検査される。

30.11 Proxy Auditの読み方

proxy_statusがmissingなら、OriginalsにファイルがあるがProxyがない。

latest_job_statusがerrorなら、Worker側で失敗した可能性が高い。

latest_upload_statusがqueuedのままなら、アップロード後の処理が進んでいない可能性がある。

originals_file_countが0なら、そもそもOriginalsにファイルがない。

latest_original_modifiedとoutput_updated_atを比較すると、Proxyが古い可能性を見ることができる。

30.12 Proxyトラブルシュート

Proxyが見えないときの順序:

1. DetailのVersions fieldにlatest pointerがあるか。
2. Originals folderにファイルがあるか。
3. UploadInboxにqueued/doneの記録があるか。
4. ProxyJobsにpending/error/doneがあるか。
5. Workerが動いているか。
6. Proxies root idが設定されているか。
7. ProxyAuditでmissingになっていないか。
8. DebugPanelでVersions/Originals resolverを見る。

31. Forum 詳細

31.1 Forumの基本

Forumは、MOTK内のスレッド型コミュニケーション画面である。

General ThreadとEntity Threadがある。

General Threadはプロジェクト全体や一般的な話題。

Entity Threadはshot/asset/task/member/userなど特定recordに紐づく議論。

現行MOTKでは、ForumThreads、ForumPosts、ForumRecentに保存され、APIは 2SV_DataCore.js 内の sv_forum_overview_v2 / sv_forum_post_v1 などで扱われる。

31.2 Forumの画面構成

左側:

• Threads
• Search
• Tags
• New Thread
• Refresh
• Thread List

右側:

• 選択中ThreadのTitle
• thread metadata
• Post button
• Composer
• Thread Posts
• Recent posts

31.3 Thread List

Thread Listには、thread type、entity:record_id、updated time、title、last post preview、tagsが表示される。

クリックすると該当Threadを開く。

検索やタグで絞り込める。

31.4 Tag Search

Tag Cloudからタグを選ぶと、そのタグを持つスレッドに絞り込む。

Composerではtagsをカンマ区切りで入力する。

タグ例:

• review
• proxy
• design
• animation
• blocking
• client

31.5 Composer

投稿モード:

• General Thread
• Entity Thread

入力欄:

• Thread Title
• Entity
• Record ID
• Post Title
• Body
• Tags

General Threadではthread titleが重要。

Entity Threadではentityとrecord_idがthread keyになる。

31.6 DetailからForumへ

DetailにはDiscussボタンがある。

DetailからForumを開く場合、entity、record id、titleをprefillできる。

ショットやタスクの議論をrecordに紐づけやすい。

31.7 Forumの日常ワークフロー

ショットレビューコメント:

1. Shot Detailを開く。
2. Discussを押す。
3. Entity ThreadとしてForumが開く。
4. Post Titleに要点を書く。
5. Bodyにレビューコメントを書く。
6. tagsにreview, animation, compなどを入れる。
7. 投稿する。

プロキシ不具合報告:

1. 対象TaskまたはShot Detailを開く。
2. Discussを押す。
3. Post Titleに「proxy missing」などを書く。
4. Bodyに何が見えないかを書く。
5. tagsにproxy, bugを入れる。
6. 投稿後、AdminがProxy Auditを確認する。

General Threadで制作連絡:

1. Forumを開く。
2. New Threadを押す。
3. General Threadを選ぶ。
4. Thread Titleを書く。
5. Bodyに連絡内容を書く。
6. tagsをつける。

31.8 Forumで追加確認する点

保存先sheet名と基本API名は確認済みである。

32. Dashboard 詳細

32.1 Dashboardの位置付け

Dashboardは、MOTKの入口であり、プロジェクトの概要と最近の更新を見る画面である。

Shellに埋め込まれ、SoftNavでTable/Detailと切り替わる。

Dashboardは編集よりも「状況把握」「入口」「軽いOps」に向いている。

32.2 Dashboardの表示内容

主なWidget:

• Project Snapshot
• Update Feed
• Drive Repair / Ops
• Layout

Project Snapshotは、Shots、Assets、Tasks、Membersなどの件数を表示する。

Update Feedは、最近更新されたshots/assets/tasksなどを表示する。

Drive Repair / Opsは、Drive folder repair、safe folder sync、proxy pipeline state、WorkerKitへの導線を持つ。

Layoutは、Dashboard widgetsの配置をleft/center/right/hiddenに変更する。

32.3 Dashboard layout

Dashboardはleft column、center feed、right columnを持つ。

left/rightは隠せる。

both offの場合、centerだけの表示になる。

layout stateはlocalStorageに保存される。

32.4 Dashboardからの導線

Dashboardから移動できるもの:

• Shots Table
• Assets Table
• Tasks Table
• Members Table
• Detail page
• Forum thread
• WorkerKit
• Settings
• Debug
• Schedule / SchedView

Feed itemやstatをクリックしてTable/Detailへ移動する。

32.5 DashboardのDrive Repair / Ops

DashboardにもSettingsの一部に近いOps導線がある。

ボタン:

• Refresh
• Fix Shot
• Fix Asset
• Fix Task
• Ensure Drive Folders
• Worker Kit
• Download Worker

DashboardのOpsはショートカットであり、本格設定はSettingsで行う。

32.6 Dashboardの使用例

朝の確認:

1. Dashboardを開く。
2. Project Snapshotで件数を見る。
3. Update Feedで直近更新を確認する。
4. Tasksに移動して今日の作業を見る。
5. SchedViewで作業量を見る。

Adminの軽い確認:

1. Dashboardを開く。
2. Drive Repair / OpsをRefresh。
3. Proxy状態を見る。
4. 必要ならWorkerKitへ移動。
5. 問題があればSettingsで詳細確認。

33. 管理者向け初期セットアップ

33.1 初期セットアップの章を作る理由

MOTKは単なるHTMLアプリではなく、Sheets、Drive、Apps Script、権限、Workerが関係する。

UserGuideには日常作業編とは別にAdmin Setup Guideが必要である。

33.2 初期セットアップ候補手順

1. Host Spreadsheetを用意する。
2. Apps Scriptをデプロイする。
3. HOST_SS_IDを設定する。
4. project_metaを用意する。
5. SystemConfigを用意する。
6. Fieldsを用意する。
7. Shots/Assets/Tasks/ProjectMembers/Users/Pagesを用意する。
8. Drive Originals rootを作る。
9. Drive Proxies rootを作る。
10. project_metaまたはSystemConfigへroot id/urlを保存する。
11. Settingsを開く。
12. Themeを設定する。
13. PNAVIを設定する。
14. Ensure All Foldersを実行する。
15. Hydrate Originals URLsを実行する。
16. User Access / Sharingを設定する。
17. WorkerKitをダウンロードする。
18. Proxy Configを保存する。
19. 1件だけVersions Upload -> Worker once -> Proxy表示までテストする。
20. SchedViewで表示確認し、Schedulerで編集導線を確認する。
21. DebugPanelでRun all checksを実行する。

33.3 セットアップ完了判定

完了条件:

• Dashboardが開く
• TableでShots/Assets/Tasksが表示される
• Detailが開く
• Link chipが名前で表示される
• Originalsが開く
• Uploadできる
• ProxyJobsにjobが入る
• Workerで1件処理できる
• DetailまたはTableにproxy/thumbnailが出る
• SchedViewとSchedulerが開く
• Settingsでproject_metaが読める
• DebugPanelで重大エラーが出ない

33.4 初期セットアップ時の注意

project_metaがexternal sourceの場合、local Settingsからは編集できない。

Drive root idが未設定だと、Originals/Proxy関連が動かない。

Fieldsのid/entity_name/typeが不正だと、LinkMaps、Detail title、Table columnsが壊れる。

Pagesが空でもDefault表示は可能だが、保存したpresetは出ない。

Google権限はSpreadsheetとDriveの両方が必要。

34. 権限・共有の補足

34.1 MOTK内権限とGoogle共有

MOTKの権限は、アプリ内でユーザーが何をできるかを決める。

Google共有は、実際にSpreadsheetやDrive folderへアクセスできるかを決める。

どちらか片方だけ合っていても、完全には動かない。

34.2 権限不一致の例

MOTKではeditorだが、Drive Originals folderにアクセス権がない:

• Tableは見える
• Detailは見える
• Originalsを開くとGoogle Drive側で拒否される
• Uploadできない可能性がある

Google Driveにはアクセスできるが、MOTKではviewer:

• Driveは見える
• MOTK上では編集できない
• Settings保存やUploadは拒否される可能性がある

34.3 User Access / Sharingで見るべきもの

• Users list
• permission
• checked users
• mismatches
• resources
• summary

34.4 権限問題の報告テンプレート

• どのGoogleアカウントか
• どのページか
• 何を押したか
• MOTK上のrole
• Google Drive/Sheetsで開けるか
• Settings Access summary
• エラー文

35. 追加ワークフロー

35.1 プロジェクト開始前のAdminワークフロー

1. Host Spreadsheetを作る。
2. Fieldsを確定する。
3. 各entity sheetを作る。
4. id/entity_name/typeの整合を確認する。
5. project_metaを作る。
6. PNAVIを作る。
7. Pages defaultを確認する。
8. Drive Originals/Proxiesを作る。
9. Settingsでroot idを保存する。
10. Drive Ensureを実行する。
11. Hydrate Originalsを実行する。
12. DebugPanelでSchema/Meta Healthを確認する。
13. Test recordを作り、Table/Detail/Versions Upload/Proxy/SchedView/Schedulerを1周確認する。

35.2 新規スタッフ参加時

1. UsersにGoogle accountを追加する。
2. permissionをviewer/editorに設定する。
3. ProjectMembersに制作上のroleを追加する。
4. User LinkでUsersとProjectMembersを紐づける。
5. SettingsのSharing Syncを実行する。
6. そのユーザーがDashboardとTableを開けるか確認する。
7. Drive Originals/Proxiesへのアクセスを確認する。
8. 必要ならSchedViewのlane visibilityに追加し、編集が必要な場合はSchedulerでも確認する。

35.3 Fieldsを追加したとき

1. Fieldsに新fieldを追加する。
2. 対象entity sheetにfield_id列を追加する。
3. type、label、editable、requiredを設定する。
4. Pages presetに列を追加する。
5. Detail presetにカードを追加する。
6. versions typeならVersions folder repairを実行する。
7. DebugPanelでFieldTypes Healthを確認する。
8. TableとDetailで表示確認する。

35.4 新しいVersions fieldを追加したとき

1. Fieldsでtype=versionsを追加する。
2. 対象entity sheetへ列を追加する。
3. Detail presetにversions cardを追加する。
4. SettingsまたはDebugからversions folder repairを実行する。
5. 既存recordにfield_id__labelフォルダができるか確認する。
6. Test uploadをする。
7. ProxyJobsが作られるか見る。
8. Worker onceで処理する。
9. Detailで最新versionが表示されるか確認する。

35.5 Drive folderが壊れたとき

1. SettingsのDrive Diffを実行する。
2. missing一覧を見る。
3. Fix Missingで不足分だけ作る。
4. Ensure All Foldersを必要に応じて実行する。
5. Hydrate Originals URLsを実行する。
6. 対象DetailでOriginalsを開く。
7. DebugPanelのOriginals diagnosticsを確認する。

35.6 Proxy pipelineを復旧するとき

1. Settings Proxy Opsでroot idを確認する。
2. Recent Proxy Jobsを見る。
3. Workerがonlineか確認する。
4. Proxy AuditをRun Nowする。
5. missing rowsを見る。
6. 必要ならRequeueする。
7. Worker onceで1件処理する。
8. ProxyJobsがdoneになるか見る。
9. Detailでproxy表示を確認する。

35.7 ページ表示がおかしくなったとき

1. 別presetを選ぶ。
2. Fields menuで表示列を確認する。
3. Save/Revertを確認する。
4. DebugPanel Viewer Stateを見る。
5. Column Manifestを疑う。
6. PageConfigが別entityのものを読んでいないか確認する。
7. Pages sheetのentity/pageType/pageId/configを確認する。

36. FAQ補足

Q. Saveとセル編集の保存は同じですか？

違う。セル編集は制作データの値を更新する。Save/Save As/Revertは主に表示設定やレイアウトを保存する。

Q. Link fieldにIDが見えます。壊れていますか？

必ずしも壊れていない。LinkMapsがまだ読み込まれていない、対象recordの名前が取れない、またはcacheが古い場合はID表示になることがある。

Q. Originalsを押したらフォルダが作られました。正常ですか？

MOTKは対象recordのOriginals folderがない場合、アクセス時に作ることがある。Admin運用ではDrive EnsureやHydrateで事前に作っておく方がよい。

Q. Proxyがすぐ出ません。

Upload後、ProxyJobsに入り、Workerが処理してから表示される。Workerが止まっている場合やProxy rootが未設定の場合は出ない。

Q. Dashboardの左右パネルは消せますか？

消せる。Dashboardはleft/right panelをhiddenにでき、配置はlocalStorageに保存される。

Q. ForumはShot専用ですか？

Shot専用ではない。General ThreadとEntity Threadがあり、shot/asset/task/member/userに紐づけられる。

Q. project_metaが編集できません。

外部Spreadsheetからミラーされている、または数式管理されている場合はread-onlyになる。管理元のSpreadsheetを編集する必要がある。

Q. Pagesが空でもTableは開きますか？

Fields metadataからDefault Pageが合成される場合がある。ただし保存されたpresetは表示されない。

Q. Workerは何をしますか？

ProxyJobsからpending jobを取り、動画をMP4 proxyに変換し、画像をimage proxyとして扱い、PDFはoriginalとして通す。完了後にProxyJobsやVersions pointerを更新する。

38. Scheduler / SchedView 詳細

38.1 Scheduler / SchedViewの基本分類

Scheduler / SchedViewは、MOTKの中でも操作リスクが高い領域である。

TableやDetailは主にrecord単位の編集だが、Schedulerは複数のTask、担当、開始/終了、Duration、Asset conflict、Publish状態に影響する。

Schedulerは単なるカレンダー画面ではない。Taskを時間軸とlane上に配置し、制作上の負荷・順序・担当・競合を見ながら、必要に応じて保存・複製・公開するSchedule editorである。

SchedViewはScheduleを読むための表示画面である。

SchedulerはScheduleを編集するための画面である。

38.2 SchedView

SchedViewは読み取り中心のSchedule viewerである。

できること:

• Daily表示
• Slot表示
• Member lane表示
• Asset lane表示
• View / Edit interaction切り替え
• Zoom調整
• Lane visibility調整
• Display fields調整
• Card list検索
• Inspector確認
• Schedulerと同じ視覚要素の一部共有

SchedViewは、今のスケジュールを理解する、密度を見る、担当やAssetごとの偏りを見る、編集前に確認するための画面である。

38.3 Scheduler

Schedulerは編集中心のSchedule boardである。

できること:

• Cardを移動する
• Cardをresizeする
• 複数Cardを選択する
• Laneを変える
• Date / Slotを変える
• InspectorでCard内容を確認・編集する
• Save Asする
• Publishする
• Undo modalを使う
• Snapshot / named snapshotを使う
• Settingsで表示・編集条件を調整する

Schedulerは計画を変える画面である。UserGuideでは、ViewとEditの違いを強く説明する。

39. SchedView 詳細

39.1 SchedViewの一文説明

SchedViewは、スケジュールを読むためのビューアである。Dailyで日ごとの密度を見たり、Slotで作業の時間幅を見たり、Member/Assetごとのlaneで負荷や競合を確認する。

39.2 SchedView toolbar

SchedView toolbarにあるもの:

• schedule switch
• Mode: Daily / Slot
• Lane: Member / Asset
• Interaction: View / Edit
• Zoom
• Fit
• Apply
• Save view
• Card List search
• Settings / display fields
• Lane visibility

39.3 Schedule switch

Schedule switchは、複数のscheduleやviewを切り替えるためのselectである。

選ぶ対象はschedule本体、またはPagesに保存されたSchedView viewである。

39.4 Mode: Daily

Dailyは日単位で見る表示である。

向いている用途:

• 1日ごとの作業量を見る
• 今日・明日・今週の密度を見る
• PMやDirectorが会議で全体を確認する
• Artistが自分の予定をざっくり確認する

Dailyでは細かいslot幅より、日ごとのまとまりが重要である。

39.5 Mode: Slot

Slotは時間またはslot単位で見る表示である。

向いている用途:

• 作業の長さを見る
• 同じ日に複数Taskが重なっていないか見る
• Lane上の隙間を見る
• Asset conflictやMember負荷を見る

SlotはSchedulerの編集画面と近い見た目を持つが、View interactionでは読み取り専用である。

39.6 Lane: Member

Member laneは、担当者または制作上のroleごとにScheduleを見る。

向いている用途:

• 担当者の作業量を見る
• 誰に負荷が集中しているか見る
• 空いているMemberを探す
• Artistが自分のlaneを見る

39.7 Lane: Asset

Asset laneは、AssetごとにScheduleを見る。

向いている用途:

• 同じAssetに作業が集中していないか見る
• Asset conflictを確認する
• Character / prop / set単位の負荷を見る
• Asset Detailと行き来して調整する

39.8 Interaction: View

Viewは読み取りモードである。

会議、レビュー、個人確認ではViewを基本にする。

誤ってScheduleを変更しないため、UserGuideではまずViewで確認する流れを書く。

39.9 Interaction: Edit

EditにするとSchedulerへ移動し、Slot編集用の操作に入る。

現行MOTKでは、Daily + ViewとSlot + ViewはSchedView、Slot + EditはSchedulerで扱う。

39.10 Zoom

Zoomは表示密度を変える。

Dailyではday height、Slotではslot pixelや時間幅の見え方に関係する。

Zoomはデータを変えず、見え方だけを変える。

39.11 SchedView Inspector

SchedViewにもInspectorがある。

SchedViewのInspectorは確認用である。TaskやCard dataを変更する場合はScheduler Editへ移動する。

39.12 SchedViewの日常ワークフロー

PMが朝に確認する:

1. SchedViewを開く。
2. Daily表示にする。
3. LaneをMemberにする。
4. 今日と明日の密度を見る。
5. 負荷が高いMemberを確認する。
6. Card Listで締切近いTaskを探す。
7. 必要ならTableやDetailを開く。
8. 必要ならInteractionをEditにしてSchedulerへ進む。

SupervisorがAsset負荷を見る:

1. SchedViewを開く。
2. Slot表示にする。
3. LaneをAssetにする。
4. Asset conflictがあるCardを見る。
5. 該当Task/Asset Detailを開く。
6. PMと調整する。

Artistが自分の予定を見る:

1. SchedViewを開く。
2. LaneをMemberにする。
3. 自分のlaneだけ表示する。
4. Dailyで今日の作業を見る。
5. CardをクリックしてTask Detailを開く。

40. Scheduler画面構成 詳細

40.1 Scheduler toolbar

Scheduler toolbarには、Scheduleの選択、保存、Publish、Undo、Settings、表示切替、Lane操作、Zoomや幅調整などがまとまる。

40.2 Grid area

Grid areaはScheduleの本体である。

ここにlane、date axis、slot、Cardが表示される。

操作:

• Card選択
• Drag
• Resize
• Drop
• Multi select
• Lane scroll
• Date scroll

40.3 Date axis

Date axisはScheduleの横または縦の時間軸である。

Dailyでは日付単位、Slotでは時間またはslot単位で見える。

40.4 Lane headers

Lane headersはMemberやAssetの名前を表示する。

Lane visibilityやLane orderの影響を受ける。

40.5 Asset column

SchedulerにはAsset columnがある。

Asset columnはAsset conflict、Asset grouping、Asset lane確認に関係する。

40.6 Inspector

Inspectorは選択したCardの情報を見る場所である。

主な内容:

• Card title
• Task link
• Assignee
• Start / End
• Duration
• Status
• Asset links
• Shot links
• Notes
• Conflict info

40.7 Inspector resizer

Inspector resizerは、Inspectorの幅を調整する。

大きい画面では広げ、小さい画面では畳む。

40.8 Settings modal / inline settings

SchedulerにはSettings modalがあり、InspectorのSettings tab内にdocked/inline表示される場合がある。

SettingsはSchedule表示や編集設定に影響する。

41. Card 詳細

41.1 Cardとは

CardはSchedule上の作業単位である。

多くの場合、CardはTaskを表す。

ただし、taskless cardのように、まだTask recordへ完全に紐づいていない作業単位もある。

41.2 Cardの表示要素

Cardに表示される要素:

• Task ID
• Main field
• Sub field
• Extra fields
• Status
• Assignee
• Start / End
• Duration
• Asset link
• Shot link
• Conflict indicator
• Camera move indicator
• Taskless marker

表示されるfieldは、Scheduler/SchedViewのdisplay fields設定に依存する。

41.3 Card status color

Cardの色はStatusに応じて変わる。

例:

• not_started
• in_progress
• review
• approved
• completed
• blocked

色は、進捗や注意状態を一目で見るための補助である。

41.4 selected / multi-selected

selectedは現在選択中のCardである。

multi-selectedは複数選択中のCardである。

複数選択では、まとめて移動できる場合がある。

41.5 unsaved

unsavedは、画面上では変更されたが保存が完了していない状態である。

保存中や失敗時はstatus areaを確認する。

41.6 taskless

taskless cardは、Task recordに紐づいていない、またはTaskとして未確定のSchedule cardである。

メモ、仮置き、作業枠、未確定予定に使われる可能性がある。

最終的にはTask recordへ変換するか、対応するTask Linkを持たせる運用が必要である。

41.7 camera-move

camera-moveは、撮影やカメラ移動に関係するCardを視覚的に区別する表示である。

Stop-motion/VFXでは、camera moveは撮影・モーションコントロール・コンポジットの連携に影響するため、Schedule上で視覚的に区別する価値がある。

41.8 asset-conflict

asset-conflictは、同じAssetに関係する作業が重なっている、または競合している可能性を示す。

asset-conflictが出た場合、Schedulerだけで直すのではなく、Task DetailとAsset Detailも確認する。

41.9 Card close/remove

Card close/removeは、Schedule上の配置を外す操作として説明する。

現行MOTKでは、Cardを消すことはTask record自体の削除ではなく、Schedule card rowまたは配置の削除として扱う。

Taskを削除する操作と混同しないように説明する。

41.10 Card resizer

Card resizerは、Cardのdurationやslot幅を変える操作である。

Resizeした結果がTask側のestimateへ反映されるか、Schedule側の配置情報として保存されるかは、Publishや設定との関係で説明する。

42. Lite token / Daily token

42.1 Lite tokenとは

Lite tokenは、Daily表示などで使う軽量なCard表現である。

Slot cardほど大きく表示せず、日ごとの予定を短く見せる。

42.2 Lite tokenの表示

Lite tokenに表示されるもの:

• Main field
• Sub field
• Status color
• Assignee
• Task / Taskless区別

42.3 DailyとSlotの違い

Daily:

• 日単位で見る
• 密度を見る
• 会議向き
• 全体把握向き

Slot:

• 時間またはslot単位で見る
• 長さを見る
• 編集前確認向き
• Scheduler編集に近い

43. Drag / Resize / Drop 操作

43.1 Drag preview

Drag previewは、Cardを動かしている途中に表示される仮表示である。

Drop前にどこへ置かれるかを確認する。

43.2 Drop slot line

Drop slot lineは、Cardを置く候補位置を示す線である。

Slotの境界や日付の境界を確認するために使う。

43.3 Gap marker / gap hitbox

Gap markerはSchedule上の空きや挿入候補を示す。

Gap hitboxは、その空きへCardを差し込むための操作領域である。

43.4 複数Card移動時の注意

複数Cardを移動すると、相対位置、日付、lane、durationの関係がまとめて変わる可能性がある。

Publishや保存の前に、以下を確認する。

• すべて同じ意図で移動したか
• 担当者が変わっていないか
• 日付がずれていないか
• Asset conflictが増えていないか
• Completed taskを意図せず動かしていないか

44. Inspector 詳細

44.1 Inspector tab

Inspector tabは、選択したCardの詳細を見る場所である。

表示候補:

• Card ID
• Task ID
• Task name
• Assignee
• Status
• Start
• End
• Duration
• Asset Link
• Shot Link
• Notes
• Conflict information

44.2 Card List tab

Card ListはSchedule上のCard一覧である。

できること:

• Card検索
• Statusで確認
• Assigneeで確認
• Tasklessを探す
• クリックして該当Cardへジャンプ

Scheduleが大きいときはCard Listから探す。

44.3 Settings tab

Settings tabではSchedule表示・編集の設定を行う。

扱うもの:

• Work hours
• Slot minutes
• Origin date
• Display fields
• Lane visibility
• Lane width
• Inspector width
• Asset width
• Color settings

44.4 Date picker overlay

Date picker overlayは、日付を直接選ぶためのUIである。

日付がずれる場合はtimezone guardやproject timezoneを確認する。

45. Lane管理

45.1 Lane visibility

Lane visibilityは、表示するlaneを選ぶ設定である。

部署、担当者、Asset種別などに応じて絞り込める。

45.2 Lane order

Lane orderは、laneの並び順である。

会議では、並び順を固定しておくと話しやすい。

45.3 Lane width

Lane widthは、laneの幅である。

名前が長い、Cardが多い、Inspectorを開いている場合に調整する。

45.4 Member laneとAsset laneの切り替え

同じScheduleでも、Member laneとAsset laneで見方が変わる。

Member lane:

• 人の負荷を見る
• 担当者ごとに整理する

Asset lane:

• Asset競合を見る
• Assetごとの作業集中を見る

46. Save View / Save As / Publish 詳細

46.1 Save View

Save Viewは、SchedViewの見え方を保存する操作である。

保存対象:

• Mode
• Lane axis
• Zoom
• Visible lanes
• Display fields
• Date range
• Width settings

Save ViewはTask dataを変えない。

46.2 Save As

Save Asは、現在のscheduleまたは表示設定を別名で保存する操作である。

Schedulerで大きな変更をする前にSave Asを推奨する。

使う場面:

• 来週案を作る
• 別案を比較する
• Published scheduleを直接編集せずdraftを作る
• 会議用の見方を保存する

46.3 Publish

Publishは、draftや作業中のscheduleを確定・反映する操作である。

現行MOTKではprogressive Publishとして扱う。

1. 未publishedのscheduleをPublishすると、published timestampを設定してlocked snapshotにする。
2. locked snapshotのPublishでは、Schedule cardをTasksへ反映する。
3. Tasksへ反映するとき、Completed tasksはskipされる。

UserGuideではPublishを最も慎重に説明する。

46.4 Publish前チェックリスト

Publish前に確認するもの:

1. 正しいscheduleを開いている。
2. 正しいView/Modeで見ている。
3. Member laneで負荷を確認した。
4. Asset laneで競合を確認した。
5. Completed taskを意図せず変えない。
6. Taskless cardの扱いを確認した。
7. Timezone warningがない。
8. Save queueが詰まっていない。
9. Card Listで未割り当てを確認した。
10. 関係者に確認した。
11. 必要ならSnapshotを作った。
12. Publish後にTable/Task側で値が反映されるか確認する。

46.5 Publish後チェック

Publish後に確認するもの:

• Schedulerを再読み込みしてCard位置が残るか。
• SchedViewで同じscheduleが見えるか。
• Tasks Tableで担当、開始日、終了日、orderが想定通りか。
• Completed tasksがskipされているか。
• DebugPanelやConsoleにfatal errorがないか。

46.6 Publishを押してはいけない場面

• どのscheduleか分からない。
• Timezone warningがある。
• Save queueが残っている。
• Asset conflictを確認していない。
• Completed taskが混ざっている可能性がある。
• Taskless cardの扱いが未確認。
• Undo/Snapshotが取れていない。
• PM/Supervisorの確認前。

47. Undo / Snapshot 詳細

47.1 Undoの位置付け

Undoは、Scheduler上の変更を戻すための機能である。

Undo modalには履歴リストがある。

Undoは安全装置だが、Publish前の確認やSave Asの代わりにはならない。

47.2 Undo item

Undo itemの種類:

• Card move
• Card resize
• Lane change
• Field edit
• Batch edit
• Snapshot restore
• Publish-related action

Undo itemは、どのscope、どのschedule、どのactorの操作かを確認して使う。

47.3 Snapshot

Snapshotは、Scheduler状態の保存点である。

使う場面:

• 大きな変更前
• Publish前
• 会議前
• 別案比較前
• Undoだけでは不安なとき

Snapshotは戻れる場所として説明する。

47.4 Named Snapshot

Named Snapshotは、名前付きの保存点である。

例:

• Before Monday PM Review
• Director Alt A
• Pre Publish Check

重要な変更前にはNamed Snapshotを使う。

現行実装では、名前付きsnapshotはrolling cleanupから除外される。

47.5 UndoとRevertの違い

Undo: 直前または履歴上の操作を戻す。

Revert: 保存済み設定やpresetへ戻す。

Snapshot restore: 特定時点のScheduler状態へ戻す。

Publish: Scheduleを正式化またはTasksへ反映する。

47.6 Undo使用時の注意

Undo使用時に確認するもの:

• 正しいscheduleか。
• 正しいUndo itemか。
• 他の人の操作を戻していないか。
• Publish後の状態を戻そうとしていないか。
• Undo後に保存またはPublishが必要か。

48. Timezone guard

48.1 Timezone guardとは

Timezone guardは、project timezoneや実行環境timezoneが不足・不一致の場合に、Schedule操作を止める安全装置である。

Schedulerでは日付・slot・durationが重要なので、timezoneの不一致は重大な問題になる。

48.2 いつ出るか

• project timezoneが未設定
• Apps Script timezoneとproject timezoneが合わない
• browser側の日付解釈が不安定
• Schedulerが日付計算を安全にできない

48.3 UserGuideでの説明

日付が1日ズレるとSchedule全体が壊れる可能性がある。

Timezone warningが残っている場合はPublishしない。

Settingsやproject_metaでtimezoneを確認する。

49. Task recalculationとScheduler

49.1 Task Est Recalculate

Task Est Recalculateは、Tasksの推定日数・推定時間・計算式を再計算する管理操作である。

対象フィールドは固定field IDではなく、現行のFields metadataとproject_meta設定に従う。

49.2 Schedulerとの関係

SchedulerのCard duration、start/end、work hours、slot minutes、Task estimateは相互に関係する。

Schedule上でCardの長さを変更した場合、それがTaskのestimateへ反映されるか、Schedule専用の配置情報として保存されるかは、Publishや設定との関係で説明する。

確認すべき観点:

• Scheduler上のduration変更がTask sheetへ反映されるか。
• Task Est RecalculateがScheduler配置に影響するか。
• Publish時にTask側の開始/終了/担当が更新されるか。
• Schedule draftではTaskを変えず、Publishで反映するか。

49.3 Task Recalculateを使う場面

• project_metaのestimate ruleを変えた。
• Task typeやdepartmentごとの計算式を変えた。
• Task durationが古い。
• Scheduler上のdurationとTask上のestimateがずれて見える。

49.4 Task Recalculateの注意

Task Recalculateは広い範囲に影響する。

完了済みタスクを含めるかどうかを確認する。

実行前後でTasks TableとSchedulerを確認する。

50. Schedule Settings

50.1 Work hours

Work hoursは、1日の作業時間帯である。

例:

• start = 09:00
• end = 18:00
• lunch breakを考慮するか

Schedulerのduration計算やCard配置に影響する可能性がある。

50.2 Slot minutes

Slot minutesは、Schedulerの最小時間単位である。

例:

• 15分
• 30分
• 60分

Slot minutesが小さいほど細かく配置できるが、画面は密になる。

50.3 Origin date

Origin dateはSchedule表示の基準日である。

間違えるとSchedule全体がずれて見える。

50.4 Display fields

Display fieldsはCard内に出すfieldを選ぶ設定である。

候補:

• Task Name
• ShotCode
• Asset Name
• Status
• Assignee
• Due Date
• Task Type
• Department

実際の表示はFields metadataとTask/Shot/Asset link解決に依存する。

50.5 Main field / Sub field

Main fieldはCardで最も目立つ文字である。

Sub fieldは補助情報である。

例:

• Main = Task Name
• Sub = Assignee / Due Date
• Extra = ShotCode / Status

51. Schedule保存対象の分類

51.1 View settings

View settingsは見え方である。

保存対象:

• Mode
• Lane axis
• Zoom
• Visible lanes
• Display fields
• Widths
• Date range

Pagesまたはview configに保存される。

51.2 Schedule layout

Schedule layoutはCard配置である。

保存対象:

• Card lane
• Card date
• Card start/end
• Card order
• Card size
• Taskless card

SchedulerのSave/Publishで保存される。

51.3 Task data

Task dataはTasks sheetの値である。

例:

• Assignee
• Status
• Start Date
• End Date
• Due Date
• Duration
• Task Order

PublishまたはInspector編集で反映される可能性がある。

52. Schedule状態モデル

52.1 Draft

Draftは、まだ公開されていない編集途中のScheduleである。

試案、別案、調整中に使う。

52.2 Working

Workingは、現在編集しているScheduleである。

保存済みか未保存かをstatus areaで確認する。

52.3 Snapshot

Snapshotは、戻れる保存点である。

Named Snapshotは名前付きの重要保存点である。

52.4 Published

Publishedは、Scheduleが正式版として扱われる状態である。

現行MOTKでは、published timestampが入るとlocked snapshotとして扱われる。

52.5 Locked

Lockedは、直接編集できない状態である。

Published scheduleはlock indicatorで表示される。

編集したい場合はSave Asでdraftを作る。

53. Schedulerの日常ワークフロー

53.1 PMが週次スケジュールを調整する

1. SchedViewを開く。
2. Dailyで今週の密度を見る。
3. LaneをMemberにする。
4. 負荷が高いMemberを確認する。
5. InteractionをEditにする。
6. Schedulerで対象scheduleを確認する。
7. Save Asで週次案を作る。
8. Named Snapshotを作る。
9. Cardを移動・resizeする。
10. Asset laneでconflictを見る。
11. Card Listで未割り当てを見る。
12. Timezone warningがないことを確認する。
13. Save queueが空になるまで待つ。
14. Publish前チェックを行う。
15. SchedViewで見え方を確認する。
16. 問題なければPublishする。

53.2 SupervisorがAsset衝突を確認する

1. SchedViewを開く。
2. Slot表示にする。
3. LaneをAssetにする。
4. asset-conflict cardを見る。
5. Task Detailを開く。
6. Asset Detailを開く。
7. 作業順序を確認する。
8. 必要ならTaskのAssigneeや日付を調整する。
9. PMに相談する。
10. PMと確認してPublishする。

53.3 Artistが自分の作業だけを見る

1. SchedViewを開く。
2. Member laneにする。
3. 自分のlaneだけ表示する。
4. Dailyで今日のTaskを見る。
5. CardからTask Detailを開く。
6. 作業後にStatusを更新する。

53.4 Directorがレビュー日程を見る

1. SchedViewを開く。
2. Daily表示にする。
3. StatusやDisplay fieldsをreview向けにする。
4. ShotやTaskをDetailで開く。
5. ForumまたはDetail Noteでコメントする。

54. Schedulerトラブルシュート

54.1 Boardが空

原因候補:

• date range外
• schedule idが違う
• view modeが違う
• lane visibilityで全lane非表示
• Cardがない
• load API failure
• timezone guardで止まっている

確認:

• URLの ?p=schedule / ?p=schedview
• schedId
• Fit
• Lane visibility
• Card List
• DebugPanel Scheduler Load Diagnostics
• Console

54.2 Cardsが見えないがCard Listにはある

原因候補:

• 現在のdate range外
• laneが非表示
• zoomが極端
• slot minutesが合っていない
• card heightが小さい
• filter/display設定

対処:

• Fitを押す
• Lane visibilityを全表示にする
• Zoomを戻す
• Card Listから該当Cardへジャンプする

54.3 Cardを動かしたのに保存されない

原因候補:

• View modeで見ている
• Published/locked scheduleを編集しようとしている
• Save queueが失敗した
• timezone guardが出ている
• write accessがない
• network/GAS error

確認:

• status area
• Console
• Settings Access
• Scheduler save path

54.4 Publish後にTaskが変わっていない

原因候補:

• 最初のPublishでlocked snapshotになった段階で、Tasks反映は次のPublish操作だった。
• Publish対象が別schedule。
• Completed tasksがskipされた。
• Taskless cardだった。
• Save queueが残っていた。
• Publish APIが失敗した。

確認:

• Publish status message
• Tasks Table
• SchedView
• Console
• DebugPanel

54.5 Undoできない

原因候補:

• Undo historyがない
• Snapshotがない
• すでにPublished/lockedで直接戻せない
• 他ユーザー操作とconflictしている
• Undo modalが開いていない
• API failure

54.6 日付が1日ずれる

原因候補:

• project timezone未設定
• Apps Script timezone不一致
• browser timezoneとの差
• date fieldの保存形式

対処:

• Timezone guardを確認する
• Settings/project_metaのtimezoneを確認する
• Publishしない
• DebugPanelに報告する

54.7 Asset conflictが消えない

原因候補:

• 同じAssetを複数Taskが同時に使っている
• Asset linkが古い
• Taskの開始/終了が重なっている
• Asset laneで見ていない
• cacheが古い

対処:

• SchedViewをAsset laneにする
• Task DetailでAsset Linkを見る
• Asset DetailでLinked Tasksを見る
• Schedulerで日付や担当を調整する
• SchedViewを再読み込みする

55. Acceptance test観点

55.1 Schedulerは完了判定のcore flow

Acceptance briefでは、Scheduler/SchedViewはoperational enough for normal useであることがcompletion criteriaに含まれている。

UserGuideでも、Schedulerはオプションではなく、MOTKの中核機能として扱う。

55.2 テストで見るべき項目

• ?p=schedule が開く。
• ?p=schedview が開く。
• Daily表示が出る。
• Slot表示が出る。
• Member laneが出る。
• Asset laneが出る。
• Cardが見える。
• Dragできる。
• Resizeできる。
• Save Asできる。
• Publishできる。
• Undo modalが開く。
• Snapshotを作れる。
• Taskless cardが壊れない。
• Completed tasksがPublishでskipされる。
• Consoleにfatal errorがない。

55.3 報告すべき重大不具合

Schedulerに関する重大不具合:

• Cardが別Taskへ保存される。
• Drag後に別laneへ勝手に入る。
• Publishで意図しないTaskが更新される。
• Undoが別scheduleへ戻す。
• 日付が1日ずれる。
• Upload/Proxyと同様に、違うrecordへ書く。
• Locked scheduleが直接編集できる。

55.4 軽微扱いでよいもの

• 文字が少し切れる
• Zoom初期値が好みでない
• Lane幅を手動調整したい
• 色が分かりにくい
• Card Listの並び順を変えたい

軽微でも、制作判断に影響する場合は報告する。

56. Scheduler用語集補足

SchedView: Scheduleを見るための画面。

Scheduler: Scheduleを編集するための画面。

Schedule: 作業配置のまとまり。

schedId: Scheduleを識別するID。

Card: Schedule上の作業単位。多くはTask。

Taskless card: Task recordにまだ紐づいていないSchedule card。

Lane: MemberまたはAssetなどで分けた行・列。

Member lane: 担当者基準のlane。

Asset lane: Asset基準のlane。

Daily: 日単位の表示。

Slot: 時間またはslot単位の表示。

Zoom: 表示密度。

Fit: 表示範囲に合わせる操作。

Inspector: 選択Cardの詳細パネル。

Card List: Schedule上のCard一覧。

Asset conflict: 同じAssetの作業が競合している可能性。

Camera move: 撮影・カメラ移動に関係するCard表示。

Publish: Scheduleを正式版としてlockし、lock済みsnapshotをTasksへ反映する操作。

Undo: Scheduler操作を戻す機能。

Snapshot: Scheduler状態の保存点。

Named Snapshot: 名前付きSnapshot。

Timezone guard: 日付ずれを防ぐ安全装置。

Save As: 別案やdraftを作る保存操作。

Save View: SchedViewの見え方を保存する操作。

第4部 作成・編集・表示

1. Create New Recordの基本

1.1 Create New Recordとは

Create New Recordは、Shots、Assets、Tasks、Usersなどのentityに新しいrecordを追加する操作。

Table toolbarのNewボタンから開く。

New modalは、現在開いているentityに対してrecordを作る。

例:

• Shots TableでNew → 新しいShotを作る。
• Assets TableでNew → 新しいAssetを作る。
• Tasks TableでNew → 新しいTaskを作る。
• Users TableでNew → 新しいUserを作る。

1.2 New modalの基本動作

Newボタンを押すとCreate modalが開く。

modal内には、そのentityで編集可能なfieldだけが表示される。

非編集fieldやsystem fieldは表示しない。

fieldの表示順は、Google Sheetsの列順に合わせる。

アルファベット順ではない。

これは重要。制作データでは、列順が人間の作業順になっていることが多い。

1.3 Create modalで出るfield

表示されるべきfield:

• editable=trueのfield
• required field
• text/select/date/linkなど、ユーザー入力対象のfield
• entity_name相当のfield
• Statusなど初期入力が必要なfield
• Shot/Asset/Task linkなどの関連field

表示されるべきでないfield:

• id field
• generated field
• system-managed field
• originals URL field
• computed field
• read-only json
• updated_atなどの自動更新field
• versions pointer JSON

1.4 IDの扱い

IDは通常自動生成される。

ユーザーはCreate modalでIDを入力しない。

理由:

• IDはlink、Drive folder、Versions、Scheduler、ProxyJobsなどの内部参照に使う。
• 手入力ミスがあると関連データが壊れる。
• 名前は後から変えられるが、IDは変えるべきではない。

UserGuideでは「IDは機械用、Name/Codeは人間用」と書く。

1.5 entity_nameの扱い

entity_nameは人間が見る名前。

Create時に必須になることが多い。

例:

• ShotCode
• Asset Name
• Task Name
• User Name
• Role

entity_nameが空だと、Link chipやDetail titleがID表示になりやすい。

1.6 Create後の表示

Createが成功すると、新しいrecordはTableに追加される。

MOTKでは作成されたrowにhighlightが付くことがある。

その後、Detailへ移動して詳細編集できる。

UserGuideでは「Createは最小情報を作る操作、Detailは作ったrecordを整える操作」と説明できる。

1.7 Create後に確認すること

新しいrecordを作った後に確認するもの:

1. Tableにrecordが表示されたか。
2. IDが自動生成されたか。
3. entity_nameが期待通りか。
4. Detailが開くか。
5. Link fieldsが正しく表示されるか。
6. Originals folderが必要なら開けるか。
7. TaskならScheduler/Cardに出す必要があるか。

2. Create New Recordのentity別説明

2.1 New Shot

New Shotは新しいShot recordを作る。

入力候補:

• ShotCode
• Episode
• Act
• Sequence
• Scene
• Shot
• Status
• Due Date
• Artist Note
• Producer Note
• Asset Link
• Task Link

Shot IDは自動生成される。

ShotCodeは手入力またはEpisode/Act/Sequence/Scene/Shotから生成される可能性がある。

New Shot後の推奨確認:

1. Shot Detailを開く。
2. ShotView/Comp/Materials/Versionsカードがあるか確認する。
3. Asset Linkを追加する。
4. Taskを作る場合はTask Linkを追加する。
5. Originals folderをEnsure/Hydrateする。

2.2 New Asset

New Assetは新しいAsset recordを作る。

入力候補:

• Asset Name
• Asset Type
• Status
• Shot Link
• Task Link
• Notes

Asset IDは自動生成される。

Asset Typeはcharacter、prop、environment、set、backgroundなどの分類に使う可能性がある。

New Asset後の推奨確認:

1. Asset Detailを開く。
2. AssetView/Versionsカードを確認する。
3. 関連ShotがあればShot Linkを追加する。
4. 関連TaskがあればTask Linkを追加する。
5. Asset originals folderを確認する。

2.3 New Task

New Taskは新しい作業単位を作る。

入力候補:

• Task Name
• Task Type
• Status
• Assignee
• Due Date
• Shot Link
• Asset Link
• Notes

TaskはSchedulerと関係が深い。

New Task後の推奨確認:

1. Task Detailを開く。
2. Shot LinkまたはAsset Linkを確認する。
3. Assigneeを設定する。
4. Due Dateを設定する。
5. Scheduler/SchedViewに出るか確認する。
6. TaskView/Versionsが必要ならUploadする。

2.4 New User

New UserはGoogle accountまたはMOTK利用者を追加する。

入力候補:

• User Name
• Email
• Permission
• Department
• Notes

User IDは自動生成される。

New User後の推奨確認:

1. Users Tableで表示を確認する。
2. permissionを確認する。
3. SettingsのUser Access / Sharingで同期する。
4. Google Drive/Sheetsへの実アクセスを確認する。
5. ProjectMembersとUser Linkで紐づける。

2.5 New Member

ProjectMembersは制作上の役割や参加者を表す。

入力候補:

• Role
• Department
• User Link
• Notes

UsersはGoogleアカウント。

ProjectMembersは制作上の立場。

同じ人が複数roleを持つ場合、UserとMemberを分ける意味がある。

3. Create modalのfield widget

3.1 text field

text fieldは自由入力。

用途:

• Notes
• Description
• Title
• Name
• Code

短文はTableでも編集できる。

長文はDetailで編集した方が安全。

3.2 select field

select fieldは選択肢から値を選ぶ。

用途:

• Status
• Asset Type
• Task Type
• Department
• Permission

選択肢はFields定義や既存値から来る可能性がある。

選択肢にない値を入れられるかどうかはfield設定による。

3.3 date field

date fieldは日付を入れる。

用途:

• Due Date
• Start
• End
• Updated date

Timezoneに注意。

ScheduleやDue Dateで1日ズレると運用上大きな問題になる。

3.4 checkbox field

checkbox fieldはtrue/falseを扱う。

用途:

• enabled
• visible
• required flag
• core field flag
• option toggles

Create modalで出ることは少ないが、設定系entityでは出る可能性がある。

3.5 link field

link fieldは他entityへの参照。

Create modalではLink Pickerを開いて選ぶ。

直接IDを手入力するよりPickerを使う方が安全。

link fieldの種類:

• asset_link
• shot_link
• task_link
• member_link
• user_link

3.6 versions field

versions fieldはCreate modalでは通常編集しない。

Versionsはrecord作成後にUploadで追加する。

Create時にversions pointer JSONを手入力するべきではない。

3.7 originals field

Originals fieldは通常Create modalでは編集しない。

Originals URLはDriveBuilder/Hydrate/Uploadによって補完される。

ユーザーが手入力すると、Drive folder整合性が壊れる可能性がある。

3.8 json field

json fieldは通常Create modalでは出さない。

Pagesやproject_metaなど一部Admin操作ではJSONを扱うが、一般record作成では非表示でよい。

4. Editable / Non-editable

4.1 editableの基本

editableは、ユーザーがUIから編集できるかどうかを決めるfield metadata。

editable=trueなら、Table inline editやDetail edit、Create modalに出る可能性がある。

editable=falseなら、通常ユーザーは編集しない。

4.2 requiredとの違い

requiredは、そのrecordを作る/保存するために必要なfield。

editableとrequiredは別。

• editable=true, required=true: ユーザーが入力すべき必須field
• editable=true, required=false: 任意入力field
• editable=false, required=true: システムが必ず持つべきfield。自動生成の可能性が高い。
• editable=false, required=false: 表示専用または内部用field

4.3 Non-editableを隠す理由

Create modalでnon-editable fieldを出すと、ユーザーが内部値を壊す可能性がある。

特に危険なfield:

• id
• field_id
• versions pointer
• originals url
• generated path
• updated_at
• system status
• worker job id

4.4 Acceptance観点

Create New RecordのAcceptanceでは、以下が確認項目。

• fields are shown in GS column order, not alphabetical
• only editable fields appear
• non-editable fields do not appear
• link fields open picker in front of modal
• field widgets match normal table/detail behavior

これはUserGuideにも「正しい挙動」として書ける。

5. Link Picker

5.1 Link Pickerとは

Link Pickerは、link fieldに他entityのrecordを選ぶためのUI。

IDを直接入力する代わりに、名前やIDで検索して選ぶ。

5.2 Link Pickerが使われる場所

使われる場所:

• Table inline edit
• Create New Record modal
• Detail field edit
• Scheduler InspectorのTask Assets編集
• Forum entity prefillの関連操作

5.3 Link Picker対象

対象entity:

• Asset Link → Assets
• Shot Link → Shots
• Task Link → Tasks
• Member Link → ProjectMembers
• User Link → Users

5.4 表示名

Link Pickerは、IDだけでなくentity_nameを表示するべき。

例:

• sh_0001 / 501A
• as_0002 / Robot Arm
• tk_0012 / Lighting
• pm_0003 / Animator A
• us_0001 / Producer

entity_nameが取れない場合はID表示になる。

5.5 複数選択

link fieldは複数IDを持てる場合がある。

例:

• Shotに複数Asset Link
• Assetに複数Shot Link
• Taskに複数Asset Link

複数選択時は、チップやカンマ区切りで表示される。

5.6 Pickerがmodalの後ろに出る問題

Create New RecordやDetail card settingsなどのmodal内でLink Pickerを開く場合、Pickerがmodalの後ろに出ると使えない。

Acceptanceでは「link picker appears in front of the modal」が確認項目。

UserGuideのトラブルシュートでは「Pickerが見えない場合はz-index問題」として書ける。

5.7 Link Pickerで選んだ後

選択後に確認すること:

• chipが表示されるか。
• IDではなく名前が出るか。
• 保存後にreloadして残るか。
• 関連Detailへ移動できるか。
• 逆方向リンクが必要なら反映されているか。

5.8 Link Pickerの失敗原因

原因候補:

• LINK_MAPSが空。
• target entityが解決できない。
• field typeがlinkとして認識されていない。
• entity_name fidがない。
• modalのz-index問題。
• API missing。
• 権限不足。

6. Inline Edit

6.1 Inline Editとは

Inline Editは、Table上のセルを直接編集する機能。

短い値やステータス更新に向いている。

長文、複雑なリンク、Versions、Originalsの操作にはDetailの方が向いている。

6.2 Inline Editの開始

セルをダブルクリック、または編集可能セルをクリックして開始する。

編集可能な場合、input/select/date/link pickerなどのwidgetが出る。

Acceptanceでは、Shot Noteのセルをダブルクリックし、値を入力してEnterで保存した例がある。

6.3 Inline Editの保存

保存方法:

• Enter
• blur
• 選択確定
• select変更

実装上の正確な保存トリガーはfield typeによる。

保存時はstatus barにUpdatingなどが出る。

成功後はTable表示が更新される。

6.4 Inline Edit後の確認

重要なのはreload後に値が残ること。

UserGuideでは、編集後に保存成功表示だけでなく、必要に応じてreload確認する方法を書く。

確認項目:

1. セルが新しい値になる。
2. Status barにエラーがない。
3. Reload後も値が残る。
4. Detailでも同じ値が出る。
5. 違うfieldが変わっていない。

6.5 Inline Editに向くfield

向くfield:

• Status
• Due Date
• short text
• Assignee
• Permission
• Asset Type
• Task Type
• simple notes

向かないfield:

• long note
• versions
• originals
• json
• multi-line complex data
• generated fields

6.6 Inline Editの失敗例

失敗として扱うべきもの:

• 保存成功表示なのにreloadで戻る。
• 違うfieldが変わる。
• 違うrecordが変わる。
• INLINE_EDIT_EXCEPTIONが出る。
• 編集inputが出ない。
• edit後にTable全体が再描画されて選択を失う。
• stale dataで直近編集が上書きされる。

6.7 Inline Editの重大度

Inline editで違うfield/recordへ保存されるのはCRITICAL。

保存されないだけならHIGH。

表示上の反映が遅いだけでreload後に正しければLOW。

7. Detail Edit

7.1 Detailでの編集

Detailは1recordを深く編集する画面。

Tableよりも文脈が見えるため、以下に向いている。

• 長めのNote
• Versions upload
• Related links確認
• Card単位の整理
• Review status更新
• Shot/Asset/Taskの詳細確認

7.2 DetailのApply

Single-field cardにはApplyボタンがある場合がある。

Applyは、そのfield値を保存する操作。

Acceptanceでは、single-field card Applyが動作し、保存後にpersistしたことが確認されている。

7.3 DetailのSaveとCard layout Save

DetailにもSave系操作があるが、field値の保存とcard layout保存を混同しない。

• Field Apply / field save = 制作データ保存
• Cards / Preset Save = Detailの見え方保存

7.4 Detail edit後の確認

1. Fieldが更新されたか。
2. Reload後に残るか。
3. Tableで同じ値が見えるか。
4. Link fieldならchipが正しいか。
5. Versionsならpreviewが出るか。

8. CommonRenderer

8.1 CommonRendererの役割

CommonRendererは、field typeに応じて値の見せ方・編集方法を決める共通レイヤー。

Table、Detail、Create modal、Link field、Versions、Thumbnailsなどで同じtype解釈を使う。

8.2 CommonRendererが重要な理由

同じfield typeなのにTableとDetailで挙動が違うと混乱する。

CommonRendererに寄せることで、以下を統一できる。

• link chip表示
• Drive link表示
• date表示
• select表示
• versions preview
• thumbnail表示
• field metadata解釈
• editable判定

8.3 SchemaResolverとの関係

CommonRendererはSchemaResolverを使い、field_idからmetadataを解決する。

SchemaResolverが見つけるもの:

• id fid
• entity_name fid
• type別fid
• field_name別fid
• fidからfield meta
• fidからentity

8.4 FIELD_TYPESとの関係

FIELD_TYPESが空または不正だとCommonRendererは正しいwidgetを出せない。

症状:

• link fieldがtextになる。
• versionsがJSON文字列になる。
• checkboxがtextになる。
• dateが通常文字列になる。
• editableでないfieldが編集可能になる。

8.5 LINK_MAPSとの関係

LINK_MAPSがないと、link chipの表示名がIDになる。

CommonRendererはLinkMapsを使ってIDを人間向けlabelへ変換する。

8.6 Routerとの関係

CommonRendererはlink chipからDetail URLを作る。

Routerはentityに応じてDetailShot、DetailAsset、DetailTask、DetailUser、DetailMemberなどへ振り分ける。

UserGuideでは「chipをクリックすると関連Detailへ移動できる」と説明する。

9. Field type別の操作説明

9.1 id

表示専用。

編集しない。

内部参照、Drive folder、link、versions、proxy、schedulerに使われる。

9.2 entity_name

表示名。

Create時・Detail編集時に重要。

変更してもIDは変わらない。

9.3 text

直接入力。

Table inline editまたはDetailで編集。

長文はDetail推奨。

9.4 select

選択肢から選ぶ。

Statusなどに使う。

Create modal、Table、Detailで同じ選択肢を使うべき。

9.5 date

日付入力。

Due DateやStart/Endに使う。

Timezoneと1日ズレに注意。

9.6 checkbox

true/false。

設定系ではよく使う。

制作recordでは限定的。

9.7 asset_link

Asset recordへのリンク。

PickerでAssetsから選ぶ。

選択後、Asset chipとして表示される。

9.8 shot_link

Shot recordへのリンク。

TaskやAssetからShotへ飛ぶために使う。

9.9 task_link

Task recordへのリンク。

ShotやAssetに関連Taskを紐づける。

9.10 member_link

ProjectMembersへのリンク。

Assigneeなどで使う。

UserではなくMemberを指す場合がある点に注意。

9.11 user_link

Usersへのリンク。

ProjectMemberとGoogle accountを紐づける用途。

9.12 originals

Originals folderへのリンク。

通常は編集しない。

Open OriginalsでDrive folderを開く。

9.13 thumbnails

サムネイル表示。

Table/Detailで視覚確認に使う。

直接編集より、Upload/Versions/Proxy経由で更新する。

9.14 versions

バージョン表示・アップロード・preview。

Upload overlayやDetail versions cardからファイルを追加する。

内部的にはlatest pointer JSONやProxyJobsと関係する。

10. Versions upload overlay

10.1 Versions upload overlayとは

TableやDetailのversions/shotview/assetviewセル上に出るUpload導線。

普段は常時表示せず、hover時に出る。

Acceptanceでは「versions upload overlay appears on hover, not always」が確認項目。

10.2 なぜhover overlayなのか

常時表示するとTableがうるさくなる。

hover時だけ出すことで、レビュー時の視認性とアップロード操作を両立する。

10.3 Upload modal

Upload overlayを押すとUpload modalが開く。

Upload modalには以下がある可能性がある。

• file input
• target entity
• record id
• field id
• proxy preset dropdown
• Upload button
• Cancel/Close

10.4 Proxy Preset

Upload modalにはProxy Preset dropdownがある。

例:

• proxy_h264

Proxy Presetは、Workerがどの変換設定でproxyを作るかを示す。

10.5 Upload後の流れ

1. ファイルを選ぶ。
2. Uploadを押す。
3. modalが閉じる。
4. UploadInboxに記録される。
5. ProxyJobsにjobが入る。
6. Versions pointerが更新される。
7. Table/Detailのversions cell/cardが更新される。
8. Worker処理後にProxy badgeまたはpreviewが出る。

10.6 Upload後に確認すること

• modalが閉じたか。
• cell/cardが更新されたか。
• previewできるか。
• correct record folderに入ったか。
• wrong bare folderが作られていないか。
• ProxyJobsが作成されたか。
• Worker処理後にproxyが出るか。

10.7 Uploadの重大不具合

重大な問題:

• 違うrecord folderへ入る。
• bare folderを再作成する。
• field_idが違うversions folderに入る。
• modalが閉じない。
• ProxyJobsが作られない。
• pointerが更新されない。
• Previewが壊れる。

10.8 Table uploadとDetail uploadの違い

Table upload:

• 一覧から素早く追加する。
• 複数recordを見ながら作業できる。
• 対象セルを間違えないように注意。

Detail upload:

• 1recordに集中して追加する。
• 関連情報を確認しながら安全に操作できる。
• 長期的にはDetail uploadの方が事故が少ない。

11. Preview modal

11.1 Preview modalとは

versionsやthumbnailのmediaを開いて大きく見るためのmodal。

画像ファイルではpreviewが表示される。

動画ではproxyまたはDrive previewを使う可能性がある。

11.2 Previewで確認すること

• 画像が表示される。
• 正しいrecordのmediaである。
• 最新versionである。
• ORIGINAL/PROXY badgeが意味と合っている。
• 閉じられる。

11.3 Previewが壊れる原因

• Drive権限がない。
• pointer JSONが壊れている。
• file idが無効。
• proxyがまだない。
• mime typeが対応外。
• image previewではなくPDF/videoだった。
• browser security制限。

12. ORIGINAL / PROXY badge

12.1 Badgeの意味

ORIGINALは元ファイルを表示している状態。

PROXYは軽量変換済みファイルを表示している状態。

12.2 どちらがよいか

レビューやTable表示ではPROXYが望ましい。

元ファイル確認や高画質確認ではORIGINALが必要な場合もある。

12.3 Badgeがcoherentであること

Acceptanceでは、ORIGINAL / PROXY state badgeがcoherentであることが確認項目。

coherentとは、表示されているmediaの状態とbadgeが一致していること。

例:

• ProxyがないのにPROXY表示されない。
• Originalを表示しているならORIGINALと出る。
• Proxy生成後はPROXYへ切り替わる。

13. Save status / Status bar

13.1 Table status bar

Table下部にはstatus barがある。

表示例:

• loading...
• Updating...
• applying page...
• 1-100 of 290 Shots
• error message

13.2 Status barを見る理由

保存や読み込みの状態を確認する。

Inline edit後はUpdatingが出る。

Errorが出たら値が保存されていない可能性がある。

13.3 0 of 0と空表示

過去には0 of 0が誤解を招く問題があった。

UserGuideでは「読み込み中やキャッシュ復元中の空表示は、実データ0件とは限らない」と説明する。

13.4 applying pageが残る場合

applying pageが長く残る場合、PageConfig適用やStatus recoveryの問題の可能性がある。

DebugPanelのViewer State、Performance Snapshot、Consoleを確認する。

14. Modal / z-index / focus

14.1 Modalの種類

MOTKには複数のmodalがある。

• Create New Record modal
• Upload modal
• Link Picker
• Preview modal
• Detail card settings modal
• Scheduler settings modal
• Undo modal
• Remove card modal

14.2 Modalの重なり順

Create modalやUpload modalはTable上に高いz-indexで表示される。

Link Pickerはmodalの上に出る必要がある。

Preview modalも他のUIに隠れない必要がある。

14.3 z-index問題の症状

• Link Pickerがmodalの後ろに出る。
• Previewが見えない。
• Upload modalが閉じられない。
• 背景のTableがクリックされる。
• Modal上のbuttonが押せない。

14.4 Acceptanceでの重要性

Link Pickerがmodalの前に出ることはAcceptance項目。

Modalが使えない場合、CreateやUploadが事実上壊れるためHIGH以上になりやすい。

15. Search / Filter / Fields / Paginationと編集の関係

15.1 編集前の絞り込み

Tableで編集する前に、対象recordをFilter/Searchで絞る。

間違ったrecordを編集しないために重要。

15.2 Server search

Server searchは、サーバー側で文字列検索する。

大量行の中から対象recordを探す場合に使う。

15.3 Filter

Filterは表示中のTableに条件をかける。

Status、Assignee、Due Dateなどで絞る。

15.4 Fields toggle

Fields toggleで必要なfieldだけ表示する。

編集時は、対象fieldと識別fieldを同時に出すと安全。

例:

• ShotCode + Status + Due Date + Assignee
• Asset Name + Asset Type + Status
• Task Name + Assignee + Due Date + Shot Link

15.5 Pagination

Paginationで別ページに移動すると、編集中の状態を失う可能性がある。

保存が完了してからページ移動する。

15.6 ALL表示

ALL表示は大量行では重くなる可能性がある。

大量編集の確認には便利だが、通常は100/200程度で使う方が安定しやすい。

16. TableとDetailの使い分け

16.1 Tableが向いている作業

• 複数recordの比較
• Statusの一括確認
• Due Date順の確認
• Assigneeの確認
• 短いinline edit
• Filter/Sort/Search
• 複数recordをまたぐチェック

16.2 Detailが向いている作業

• 1recordの深い確認
• 長文Note
• Versions upload
• Preview
• 関連Shot/Asset/Task確認
• Card layoutで情報を見る
• Review作業

16.3 Createは入口、Detailは整備

新規recordはTableのNewで作る。

作ったrecordはDetailで情報を整える。

17. 操作別ワークフロー

17.1 新しいShotを作ってAssetを紐づける

1. Shots Tableを開く。
2. Newを押す。
3. ShotCodeやStatusなど必要fieldを入力する。
4. Asset Link fieldでLink Pickerを開く。
5. 対象Assetを検索して選ぶ。
6. Createを押す。
7. 作成されたrowがTableに出ることを確認する。
8. Shot Detailを開く。
9. Asset chipをクリックしてAsset Detailへ移動できるか確認する。
10. 必要ならOriginals folderを開く。

17.2 Taskを作って担当者を入れる

1. Tasks Tableを開く。
2. Newを押す。
3. Task NameとTask Typeを入れる。
4. Statusをnot_startedにする。
5. AssigneeでMember Link Pickerを開く。
6. 担当Memberを選ぶ。
7. Shot LinkまたはAsset Linkを選ぶ。
8. Due Dateを入れる。
9. Createする。
10. Scheduler/SchedViewで表示されるか確認する。

17.3 TableでStatusを更新する

1. 対象entityのTableを開く。
2. Search/Filterで対象recordを絞る。
3. ShotCode/Asset Name/Task Nameで対象を確認する。
4. Status cellを編集する。
5. 保存状態を確認する。
6. Reloadしてpersistを確認する。

17.4 DetailでVersionを追加する

1. 対象recordのDetailを開く。
2. Versions cardを探す。
3. Uploadを押す。
4. ファイルを選ぶ。
5. Proxy Presetを確認する。
6. Uploadする。
7. modalが閉じるか確認する。
8. previewできるか確認する。
9. ProxyOps/ProxyAuditでjob状態を見る。

17.5 Linkを修正する

1. 対象recordをTableまたはDetailで開く。
2. link fieldを編集する。
3. Link Pickerで正しいrecordを選ぶ。
4. 保存する。
5. chipが期待名で表示されるか確認する。
6. chipクリックでDetailへ飛べるか確認する。
7. 必要なら逆側recordでも関連を確認する。

18. トラブルシュート

18.1 New modalが開かない

原因候補:

• New button handlerが壊れている。
• google.script.runが使えない。
• Fields metadataが取れていない。
• entityが不明。
• modalがCSSで隠れている。
• JavaScript error。

確認:

• Console
• Runtime
• FieldTypes Health
• URL entity

18.2 New modalにfieldが出ない

原因候補:

• editable=trueのfieldがない。
• Fields metadataが空。
• entity mismatch。
• field_idがsheetにない。
• field type判定が失敗。

確認:

• FieldTypes Health
• Column Contract
• Fields定義
• target entity

18.3 Non-editable fieldが出ている

これは危険。

原因候補:

• editable判定が壊れている。
• metadata bool変換が失敗。
• field type推定でsystem fieldをtext扱いしている。

対応:

• DebugPanelでFieldTypes Healthを見る。
• Createは中断する。
• Adminに報告する。

18.4 Link Pickerが空

原因候補:

• LINK_MAPSが空。
• target entityが間違っている。
• search条件が強すぎる。
• 権限がない。
• entity_name fidがない。

確認:

• LINK_MAPS counts
• Entity samples
• FieldTypes Health
• Console

18.5 Inline editが開始できない

原因候補:

• fieldがeditable=false。
• cellが特殊renderer。
• field typeが編集対象外。
• Tableがまだloading中。
• overlayが被っている。

18.6 Inline editが保存されない

原因候補:

• write accessがない。
• API failure。
• field validation failure。
• stale rows overwrite。
• wrong field binding。

確認:

• Status bar
• Console
• Binding Integrity
• Reload後の値

18.7 Upload modalが閉じない

原因候補:

• upload request failure。
• success handlerが走っていない。
• file size/mime type問題。
• Drive permission問題。
• proxy config missing。

確認:

• Console
• Settings Proxy Ops
• UploadInbox
• ProxyJobs

18.8 Previewが出ない

原因候補:

• file idが無効。
• Drive権限がない。
• pointer JSONが壊れている。
• Proxy未生成。
• mime type未対応。

確認:

• Versions field value
• Drive URL
• Proxy Audit
• Console

19. QA / Acceptance

19.1 Create New Recordで確認すること

• New button opens modal quickly enough for practical use.
• Fields are shown in GS column order, not alphabetical.
• Only editable fields appear.
• Non-editable fields do not appear.
• Link fields open picker in front of the modal.
• Field widgets match normal table/detail behavior.
• Record is created.
• Table highlights or surfaces it.
• Detail opens correctly.

19.2 Inline editで確認すること

• Safe text field can be edited.
• Safe select field can be edited.
• Safe permission/text field can be edited.
• No INLINE_EDIT_EXCEPTION.
• Value persists after refresh.
• No stale overwrite.

19.3 Versions uploadで確認すること

• Upload from Table works.
• Upload from Detail works.
• Modal closes on upload action.
• Uploaded file lands in correct record versions folder.
• Wrong bare folder is not recreated.
• Versions cell/card updates correctly.
• Preview can show image files.
• ORIGINAL / PROXY state badge is coherent.

19.4 重大Findingになるもの

• Create form omits editable fields.
• Create form includes non-editable fields.
• Link picker appears behind modal.
• Save appears successful but value does not persist.
• Stale data overwrites recent edit.
• Upload goes to wrong record folder.
• Wrong bare folder is recreated.
• Modal cannot be used.

20. 注意事項の要点

20.1 New Record注意

Newで作るのはrecordの入口です。作成後はDetailを開いて、関連リンク、Originals、Versions、Scheduleへの反映を確認してください。

20.2 Inline Edit注意

Tableのinline editは短い値の修正に向いています。長文Note、Versions、Originals、複雑なLink修正はDetailで行う方が安全です。

20.3 Link Picker注意

Link fieldはIDを直接入力せず、できるだけLink Pickerから選んでください。Pickerを使うと、対象entityと表示名を確認しながら安全にリンクできます。

20.4 Upload注意

Upload後、すぐにProxyが出るとは限りません。UploadはProxyJobsに入り、Workerが処理した後にProxyとして表示されます。

20.5 Save status注意

保存表示が出ても、重要な編集はreload後に残っているか確認してください。特に初期セットアップ中やfield定義変更後は確認が必要です。

第5部 ナビゲーションとURL

1. MOTKの画面遷移の基本構造

MOTKの画面遷移は、通常の単純なWebページ遷移ではない。

大きく分けると、以下の2種類がある。

1. Shell内で切り替わる画面 - Dashboard - Table - Detail

2. 独立ページまたは別タブで開く画面 - Settings - UserGuide - DebugPanel - Forum - WorkerKit - Scheduler - SchedView

Shell内ではDashboard/Table/Detailが静的にincludeされ、クリックイベントを捕まえてSoft Navigationで表示を切り替える。ブラウザのURLは変わるが、毎回フルリロードしているとは限らない。

UserGuideでは、これを「作業画面内の高速切り替え」と「管理・診断・大画面系の別ページ」という二層で説明するとよい。

2. Server template routing

2.1 doGetの役割

GASの doGet は、URLパラメータを読み、どのHTML templateを返すかを決める。

代表的なtemplate:

• 3CL_Shell
• 3CL_Forum
• 3CL_WorkerKit
• 1SA_DebugPanel
• 3CL_UserGuide
• 3CL_Scheduler
• 3CL_SchedView
• 3CL_Settings
• 3CL_Upload

2.2 Shellへ入るページ

以下は主にShellへ入る。

• empty page
• dashboard
• index
• table
• viewer
• shots
• assets
• tasks
• members
• projectmembers
• users

つまり、Shots/Assets/Tasksなどは別templateではなく、Shell内のTableとして扱われる。

2.3 独立templateへ入るページ

以下は独立templateとして返る。

• forum / chat
• workerkit / worker
• debug / debugpanel / debugpanelpage / tests / testresults
• userguide / guide / help
• schedule
• schedview
• settings
• upload

2.4 Settingsのaccess check

Settingsはtemplateを返す前にaccess helperで権限チェックが行われる。

権限がない、またはSettings auth helperが欠けている場合、Settings本体ではなくAccess error pageが返る。

UserGuideでは、Settingsが開けない場合は単なる表示エラーではなく、権限または管理ヘルパー問題として見る。

3. URLパラメータの体系

3.1 page と p

MOTKには page と p の両方がある。

page は明示的なページ名として使われる。

p は短いroute keyとして使われることが多い。

例:

• ?page=Dashboard
• ?p=table&e=shots
• ?page=DetailShot&entity=shot&id=sh_0001
• ?p=schedview
• ?page=Settings

UserGuideでは「どちらも画面指定。内部で正規化される」と説明する。

3.2 entity と e

entity と e も両方ある。

Tableでは e がよく使われる。

Detailでは entity がよく使われる。

例:

• ?p=table&e=assets
• ?page=DetailAsset&entity=asset&id=as_0001

3.3 id

id はrecord ID。

Detailではほぼ必須。

例:

• ?page=DetailShot&entity=shot&id=sh_0001
• ?page=DetailAsset&entity=asset&id=as_0001
• ?page=DetailTask&entity=task&id=tk_0001

3.4 pid

pid はpageIdまたはpreset idとして使われる可能性がある。

通常ユーザーは意識しないが、Table presetやPageConfig問題では重要。

3.5 schedId

schedId はScheduleを識別するID。

例:

• ?p=schedview&schedId=sched_0001

3.6 action

action は画面ではなく処理を返すrouteで使われる。

例:

• ?action=status
• ?action=worker-bootstrap
• ?action=diag-table-smoke
• ?action=diag-scheduler-smoke
• ?action=app-bundle

通常ユーザーは直接使わない。Admin/QA/WorkerKitでは重要。

4. Page / Entity normalization

4.1 正規化の目的

MOTKでは、複数の表記を内部の一貫した表現へ変換する。

例:

• shot / shots
• asset / assets
• member / members / projectmembers
• page / p
• entity / e
• table / viewer / index

4.2 entity正規化

基本対応:

• shots / shot → shot
• assets / asset → asset
• tasks / task → task
• users / user → user
• members / member / projectmembers / projectmember → member
• sched / schedule / schedules → sched

4.3 page正規化

代表例:

• empty / index / list / viewer → DashboardまたはTable
• table → Table
• schedule → Schedule
• schedview → SchedView
• settings → Settings
• testresults / tests / debug → DebugPanelPage
• forum / chat → Forum
• worker / workerkit → WorkerKit

4.4 Detail page正規化

Detail系は DetailShot, DetailAsset, DetailTask, DetailUser, DetailMember のように分かれる。

RouterはentityからDetail page名を作る。

例:

• shot → DetailShot
• asset → DetailAsset
• task → DetailTask
• user → DetailUser
• member → DetailMember

4.5 正規化が壊れた時の症状

• Assetsを開いたのにShots Tableが出る。
• DetailAssetのはずがDetailShotへ飛ぶ。
• MembersがUsers扱いになる。
• ScheduleがTable扱いされる。
• URLは変わるが画面が変わらない。
• PNAVIのactive表示がずれる。

5. Shellの役割

5.1 Shellとは

ShellはMOTKの主要作業画面を包むcontainer。

含まれるもの:

• GNAVI
• PNAVI
• Router
• Dashboard
• Table
• Detail
• console capture
• theme bootstrapping
• scriptUrl bridge
• soft navigation handler
• loader

5.2 Dashboard/Table/Detailの静的include

ShellはDashboard、Table、Detailを最初からincludeする。

表示中でないものはdisplay:noneで隠す。

これにより、Dashboard/Table/Detail間の切り替えを高速にできる。

5.3 Detail container

Detailは #detail-view-container に入る。

初期状態ではdisplay:none。

Detail routeになると表示され、bodyにdetail-page、htmlにdetail-rootが付く。

5.4 Loader

Shellには .loader があり、初期表示中はLoadingを出す。

route activationが完了するとloaderが消える。

loaderが消えない場合、route activationやsoftnav関数に失敗している可能性がある。

6. Soft Navigation

6.1 Soft Navigationとは

Soft Navigationは、ブラウザ全体をリロードせず、Shell内の表示containerを切り替える遷移。

対象:

• Dashboard
• Table
• Detail

対象外または別ページ扱い:

• Settings
• Guide
• DebugPanel
• Forum
• WorkerKit
• Scheduler
• SchedView

6.2 SoftNavの利点

• 体感が速い。
• Tableの状態を維持しやすい。
• Dashboard/Table/Detail間を自然に移動できる。
• Viewer Stateやcacheを活かせる。

6.3 SoftNavの注意

• URLが変わってもフルリロードとは限らない。
• JavaScript stateやcacheが残る。
• 問題調査では、SoftNavだけでなくreload後の再現確認も必要。
• Detailから戻ると、Tableが前回状態を復元する場合がある。

6.4 Shell内遷移API

Shellは window.__MOTK_SHELL_NAV__.navigate(href) を提供する。

DashboardやCommonRendererは、このAPIを使ってShell内遷移を行う。

失敗した場合は通常のlocation遷移へfallbackする。

6.5 click interception

Shellはdocument clickを捕まえる。

ただし以下は捕まえない。

• すでにpreventDefaultされている
• 左クリック以外
• meta/ctrl/shift/alt付き
• target=_blank
• Shell外URL
• SoftNav対象外route

このため、Ctrl+クリックやtarget=_blankは通常通り別タブで開く。

7. History / URL更新

7.1 GAS history API

GAS Web App内では、外側のscript.google.com URLをiframe内から直接変更しづらい。

Shellは google.script.history.push/replace を使って、外側のURLパラメータを更新する。

7.2 inner-frame history

Shellは同時にinner frame側のhistory.pushState/replaceStateも更新する。

これにより、セッション内の戻る/進む操作に対応する。

7.3 popstate

popstate時には現在URLを読み直し、Dashboard/Table/Detailを再表示する。

7.4 Reload時のroute復元

Reload時には google.script.url.getLocation で外側URLのパラメータを読む。

これにより、?p=table&e=assets のようなURLから直接開いても、適切な画面を復元できる。

7.5 URLと実画面がずれた場合

原因候補:

• GAS history更新に失敗。
• inner frame historyだけ変わった。
• Shell route parserが対象外routeと判断した。
• target=_blankで別ページとして開いた。
• URL正規化が期待と違う。

報告時には、address barのURLと実際に表示されている画面の両方を書く。

8. GNAVI

8.1 GNAVIとは

GNAVIはGlobal Navigation。

アプリ全体に共通する上部ナビゲーション。

主な項目:

• MOTK logo
• Dashboard
• Settings
• Guide
• Debug

8.2 Settings / Guide / Debugが別タブになりやすい理由

Settings、Guide、Debugはtarget=_blankで開くことが多い。

理由:

• 作業中のTable/Detailを失わない。
• Settings操作は管理作業なので通常作業と分ける。
• Guideを見ながら作業できる。
• DebugPanelは問題画面を残したまま診断する必要がある。

8.3 Debugは問題画面を閉じずに開く

UserGuideでは、問題報告時に「問題画面を閉じず、Debugを別タブで開く」と書く。

DebugPanelはShellのconsole bufferやViewer Stateを見るため、問題状態を残したまま開く方がよい。

9. PNAVI

9.1 PNAVIとは

PNAVIはProject Navigation。

制作データの主要entityへ移動するためのナビゲーション。

主な項目:

• Shots
• Assets
• Tasks
• Members
• Users
• Forum
• Schedule

9.2 PNAVI defaults

標準のPNAVI:

• Shots → ?p=table&e=shots
• Assets → ?p=table&e=assets
• Tasks → ?p=table&e=tasks
• Members → ?p=table&e=members
• Users → ?p=table&e=users
• Forum → ?page=Forum
• Schedule → ?p=schedview

9.3 PNAVI config

PNAVIはproject_metaの pnavi.config.json または pnavi.config から設定できる。

設定がなければdefaultsが使われる。

config itemに含まれる候補:

• id
• label
• href
• url
• page
• entity
• enabled
• target

9.4 enabled

enabled=falseの項目は表示しない。

小規模制作ではUsersやMembersを隠し、大規模制作ではScheduleを目立たせるなどができる。

9.5 Forum itemの強制追加

PNAVI configからForumが抜けていても、Forum itemを追加する処理がある。

議論導線を常に残すための設計と考えられる。

9.6 Schedule itemの特別扱い

Schedule-likeなitemは ?p=schedview に寄せられる場合がある。

PNAVIのScheduleは基本的にSchedViewを開く。

編集が必要なときはSchedViewのInteractionをEditにするか、Schedule editorへ進む。

9.7 PNAVI active表示

Tableではentity一致が優先される。

例:

• e=assetsならAssets active
• e=tasksならTasks active

Active表示がずれるだけなら軽微だが、route誤判定の結果ならDetail/Table遷移不具合につながる。

10. Router

10.1 Routerの役割

Routerは、MOTK内リンクを生成する共通ヘルパー。

主な役割:

• baseUrlの解決
• entity Detail URL生成
• Schedule URL生成
• Table/List URL生成
• Detail page name生成

10.2 baseUrlの解決

Routerは以下の優先順位でbase URLを解決する。

1. __VIEW_CTX__.scriptUrl
2. window.__SCRIPT_URL__
3. window.SCRIPT_URL
4. window.scriptUrl
5. location.origin + location.pathname

GASでは /userCodeAppPanel になることがあるため、exec URLを優先する必要がある。

10.3 buildEntityUrl

Detail URLを作る。

例:

• shot + sh_0001 → DetailShot
• asset + as_0001 → DetailAsset
• task + tk_0001 → DetailTask
• sched + sched_0001 → SchedView

10.4 buildScheduleUrl

Schedule/SchedView URLを作る。

例:

• ?p=schedview&schedId=sched_0001

10.5 buildListUrl

Table/List URLを作る。

例:

• shot → Table Shots
• asset → Table Assets
• task → Table Tasks

10.6 CommonRendererとの関係

CommonRendererはLink chipを表示するとき、Routerを使ってDetail URLを作る。

Routerが壊れると、chipをクリックしても正しいDetailへ飛ばない。

10.7 Link replacer diagnosticsとの関係

DebugPanelのLink replacer diagnosticsは、RouterやGNAVI/PNAVI linkが正しく置き換えられているかを見る。

11. Dashboard routing

11.1 DashboardはShell内でも独立でも動く

DashboardはShellにincludeされる場合と、独立templateとして開かれる場合がある。

そのため、Dashboard内のリンクはSoftNavと通常遷移の両方を考える必要がある。

11.2 appHref

Dashboardは相対pathやqueryをscript URLに変換する。

例:

• ?p=table&e=shots → full script URL
• ?page=Forum → full script URL

11.3 data-app-href

Dashboard内のlinkには data-app-href が付く場合がある。

Shell click interceptorはこれを拾ってSoftNavできる。

11.4 DashboardからDetailへ

Update FeedやProject SnapshotからDetailへ飛ぶ。

Detail URLはentityに応じてDetail page名を変える。

11.5 DashboardからForumへ

Forum linkにはentity/id/titleをprefillするURLを作る。

例:

• ?page=Forum&entity=shot&id=sh_0001&title=...

12. Forum routing

12.1 Forumは独立ページ

ForumはShell内SoftNav対象ではなく、独立templateとして開く。

Forumは自前のGNAVI/PNAVIを持つ。

12.2 Forum prefill

ForumはURLから以下をprefillする。

• entity
• id
• title

DetailからDiscussを押すと、該当entity/threadを開きやすくなる。

12.3 Forum detail links

Forum内のentity linkはDetail URLを作る。

例:

• shot → DetailShot
• asset → DetailAsset
• task → DetailTask
• member → DetailMember
• user → DetailUser

Forumはtarget=_blankでDetailを開くことがある。

13. WorkerKit routing

13.1 WorkerKit page

WorkerKitは ?page=WorkerKit またはworkerkit/worker routeで開く。

13.2 worker-bootstrap action

WorkerKitやWorkerは ?action=worker-bootstrap を使って、scriptUrl、spreadsheetId、spreadsheetTitle、workerKitUrl、githubRepoUrlを取得できる。

UserGuideでは、WorkerKit setup時にDetect/Bootstrapがこの情報を使うと説明できる。

13.3 DashboardからWorkerKitへ

DashboardのDrive Repair / OpsにはWorker KitやDownload Workerへの導線がある。

14. Settings / Debug / Guide routing

14.1 Settings

Settingsは ?page=Settings で開く。

GNAVIではtarget=_blankになっていることが多い。

Settingsは管理操作が多いため、作業中のTable/Detailと分けて開くのが自然。

14.2 DebugPanel

DebugPanelには複数aliasがある。

• debug
• debugpanel
• debugpanelpage
• tests
• testresults

すべてDebugPanelへ正規化される。

問題画面を残したまま診断するため、Debugは別タブで開く。

14.3 UserGuide

Guide/UserGuide/HelpはUserGuideへ正規化される。

別タブで開くことで、作業しながら参照できる。

15. Schedule routing

15.1 SchedView

PNAVIのScheduleは基本的に ?p=schedview を開く。

SchedViewは閲覧画面。

15.2 Scheduler

Schedule editorは ?p=schedule。SchedViewは ?p=schedview。

編集画面。

15.3 schedId

特定scheduleを開くにはschedIdを付ける。

例:

• ?p=schedview&schedId=sched_0001

15.4 target=_blank

Scheduleは別タブで開くことが多い。

理由:

• 画面が大きい。
• Dashboard/Table/Detailの作業状態を残したい。
• Scheduler編集は操作リスクが高い。

16. GAS / OAuth / scriptUrlの注意

16.1 GAS特有のURL問題

GAS HTML Serviceでは、実際の表示がiframeやuserCodeAppPanel内になることがある。

そのため、location.hrefだけを使うと正しいexec URLが取れない場合がある。

16.2 scriptUrl bridge

Shellはserverから渡されたscriptUrlを以下へbridgeする。

• window.__SCRIPT_URL_SERVER__
• window.__SCRIPT_URL__
• window.SCRIPT_URL
• window.scriptUrl

RouterやDashboardはこれを使って正しいlinkを作る。

16.3 createOAuthDialog

OAuth dialogから戻ったURLには createOAuthDialog が付く場合がある。

Boot/Routerはこれを通常route hintと混同しないように処理する。

16.4 Return URL sanitization

OAuth後の戻りURLから、code/state/scope/authuser/promptなどを除去する処理がある。

通常ユーザーには説明不要だが、Admin/Developer向けには「OAuth後にURLが変でもroute復元処理がある」と書ける。

17. Console capture / quiet console

17.1 Early console capture

Shellはheadで早期console captureを入れている。

console logはlocalStorage/sessionStorageへ保存される。

DebugPanelのCopy consoleで使われる。

17.2 quiet_console

quiet_console=1 またはlocalStorage設定で、GAS/iframe/Tailwindなどのノイズを抑制できる。

抑制対象例:

• dropping postMessage
• SES removing unpermitted intrinsics
• unrecognized feature
• iframe allow-scripts/allow-same-origin warning
• Tailwind CDN warning

17.3 問題報告との関係

Console captureは問題発生前から記録を取るために重要。

問題が起きた後にDebugPanelを開いても、Shell側のconsole bufferが残っていれば報告できる。

18. Theme bootstrapping

18.1 Themeの初期適用

ShellはlocalStorageの motk_ui_theme を読み、dark/lightを早期にhtmlへ適用する。

その後、project_metaのui_themeを読み、bodyのdata-ui-themeへ反映する。

18.2 Theme値

候補:

• dark
• light
• system
• auto

system/autoはsystem扱い。

18.3 UserGuideでの説明

ThemeはSettingsで変える。

変更後、localStorageにも保存され、次回ロード時のちらつきを減らす。

19. Route / Navigationトラブルシュート

19.1 URLは変わるが画面が変わらない

原因候補:

• SoftNav activationが失敗。
• click interceptionだけ成功し、container切替が失敗。
• route kind判定が対象外。
• JavaScript error。
• loaderが消えていない。

確認:

• Console
• Runtime URL Params
• Link replacer diagnostics
• address bar URL

19.2 Detailリンクが違うrecordを開く

原因候補:

• Router.buildEntityUrlのentity/idが違う。
• CommonRendererが違うrowからIDを取っている。
• LinkMapsが古い。
• Detail SoftNavが前回IDを残している。
• URL正規化でentityがshotへfallbackしている。

確認:

• クリックしたchipの表示名
• 生成URL
• entity
• id
• Viewer State
• Console

19.3 PNAVI activeが違う

原因候補:

• entity正規化の不一致。
• data-entityが不足。
• href内のe/entityが違う。
• Dashboard/Forum/Scheduleなど非Table route。

軽微に見えるが、route誤判定が原因なら重要。

19.4 Settingsが開かない

原因候補:

• access helperで拒否。
• Admin権限がない。
• Settings auth helper missing。
• template error。

確認:

• Access error pageの文面
• Settings Access info
• DebugPanel Runtime

19.5 ForumからDetailへ飛べない

原因候補:

• entity/id prefillがない。
• Forum detailHrefのpage名が間違い。
• target blankでpopupがブロック。
• Detail page routeがShell内に吸収されない。

19.6 Scheduleが意図せず別タブで開く

Scheduleはtarget=_blankにされることがあるため、これは仕様の可能性が高い。

UserGuideでは、Schedule/SchedViewは大画面かつ編集リスクがあるため別タブで開くことがあると説明する。

20. URL報告テンプレート

20.1 画面遷移問題の報告

問題名:

現在のURL:

クリックしたリンクの表示名:

クリックしたリンクのhref:

期待した画面:

実際に開いた画面:

同じタブか別タブか:

GNAVI/PNAVIのactive状態:

Reload後に同じ画面になるか:

Console:

DebugPanel Link replacer diagnostics:

20.2 Detail link問題の報告

元画面:

元entity:

元record id:

クリックしたchip/リンク:

生成されたURL:

期待entity/id:

実際entity/id:

Reload後の結果:

Viewer State:

Console:

20.3 PNAVI問題の報告

PNAVI item:

href:

data-page:

data-entity:

期待画面:

実際画面:

active表示:

project_metaのpnavi.config.json:

21. 覚えておきたい要点

21.1 Shell内遷移

Dashboard、Table、Detailは同じShell内で高速に切り替わるため、URLが変わってもフルリロードされない場合があります。表示がおかしい場合は、まず通常の再読み込みでも再現するか確認してください。

21.2 Debug別タブ

問題調査では、問題が起きた画面を閉じずにDebugを別タブで開いてください。DebugPanelは、その時点のConsoleやViewer Stateを確認するために使います。

21.3 Settings別タブ

Settingsは管理操作用です。通常の作業画面を残すため、別タブで開く設計になっています。

21.4 Schedule別タブ

Schedule/SchedViewは大画面で扱うため、別タブで開くことがあります。閲覧はSchedView、編集はSchedulerを使います。

21.5 URL報告

画面遷移の問題を報告するときは、表示中のURL、クリックしたリンク、期待した画面、実際の画面を必ず一緒に送ってください。

第6部 アクセス権と共有

1. Access modelの基本

MOTKの権限は、少なくとも2層で考える必要がある。

1. MOTK内の権限 - Users sheetやADMIN_USERSなどに記録されるアプリ上の役割。 - MOTKのUI上で何を表示・編集・管理できるかに関係する。

2. Google側の実共有 - Spreadsheet、Drive root、Originals、Proxies、Admin workbookなどに対するGoogle Drive/Sheets上の共有権限。 - 実際にファイルやシートを開けるか、書き込めるかに関係する。

この2つは似ているが別物。

MOTK内ではeditorでも、Google DriveのOriginals folderにアクセス権がなければOriginalsは開けない。

Google Driveにはアクセスできても、MOTK内でviewerならTable編集やSettings保存はできない可能性がある。

UserGuideでは、権限問題を「MOTK内role」と「Google共有」の2段階で説明する。

2. UsersとProjectMembersの違い

2.1 Users

Usersは、MOTKを使う人、またはGoogleアカウントに近い概念。

代表的なfield:

• User ID
• User Name
• Email
• Permission
• Department
• Notes

Usersは、アクセス管理、共有同期、ログインユーザー判定、Googleアカウントとの対応に関係する。

2.2 ProjectMembers

ProjectMembersは、制作上の参加者・役割・担当枠を表す。

代表的なfield:

• Member ID
• Role
• Department
• User Link
• Notes

ProjectMembersは、Schedulerのlane、TaskのAssignee、制作上のrole、部署割り当てに関係する。

2.3 なぜUsersとProjectMembersを分けるのか

同じ人物でも、GoogleアカウントとしてのUserと、制作上のRoleは一致しない場合がある。

例:

• 1人がDirectorとAnimatorの両方を担当する。
• 1つのGoogleアカウントをProduction Teamとして使う。
• 外部スタッフにはGoogleアカウントはあるが、Scheduler laneには出さない。
• 仮の担当枠はあるが、まだUserが決まっていない。
• AdminはMOTK管理者だが、制作上のMemberではない。

UserGuideでは、Usersは「ログイン・共有・権限」、ProjectMembersは「制作上の担当・役割」と説明するとよい。

2.4 User Link

ProjectMembersはUser LinkでUsersと紐づく。

User Linkがあると、制作上の担当とGoogleアカウントを結びつけられる。

User Linkが空でも、ProjectMemberとしては存在できる可能性がある。

User Linkが不正だと、Assignee表示、共有、通知、Scheduler lane、担当者検索がズレる可能性がある。

3. Permission role

3.1 viewer

viewerは閲覧中心のrole。

できる可能性があること:

• Dashboardを見る。
• Tableを見る。
• Detailを見る。
• SchedViewを見る。
• Forumを見る、または投稿できるかは設定次第。
• Originals/ProxiesをGoogle側共有があれば開く。

できない、または制限される可能性が高いこと:

• Inline edit。
• Create New Record。
• Upload。
• Settings保存。
• Proxy requeue。
• Sharing sync。
• Drive Ensure/Fix。
• Publish。

3.2 editor

editorは制作データを編集するrole。

できる可能性があること:

• Table inline edit。
• Detail field edit。
• Create New Record。
• Versions upload。
• Forum投稿。
• Task/Status/Assignee/Due Date編集。
• Scheduler上の安全な編集。

制限される可能性があること:

• Settingsの管理操作。
• User Access / Sharing sync。
• Admin追加。
• project_meta編集。
• SystemConfig編集。
• Proxy root設定。
• Drive Ensure/Fix。

3.3 admin

adminは管理者role。

できる可能性があること:

• Settingsを開く。
• project_metaを編集する。
• PNAVI Configを保存する。
• Themeを保存する。
• Hydrate Originalsを実行する。
• Drive Diff/Fix/Ensureを実行する。
• Proxy Configを保存する。
• Proxy Auditを設定・実行する。
• Requeueする。
• User Access / Sharingを同期する。
• Admin listを管理する。
• DebugPanelで診断する。

注意:

admin roleでも、Google側の共有権限が不足しているとDrive/Sheet操作は失敗する。

3.4 open / bootstrap

Settings server側には、access infoとして open や bootstrap に近い状態が出る可能性がある。

bootstrapは初期管理者未設定時の暫定許可・初期化状態を示す可能性がある。

4. Admin list

4.1 Admin listとは

Admin listは、MOTKの管理者を識別するためのリスト。

Settings画面にはAdmins sectionがあり、Add Adminボタンがある。

管理用workbookのADMIN_USERS sheetに関係する可能性がある。

4.2 AdminとUsers.permissionの違い

Users.permissionのviewer/editorと、Admin listのadminは別管理の可能性がある。

Settings UIにも「Users.permission drives sharing. Valid roles: viewer/editor.」という説明があり、adminは別枠で扱われている。

UserGuideでは、以下のように分けるとよい。

• Users.permission: Google共有同期や通常の閲覧/編集roleに使う。
• Admin list: Settingsや管理操作の許可に使う。

4.3 Admin追加

Admin追加はSettingsのAdd Adminから行う。

想定手順:

1. Settingsを開く。
2. User Access / SharingのAdmins sectionを見る。
3. Add Adminを押す。
4. 候補Userを選ぶ。
5. Addを押す。
6. Admin listに追加されたことを確認する。
7. 対象ユーザーがSettingsを開けるか確認する。

4.4 最初のAdmin

初期セットアップ時に最初のAdminをどう作るかは重要。

可能性:

• Script ownerがbootstrap adminになる。
• ADMIN_USERS sheetに手動で追加する。
• Admin workbookで管理する。
• Settingsのbootstrap modeから追加する。

4.5 Adminを削除する場合

削除・無効化導線は実行前に対象ユーザー、ADMIN_USERS、Google共有の3点を確認する。

Admin削除は高リスク。

最後のAdminを消すと管理不能になる可能性がある。

UserGuideでは、削除導線が確定するまで「最後のAdminを消さない」「Script ownerを残す」と注意を書く。

5. User Access / Sharing

5.1 User Access / Sharingの役割

User Access / Sharingは、MOTK内のUsers.permissionと、Google Drive/Sheetsの実共有状態を照合・同期するためのSettings section。

目的:

• 誰がMOTKにアクセスできるか確認する。
• Users.permissionとGoogle共有のズレを見つける。
• viewer/editorをDrive/Sheets共有に反映する。
• mismatchesを検出する。
• 必要なユーザーだけ同期する。

5.2 Valid roles

Sharing syncの対象roleは主に以下。

• viewer
• editor

adminはAdmin list側で別管理される可能性がある。

5.3 Refresh

Refreshは、User Access / Sharingの現在状態を読み直す。

見るもの:

• Users list
• permission
• Google共有状態
• mismatches
• resources
• summary

5.4 Sync Checked

Sync Checkedは、選択したユーザーだけ共有同期する。

使いどころ:

• 新規スタッフを1人追加した。
• 特定ユーザーの権限だけ直したい。
• 全体同期前に小さくテストしたい。

5.5 Sync Mismatches

Sync Mismatchesは、設定と実共有がズレているユーザーをまとめて同期する。

使いどころ:

• 共有状態を一括整備したい。
• ユーザー追加・削除後にズレが多い。
• Drive/Sheetsを手動で触った後にMOTK側へ合わせたい。

注意:

Sync Mismatchesは影響範囲が広い可能性がある。まずRefreshで件数を確認する。

5.6 Access Summary

Access Summaryには、role別件数、mismatch件数、resource別状態などが出る可能性がある。

UserGuideでは「同期前にsummaryを見る」と書く。

5.7 Access Table

Access Tableには各ユーザーの状態が出る。

見るべきもの:

• email
• permission
• checked
• mismatch
• resource access
• Google sharing state
• sync result
• error message

6. Google共有の対象

6.1 Spreadsheet

MOTKのHost Spreadsheetへのアクセス。

Table/Detail/Settingsなど多くの操作に関係する。

viewerなら閲覧、editorなら編集が必要。

ただし、GAS Web Appが「実行ユーザー」または「デプロイ所有者」として実行される設定により、挙動が変わる可能性がある。

6.2 Project Drive root

MOTK project root folder。

OriginalsやProxiesを含む上位フォルダ。

6.3 Originals root

元ファイルの保管場所。

Originalsを開く、Uploadする、Drive Ensureする場合に必要。

6.4 Proxies root

Proxy出力の保管場所。

Proxy preview、Worker output、Proxy Auditに関係する。

6.5 Admin workbook

Admin listや管理用設定が外部workbookにある場合、そのworkbookへのアクセスも必要。

project_metaがexternal sourceの場合も同様。

6.6 Apps Script deployment

Web App自体へのアクセス。

Deployment設定が「Anyone」なのか「組織内」なのか、「実行ユーザー」が誰かによって、ユーザー体験が変わる。

7. 権限不一致の典型例

7.1 MOTKではeditorだがDriveが見えない

症状:

• Tableは見える。
• Detailは見える。
• Originalsを押すとGoogle Drive側でAccess denied。
• Uploadに失敗する。
• Previewが出ない。
• Proxyはあるのに開けない。

原因:

• Users.permissionはeditorだが、Originals/Proxies folderのGoogle共有が不足。

対応:

• SettingsのUser Access / SharingでRefresh。
• 対象ユーザーにmismatchが出るか確認。
• Sync Checkedを実行。
• Google Drive側で実際に開けるか確認。

7.2 Google Driveは見えるがMOTKでは編集できない

症状:

• Drive folderは開ける。
• Tableは見える。
• Inline editができない、または保存で拒否される。
• Settings保存ができない。
• Uploadできない。

原因:

• Google共有はあるが、MOTK内roleがviewer。

対応:

• Users.permissionをeditorに変更。
• 必要ならSharing sync。
• ReloadしてMOTK内roleを再判定。

7.3 AdminのはずがSettingsを開けない

症状:

• Settingsを開くとAccess error。
• Settings画面が出ない。
• Admin sectionが見えない。

原因候補:

• Admin listに入っていない。
• 使用中のGoogleアカウントが違う。
• Admin workbookが読めない。
• Settings auth helperがmissing。
• Web App実行設定によってユーザーemailが取れていない。

対応:

• 現在ログイン中のGoogleアカウントを確認。
• Admin listを確認。
• Script ownerでSettingsを開く。
• DebugPanelのSettings Access infoを見る。

7.4 UsersにいるがPNAVI/Tableが見えない

症状:

• LoginできるがTableが空。
• 一部ページだけ見えない。
• Driveは見えるがMOTKデータが出ない。

原因候補:

• Spreadsheet共有不足。
• Web Appが別Deployment。
• Host Spreadsheet IDが違う。
• Users sheetにemailがあるが、実ログインemailと一致しない。
• Permissionが空または無効値。

7.5 Syncしたのにまだ開けない

原因候補:

• Google共有反映に時間がかかる。
• 別Googleアカウントで開いている。
• Browser cache/sessionが古い。
• 対象resourceがSync対象に含まれていない。
• Shared Driveの権限継承が特殊。
• Web App deployment自体のアクセス制限。

対応:

• Googleアカウントを確認。
• 別ブラウザ/シークレットで試す。
• Drive folderを直接開く。
• SettingsでRefresh。
• DebugPanel Runtime/Accessを見る。

8. 新規スタッフ参加ワークフロー

8.1 最小手順

1. Users Tableを開く。
2. NewでUserを追加する。
3. Emailを入力する。
4. User Nameを入力する。
5. permissionをviewerまたはeditorにする。
6. ProjectMembers Tableを開く。
7. 必要ならMemberを作る。
8. User LinkでUserとMemberを紐づける。
9. Settingsを開く。
10. User Access / SharingでRefreshする。
11. 対象Userにチェックを入れる。
12. Sync Checkedを実行する。
13. 対象UserにWeb App URLを渡す。
14. Dashboard/Tableが開けるか確認する。
15. Drive Originals/Proxiesが開けるか確認する。

8.2 制作上の担当者として追加する場合

1. UsersにGoogle accountを追加。
2. ProjectMembersに制作roleを追加。
3. Departmentを設定。
4. User Linkを設定。
5. TasksのAssigneeでMemberを選べるか確認。
6. SchedulerのMember laneに出るか確認。
7. SchedViewでlane visibilityに表示されるか確認。

8.3 閲覧だけの外部スタッフ

1. Usersに追加。
2. permissionをviewerにする。
3. ProjectMembersには追加しない、または必要に応じてGuest roleを作る。
4. Sharing syncでviewer共有。
5. Table/Detail/SchedViewが見えるか確認。
6. Uploadや編集ができないことも確認する。

8.4 一時的な外部editor

1. Usersに追加。
2. permissionをeditorにする。
3. 期間と担当範囲をNotesに書く。
4. 必要なDrive folderだけ共有されるか確認する。
5. 作業終了後にviewerへ戻す、または共有解除する。
6. Sync Mismatchesで状態を揃える。

8.5 Adminを追加する場合

1. 先にUsersに追加する。
2. Google Drive/Sheets共有をeditor相当にする。
3. SettingsのAdmin sectionからAdd Adminする。
4. Admin listに出るか確認する。
5. 対象者がSettingsを開けるか確認する。
6. Proxy/Drive操作は最初に小さい操作でテストする。

9. スタッフ退場 / 権限削除ワークフロー

9.1 退場時の基本

1. 対象Userを確認する。
2. 担当中Tasksを確認する。
3. ProjectMembersのroleを確認する。
4. 未完了TaskのAssigneeを変更する。
5. User permissionをviewerまたは無効相当に変更する。
6. Google Drive/Sheets共有を外す。
7. Admin listに入っていれば削除する。
8. Sharing Syncを実行する。
9. 対象Userでアクセスできないことを確認する。

9.2 退場前に確認するもの

• 担当中Task
• Scheduler card
• Forum投稿
• Upload履歴
• ProxyJobs claimed_by
• Drive上の所有ファイル
• Admin権限
• 外部共有リンク

9.3 完全削除ではなく無効化

制作履歴を保つため、User recordやProjectMember recordを物理削除しない方がよい場合がある。

退場者の記録を残しつつ、permissionと共有だけ外す運用が安全。

UserGuideでは「制作履歴を残すため、削除より無効化を基本にする」と説明候補にできる。

9.4 最後のAdminを消さない

最後のAdminを削除すると、Settingsを管理できなくなる可能性がある。

Admin削除前には、少なくとも2人のAdminが残るか確認する。

10. role変更ワークフロー

10.1 viewerからeditorへ

1. Users Tableでpermissionをeditorに変更する。
2. SettingsのUser Access / Sharingを開く。
3. Refreshする。
4. 対象UserをSync Checkedする。
5. 対象UserがTable編集またはUploadできるか確認する。

10.2 editorからviewerへ

1. 未完了の編集作業がないか確認する。
2. Tasks/SchedulerのAssigneeを必要なら変更する。
3. Users.permissionをviewerに変更する。
4. Sync Checkedを実行する。
5. 対象Userが編集できないことを確認する。

10.3 admin追加

1. Users.permissionだけではadminにならない可能性がある。
2. Admin sectionでAdd Adminする。
3. Settingsを開けるか確認する。
4. Google Drive/Sheetsのeditor権限も確認する。

10.4 admin解除

1. 代替Adminがいるか確認する。
2. 対象者の管理作業が完了しているか確認する。
3. Admin listから外す。
4. Users.permissionは必要に応じてeditor/viewerにする。
5. Settings accessが消えたことを確認する。

11. Sharing syncの安全運用

11.1 まずRefresh

Sync前に必ずRefreshする。

現在のmismatchやresourcesを確認せずにSyncすると、意図しない共有変更が起きる可能性がある。

11.2 小さくSyncする

新しいユーザー1人だけなら、Sync Checkedを使う。

全体のズレを直す場合だけSync Mismatchesを使う。

11.3 実行後に確認する

Sync後に確認するもの:

• Settingsのstatus/log
• Access Summary
• 対象ユーザーのmismatchが消えたか
• Drive folderを直接開けるか
• Web Appを開けるか
• Table/Detail/Uploadの操作権限が期待通りか

11.4 大量同期前の注意

大量のUserをSyncする前に確認すること:

• Users.permissionが正しい。
• 退場者が残っていない。
• Adminを誤ってviewerにしていない。
• Drive root idが正しい。
• Host Spreadsheetが正しい。
• Script deploymentが正しい。

11.5 共有同期のログ

SettingsにはLogがある。

Sharing sync後はLogを確認する。

エラーが出た場合は、Settings LogとAccess Summaryを報告に含める。

12. Access errorの読み方

12.1 Access error page

Settingsを開いたときにAccess error pageが出る場合がある。

これはSettings templateが壊れたとは限らない。

権限チェックで止めている可能性がある。

12.2 Access required系

Access requiredと出た場合:

• ログイン中のGoogleアカウントを確認する。
• Users.permissionを確認する。
• Admin listを確認する。
• Google Drive/Sheets共有を確認する。
• Web App deploymentのaccess設定を確認する。

12.3 Settings auth helper missing

Settings auth helper missingは、権限判定用関数が見つからない状態。

通常ユーザーが直す問題ではない。

Admin/Developerへ報告する。

12.4 NO_ADMIN_WORKBOOK

Admin workbookが必要なのに見つからない場合の可能性がある。

初期セットアップ、admin workbook ID、共有権限を確認する。

13. Role別にできること

13.1 Viewer向けUserGuide

Viewerは、プロジェクトの状態を見るためのrole。

できること:

• Dashboardを見る。
• Shots/Assets/Tasks Tableを見る。
• Detailを見る。
• SchedViewを見る。
• Forumを見る。
• Drive共有があればOriginals/Proxiesを開く。

注意:

• 編集・Upload・Settings操作はできない場合がある。
• 見えないファイルがある場合はMOTKではなくGoogle Drive共有不足の可能性もある。

13.2 Editor向けUserGuide

Editorは制作データを更新するrole。

できること:

• Table inline edit。
• Detail edit。
• New Record作成。
• Link Pickerで関連付け。
• Upload Versions。
• Task status更新。
• Schedulerで自分の範囲を編集できる可能性。

注意:

• SettingsやSharing操作はAdmin向け。
• ID、Originals URL、versions pointer JSONなどは直接編集しない。

13.3 Admin向けUserGuide

Adminはプロジェクト運用を保守するrole。

できること:

• Settings管理。
• Users/Sharing同期。
• project_meta/SystemConfig管理。
• PNAVI/Theme設定。
• Drive Ensure/Fix/Hydrate。
• Proxy Config/Audit/Requeue。
• WorkerKit setup。
• DebugPanel診断。

注意:

• Admin操作は制作全体に影響する。
• Sync Mismatches、Drive Ensure、Proxy Requeue、Task Recalculate、Publishは実行前に対象を確認する。

14. User Access / SharingのUI

14.1 Admins section

Admins sectionは、MOTKの管理者一覧を表示する。

AddボタンからAdminを追加する。

Admin workbookまたはADMIN_USERS sheetに関係する。

14.2 Sharing sync section

Sharing sync sectionは、Users.permissionをもとにGoogle共有を同期する。

説明文としては「Users.permission drives sharing. Valid roles: viewer / editor.」がある。

14.3 Refresh button

現在のUsersと共有状態を読み直す。

14.4 Sync Checked button

チェックしたユーザーだけ同期する。

14.5 Sync Mismatches button

設定と共有がズレているユーザーをまとめて同期する。

14.6 accessHint

処理中や結果のメッセージが出る。

14.7 accessSummary

role別件数、mismatch件数、resource別状態などのsummaryが出る。

14.8 accessTable

ユーザーごとの状態を表示する。

15. Dashboard側のUser Access表示

DashboardにもUser Access / SharingやSystem Health / Mismatchが出る可能性がある。

Dashboardでの位置付け:

• 軽い確認
• mismatchの気づき
• Settingsへ移動する前のsummary

Settingsでの位置付け:

• 詳細確認
• 同期実行
• Admin追加
• Log確認

UserGuideでは、Dashboardは確認、Settingsは実行、と分ける。

16. User/Member/Task/Schedulerの関係

16.1 TaskのAssignee

TaskのAssigneeはProjectMemberを指すことが多い。

つまり、TaskはGoogle Userではなく制作上のMemberへ割り当てられる。

16.2 Scheduler lane

SchedulerのMember laneはProjectMembersを使う可能性が高い。

Usersに追加しただけではScheduler laneに出ない場合がある。

16.3 Google accountとの接続

ProjectMemberがUser Linkを持つことで、Google accountと制作上の担当を結びつける。

16.4 権限と担当は別

editor権限があることと、Task担当であることは別。

• editor権限: MOTK上で編集できる。
• Assignee: 作業担当としてスケジュールやTaskに出る。

この違いはUserGuideで強調する必要がある。

17. セキュリティ上の注意

17.1 viewer/editorの最小権限

必要以上にeditorを付与しない。

閲覧だけの人はviewerにする。

外部スタッフは必要期間だけeditorにする。

17.2 Adminは少数にする

AdminはSettings、Sharing、Drive、Proxy、project_metaに影響する。

制作メンバー全員をAdminにしない。

17.3 Drive共有リンクに注意

Google Driveの共有リンクが「リンクを知っている全員」になっていると、MOTK内権限とは別にファイルが見える可能性がある。

UserGuideでは、Drive rootやOriginals/Proxiesの共有設定を確認するよう書く。

17.4 Web App deployment設定

Web Appの公開範囲と実行ユーザー設定は、MOTKのセキュリティに強く影響する。

• 誰がアクセスできるか
• 誰の権限で実行されるか
• ユーザーemailが取得できるか

17.5 退場者処理

退場者はUsers.permissionだけでなく、Google Drive/Sheets共有も外す必要がある。

Admin listからも外す。

18. 権限問題トラブルシュート

18.1 Settingsが見えない

確認順:

1. どのGoogleアカウントで開いているか。
2. Usersにそのemailがあるか。
3. Admin listにあるか。
4. Spreadsheetを開けるか。
5. Admin workbookを開けるか。
6. Web App deploymentが許可しているか。
7. DebugPanelでSettings Access infoを見る。

18.2 Tableは見えるが編集できない

確認順:

1. Users.permissionがviewerではないか。
2. editorになっているか。
3. 対象fieldがeditableか。
4. write accessがあるか。
5. Consoleにpermission errorがないか。
6. Google Spreadsheet側で編集権限があるか。

18.3 Uploadできない

確認順:

1. Users.permissionがeditor以上か。
2. write accessがあるか。
3. Originals folderに書き込めるか。
4. Proxies root idが設定されているか。
5. field_idがversions typeか。
6. Console/Settings Logを見る。

18.4 Originalsを開けない

確認順:

1. Originals URLがあるか。
2. Drive folderが存在するか。
3. Google Drive共有があるか。
4. Hydrate Originalsを実行済みか。
5. Drive rootが正しいか。

18.5 Sync Checkedが失敗する

確認順:

1. Admin権限があるか。
2. 対象Userのemailが正しいか。
3. permissionがviewer/editorか。
4. Drive/Sheets resource IDが正しいか。
5. Admin workbookにアクセスできるか。
6. Settings Logを見る。

18.6 Sync Mismatchesが怖い場合

まずRefreshして、mismatch件数と対象ユーザーを確認する。

不明なユーザーが含まれる場合はSync Checkedで小さく試す。

大量同期は、退場者や外部共有を確認してから実行する。

19. 問題報告テンプレート

19.1 権限問題テンプレート

問題名:

対象ユーザーemail:

ログイン中のGoogleアカウント:

MOTK Users.permission:

Admin listにいるか:

ProjectMemberにいるか:

User Link:

操作した画面:

操作内容:

Observed result:

Expected result:

Spreadsheetを直接開けるか:

Originals folderを直接開けるか:

Proxies folderを直接開けるか:

Settings User Access / Sharing summary:

Settings Log:

Console:

19.2 新規ユーザー追加失敗テンプレート

追加したUser:

Email:

Permission:

ProjectMember:

User Link:

Sync Checked実行済みか:

Drive/Sheetsを直接開けるか:

Web Appを開けるか:

Dashboard表示:

Table表示:

Detail表示:

Upload可否:

19.3 Admin追加失敗テンプレート

対象User:

対象email:

Usersに存在するか:

Add Admin操作結果:

Admin listに表示されるか:

対象者がSettingsを開けるか:

Access error message:

Admin workbook access:

Settings Log:

19.4 Sharing sync失敗テンプレート

操作:

• Refresh
• Sync Checked
• Sync Mismatches

対象User数:

対象email:

permission:

mismatch表示:

sync result:

error message:

Google Drive/Sheets実確認:

Settings Log:

20. QA / Acceptance

20.1 User Access / Sharingで確認すること

• SettingsがAdminで開ける。
• Admin listが表示される。
• Add Admin modalが開く。
• Users listが表示される。
• mismatches filterが動く。
• all users filterが動く。
• searchが動く。
• resource filterが動く。
• Refreshが動く。
• Sync Checkedがcoherentに応答する。
• Sync Mismatchesがcoherentに応答する。
• frontend/backend result mismatchがない。

20.2 Access制限はbug扱いしない場合がある

非AdminユーザーでSettingsが見えないことはexpectedの場合がある。

QA報告では、access-limitedとbugを分ける。

20.3 高重大度になる問題

• viewerが管理操作できる。
• editorがSharing syncできる。
• AdminではないのにAdmin追加できる。
• 退場者がまだDrive/Sheetsにアクセスできる。
• Syncで意図しないユーザーをeditorにする。
• Users.permissionと違う共有が大量に適用される。

20.4 中重大度になる問題

• Settings UIではerrorだがbackendは成功している。
• Summaryのmismatch件数が更新されない。
• Search/filterが効かない。
• Sync後に画面更新が必要。

20.5 低重大度になる問題

• 表示文が分かりにくい。
• Role説明が不足。
• Table幅が狭くて読みづらい。
• 読み込みが遅いが正しい。

21. 注意事項の要点

21.1 UsersとMembers

UsersはGoogleアカウントとMOTK権限に関係します。ProjectMembersは制作上の担当・役割に関係します。TaskのAssigneeやScheduler laneに出したい場合は、UserだけでなくProjectMemberも確認してください。

21.2 権限は2層

MOTK内でeditorでも、Google Drive/Sheetsの共有が不足しているとファイルを開いたりUploadしたりできません。権限問題では、MOTK内roleとGoogle共有の両方を確認してください。

21.3 Sync前のRefresh

Sharing syncを実行する前に、必ずRefreshして現在のmismatchと対象ユーザーを確認してください。

21.4 Adminは最小限

AdminはSettings、Drive、Proxy、Sharingに影響します。通常の制作編集者はeditorで十分な場合があります。

21.5 新規スタッフ追加

新規スタッフを追加したら、Usersへの追加、ProjectMembersとの紐づけ、Sharing sync、実際のログイン確認までを1セットとして扱ってください。

21.6 退場者処理

退場者はMOTKのpermissionだけでなく、Google Drive/Sheets共有とAdmin listも確認してください。

第7部 管理・保守(Adminガイド)

1. Admin setupの位置付け

MOTKは単なるフロントエンドではない。

Admin setupでは、以下をつなぐ必要がある。

• Google Apps Script Web App
• Host Spreadsheet
• project_meta
• SystemConfig
• Fields
• Pages
• Shots / Assets / Tasks / ProjectMembers / Users
• Google Drive Originals root
• Google Drive Proxies root
• Proxy Worker Kit
• User Access / Sharing
• DebugPanel

UserGuideでは、Admin setupを「最初に1回だけ行う設定」と「制作中に継続的に行う保守」に分ける。

2. Admin setupの大分類

2.1 Initial setup

初回構築。

やること:

• Host Spreadsheetを決める。
• Apps Scriptをデプロイする。
• HOST_SS_IDを設定する。
• project_metaを用意する。
• Fieldsを用意する。
• 各entity sheetを用意する。
• Drive rootを作る。
• Settingsを開く。
• User Access / Sharingを設定する。
• WorkerKitをセットアップする。
• DebugPanelで診断する。

2.2 Maintenance

制作中の保守。

やること:

• Drive foldersをEnsure/Fixする。
• Hydrate Originalsを実行する。
• Proxy Auditを見る。
• Requeueする。
• Users/Sharingを同期する。
• FieldsやPages変更後にDebugPanelで確認する。
• Worker稼働を確認する。

2.3 Recovery

問題発生時の復旧。

やること:

• DebugPanelで原因範囲を切る。
• Settings Logを確認する。
• Drive Diff/Fixを使う。
• ProxyJobs/UploadInbox/ProxyAuditを見る。
• Cache Hydrateする。
• FieldTypes/Column Contract/Binding Integrityを確認する。
• PublishやSyncなど広範囲操作の前に対象を限定する。

3. 初期セットアップ完全版

3.1 Host Spreadsheetを決める

Host SpreadsheetはMOTKの制作データを保持する中心ファイル。

入るもの:

• Shots
• Assets
• Tasks
• ProjectMembers
• Users
• Pages
• Fields
• project_meta
• SystemConfig
• UploadInbox
• ProxyJobs
• ProxyAudit
• ProxyWorkers

一部は外部admin workbookやIMPORTRANGE mirrorになる可能性がある。

3.2 HOST_SS_IDを設定する

DriveBuilderには installHostSpreadsheet() があり、Active SpreadsheetのIDをScript PropertiesのHOST_SS_IDへ保存する。

手順:

1. Host Spreadsheetを開く。
2. Apps Script editorを開く。
3. installHostSpreadsheet() を1回実行する。
4. LogでHOST_SS_IDが設定されたことを確認する。

注意:

• 間違ったSpreadsheetで実行すると、MOTKが別のデータを読む。

3.3 Apps Script Web Appをデプロイする

設定時に確認すること:

• Web App URLを取得する。
• Execute asの設定。
• Who has accessの設定。
• Google認証が必要か。
• Deployment URLをUserGuide/Debug/WorkerKitに渡す。

3.4 project_metaを用意する

project_metaはプロジェクト全体の意味設定。

代表key:

• originals_root_url
• ui_theme
• pnavi.config.json
• schedule系設定
• fieldmap系設定
• project name系設定

project_metaはlocal_sheet、external_importrange_mirror、formula_managed_local_sheet、external_source_only、missingなどの管理モードがある。

Settingsでread-onlyになる場合がある。

3.5 SystemConfigを用意する

SystemConfigは運用設定。

代表key:

• drive.originals.root_id
• drive.proxies.root_id
• proxy.preset.default
• proxy.audit.enabled
• proxy.audit.hour
• proxy.audit.limit
• proxy.audit.entities
• project_meta.source_spreadsheet_id

Proxy/Worker/Audit/外部project_metaに関係する。

3.6 Fieldsを用意する

FieldsはMOTKのschema。

必須:

• field_id
• entity
• label / field_name
• type
• editable
• required
• options
• core flag

UserGuideでは、FieldsがMOTKの列理解の中心であると説明する。

3.7 Entity sheetsを用意する

必要sheet:

• Shots
• Assets
• Tasks
• ProjectMembers
• Users
• Pages

行構造:

• 1行目: field_id
• 2行目: label
• 3行目以降: data rows

MOTKは列番号ではなくfield_idで読むべき。

3.8 Drive Originals rootを作る

Originals rootは元ファイルを保持するDrive folder。

Settingsまたはproject_meta/SystemConfigにfolder id/urlを保存する。

DriveBuilderはOriginals rootの下にentity rootを作る。

3.9 Drive Proxies rootを作る

Proxies rootはProxy Workerが出力する軽量プレビュー用folder。

SystemConfigの drive.proxies.root_id に保存する。

3.10 Settingsで初期確認

Settingsで見るもの:

• project_meta rowsが読める。
• meta_management modeが期待通り。
• Themeが保存できる。
• PNAVI Configが保存できる。
• SystemConfigにroot idがある。
• User Access / Sharingが表示される。
• Proxy Opsが表示される。
• Proxy Auditが表示される。

3.11 DebugPanelで初期診断

初期セットアップ完了前にDebugPanelでRun all checks。

見るもの:

• Runtime
• Data Maps / Page
• Schema/Meta Health
• FieldTypes Health
• Entity samples
• Originals diagnostics
• Column Contract
• Binding Integrity

3.12 1件のEnd-to-End test

最初に1件だけテストrecordで全体を通す。

推奨:

1. Test Shotを作る。
2. Shot Detailを開く。
3. Open Originalsを試す。
4. Versions Uploadを試す。
5. ProxyJobsにjobが入るか見る。
6. Worker onceで1件処理する。
7. Previewが出るか見る。
8. Taskを作り、Shot Linkを設定する。
9. Scheduler/SchedViewに出るか見る。
10. ForumでEntity Threadを作る。
11. DebugPanelで重大エラーがないか見る。

4. DriveBuilder運用

4.1 DriveBuilderの役割

DriveBuilderはMOTKのGoogle Drive folder構造を保証・監査する。

役割:

• Originals rootを確認する。
• 01shots / 02assets rootを作る。
• 03tasks / 04misc / 05deletedをオンデマンドで作る。
• record folderを作る。
• id__codeへrename/consolidateする。
• Versions folderを作る。
• Diff/Fixする。
• Soft deleteする。

4.2 Safety principle

DriveBuilder系操作は「不足分を作る」方向が基本。

SettingsのEnsure All Foldersは安全系。

既存フォルダやファイルを削除・移動・掃除しない。

ただし、folder consolidationやsoft deleteは重複整理・移動を含む可能性があるため、Admin向けに慎重に説明する。

4.3 Ensure All Folders

用途:

• 初期セットアップ後。
• 新規Shot/Asset/Taskを大量追加した後。
• Drive folderが不足しているとき。

動作:

• Shots / Assets / Tasks の不足Originals folderを作る。
• 既存folder/fileは動かさない。

実行後確認:

• Settings Log。
• Drive Diff。
• 対象DetailのOpen Originals。
• DebugPanel Originals diagnostics。

4.4 Drive Diff

用途:

• Sheets上のrecordとDrive folderのズレを見る。

出力:

• missing
• existing
• hubTotal
• driveTotal

使い方:

1. Settingsを開く。
2. Drive Folders Diff/Fixへ移動。
3. entityを選ぶ。
4. Diffを押す。
5. missing件数を見る。

4.5 Fix Missing

用途:

• Drive Diffでmissingになったfolderだけを作る。

安全性:

• 不足folderだけ作る。
• 既存folder/fileは基本的に動かさない。

使い方:

1. Diffを実行する。
2. missingがあることを確認する。
3. 必要ならlimitを入れる。
4. Fix Missingを押す。
5. 再度Diffを実行する。

4.6 Record folder naming repair

DriveBuilderは、bare id folderとid__code folderを統合する可能性がある。

例:

• sh_0001
• sh_0001__501A

両方ある場合、canonical folderへ中身を統合し、重複folderをtrashに送る場合がある。

UserGuideでは、通常ユーザー向けではなくAdmin/Recovery向けに書く。

4.7 Versions folder repair

用途:

• 新しいversions fieldを追加した。
• 既存recordsにversions folderがない。
• legacy shotview / assetview folderをfield_id付きに移行したい。

動作:

• record folder内に field_id__label folderを作る。
• legacy folderがあればrename/promotionする可能性がある。
• nested versions folderをpromoteする可能性がある。

確認:

• 対象record folder内のversions folder名。
• Upload後の保存先。
• ProxyJobsのfield_id。
• Detail versions card。

4.8 Soft delete

Soft deleteはrecord folderを05deletedへ移動する。

完全削除ではない。

UserGuideでは「物理削除ではなく退避」と説明候補にする。

5. Cache Hydrator運用

5.1 Cache Hydratorの役割

Cache HydratorはOriginals URLの定期水和処理。

目的:

• Shots / Assets / TasksのOriginals URLを埋める。
• 既存の有効URLは維持する。
• 無効なURLはclearする。
• Drive folder名からrecord IDを推定してmapする。

5.2 Daily hydration

SA_installCacheHydratorTriggers() は毎日3時に SA_runCacheHydrationDaily を動かすtriggerを作る。

SA_runCacheHydrationDaily() は SA_hydrateOriginalsUrls() を実行する。

5.3 Hydrate Originals URLs

SettingsにもHydrate Originals URLs操作がある。

対象:

• all
• shot
• asset
• task

ただし実装側の SA_hydrateOriginalsUrls() は全entityを回す形に見える。

5.4 Hydrationがすること

各entityで行うこと:

1. 対象sheetを開く。
2. id columnを見つける。
3. originals columnを見つける。
4. originals root folderを見つける。
5. entity root folderを探す。
6. folder名からrecord IDを抽出する。
7. 現在のOriginals URLが有効なら維持する。
8. 無効ならclearする。
9. 空ならDrive folder mapからURLを入れる。

5.5 Hydrationの結果

結果summary:

• updated
• unchanged
• missing
• invalidCleared
• ms

5.6 Hydrationを使う場面

• 手動でDrive folderを作った。
• Sheet上のOriginals URLが空。
• Originals URLが無効になった。
• Drive rootを移行した。
• Open Originalsが効かない。
• Proxy AuditがOriginals folderを見つけられない。

5.7 Hydrationの注意

HydrationはURLキャッシュ補完であり、record自体を作るものではない。

Drive folderがない場合、Hydrateだけではmissingのままになる可能性がある。

その場合はDrive Ensure/Fixが必要。

6. Proxy Worker運用

6.1 Proxy pipelineの全体

Proxy pipelineは以下の流れ。

1. UserがVersions/OriginalsへUploadする。
2. UploadInboxへ記録される。
3. ProxyJobsへpending jobが入る。
4. Workerがpending jobをclaimする。
5. Workerがffmpeg等でproxyを作る。
6. Proxies rootへoutputする。
7. ProxyJobsがdoneまたはerrorになる。
8. Versions pointerが更新される。
9. Table/Detail/Previewに反映される。

6.2 WorkerKitのSetup

手順:

1. WorkerKit pageを開く。
2. Download Worker Kitを押す。
3. zipを展開する。
4. MOTK Proxy Worker.bat を起動する。
5. MOTK public URLを貼る。
6. Detectを押す。
7. Google sign-inを行う。
8. Companion appがffmpeg、OAuth token、Spreadsheet reachabilityを確認する。
9. Startする。
10. Settings Proxy OpsでWorkersとProxyJobsを見る。

6.3 Run one job only

04_run_worker_once.bat は1件だけ処理する。

使いどころ:

• 初回セットアップ確認。
• 変換preset確認。
• エラー再現。
• 本番連続運転前の小テスト。

6.4 Workerが処理するmedia

WorkerKitの説明:

• Video becomes MP4 proxy.
• Images become image proxy without resizing.
• PDFs pass through as original.

UserGuideに書ける方針:

• 動画は軽量MP4化。
• 画像はimage proxyとして扱う。
• PDFは変換せずoriginal扱い。

6.5 Workerが止まっている場合

症状:

• ProxyJobsがpendingのまま。
• UploadInboxはqueuedだがPreviewが出ない。
• Proxy Auditでmissingになる。
• Recent Proxy Jobsのheartbeatが古い。

対応:

1. WorkerKitを起動する。
2. OAuth/token状態を確認する。
3. ffmpegが使えるか確認する。
4. Spreadsheet reachabilityを確認する。
5. Run one job onlyで1件処理する。
6. Settings Proxy Opsでdone/errorを見る。

7. Proxy Audit運用

7.1 Proxy Auditの目的

Proxy Auditは、OriginalsにファイルがあるのにProxyがないrecordを見つける。

制作レビューではProxyがないとTable/Detailの表示が重くなる、またはPreviewできない。

7.2 Proxy Audit schedule

設定:

• Daily Scan enabled
• Hour
• Limit
• Entities: shots/assets/tasks

Daily ScanをONにすると、指定時間に自動scanする。

7.3 Run Audit Now

手動でscanする。

使いどころ:

• Upload後に確認したい。
• Worker復旧後にmissingが減ったか確認したい。
• Release前チェック。
• 週次保守。

7.4 Proxy Audit rowの読み方

見る項目:

• entity
• record_id
• display_name
• originals_file_count
• latest_original_file_name
• latest_original_file_id
• latest_original_modified
• proxy_status
• proxy_file_name
• latest_job_status
• latest_upload_status
• note

7.5 Requeue

Proxy Audit rowからRequeueすると、新しいProxyJobsを作る。

使いどころ:

• Originalsはある。
• Proxyがmissing。
• Workerを再起動済み。
• 既存jobがerrorまたは古い。

注意:

• 同じrecordに重複jobを作りすぎない。
• まず1件で試す。
• Worker onceで結果を見る。

7.6 Proxy Audit復旧手順

1. Settings Proxy Opsでroot idを確認。
2. Workerが動いているか確認。
3. Proxy AuditをRun Now。
4. Missing rowsを見る。
5. 1件だけRequeue。
6. Worker onceで処理。
7. ProxyJobsがdoneになるか確認。
8. Detail/Previewで表示確認。
9. 問題なければ複数件を処理する。

8. Field追加後の保守手順

8.1 通常fieldを追加した場合

1. Fieldsに新fieldを追加する。
2. 対象entity sheetの1行目にfield_idを追加する。
3. 2行目にlabelを追加する。
4. typeを設定する。
5. editable/required/optionsを設定する。
6. Pages presetに表示列を追加する。
7. Detail presetにcardを追加する。
8. DebugPanelでFieldTypes Healthを確認する。
9. Column Contractを確認する。
10. Table/Detailで表示確認する。
11. Inline editが必要ならsafe fieldでテストする。

8.2 link fieldを追加した場合

追加確認:

• link target entity。
• LINK_MAPSに対象entityがある。
• Link Pickerが開く。
• IDではなくentity_nameで表示される。
• chip clickでDetailへ飛ぶ。
• Table/Detail/Create modalで同じwidgetが出る。

8.3 versions fieldを追加した場合

追加手順:

1. Fieldsでtype=versionsを設定する。
2. 対象entity sheetへfield_id列を追加する。
3. Detail presetにversions cardを追加する。
4. SettingsまたはDebugからVersions folder repairを実行する。
5. 既存recordに field_id__label folderができるか確認する。
6. Test uploadする。
7. UploadInboxとProxyJobsを見る。
8. Worker onceで1件処理する。
9. Detail/Previewで表示確認する。

8.4 originals fieldを追加/変更した場合

追加確認:

• originals columnをServerFieldsが見つける。
• Hydrate Originalsが対象列へ書く。
• Open Originalsが正しいfolderを開く。
• Drive Diff/Fixと整合する。

8.5 field_idを変えてはいけない理由

field_idはMOTK内の参照ID。

変更すると以下が壊れる可能性がある。

• Pages JSON
• Detail card layout
• Table preset
• Versions folder name
• ProxyJobs field_id
• latest_pointer_json
• Column Contract
• Binding Integrity

field labelは変えられるが、field_idは原則変えない。

9. PageConfig / Preset保守

9.1 Presetが壊れたとき

症状:

• Tableに列が出ない。
• Detail cardが空。
• 別entityのfieldが出る。
• Save/Revertが効かない。
• Page selectorに出ない。

原因候補:

• Pages JSONが壊れている。
• field_idが存在しない。
• entity/pageType mismatch。
• Pages cacheが古い。
• Fields変更後にpresetを更新していない。

9.2 修復手順

1. DebugPanelのData Maps / Pageを見る。
2. Schema/Meta Healthを見る。
3. Pages JSONがvalid field_idだけを参照しているか確認する。
4. TableでDefault Pageを開く。
5. Fields menuで必要列を選び直す。
6. Save Asで新しいPresetを作る。
7. 壊れたpresetを退避または修正する。

9.3 Default Pageに戻す

Pagesが壊れた場合、Fields metadataからDefault Pageを合成できる可能性がある。

UserGuideでは「表示設定が壊れたら、まずDefault表示に戻してデータ自体が読めるか確認する」と書ける。

10. Drive障害Runbook

10.1 Open Originalsが開けない

確認順:

1. record IDがあるか。
2. Originals URL fieldがあるか。
3. Sheet上のOriginals URLが空か無効か。
4. project_meta/SystemConfigにOriginals rootがあるか。
5. Drive folderが存在するか。
6. Google共有があるか。
7. Hydrate Originalsを実行する。
8. それでもなければDrive Diff/Fixを実行する。
9. DebugPanel Originals diagnosticsを見る。

10.2 Folderが重複している

例:

• sh_0001
• sh_0001__501A

対応:

1. どちらにファイルがあるか確認する。
2. DriveBuilder consolidation対象か確認する。
3. いきなり手動削除しない。
4. AdminがDriveBuilder修復処理または手動統合を判断する。
5. 修復後、Hydrate Originalsを実行する。

10.3 Wrong folderにUploadされた疑い

重大度は高い。

確認:

• entity
• record_id
• field_id
• UploadInbox originals_folder_id
• ProxyJobs originals_folder_id
• Drive folder path
• latest_pointer_json
• Detail Preview

対応:

1. 追加Uploadを止める。
2. 対象recordを特定する。
3. Drive上の実ファイルを確認する。
4. UploadInbox/ProxyJobsのrowを確認する。
5. DebugPanel Originals diagnosticsを見る。
6. 必要なら手動移動ではなく修復方針を決める。

10.4 Drive rootを移行した場合

手順候補:

1. 新しいOriginals rootを作る。
2. 新しいProxies rootを作る。
3. project_meta/SystemConfigのroot id/urlを更新する。
4. Drive Ensureを実行する。
5. Hydrate Originalsを実行する。
6. Proxy Auditを実行する。
7. WorkerKitのconfigを再Detect/確認する。
8. 1件Upload/Worker onceで確認する。
9. DebugPanelでOriginals diagnosticsを見る。

11. Proxy障害Runbook

11.1 UploadしたがProxyが出ない

確認順:

1. Uploadが成功したか。
2. UploadInboxにrowがあるか。
3. ProxyJobsにpending jobがあるか。
4. Workerが動いているか。
5. Worker heartbeatがあるか。
6. ProxyJobsがerrorになっていないか。
7. Proxies root idが設定されているか。
8. Proxy Auditでmissingか。
9. Requeueが必要か。

11.2 ProxyJobsがpendingのまま

原因候補:

• Workerが起動していない。
• OAuth tokenがない。
• Spreadsheet reachabilityがない。
• Workerが別deployment URLを見ている。
• pending job claimに失敗している。

対応:

• WorkerKitを開く。
• Companion checksを確認する。
• 04_run_worker_once.bat で1件だけ処理する。
• Settings Proxy Opsでjob statusを見る。

11.3 ProxyJobsがerror

原因候補:

• failed transcode。
• invalid file type。
• source fileにアクセスできない。
• upload to Proxies failed。
• ffmpeg missing。
• output filename issue。

対応:

1. error_messageを見る。
2. source fileをDriveで開けるか確認。
3. Worker環境でffmpegを確認。
4. 1件だけ再実行。
5. 必要ならRequeue。

11.4 Proxyが古い

原因候補:

• Originalが更新されたがProxyが再生成されていない。
• latest_original_modifiedがoutput_updated_atより新しい。
• latest_pointer_jsonが古い。

対応:

• Proxy Auditを実行。
• Requeue。
• Worker once。
• Previewで確認。

12. Sharing/Access障害Runbook

12.1 新規ユーザーが開けない

確認順:

1. Usersにemailがあるか。
2. permissionがviewer/editorか。
3. User Access / SharingでRefresh。
4. Sync Checkedを実行。
5. Spreadsheetを直接開けるか。
6. Originals/Proxiesを直接開けるか。
7. Web App deployment accessを確認。
8. Googleアカウントが違っていないか確認。

12.2 EditorがUploadできない

確認順:

1. MOTK roleがeditorか。
2. Google Drive Originalsに書けるか。
3. Proxies root idが設定されているか。
4. write access errorが出ていないか。
5. Settings LogとConsoleを見る。

12.3 AdminがSettingsを開けない

確認順:

1. Admin listにいるか。
2. Usersにemailがあるか。
3. Admin workbookが開けるか。
4. Settings auth helperがあるか。
5. Web App execution user設定を確認。

13. Release前チェックリスト

13.1 Workbook Contract Tests

確認:

• fieldmap.* が存在するFields.field_idを指す。
• 参照fieldが意図したentityに属する。
• required sheetがrequired field idsを含む。
• Pages JSONがvalid field idsだけを参照する。

13.2 App Behavior Tests

確認:

• list viewが全entityで開く。
• detail save pathがfull side effectsを起こす。
• settingsがproject_metaを読み書きできる。
• schedulerがload/commit/snapshot/restoreできる。

13.3 Drive Tests

確認:

• stored URLからOriginals解決できる。
• fallback folder discoveryが動く。
• folder auto-createが動く。
• orphan folder soft deleteが想定通り。

13.4 Proxy Tests

確認:

• uploadでqueue itemが1件作られる。
• workerが1件claimする。
• worker heartbeatが更新される。
• proxy fileがtarget folderへuploadされる。
• queue itemが決定的にcompleteまたはfailする。

13.5 Failure Tests

確認:

• stale worker claim recovery。
• failed transcode。
• failed upload。
• missing folder permissions。
• invalid file type。

14. 週次保守チェックリスト

14.1 毎週見るもの

• Dashboard Project Snapshot。
• Update Feed。
• Settings Proxy Ops summary。
• Proxy Audit missing count。
• User Access mismatches。
• DebugPanel Regression Coverage。
• Scheduler/SchedViewが開くか。

14.2 毎週やる可能性がある操作

• Proxy Audit Run Now。
• Missing ProxyのRequeue。
• Worker heartbeat確認。
• Drive Diff確認。
• User Access Refresh。
• 問題があればSync Checked。
• DebugPanel Run all checks。

14.3 毎週やらない方がよい操作

• 無意味なSync Mismatches一括。
• 不要なDrive Fix大量実行。
• 不要なTask Recalculate。
• Publish前提のScheduler操作。
• field_id変更。

15. 月次保守チェックリスト

15.1 月次で見るもの

• ProjectMeta management mode。
• SystemConfig root id。
• Drive root共有。
• Admin list。
• 退場者の共有。
• ProxyJobs error傾向。
• UploadInbox増加量。
• Pages presetの不要/重複。
• FieldTypes Health。
• Column Contract / Binding Integrity。

15.2 月次で整理するもの

• 退場者のpermission。
• 外部共有。
• 古いdraft schedule。
• 不要なtest record。
• 古いproxy errors。
• 壊れたpreset。

16. 危険操作リスト

16.1 高リスク操作

• Publish schedule。
• Sync Mismatches。
• Admin追加/削除。
• project_meta root id変更。
• SystemConfig root id変更。
• field_id変更。
• Pages JSON直接編集。
• Proxy requeue大量実行。
• Task Recalculateでcompleted含める。
• Drive root migration。

16.2 中リスク操作

• Drive Ensure All。
• Hydrate Originals。
• Fix Missing。
• Versions folder repair。
• PNAVI Config変更。
• Theme変更。

16.3 低リスク操作

• DebugPanel Run all checks。
• Proxy Audit Refresh。
• User Access Refresh。
• SchedViewでView mode確認。
• Dashboard layout変更。

16.4 高リスク操作前チェック

1. 対象が正しいか。
2. 変更範囲が分かっているか。
3. 直前状態を記録したか。
4. DebugPanel reportを取ったか。
5. 小さい対象で試せるか。
6. 失敗時に戻す方法があるか。
7. 他の人が作業中でないか。

17. Recovery時の基本原則

17.1 まず壊れている層を分ける

層:

• UI表示
• PageConfig/Preset
• Fields/Schema
• Data rows
• Drive folder
• Proxy queue
• Worker
• Permission/Sharing
• Routing

どの層かを分けずに修復すると、別のものを壊しやすい。

17.2 データ修正より診断を先にする

まず見るもの:

• DebugPanel report
• Console
• Settings Log
• Viewer State
• Schema/Meta Health
• FieldTypes Health
• Column Contract
• Binding Integrity
• Proxy Ops/Audit
• Drive Diff

17.3 いきなり手動でDriveを削除しない

Drive folderの重複やmissingがあっても、手動削除は最終手段。

まずDriveBuilderのDiff/Fix/Ensure/Hydrateで状態を把握する。

17.4 いきなりfield_idを変えない

field_idはMOTK全体の参照基盤。

表示名やlabel変更で済むならfield_idは変えない。

17.5 大量修正前に1件で試す

Proxy Requeue、Worker、Upload、Drive Fix、Sharing Syncは1件または小範囲で試す。

18. Admin向け問題別Runbook一覧

18.1 Tableが空

1. DebugPanel Viewer State。
2. Data Maps / Page。
3. FieldTypes Health。
4. Schema/Meta Health。
5. Pages JSON。
6. Table entity/preset。
7. Console。

18.2 Detailが開かない

1. URL entity/id。
2. Router/Link diagnostics。
3. Entity samples。
4. Detail smoke。
5. Console。

18.3 Link chipがID表示

1. LINK_MAPS counts。
2. Entity samples。
3. entity_name fid。
4. FieldTypes Health。
5. CommonRenderer。

18.4 Originalsが開かない

1. Originals diagnostics。
2. project_meta/SystemConfig root。
3. Hydrate Originals。
4. Drive Diff/Fix。
5. Google共有。

18.5 Proxyが出ない

1. UploadInbox。
2. ProxyJobs。
3. Worker heartbeat。
4. Proxy Audit。
5. Requeue。
6. Worker once。

18.6 Settingsが保存できない

1. Access info。
2. project_meta management mode。
3. read-onlyか。
4. Admin list。
5. Console/Settings Log。

18.7 Schedulerが壊れた

1. SchedViewで見る。
2. Scheduler Load Diagnostics。
3. Card List。
4. Lane visibility。
5. Snapshot/Undo。
6. Publish前ならPublishしない。

第8部 データモデルリファレンス

1. Data modelの基本原則

MOTKのデータモデルは、Google Sheetsを中心にする。

Sheetsは制作データのソース。

Fieldsは、Sheets上の列をアプリがどう読むかを決める翻訳レイヤー。

Pagesは、データの見え方を保存する表示設定。

Driveは、OriginalsとProxiesというファイル実体を保持する。

ProxyJobs / UploadInbox / ProxyAuditは、ファイルとプロキシ生成の状態を記録する運用テーブル。

DebugPanelは、これらの解釈と整合性を検査する診断レイヤー。

UserGuideでは、まず次の分類を出すと理解しやすい。

1. Entity data - Shots - Assets - Tasks - ProjectMembers - Users - Pages

2. Schema / metadata - Fields - project_meta - SystemConfig

3. File / proxy operations - UploadInbox - ProxyJobs - ProxyAudit - ProxyWorkers

4. Aggregation / acceleration - DataHub - cache / viewer snapshot / bootpack

5. External storage - MOTK_ORIGINALS - MOTK_PROXIES

2. Source of truthの説明

2.1 Google Sheets is source

MOTKでは、Google Sheets上のデータ構造・値・ヘッダを正しいものとして扱う。

問題が起きた場合、UserGuideでは「シートが間違っている」と書かない。

正しい説明は以下。

• アプリ側が現在のGS構造を正しく解釈できていない。
• Fields/metadataの翻訳が足りない。
• ServerFieldsやCommonRendererの解釈が合っていない。
• PageConfigが現在のFieldsと合っていない。

2.2 Fieldsは翻訳レイヤー

FieldsはGS実データに合わせてアプリが意味を理解するための翻訳レイヤー。

Fieldsが壊れているからGSを変える、という説明は避ける。

必要なら「現在のGS構造を正しく読むためにFieldsまたは解釈コードを調整する」と説明する。

2.3 field_idはアプリの契約

各entity sheetの1行目にfield_idがある。

アプリはfield_idを基準に列を解釈する。

列番号に依存しない。

field_idを勝手に変えると、Pages JSON、Detail layout、ProxyJobs、Versions folder、latest_pointer_json、Column Contractが壊れる可能性がある。

2.4 labelは人間向け

2行目のlabelは人間向け。

表示名やUI上の説明に使う。

labelは変えられる可能性があるが、field_idとは別。

2.5 idとentity_nameの分離

idは機械用。

entity_nameは人間用。

例:

• Shot ID = sh_0001
• ShotCode = 501A
• Asset ID = as_0001
• Asset Name = Robot Arm
• Task ID = tk_0001
• Task Name = Layout
• Member ID = pm_0001
• Role = Lead Animator
• User ID = us_0001
• User Name = John Smith

idは変えない。

entity_nameは表示名として編集可能にする方針。

3. Sheet row structure

3.1 Entity sheetの標準構造

Shots、Assets、Tasks、ProjectMembers、Users、Pagesは標準的に2段ヘッダを持つ。

• Row 1: Field IDs
• Row 2: Labels
• Row 3+: Data rows

Row 1のfield_idはアプリが読む。

Row 2のlabelは人間が読む。

Row 3以降が実データ。

3.2 なぜ2段ヘッダか

2段ヘッダにする理由:

• field_idでコードが安定して読む。
• labelで人間が分かりやすく見る。
• label変更と内部参照を分離する。
• 列移動に強くする。
• 多言語化や表示名変更に対応しやすくする。

3.3 Admin向け注意

Admin向けには以下を明記する。

• Row 1のfield_idは消さない。
• Row 1のfield_idは重複させない。
• Row 2のlabelだけでfieldを判断しない。
• Row 3以降にデータが入る。
• 新しい列を追加したらFieldsにも定義が必要。
• field_idを変更した場合、PagesやVersionsなども連動して壊れる可能性がある。

3.4 通常ユーザー向け説明

通常ユーザーには、2段ヘッダの詳細は不要。

ただし、Tableで見える列名はlabelであり、内部的にはfield_idで管理されていると軽く説明する価値がある。

4. Entities overview

4.1 shot

shotは映像制作上のショット単位。

主な用途:

• 進捗管理
• レビュー
• タスク連携
• アセット連携
• 素材管理
• スケジュール連携

代表ID:

• sh_0001

代表entity_name:

• ShotCode

4.2 asset

assetは制作で再利用される要素。

主な用途:

• キャラクター
• プロップ
• セット
• 背景
• 環境
• 衣装
• モデル
• リグ
• 素材

代表ID:

• as_0001

代表entity_name:

• Asset Name

4.3 task

taskは作業単位。

主な用途:

• 担当割り当て
• Due Date管理
• Scheduler Card
• Shot/Assetとの紐づけ
• Status管理
• Version upload

代表ID:

• tk_0001

代表entity_name:

• Task Name

4.4 member

memberは制作上の担当・役割。

主な用途:

• Task Assignee
• Scheduler lane
• Department
• Role
• User Link

代表ID:

• pm_0001

代表entity_name:

• Role

4.5 user

userはGoogleアカウントやMOTK利用者。

主な用途:

• Email
• Permission
• Sharing sync
• Admin/User access
• Memberとの紐づけ

代表ID:

• us_0001

代表entity_name:

• User Name

4.6 page

pageはTable/Detail/SchedView/Schedulerなどの見え方を保存する設定データ。

主な用途:

• Table preset
• Detail card layout
• Schedule view
• Config JSON

代表ID:

• pg_default
• pg_shot_detail_grid

代表entity_name:

• Page Name

5. Entity relationship

5.1 ShotとAsset

ShotはAsset Linkで複数Assetを参照できる。

AssetはShot Linkで使用先Shotを参照できる。

関係:

• Shot → Asset: このShotで使うAsset
• Asset → Shot: このAssetが使われるShot

UserGuideでは、どちらか一方のlinkだけで十分なのか、双方向更新されるのかは最終確認が必要。

5.2 ShotとTask

ShotはTask Linkで関連Taskを参照できる。

TaskはShot Linkで対象Shotを参照できる。

関係:

• Shot → Task: このShotに必要な作業
• Task → Shot: この作業が属するShot

SchedulerではTaskがCardになる可能性が高い。

5.3 AssetとTask

AssetはTask Linkで関連Taskを参照できる。

TaskはAsset Linkで対象Assetを参照できる。

関係:

• Asset → Task: このAssetに必要な作業
• Task → Asset: この作業が属するAsset

Asset laneやAsset conflictの判定に関係する。

5.4 TaskとMember

TaskはAssigneeまたはmember_linkでProjectMemberを参照する。

Memberは制作上の担当者・役割。

関係:

• Task → Member: 誰が担当するか
• Member → Task: その人/役割の担当作業

5.5 MemberとUser

ProjectMemberはUser LinkでUserを参照する。

関係:

• Member → User: 制作上の担当をGoogleアカウントへ紐づける
• User → Member: そのGoogleアカウントが持つ制作上の役割

5.6 PageとEntity

PageはEntityを対象に持つ。

例:

• table page for shot
• detail page for asset
• schedule view for task/member

Pageは制作データではなく、見え方の設定。

5.7 Upload/ProxyとEntity

UploadInboxとProxyJobsはentityとrecord_idを持つ。

関係:

• UploadInbox → entity/record_id/field_id
• ProxyJobs → entity/record_id/field_id/source_file/output_file
• ProxyAudit → entity/record_id/originals/proxy status

つまり、ファイルは単独で存在するのではなく、必ずentity recordとfield_idへ結びつく。

6. Shots sheet detail

6.1 役割

Shots sheetは、ショット単位の制作データを持つ。

レビュー、進行、素材、タスク、アセット、スケジュールの中心。

6.2 代表field

代表field:

• Shot ID
• ShotCode
• Episode
• Act
• Sequence
• Scene
• Shot
• Status
• TC @fps
• Artist Note
• Producer Note
• Frames
• ShotView
• ShotView Versions
• Materials
• Comp
• Comp Versions
• Asset Link
• Task Link
• Due Date

6.3 Shot ID

Shot IDはprimary key。

形式例:

• sh_0001

編集不可。

Drive folder、link、versions、proxy、schedulerの参照基盤。

6.4 ShotCode

ShotCodeは人間が見るショット名。

例:

• 201A
• 501A

Episode/Act/Sequence/Scene/Shotから派生する可能性がある。

ただし、manual editをAutomationが上書きしないことが重要。

6.5 Hierarchy fields

階層field:

• Episode
• Act
• Sequence
• Scene
• Shot

これらはShotCode生成やHierarchy navigationに使う。

project_metaで表示/非表示が制御される可能性がある。

6.6 Status

Shotの進捗。

例:

• not_started
• in_progress
• review
• approved
• completed

Table filter、Dashboard summary、Scheduler card color、レビュー抽出に使う。

6.7 Shot media fields

ShotView、Comp、Materialsなどは映像・画像・素材に関係する。

• ShotView: レビュー用のショットビュー
• ShotView Versions: バージョン履歴
• Materials: 参照素材や撮影素材
• Comp: 合成結果
• Comp Versions: 合成バージョン履歴

6.8 Link fields

ShotはAsset LinkとTask Linkを持つ。

Asset Link: このShotで使うAsset。

Task Link: このShotに必要なTask。

6.9 Due Date

Shotの締切。

SchedulerやProduction reviewで重要。

Timezoneやdate handlingに注意。

7. Assets sheet detail

7.1 役割

Assets sheetは、制作で使う要素の管理。

キャラクター、プロップ、環境、背景、セット、リグ、モデル、素材などを管理する。

7.2 代表field

代表field:

• Asset ID
• Asset Name
• Asset Type
• Status
• AssetView
• AssetView Versions
• Shot Link
• Task Link
• Notes

7.3 Asset ID

Asset IDはprimary key。

形式例:

• as_0001

編集不可。

7.4 Asset Name

Asset Nameは人間向け表示名。

例:

• Robot Arm
• Body Geo
• Sword100

7.5 Asset Type

Asset Typeは分類。

例:

• character
• prop
• set
• environment
• background
• costume
• rig
• model

実際のoptionsはFields定義に従う。

7.6 Asset media fields

AssetView、AssetView Versionsなど。

Assetのサムネイル、レビュー画像、リファレンス、バージョン確認に使う。

7.7 Asset LinkではなくShot Link

Assets sheet側では、使用先ShotをShot Linkで持つ。

TasksとはTask Linkでつながる。

7.8 Asset conflictとの関係

SchedulerのAsset laneやasset conflictは、TaskのAsset LinkまたはAsset sheetとの関係を使う可能性がある。

Asset Linkが不正だと、conflict表示も不正になる。

8. Tasks sheet detail

8.1 役割

Tasks sheetは作業単位を持つ。

SchedulerでCardとして扱われる可能性が高い。

8.2 代表field

代表field:

• Task ID
• Task Name
• Task Type
• Assignee
• Status
• Due Date
• Shot Link
• Asset Link
• TaskView
• TaskView Versions
• Notes
• Estimate / formula fields

8.3 Task ID

Task IDはprimary key。

形式例:

• tk_0001

編集不可。

8.4 Task Name

Task Nameは人間向け表示名。

例:

• Layout
• Animation Block
• Lighting
• Comp

8.5 Task Type

Task Typeは作業種別。

例:

• layout
• animation
• lighting
• comp
• modeling
• rigging
• review

実際のoptionsはFields定義に従う。

8.6 Assignee

AssigneeはProjectMemberを指すmember_linkである可能性が高い。

UserではなくMemberを参照する点が重要。

8.7 Task Status

Taskの進捗。

Scheduler card color、Table filter、Dashboard summaryに使う。

8.8 Task Due Date

Task締切。

Scheduler、Producer workflow、遅延検出に使う。

8.9 Task Link directions

TaskはShot LinkとAsset Linkを持つ。

Shot taskならShot Linkを持つ。

Asset taskならAsset Linkを持つ。

両方持つ場合もある。

8.10 Task estimate fields

Task Est Recalculateの対象fieldがある。

具体field番号はプロジェクト定義依存。

UserGuideでは「推定日数・推定時間・作業量などを計算するfield」と説明する。

9. ProjectMembers sheet detail

9.1 役割

ProjectMembersは制作上の担当・役割。

Usersとは別。

Scheduler laneやTask Assigneeに使う。

9.2 代表field

• Member ID
• Role
• Department
• User Link
• Notes