vmall/openspec/changes/archive/2026-09-23-add-content-admin-ui/proposal.md

Why

The home-content APIs (GET /api/admin/content, PUT /api/admin/content/{kind} for banners, promos, quick links and floor adverts) and the brand registry APIs (GET /api/brands, PUT /api/admin/brands) already exist and already feed the mall, but the platform console has no pages for them: content and brands can only be changed with hand-built API calls. A shop profile is likewise writable only through the platform-admin endpoint PUT /api/admin/shops/{id}/profile, so a merchant cannot maintain their own store identity, contact and service copy at all.

What Changes

• Add a content management page to apps/admin with one editor per home-content kind (banners, promos, quick links, floor adverts): ordered rows with add, remove and reorder, per-entry fields and active flags, form validation mirroring the API rules, a storefront preview, and per-kind whole-list replacement saves with the exact semantics of the existing PUT /api/admin/content/{kind}.
• Add a brand management page to apps/admin editing the whole ordered brand list (slug, bilingual name, active flag) and saving it with the exact semantics of the existing PUT /api/admin/brands, with validation, preview and save feedback.
• Add a shop profile editing page to apps/shop-admin where a merchant maintains their own logo, banner, company, region, and bilingual address, notice and after-sale copy through the shared API adapter.
• Add one minimal merchant-scoped endpoint, PUT /api/shop/profile, plus its @vmall/shared contract method, because no merchant-writable profile route exists today; profile scores stay platform-set.

Capabilities

New Capabilities

None.

Modified Capabilities

• frontend-admin: platform-console pages for storefront home content and the brand registry, with per-row form validation, storefront preview, and explicit whole-list save feedback.
• frontend-shop-admin: merchant self-editing of the shop profile through the shop-scoped endpoint, with bilingual validation and read-only platform-set scores.
• store-directory: shop owners may write their own shop profile through PUT /api/shop/profile under the own_shop scope; the platform-admin write and the public reads keep their existing behavior.

Non-goals

Drag-and-drop storefront decoration, draft/publish states for content entries, multi-page templates, and full shop storefront decoration (the tigshop store-fitting scope) are excluded. Media upload and hosting are excluded (entries keep carrying image URLs), as are a platform-admin UI for shop profiles (the existing admin API stays as-is), mall rendering changes for content and brands, brand-to-product assignment UI, and per-entry scheduling or analytics.

Impact

• apps/admin: new content and brands pages, nav entries, and bilingual strings in the existing admin locale sources.
• apps/shop-admin: new shop profile page, nav entry, and bilingual strings in the existing shop-admin locale sources.
• apps/api: one new shop-scoped route PUT /api/shop/profile reusing the existing profile upsert and bilingual validation (no migration), with integration coverage in apps/api/tests/.
• @vmall/shared: one shop.updateMyProfile method; the existing content, brand and store-directory contract methods are consumed unchanged.
• No database migration and no change to the public storefront contract.