AgentSkillsCN

scaffold-frontend-feature

为 Web 前端（Blazor）新增一项功能，引入响应式状态、乐观更新与缓存失效机制。当您需要实现面向用户的功能，并要求实时更新时，可使用本技能。

SKILL.md
--- frontmatter
name: scaffold-frontend-feature
description: Adds a new feature to the Web Frontend (Blazor) with Reactive State, Optimistic Updates, and Cache Invalidation. Use this when implementing user-facing features that need real-time updates.

Follow this guide to implement a responsive frontend feature in src/Web/BookStore.Web.

  1. •

    Prerequisites

    • •Ensure the API Client exists: src/Client/BookStore.Client/I{Resource}Client.cs.
    • •Ensure the Shared/Response DTOs exist in BookStore.Shared.
    • •if NOT, run /scaffold-read or /scaffold-write first.
  2. •

    Create the Component

    • •Create/Update src/Web/BookStore.Web/Components/Pages/{Feature}.razor.
    • •Template: templates/Page.razor
    • •Lifecycle: Use OnInitializedAsync to start listening: EventsService.StartListening();.
  3. •

    Implement Data Fetching

    • •Pattern: Use ReactiveQuery<T>.
    • •Setup (Template): templates/ReactiveQueryInit.cs
  4. •

    Implement Optimistic Updates (Properties)

    • •Use Case: Toggling a boolean, changing a number (e.g., Favorites).
    • •Pattern: Mutate -> Call -> Rollback.
      csharp
      query.MutateData(s => s with { IsFavorite = true }); // 1. Instant UI update
try {
    await Client.UpdateAsync(); // 2. API Call
} catch {
    query.MutateData(s => s with { IsFavorite = false }); // 3. Revert on error
}
  5. •

    Implement Optimistic Updates (Lists)

    • •Use Case: Adding a new item to a list instantly.
    • •Pattern:
      csharp
      OptimisticService.AddOptimisticBook(id, title); // 1. Add to separate list
await Client.CreateAsync(); // 2. API Call (Event will confirm/remove it)
    • •UI: Merge query.Data with OptimisticService.GetOptimisticBooks() when rendering lists.
  6. •

    Configure Invalidation

    • •Open src/Web/BookStore.Web/Services/QueryInvalidationService.cs.
    • •Add cases to GetInvalidationKeys(IDomainEventNotification notification).
    • •Rule: Map the Domain Event (e.g., BookCreated) to the Query Keys you defined in Step 2 (e.g., "Books").
  7. •

    Verify

    • •Run the app and verify:
      1. •Data loads.
      2. •Mutations update UI instantly.
      3. •SSE events (from other tabs/users) trigger auto-refetch.
    • •Run /verify-feature for complete verification.

Related Skills

Prerequisites:

  • •Backend endpoints must exist first:
    • •/scaffold-write - For mutation endpoints
    • •/scaffold-read - For query endpoints
  • •Client SDK must be configured (usually done by scaffold-write/read)

Next Steps:

  • •/scaffold-test - Create integration tests for the feature
  • •/verify-feature - Complete verification

Debugging:

  • •/debug-sse - If real-time updates don't work
  • •/debug-cache - If query data is stale

See Also: