All business logic in a Pionia app lives in services — PHP classes with one method per action. Pionia Shop clients POST JSON to http://127.0.0.1:8000/api/v1/:

{ "service": "product", "action": "list" }

Who this is for#

You finished Pionia Shop tutorial Step 1 and want to design Pionia Shop’s Moonlight API — services, actions, validation, and optional generic CRUD for task, member, and project.

What you will learn#

• How { "service", "action" } maps to PHP classes and *Action methods
• When to use hand-written services vs Generic services
• How to document actions for frontend teams at /docs

How it works#

flowchart LR
  POST["POST /api/v1/"] --> Switch[MainSwitch]
  Switch --> Task["task → ProductService"]
  Switch --> Member["member → CustomerService"]
  Switch --> Project["project → OrderService"]
  Task --> Action["listAction / createAction"]

Start here#

Pionia Shop services#

In the Pionia Shop tutorial you build:

Reference#

• API versioning — when Pionia Shop adds /api/v2/
• Moonlight security model — auth at the switch layer
• Documenting your API — @moonlight-* and OpenAPI

Every response uses the same envelope: returnCode, returnMessage, returnData. See Requests & responses.

Common mistakes#

• Legacy uppercase JSON keys — Moonlight expects lowercase service and action.
• Skipping switch registration — scaffolding ProductService is not enough; add 'task' => ProductService::class in MainSwitch::registerServices().
• Using generic services for complex rules — keep ProductService manual when assignee logic grows; use OrderService as generic CRUD first.
• Wrong dev port — Pionia Shop examples use 8000 (PORT in environment/.env), not 3000 or 8003.

What’s next#