moteva/findings.md

Findings: Server-Backed Brand Kit Canvas Context

Requirements

• The previous implementation is frontend-only and insufficient for durable user ownership.
• The canvas header needs a compact Brand Kit selector beside the project name.
• The selector contains None plus the authenticated user's Brand Kits and shows the active selection.
• Agent Chat and every new session within that canvas must use the selected Brand Kit as a creative baseline.
• The Home prompt composer also needs a Brand Kit picker. Its empty state provides a direct 创建 Brand Kit action.

Initial Decisions

• Persist the project-to-kit relation on the server and inject context server-side so clients cannot silently omit it.
• Preserve the existing restrained Moteva canvas visual language and use the supplied interaction hierarchy without copying product identifiers.

Repository Discovery

• The server is an existing go-zero REST service with one img_infinite_canvas.api, generated handlers/types, thin logic files, and a shared ServiceContext.
• PostgreSQL persistence is SQLC-based (server/sqlc.yaml, schema.sql, query.sql) while memory storage supports local development and tests.
• The local mcp-zero binary and /Users/liangxu/go/bin/goctl are both available; API generation can follow the required spec-first workflow.
• The frontend Brand Kit implementation is still uncommitted and browser-local, so it must be migrated carefully without discarding its editor/model work.
• Playwright prerequisites are available, and the user has an authenticated browser session for final integration testing.
• design.Project is the common object passed through chat planning, conversation, and image-prompt generation, so adding resolved Brand Kit context there gives one reliable injection point for all Agent Chat flows.
• design.Repository currently owns project CRUD; both memory and PostgreSQL implementations enforce user scope through design.UserIDFromContext.
• Projects currently persist title/canvas/thread state but no brandKitId; SQLC generates PostgreSQL accessors from schema.sql and query.sql.
• Agent messages already carry thread_id, and the request can start a new thread; the selected kit should therefore be loaded from the project before every chat operation rather than copied into individual messages.
• DesignService.AgentChat reloads the project before planning every turn, then passes project-scoped copies to planning, research, conversation, and background generation. Hydrating the Brand Kit immediately after that load covers existing and newly created threads.
• Creative-agent prompt builders already centralize project identity through projectBriefContext, while deterministic/fallback image generation reads design.Project; Brand Kit context should be added to both centralized context builders and agent memory.
• Project creation has synchronous and asynchronous paths. Both should accept an optional requested kit and otherwise bind the authenticated user's default kit server-side.
• An explicit Home selection should override the default kit; the server must still verify that the selected kit belongs to the authenticated user.
• Home's composer has a compact action row with existing Radix Popovers for model selection, making a palette-icon Brand Kit popover a native extension rather than a new interaction pattern.
• Home currently appends a browser-local default kit prompt. This must be removed once project creation sends brandKitId, preventing duplicated or client-controlled brand instructions.
• Frontend Project and canvas snapshot merge paths need to preserve brandKitId; the direct project-document endpoint remains the authoritative source.
• Canvas workspace already centralizes title rendering and project updates, so the selector can live beside WorkspaceTitle and update the same in-memory project after a binding API call.
• The existing Brand Kit document is already versioned and contains the requested grouped colors, uploaded fonts with optional sizes/descriptions, logos, cover, references, voice, and visual direction. The server can validate this exact version-1 shape and compile it into authoritative prompt context.
• The project repository abstraction has a single Save operation and user-scoped Get; adding BrandKitID to design.Project will naturally flow through memory/cache/realtime wrappers as long as PostgreSQL mapping and API mappers are updated.
• ServiceContext constructs storage-specific modules beside the project repository. A dedicated Brand Kit service/store should follow the existing auth/sharing module pattern and use the same configured memory/PostgreSQL driver.
• All /api/* routes except the explicit public allowlist already require a valid bearer session, so new /api/brand-kits routes automatically enforce login before logic runs.
• SQLC is installed locally. The existing PostgreSQL repository runs the idempotent schema at startup, making schema/query changes plus SQLC regeneration the consistent persistence path.
• Direct image mode currently sends the raw user prompt to image generation, bypassing the creative planner. Brand context therefore must also be added to the direct/fallback image prompt builders, not only long-term memory and projectBriefContext.
• Asynchronous create/follow-up jobs reload projects from persistence, so Brand Kit context must be re-resolved inside those job execution paths; hydrating only the initial HTTP turn would be insufficient.
• Uploaded Brand Kit logos, cover images, and reference images are resolved server-side as ephemeral project inputs. Image generation appends them after user-supplied references so existing inline reference numbering remains stable.