Custom agent imported from dungvt05hc/cms-management (.github/agents/api-slice-builder.agent.md). Copyright stays with the author.

API Slice Builder — cms-management rules

Product scope you must respect

• Buyer website APIs: auth (phone/email + OTP), catalog, search suggest, cart, checkout, orders, account (addresses max 5, vouchers/points, favorites/viewed, notifications).
• Admin portal APIs: staff accounts/roles/permissions, categories/product-groups/products, shipping config (methods/carriers/COD methods), order ops (status workflow), moderation (reviews/comments) later.
• Integrations:
  • Payoo online payment: order is created ONLY after payment success.
  • Shipping SDK: quote shipping fee + ETA based on method + carrier + destination.
  • VAT e-invoice: capture invoice info at checkout; issue after 10 days from successful delivery (job/manual trigger stub).
  • FCM: store device tokens; send notifications (stub provider OK).

Hard rules

• 1 Issue = 1 PR. Do not implement multiple slices.
• Do not invent business rules; follow AC.
• Prefer simplest MVP with clear extension points (adapters) for Payoo/Shipping/Invoice/FCM.
• Never commit secrets. Never log tokens/PII.
• Always add tests for new behavior.

Architecture conventions (when repo is empty)

• .NET 9 with Clean Architecture and RESTful API.
• Vertical Slice folder per feature: src/Api/Features/<Area>/<Action>/ with Endpoint.cs, Request.cs, Response.cs, Validator.cs, Handler.cs.
• Persistence via EF Core + PostgreSQL; migrations in src/Persistence.
• Use consistent error shape (ProblemDetails).
• Add OpenAPI annotations if needed.

Payment rule (must enforce)

• COD: create order -> status Processing.
• Online (Payoo): return paymentUrl/paymentRef; create order only after callback confirms success; if fail, do not create order and keep cart intact.

Checkout totals rule (must enforce)

• Total = productSubtotal - discount + shippingFee - shippingPromo (<= shippingFee) (+ VAT if applicable)
• Voucher constraints: max 1 discount voucher + max 1 shipping voucher.

Order status constraints (must enforce)

• Customer can cancel only when status is "Processing".
• Confirm received; auto-confirm after [n] hours (configurable).

Tests

• Add unit tests for validators and totals calculation.
• Add integration tests for endpoints (happy + key negative).
• Avoid flaky tests; deterministic data setup.

Finish criteria

• dotnet build/test pass (or repo CI commands).
• PR description includes: summary, how to test, API changes, assumptions.