<!-- Generated by scripts/generate_ai_collab_docs.py. Edit metadata in that script. -->

# Backend Service: billing

This file adds local guidance for `src/api/flaskr/service/billing`. Read the
repository root and `src/api/AGENTS.md` first, then use this file for
module-specific ownership and risk points.

## Scope

- This service owns creator billing routes, payment orchestration, wallet
  state, ledger state, subscription lifecycle, and future settlement tasks.

- Primary checked-in entry files today:
  `src/api/flaskr/service/billing/consts.py`,
  `src/api/flaskr/service/billing/models.py`,
  `src/api/flaskr/service/billing/routes.py`,
  `src/api/flaskr/service/billing/tasks.py`

- Keep creator billing isolated from the legacy learner `/order` domain and
  `order_orders` business state unless the design doc explicitly says to reuse
  shared provider raw snapshot tables or the shared provider adapter boundary.

- Preferred pytest location: `src/api/tests/service/billing/` should remain
  the first stop for focused route, model, and orchestration coverage.

## Do

- Start from the billing design doc and preserve the documented split between
  `billing_*` / `credit_*` tables and the legacy `order_*` payment flow.

- Reuse shared response envelopes, auth handling, and
  `service/order/payment_providers` adapters before adding new cross-service
  payment abstractions.

- Keep route registration in `routes.py` plugin-style so `/api/billing` stays
  independent from `flaskr/route/order.py`.

- Add focused tests whenever route wiring, creator permissions, webhook
  boundaries, or DTO payload shapes change.

## Avoid

- Do not write new creator billing business state into legacy `/order`
  handlers or reuse `order_orders`; if provider raw snapshots are mirrored into
  `order_pingxx_orders` / `order_stripe_orders`, keep them isolated with
  billing-specific keys and domain filters.

- Do not let route handlers absorb settlement, ledger mutation, or provider
  orchestration logic that belongs in dedicated billing helpers.

- Do not invent billing response shapes that diverge from the design doc
  without updating the spec and downstream frontend types together.

- Avoid expanding this module with runtime code paths that depend on schema not
  yet added in the current task.

## Commands

- `rg -n "billing" src/api/flaskr/service src/api/tests docs/billing-subscription-design.md`
  to locate the design contract, service code, and tests before editing.

- `cd src/api && pytest tests/service/billing/ -q` for the narrowest focused
  regression pass while iterating on this module.

- `cd src/api && pytest -q` when a change here also touches shared auth,
  provider adapters, database models, or other backend services.

- `python scripts/check_ai_collab_docs.py` when adding or changing local
  backend AI instruction files.

## Tests

- Cover creator access control and the highest-risk bootstrap or orchestration
  behavior in `src/api/tests/service/billing/`.

- Expand tests when DTO contracts, provider callbacks, or persistence state
  transitions change.

- Review schema work manually for business-key indexes, idempotency, and table
  isolation from legacy `/order` data.

- Document any skipped provider, webhook-signature, or credential-dependent
  verification in the final task summary.

## Related Skills

- `src/api/SKILL.md`

- `SKILL.md`

- Create a new backend skill under `src/api/skills/<topic>/SKILL.md` when this
  module grows a repeatable billing-specific implementation or debugging flow.
