Sony Wiki

Sony Wiki là repo làm việc chính cho runtime mới của dự án. Đây là monorepo dùng Turborepo, hiện có một ứng dụng triển khai thật tại apps/web.

BMAD Entry Point

Nếu cần nắm dự án nhanh theo workflow BMAD, đọc theo thứ tự:

1. docs/index.md
2. codex.md
3. design_tokens.md
4. project_report.md
5. docs/repository_structure.md

Repository Role

• apps/web: runtime Next.js 16 App Router đang được phát triển thật.
• docs: lớp project_knowledge của repo, dùng để giữ current state, structure notes và rollout checklists.
• _bmad: BMAD framework, skills, workflows và templates.
• _bmad-output: planning artifacts và implementation artifacts sinh ra trong quá trình làm việc theo BMAD.
• ../sony-wiki-ref/sony-wiki-dev: legacy reference để đọc flow cũ, không phải nơi phát triển mới.

Runtime Capabilities

Shared Shell

• / redirect server-side sang /wiki.
• /wiki là public root hub có card điều hướng DI và PE; /wiki?mode=admin mount unified admin workspace.
• Top navigation dùng Product Wiki launcher và Utilities; card DI và PE trong launcher vẫn phải giữ sub-links theo business group.
• Global search gợi ý product và category qua /api/search.
• Shell light-only, không còn theme switcher.
• /livestream là internal noindex workspace state cho tới khi có runtime thật.
• /burn-in là playlist tool tối giản.
• Landing catalog cũ được archive mềm tại /_archive/catalog-home.

Wiki

• Public routes: /wiki, /wiki/di, /wiki/di/[categorySlug], /wiki/pe, /wiki/pe/[categorySlug], /wiki/[slug].
• Admin workspace: /wiki?mode=admin, tree DI/PE > Category > Product, product modal dùng shared surfaces cho overview/specs/trainer/SEO.
• Canonical Supabase source: wiki_catalog_nodes.
• Legacy adapter routes wiki/categories* và wiki/products* vẫn tồn tại để bảo toàn caller cũ, nhưng write path mới đi qua node/admin helpers.
• Structured specs dùng specAttributes, custom fields, field options, table columns và template presets.
• Public product detail đọc qua typed query/SEO layer và có grouped specs, related products, canonical metadata.
• Compare queue giới hạn tối đa 4 sản phẩm.

Color Lab

• Public route: /color-lab.
• Runtime đọc typed recipes/photos từ Supabase, parse q, cameraLine, profile từ URL và gắn gallery đúng recipe đang chọn.
• Load state phân biệt live, seeded-fallback và degraded.
• Preview photos dùng public URL từ Supabase Storage bucket color-lab-preview, hỗ trợ cả upload file và manual URL.
• Admin workspace dùng Supabase auth cookie session chung với Wiki admin contract.

API Surface

Shared:

• GET /api/search

Wiki:

• POST /api/wiki/admin/login
• POST /api/wiki/admin/verify
• GET /api/wiki/admin/session
• POST /api/wiki/admin/logout
• GET /api/wiki/admin/catalog
• POST /api/wiki/nodes
• PATCH|DELETE /api/wiki/nodes/[id]
• GET|POST /api/wiki/categories
• PATCH|DELETE /api/wiki/categories/[id]
• GET|POST /api/wiki/products
• PATCH|DELETE /api/wiki/products/[id]
• GET /api/wiki/public/products/[slug]
• POST /api/wiki/media/upload
• GET|POST /api/wiki/spec-fields
• PATCH|DELETE /api/wiki/spec-fields/[id]
• GET|POST /api/wiki/spec-field-options
• PATCH|DELETE /api/wiki/spec-field-options/[id]
• GET|POST /api/wiki/spec-table-columns
• PATCH|DELETE /api/wiki/spec-table-columns/[id]
• GET|POST /api/wiki/spec-template-field-options
• PATCH|DELETE /api/wiki/spec-template-field-options/[id]
• GET|POST /api/wiki/spec-template-field-presets
• PATCH|DELETE /api/wiki/spec-template-field-presets/[id]

Color Lab:

• GET /api/color-lab/admin/catalog
• GET|POST /api/color-lab/recipes
• PATCH|DELETE /api/color-lab/recipes/[id]
• GET|POST /api/color-lab/photos
• PATCH|DELETE /api/color-lab/photos/[id]

Tech Stack

• Framework: Next.js 16 App Router
• Language: TypeScript strict
• UI: React 19 + HeroUI v3
• Styling: Tailwind CSS v4 + shadcn theme bridge trong globals.css
• Data: Supabase
• Forms/validation: React Hook Form + Zod
• Motion: Lenis + GSAP
• Client state phụ trợ: Zustand
• Workspace orchestration: Turborepo
• Node baseline trong repo: 22.22.0

Structure

sony-wiki/
├── apps/
│   └── web/                    # Next.js runtime chính
├── docs/                       # BMAD project knowledge cho repo này
├── _bmad/                      # BMAD framework
├── _bmad-output/               # Planning + implementation artifacts
├── scripts/                    # Setup, import và Supabase sync utilities
├── supabase/                   # Supabase CLI workdir + synced migrations
├── README.md
├── codex.md
├── design_tokens.md
└── project_report.md

Getting Started

Prerequisites:

• Node 22.22.0 theo .nvmrc
• npm 10.9.4
• Supabase project với public URL, anon key và service role key

Setup:

nvm use
npm run setup
cp apps/web/.env.local.example apps/web/.env.local

Điền các biến chính:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• WIKI_E2E_ADMIN_EMAIL
• WIKI_E2E_ADMIN_PASSWORD

Local development:

npm run dev

Verification Model

Local gates cho pass hiện tại:

npm --workspace apps/web run lint
npm --workspace apps/web run typecheck
npm --workspace apps/web run test

npm --workspace apps/web run build vẫn là release/route-surface gate quan trọng, nhưng không phải acceptance gate của pass cleanup này nếu môi trường local bị chặn bởi network/font fetch.

CI hiện có tại .github/workflows/node.js.yml chạy:

• npm ci
• npm run build --if-present
• npm test

CI chưa chạy riêng lint hoặc typecheck, nên hai gate này vẫn phải xác nhận local trước khi chốt thay đổi quan trọng.

Last Verified

Đã xác nhận cục bộ ngày 2026-04-23 trong pass BMAD docs sync + hotspot cleanup:

• npm --workspace apps/web run lint: pass
• npm --workspace apps/web run typecheck: pass
• npm --workspace apps/web run test: pass