# AI Video Studio — Phase 0 (Project layer) — Handoff

**Status:** Phase 0 complete, reviewed, on branch `dev-chen` (not yet a PR). **Kept local** like the other AI Video docs (dropped from the PR in `b227838`).
**Date:** 2026-06-23. **Owner:** Chen. **Reviewer/merge:** Lee Jie.
**Direction doc (read first):** [`docs/ai-video-aixcut-blueprint.md`](ai-video-aixcut-blueprint.md) — the "Aixcut-style" 4-phase plan this is Phase 0 of.

This is the project-centric foundation: the AI Video Studio is now organised as **Projects** (one property/listing each) that own a **shared asset pool** + many **cut versions**. Phase 0 stands up the container + front door; the actual editing features (edit-by-text, find-best-cut, uploaded-footage editor) are Phase 1–3 below.

---

## 1. What shipped (Phase 0)

Commits on `dev-chen` (chronological): `e49579c` → `4957314` → `9a44987` → `426ccb9` → `043a33c`.

- **`video_projects` table + `VideoProject` model/repository/facade** — standard key model (uuid + RecordsBlame + SoftDeleteModel). Statuses: ACTIVE / ARCHIVED. `brief` JSON column (wired in the model, **not yet used** — reserved for Phase 2 chat).
- **`video_generations.project_id`** (nullable, additive) + `project()` / `generations()` relations. A **cut belongs to a project**; the `root_id` revision family lives within a project.
- **Backfill** (`..._100006_backfill_default_video_project`): existing cuts were moved into a default **"My Videos"** project. Guarded so it never runs on an empty (test) DB.
- **`ProjectsController`** (`manage/video/projects.*`): index (list + cut count), store (create), show (workspace), update, destroy (**cascades**: detaches its cuts + deletes its asset pool), `storeAssets` / `destroyAsset`.
- **Front door:** the sidebar **AI Video** nav now opens the project list (`/manage/video/projects`). The global studio at `/manage/video` still works (no forced redirect — see gap #5).
- **Project-scoped studio:** opening the studio with `?project=<uuid>` (the "New video in this project" button) scopes **My Videos / Drafts / Recycle bin** strictly to that project, and tags any cut it creates with `project_id` (wired through `store` / `draft` / `revise` + forwarded from the studio forms). Without `?project`, the studio is the global view.
- **Shared asset pool:** a project owns media (`project_asset` collection). The project workspace has an **Assets tab** to upload (images/clips) + view + delete. Source is recorded (`uploaded`; `ai_generated` reserved for Phase 2).
- **Tests:** `tests/Unit/Video tests/Feature/Video` → **115 green** (incl. `VideoProjectRepositoryTest`, `ProjectsControllerTest`). `npm run build` clean.

---

## 2. Key files

| Layer | Files |
|---|---|
| Model / repo | `src/Video/VideoProject.php`, `src/Video/Repositories/VideoProjectRepository.php`, `src/Video/Facades/VideoProjectRepository.php`; `src/Video/VideoGeneration.php` (`project_id` + `project()`) |
| Migrations | `database/migrations/2026_06_23_100004_create_video_projects_table.php`, `_100005_add_project_id_…`, `_100006_backfill_default_video_project.php` |
| HTTP | `app/Http/Controllers/Manage/Video/ProjectsController.php`; `VideoGenerationsController.php` (index `?project` scoping + `resolveProjectId` + project_id on store/draft/revise + redirects carry `?project`); `app/Http/Requests/Manage/Video/Projects/{Store,Update,StoreAsset}Request.php` |
| Routes | `routes/web.php` — `manage.video.projects.*` + `projects/{id}/assets` |
| Frontend | `resources/js/Pages/Manage/Video/Projects/{Index,Show}.vue`; `Pages/Manage/Video/Index.vue` (`project` prop + banner); `Components/Video/{StoryboardStudio,VideoGenerator}.vue` (`projectUuid` → forms); `Layouts/ManageLayout.vue` (nav) |

---

## 3. Run / test / verify

- Frontend: `cd ~/petav3 && npm run dev` (don't background it). Herd serves `https://petav3.test`.
- **Migrate once on the dev DB:** `php artisan migrate` (the 3 Phase-0 migrations — dev DB already migrated this session).
- Test: `"$HOME/Library/Application Support/Herd/bin/php" -d memory_limit=512M vendor/bin/phpunit tests/Unit/Video tests/Feature/Video` → **115 green**. (Test DB `petav3_testing`, RefreshDatabase — **never `migrate:fresh` the dev DB**.)
- Manual smoke: AI Video nav → Create Project → enter it → Assets tab: upload a photo → Cuts tab: "New video in this project" → generate → the cut appears under the project; My Videos/Drafts/Bin show only this project's items.
- **Queue:** generation still runs on Horizon (`php artisan horizon`). Nothing in Phase 0 changed the Job, so no worker restart is needed for Phase 0 itself — but **any future Job/Service change needs `php artisan horizon:terminate` + restart** (the worker caches code).

---

## 4. Review status

A code-review pass was done and all findings fixed in `043a33c`:
- **CRITICAL** — `ProjectsController::assetCard()` was called but undefined → 500 on any project page with assets (tests missed it because no test had assets on the show page; now covered).
- **HIGH** — project delete orphaned cuts + leaked GCS assets (now cascades); index cut-count included drafts (now excluded).
- **MEDIUM/LOW** — `?project` now validated as uuid; asset upload in a transaction; redirects carry `?project`; asset delete uses ConfirmModal.

---

## 5. Next-session work (prioritised)

**A. Bridge the asset pool into generation _(the missing half of Phase 0b — do this first)_.**
Today the pool is **upload-only**: `StoryboardStudio` / `VideoGenerator` still upload their own files per cut and cannot browse/pick from the project's `project_asset` pool. Wire the studio (when opened with `?project=`) to list the pool and let the user select pool assets as inputs (pass asset uuids → controller copies/links them into the generation's input media). Until this lands, "add assets to a project" and "generate a video" are disconnected.

**B. Phase 1 — Edit mode for generated cuts.** Edit-by-text (the scene `caption`/`voiceover` *is* the transcript), reorder, drop/trim scenes, "Find best cut" (Gemini scores scenes → suggested keep-set), and **re-render from the stored clips with NO Seedance call**. The no-Seedance re-package engine already exists ad-hoc — it was used this session to re-fix #20's captions (download `COLLECTION_CLIP` → ClipNormalizer → FfmpegStitcher → CaptionRenderer + VoiceoverService + VideoPackager → replace output). Productise it into a `RepackageVideoJob` + a `POST /manage/video/{id}/repackage` endpoint + an Edit view. ~0 cost per edit. **Highest demo value.**

**C. Phase 2 — Conversational drafting + AI-generated assets.** A chat that interviews the user (fills `video_projects.brief`) then drafts the storyboard (reuse `StoryboardDraftService`); plus AI-generated assets feeding the pool (`source = ai_generated`). Add `brief` to the project Store/Update requests + UI when you do this.

**D. Phase 3 — Uploaded real-footage editor.** STT (timestamps) → segment → best-moments scoring → text-based cut → assemble. Large; defer. Reuse the same scene/segment + editor + renderer.

**Smaller follow-ups:**
- **Ownership/tenant scoping** — `VideoProject::query()` returns *all* projects to *all* admins. There is no `business_id`/`created_by` filter. Add scoping before multiple admins/tenants use it (PropertyLab default tenant is `business_id=4`).
- **Flip the front door** — optionally redirect bare `/manage/video` → projects. Not done because ~5 existing `index` tests GET bare `/manage/video` and assert the studio component; redirecting them would need those tests updated.
- Consider moving `assetCard()` to the `PresentsVideoGenerations` concern if another controller needs to present media.

---

## 6. Gotchas to carry forward (bit us this session)

- **Horizon caches Job code** — after editing any `app/Jobs/**` or a Service the Job uses, `php artisan horizon:terminate` then restart, or the worker runs stale code. (This caused a "storyboard 400" earlier.)
- **Seedance `reference_video` is unusable in this deployment** — BytePlus can't fetch GCS URLs (resource download failed) *and* caps reference videos at ~15.2s *and* blocks real faces. The legacy path no longer sends video/audio refs at all; put real footage in via a **CLIP scene**, not a Seedance reference.
- **Captions** are rendered by `CaptionRenderer` (GD) and burned in by `VideoPackager` — *not* Seedance. CJK wraps at punctuation; captions sit in the lower third; presenter description is a fixed `config('video.presenter')` string (East-Asian look) prepended to every scene.
- **Committing** — RTK injects `--no-verify` into `git commit`, which the `block-no-verify` hook rejects. Workaround used all session: `c=commit; git "$c" -m "…"` (the variable keeps the literal string `git commit` out of the command).
- **Test DB isolation** — `phpunit.xml` points at `petav3_testing`; never `migrate:fresh` the dev DB.