# BÁO CÁO PHÂN TÍCH CHUYÊN SÂU: GIAO DIỆN WEB REVIEW STUDIO & QUY CHUẨN VERSIONING 188 SHOTS (MILESTONE 4) **Tác giả**: teamwork_preview_explorer (M4 Web UI & Versioning Governance Specialist 3) **Ngày thực hiện**: 2026-10-08T07:41:00Z **Phạm vi**: `web_review/`, `02_AI_Prompts/`, `04_Assets/`, `05_Production_Pipeline/`, `PROJECT.md` **Mục tiêu**: Điều tra toàn diện frontend Web Review Studio, kiểm chứng ma trận 188 shots EP01 trên 15 phân cảnh, đánh giá hiển thị prompt Sweet-Spot 720p / Audio Guard / Lip-Sync Guard / Versioning `_v`, xác nhận cập nhật bảng Milestone `PROJECT.md`, và xây dựng bộ đề xuất mã nguồn cho Worker M4. --- ## 1. TỔNG QUAN HIỆN TRẠNG KIẾN TRÚC FRONTEND (`web_review/`) ### 1.1. Cấu Trúc Tập Tin Frontend - **Tập tin giao diện chính**: Duy nhất `web_review/templates/index.html` (dung lượng 71,399 bytes, 2,053 dòng code). Không có thư mục `static/` riêng lẻ; toàn bộ CSS, HTML và JavaScript logic được đóng gói dạng Single-File Application (SPA). - **Static Mounts trong `web_review/server.py`**: * `/assets/videos` -> `04_Assets/videos` (189 tệp video raw và test) * `/assets/characters` -> `04_Assets/characters` (ảnh concept art 32 nhân vật) * `/assets/keyframes` -> `04_Assets/keyframes` (10 ảnh gốc và 169 thư mục chứa tail frames `clean_frame_239.jpg`) * `/assets/exports` -> `06_Exports` (các bản master cảnh, roadshow và shorts) - **Hệ thống Tab điều hướng hiện tại** (dòng 998-1004): 1. `tab-videos` ("🎬 Xem Review Phim"): Trình phát VIP Cinema Player với 5 bộ lọc Category (`feature_masters`, `episode_masters`, `scene_masters`, `shorts`, `raw_shots`). 2. `tab-file-manager` ("📂 Quản Lý Tệp & Bộ Nhớ"): Bảng danh mục tệp và thống kê dung lượng lưu trữ. 3. `tab-characters` ("🎨 Concept Art 32 Nhân Vật"): Lưới ảnh chân dung nhân vật kèm modal xem ảnh phóng to (`image-modal`). 4. `tab-scripts` ("📜 Kịch Bản 6 Tập"): Trình đọc kịch bản định dạng Hollywood từ `FilmMaker/TAP_01..06.md`. 5. `tab-prompts` ("⚡ Muse.ai Generator"): Biểu mẫu nạp prompt thủ công và danh sách hiển thị các prompt mẫu (`prompts-list`). --- ## 2. KẾT QUẢ ĐỐI SOÁT CHI TIẾT THEO 5 TRỌNG TÂM NGHIỆP VỤ ### 2.1. Khả Năng Hiển Thị Toàn Bộ Ma Trận 188 Shots Thuộc 15 Cảnh (C01 đến C15) - **Hiện trạng kiểm chứng**: * Trong cơ sở dữ liệu prompt (`02_AI_Prompts/gemini_banana_prompts.json` và `muse_ai_video_prompts.json`), EP01 được định nghĩa chính xác **188 shots** trải đều trên **15 phân cảnh**: - `ep01_scene01`: 21 shots - `ep01_scene02`: 15 shots - `ep01_scene03`: 15 shots - `ep01_scene04`: 12 shots - `ep01_scene05`: 27 shots (Đạm Tiên: C05-A 8 shots, C05-B 7 shots, C05-C 12 shots) - `ep01_scene06`: 14 shots - `ep01_scene07`: 8 shots - `ep01_scene08`: 8 shots - `ep01_scene09`: 6 shots - `ep01_scene10`: 14 shots - `ep01_scene11`: 10 shots - `ep01_scene12`: 8 shots - `ep01_scene13`: 12 shots - `ep01_scene14`: 12 shots - `ep01_scene15`: 6 shots - **Tổng cộng**: 21 + 15 + 15 + 12 + 27 + 14 + 8 + 8 + 6 + 14 + 10 + 8 + 12 + 12 + 6 = **188 shots**. * **Hạn chế nghiêm trọng trên UI hiện tại**: 1. Trong Tab 1, bộ lọc `raw_shots` hiển thị Accordion (`raw-scenes-accordion-container`, dòng 1724-1797) nhưng danh sách này được tạo hoàn toàn từ **các tệp mp4 thực tế có sẵn trên ổ cứng** (`VIDEOS_DIR.glob("*.mp4")`). 2. Hiện tại thư mục `04_Assets/videos` chỉ mới có **71 tệp EP01** (trong đó có 48 shot đơn lẻ). **140 shot chưa render hoàn toàn biến mất trên giao diện**, người kiểm duyệt không thể theo dõi tiến độ tổng thể của 188 shots. 3. Frontend hoàn toàn **không gọi `/api/shots`** hay `/api/scenes` từ backend; Tab 5 chỉ fetch `/api/prompts` và đổ toàn bộ 1,149 prompt của cả 6 tập thành một danh sách phẳng (`prompts-list`), không phân chia theo 15 cảnh của Tập 1. ### 2.2. Hiển Thị Sweet-Spot 720p Start Frame Prompt Từ `gemini_banana_prompts.json` - **Hiện trạng kiểm chứng**: * Tệp `02_AI_Prompts/gemini_banana_prompts.json` chứa 188 mục shot tương ứng với đầy đủ thuộc tính: `character_anchor`, `environment_anchor`, `resolution: "1280x720"`, và prompt phong cách mỹ thuật cổ phong Á Đông 720p không cháy sáng. * **Hạn chế nghiêm trọng**: 1. Backend `web_review/server.py` **hoàn toàn không nạp hay đọc tệp `gemini_banana_prompts.json`** tại bất kỳ endpoint nào (chỉ có biến `PROMPTS_FILE` trỏ tới `muse_ai_video_prompts.json`). 2. Frontend `index.html` **hoàn toàn không có cửa sổ Modal chi tiết phân cảnh/shot (Shot Detail Modal)**. Modal duy nhất trong file là `image-modal` (dòng 1266) dùng để xem ảnh nhân vật. 3. Người dùng trên UI không thể xem Start Frame prompt, không thể xem Character Anchor hay Environment Anchor của shot. ### 2.3. Hiển Thị Muse.ai Video Motion Prompt và Audio Guard Bắt Buộc - **Hiện trạng kiểm chứng**: * Tệp `02_AI_Prompts/muse_ai_video_prompts.json` định nghĩa chuẩn xác `motion_prompt`, `camera_motion`, `duration_sec: 10`, `audio_prompt`, và chỉ thị Audio Guard: *`Âm thanh: ... Quy tắc âm thanh: Tuyệt đối KHÔNG sinh nhạc nền (no music/BGM), không âm thanh điện tử, không tạp âm rè nhiễu. Chỉ sinh âm thanh môi trường tự nhiên (foley, ambience) và thoại nhân vật chân thực.`* * **Hạn chế nghiêm trọng**: 1. Trong danh mục duyệt video (Tab 1), thẻ video card chỉ hiển thị tên tệp và thời lượng; motion prompt và audio guard hoàn toàn không xuất hiện. 2. Trong Tab 5 (Muse Generator), prompt được hiển thị thành một khối văn bản thô không ngắt đoạn; Audio Guard bị chìm lẫn trong chuỗi văn bản, không có khung cảnh báo riêng biệt (callout) hay huy hiệu kiểm chứng chuẩn YouTube Green Dollar (-14 LUFS). ### 2.4. Hiển Thị Chỉ Thị Khóa Khẩu Hình (Lip-Sync Closed Lips Guard) - **Hiện trạng kiểm chứng**: * Các shot có thoại ngoài khung hình hoặc tiếng gọi từ xa trong `muse_ai_video_prompts.json` đều được gắn chỉ thị: *`[KHÓA KHẨU HÌNH BẮT BUỘC / LIPS CLOSED]: Đôi môi nhân vật trong khung hình khép chặt tự nhiên khi nghe tiếng gọi từ xa hoặc giọng dẫn chuyện V.O. (lips closed), tuyệt đối không mấp máy.`* * **Hạn chế nghiêm trọng**: 1. UI hoàn toàn không phân tích chuỗi văn bản để phát hiện chỉ thị `[KHÓA KHẨU HÌNH` hoặc `LIPS CLOSED`. 2. Không có huy hiệu bảo vệ khẩu hình (ví dụ: `🔒 Closed Lips Guard`), không có bộ lọc để đạo diễn rà soát nhanh các shot cần kiểm tra cử động môi. ### 2.5. Hỗ Trợ Phát Lại Video Có Đặt Tên Versioning (`_10s_v1.mp4`, `_v2.mp4`) và Master Cảnh (`_master_v1.mp4`) - **Hiện trạng kiểm chứng**: * Theo chỉ thị đạo diễn ngày 2026-10-08T05:38:03Z, mọi tệp video MP4 (shot đơn lẻ, master cảnh) bắt buộc có hậu tố `_v` (ví dụ: `ep01_scene01_shot01_10s_v1.mp4`, `ep01_scene01_master_v1.mp4`). * Pipeline `run_shot.py` (dòng 101-113) và `production_orchestrator.py` (dòng 350-363) đã triển khai logic sinh `_v1.mp4`, `_v2.mp4` và ưu tiên bản version cao nhất. * **Hạn chế trên UI hiện tại**: 1. Backend `server.py` (dòng 303-310) **chưa có regex bóc tách version `_v(\d+)`**. Khi có cả `_v1.mp4` và `_v2.mp4` trong thư mục, cả hai đều xuất hiện với cùng một tiêu đề hiển thị `Tập 1 • Cảnh 01 • Shot 01 (10s)`. 2. Trình phát VIP Cinema Player chỉ hiển thị tên file ở dòng chữ mờ nhỏ xíu (`#player-filename`), không có huy hiệu phân biệt phiên bản (`v1`, `v2`, `Re-take`) trên thanh metadata của player. 3. Không có cơ chế gom nhóm (version switcher) để chuyển đổi giữa bản nháp (Take 1) và bản quay lại (Take 2). --- ## 3. KIỂM TRA BẢNG MILESTONES TRONG `PROJECT.md` (DÒNG 49-50) - **Trạng thái ghi nhận trong `PROJECT.md` hiện tại**: * Dòng 49: `| M3 | 4-Stem Audio Engine & Ambience Continuity | Audio crossfade concat, continuous festival ambience, 2-pass EBU R128 -14 LUFS normalization | M1 | IN_PROGRESS |` * Dòng 50: `| M4 | Web Review Studio Sync & Production Integration | Upgrade web_review/server.py, sync generation schema with run_shot.py, verify live display on port 1515 | M2, M3 | PLANNED |` - **Kết quả điều tra thực tế**: 1. Worker M3 (`.agents/teamwork/worker_m3_1/handoff.md`) đã hoàn thành toàn bộ 6 tác vụ của Milestone 3 (AudioContinuityEngine 4-stems, Two-Pass Linear Normalization, Festival Ambience wav synthesis, `concat_scene_shots` upgrade). 2. Toàn bộ 173 test cases thuộc Tiers 1-4 trong `tests/` đã PASS 100% (thời gian chạy 36.16s). 3. Milestone 4 hiện đang được phân tích và chuẩn bị triển khai mã nguồn. - **Kết luận chỉ thị**: Cần cập nhật bảng Milestones trong `PROJECT.md` tại dòng 49-50: * Dòng 49: Milestone M3 chuyển thành **`DONE`**. * Dòng 50: Milestone M4 chuyển thành **`IN_PROGRESS`**. --- ## 4. BỘ ĐỀ XUẤT NÂNG CẤP MÃ NGUỒN CHO WORKER M4 Nhằm giải quyết triệt để các hạn chế trên và đáp ứng 100% yêu cầu nghiệm thu, Worker M4 cần triển khai các khối mã sau: ### Đề Xuất 1: Nâng Cấp Backend `web_review/server.py` 1. **Nạp thêm `BANANA_PROMPTS_FILE`**: ```python BANANA_PROMPTS_FILE = BASE_DIR / "02_AI_Prompts" / "gemini_banana_prompts.json" ``` 2. **Bóc tách Version `_v(\d+)` trong `build_library_data()`**: ```python v_m = re.search(r"_v(\d+)", lower) version_str = f"v{v_m.group(1)}" if v_m else ("v1" if ("_10s" in lower or "master" in lower) else "") item["version"] = version_str ``` 3. **Bổ sung Endpoint `GET /api/matrix/ep01`**: Tập hợp đầy đủ 188 shots của EP01 phân bổ trên 15 cảnh (C01 đến C15), kết hợp thông tin từ `gemini_banana_prompts.json`, `muse_ai_video_prompts.json`, và kiểm tra trạng thái tệp video/tail frame thực tế trên đĩa: - Trả về danh sách 15 cảnh chuẩn. - Mỗi cảnh chứa danh sách các shot với đầy đủ Banana prompt, Muse motion prompt, Audio Guard, cờ Lip-Sync guard (`has_lip_sync_guard`), trạng thái `rendered`, và danh sách các phiên bản video có sẵn. 4. **Bổ sung Endpoint `POST /api/concat`**: Nhận `{ "scene_id": "ep01_scene01" }`, gọi `concat_scene_shots(scene_id)` từ `05_Production_Pipeline/production_orchestrator.py` để ghép Master cảnh có bảo toàn âm thanh và gắn nhãn `_master_v.mp4`. 5. **Nâng cấp `POST /api/generate`**: Hỗ trợ tham số `shot_id`, gọi trực tiếp `run_shot_pipeline` từ `run_shot.py` với Start Frame và Audio Guard tự động. ### Đề Xuất 2: Nâng Cấp Frontend `web_review/templates/index.html` 1. **Thêm Tab Điều Hướng "Ma Trận 188 Shots (EP01)"**: ```html ``` 2. **Khu Vực Giao Diện Ma Trận (`tab-matrix`)**: - Thanh thống kê tiến độ: Tổng 188 shots, số shot đã render, số shot chờ render, tỷ lệ % hoàn thành. - Thanh điều khiển lọc: Lọc theo Cảnh (C01..C15), lọc trạng thái (`Đã Render`, `Chờ Render`), lọc theo `Khóa Khẩu Hình Guard`. - 15 Thẻ Accordion tương ứng 15 Cảnh: * Tiêu đề cảnh & tóm tắt kịch bản. * Nút `⚡ Ghép Nối Master Cảnh` (gọi `/api/concat` kèm thông báo toast và spinner). * Lưới thẻ các shot (Shot Card): Thumbnail Start Frame/Tail Frame, Shot ID, Cỡ cảnh, Badge trạng thái (`v1`, `v2`), Badge `🔒 Closed Lips`, Badge `720p Sweet-Spot`. * Nút bấm: `🔍 Chi Tiết Prompt` (mở Modal) và `▶ Phát Video` (nếu đã có video). 3. **Cửa Sổ Modal Chi Tiết Phân Cảnh (`#shot-detail-modal`)**: - Cột trái: Khung xem trước Start Frame 720p, Tail Frame 239, hoặc video player thử nghiệm. - Cột phải: * **Sweet-Spot 720p Start Frame Prompt (Gemini Banana)**: Hiển thị Character Anchor, Environment Anchor, độ phân giải 1280x720, prompt chi tiết và nút Copy. * **Muse.ai Motion Prompt**: Mô tả chuyển động máy quay và hành động nhân vật. * **Lip-Sync Closed Lips Guard**: Khung tím nổi bật cảnh báo khóa cử động môi khi nhân vật lắng nghe hoặc có thoại ngoài khung hình. * **Mandatory Audio Guard**: Khung vàng/hổ phách độc lập nhấn mạnh chỉ thị cấm nhạc nền, bảo tồn foley/ambience, đạt chuẩn -14 LUFS. * **Mục tiêu tệp & Phiên bản**: Tên file mục tiêu (`ep01_sceneXX_shotYY_10s_v1.mp4`) và danh sách các take nếu có. * Nút hành động: `🚀 Nạp Lệnh Render Ngay`, `📋 Copy Toàn Bộ Prompt`, `✕ Đóng`. 4. **Hiển Thị Versioning Trên VIP Cinema Player**: - Thêm nhãn `v1` trên thanh tiêu đề player. - Thêm nút chuyển đổi phiên bản nếu shot/master có nhiều bản render (`v1`, `v2`).