Source document · API/docs/ADMIN_AND_REPORTING.md
Administration, roles and reports
Administrative endpoints use the same signed bearer tokens as other protected routes, then check the role claim and resource-specific policy. A client UI is not a security boundary. The API derives the actor ID from the token, applies the role/ownership checks, and writes audit events for material administrative changes.
Roles and scope
| Role | Intended authority |
|---|---|
member | Own account, customer bookings/payments, inbox, conversations, and community actions. |
provider | Provider profile, owned listing/menu, provider dashboard, eligible orders, and provider-owned manual sales. |
accountant | Report summary limited to active service assignments. It does not grant general admin endpoints or global audit access. |
admin | Administrative overview/search, role/status changes, provider approval, payment rejection, content moderation, announcements, accountant assignments, audit, and export. |
Authorization is layered. First, the bearer token identifies a user and role. Then a module checks who owns the target resource and whether its current state allows the action. For example, a provider role alone does not allow changing another provider’s menu, confirming an unrelated order payment, or ending another host’s meeting.
Admin route map
| Endpoint | Access | Behavior |
|---|---|---|
GET /api/v1/admin/overview | Admin | Returns operational summary totals. |
GET /api/v1/admin/{kind}?q=&status=&limit=&offset= | Admin | Searches one supported collection: users, accountants, services, providers, listings, orders, or payments. Default page size is 25; the service accepts up to 100. Search/status behavior is collection-specific. |
PATCH /api/v1/admin/{kind}/{id}/status | Admin | Supports users (active or suspended) and listings (active, draft, or deactivated). The actor and resource are audited. An admin cannot suspend their own user account through this operation. |
PATCH /api/v1/admin/users/{id}/role | Admin | Assigns one of member, provider, accountant, or admin. The target’s refresh sessions are revoked so the next session gets the new role; accountant assignments are disabled when the new role is not accountant. The action is audited. |
POST /api/v1/admin/providers/{id}/approve | Admin | Approves the provider and promotes its owner to provider role transactionally. |
POST /api/v1/admin/orders/{id}/transition | Admin | Applies the same order state/version transition policy with administrative authority. |
POST /api/v1/admin/payments/{id}/reject | Admin | Rejects a submitted payment claim. It does not issue a refund. |
GET /api/v1/admin/community/reports?status= | Admin | Lists up to 50 moderation reports, optionally filtered by status. |
POST /api/v1/admin/community/reports/{id}/status | Admin | Sets a report status from the supported moderation state set and writes an audit event. |
POST /api/v1/admin/community/reports/{id}/moderate | Admin | Alternate moderation route through the lifestyle module; it accepts a non-empty status string. Prefer the /status route when you need the validated open, under_review, resolved, or dismissed values. |
POST /api/v1/admin/announcements | Admin | Creates an announcement as the token owner. Title and body are required. |
GET /api/v1/announcements | Any signed-in user | Lists published announcements; the route is protected but not admin-only. |
GET /api/v1/admin/audit | Admin | Returns the latest 50 audit events. Accountants do not have global audit access. |
GET /api/v1/admin/accountants/{id}/services | Admin | Reads service assignment rows for an accountant. |
PUT /api/v1/admin/accountants/{id}/services | Admin | Replaces the assignment set using service_ids; validates the target’s accountant role and every service ID, then audits the change. |
GET /api/v1/admin/exports/reports.csv?status= | Admin | Downloads up to 200 moderation report rows as CSV. This exports content reports, not orders, payments, or a financial ledger. |
The general collection endpoint accepts only known kinds in the repository. Its q, status, limit, and offset semantics vary by kind; use the OpenAPI operation and collection name rather than assuming every status value is interchangeable. Invalid kinds/filters are rejected. The search uses parameterized SQL; user-provided search text is not SQL syntax.
Accountant assignments and summary report
GET /api/v1/reports/summary is available to administrators and accountants. The API computes a UTC window from 30 days ago through the current time. The response includes order count, completed-order count, and gross amount. fees_minor currently remains zero because no fee calculation is wired into the reporting repository.
For an accountant, the PostgreSQL query includes only orders whose service_id has an active assignment to that accountant. An administrator receives an unscoped summary. The current order creation service derives bookings from listing menu items and intentionally sets service_id to null, so those new bookings do not match accountant service assignments. Until the order/reporting model connects menu items/listings to assigned services, an accountant’s summary may omit the main booking volume; do not treat it as a complete financial statement.
Assignments are a complete replacement: the PUT body must contain a service_ids array. The repository deactivates the prior active set, reactivates/inserts the requested services, and writes one audit event in the same transaction. An empty array removes all assignments.
Audit behavior
Audit records include actor ID, action name, resource type, resource ID, and timestamp. Role changes, provider approval, payment confirmation/rejection, moderation, accountant assignment, and status changes record events in their respective transactions. GET /api/v1/admin/audit returns only the latest 50 events in the current handler; it has no paging/filter API. Do not infer that every ordinary member action is audited: the audit table is currently used for selected control-plane changes.
Safety model
- Role changes revoke the target’s current refresh sessions; clients must reauthenticate and receive a new role-bearing access token.
- Admin routes return
403when the token is valid but not administrative. - Resource routes still apply ownership and state checks even for provider-level actions.
- A payment rejection records a status and audit event; no payment processor refund is issued.
- CSV output is a moderation report export and may contain user-generated reason text. Treat it as sensitive operational data.
- Development in-memory repositories are not an authorization persistence proof and reset on restart; use PostgreSQL for realistic role tests and production.