buzz-sheet/Plan.md

Buzz Guide Structured Guide Platform

Product

Buzz Guide is a Thai-first, image-first Genshin guide CMS. The public directory shows a required cover and Overview for every guide. Each guide exposes only non-empty Weapons, Artifacts & Stats, Constellations, Team Calc, and optional Extra sections. Use the English terms “Build” and “Team” throughout the UI.

The admin workflow stays intentionally simple:

1. Sync the latest Lunaris catalog manually or from its Discord announcement.
2. Select one Lunaris character at /admin/create.
3. Upload a required Guide Image and write the Overview.
4. Edit one structured section at a time under /admin/[charid].
5. Press Save to update the public website immediately.

There is one guide per Lunaris character key. Empty sections remain private. Remove Guide moves content to a recoverable Trash before permanent deletion.

Structured content

• Weapons: catalog weapon, R1–R5, overall percent and/or personal percent.
• Artifacts: multiple named ranking groups, one-set or two-set rows, percent, up to two main stats per slot, ordered substats, targets, NA/E/Q priority and levels, and an optional note.
• Constellations: C1–C6 description and cumulative performance against C0=100%.
• Team Calc: multiple four-character teams, raw damage, calculated member shares, rotation duration, total DPS, and combo text.
• Extra: multiple sections of image-first rows with heading, short body, an optional percentage, and an optional editable mini spreadsheet.

Catalog and media

The manual Sync button fetches Lunaris version.json. A dedicated Discord worker instead extracts the exact version from followed announcements and recovers missed announcements from recent channel history. Both paths share a Redis lock, validate the versioned character, weapon, and artifact lists, filter placeholder or missing-image records, mirror unique assets and normalized JSON to Bun S3, then activate the completed version. Failed syncs do not replace the active catalog.

S3_ENDPOINT is the private Garage API used for writes. S3_PUBLIC_URL=https://buzz-cdn.astrxl.dev is the public read base. Browser uploads go to an authenticated application route, which validates PNG, JPEG, WebP, or GIF files up to 20 MB and writes them server-side through Bun S3.

Operations and acceptance

• PostgreSQL migrations run before the ARM64 web and worker rollout.
• Better Auth users and sessions are preserved; the legacy block-editor guide content is intentionally reset by migration 0002.
• Redis outbox events invalidate the directory and guide streams after saves, trash, restore, or delete actions.
• Verification requires bun run test, bun run typecheck, bun run lint, kubectl kustomize k8s/, a successful ARM64 container build, ready health checks, CDN reads, authenticated upload, catalog sync, and public rendering.
• Do not use Chromium or Playwright. Use Vitest, HTTP checks, and manual browser verification.