Skip to content

Commit 6376b60

Browse files
wldswlds
committed
docs: propose op backoffice direction
1 parent 4a5665d commit 6376b60

1 file changed

Lines changed: 212 additions & 0 deletions

File tree

‎docs/superpowers/specs/2026-06-17-op-backoffice-design.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# OP Backoffice Design Proposal
2+
3+
## Context
4+
5+
Sub2API already has a broad admin console for configuration and management:
6+
7+
- Users, API keys, groups, subscriptions, platform quotas, and user attributes
8+
- Upstream accounts, proxies, channels, channel monitors, scheduled tests, and TLS profiles
9+
- Usage dashboards, request drilldown, ops errors, alert rules, alert events, and system logs
10+
- Payment orders, plans, payment providers, redeem codes, promo codes, announcements, affiliates, and risk control
11+
- Backup, data management, system updates, and compliance acknowledgement
12+
13+
The OP backoffice should not duplicate those CRUD pages. It should sit above the existing admin modules as an operations workflow layer for customer support, business operations, and on-call handling.
14+
15+
## Goals
16+
17+
- Give operators one place to answer: what needs attention now?
18+
- Turn scattered admin actions into guided workflows for user support, account-pool health, payment follow-up, and incident triage.
19+
- Reuse existing `/admin/*` capabilities where possible.
20+
- Keep risky system configuration in the existing admin pages unless an OP workflow needs a narrow action.
21+
- Prepare for role-based access control and audit logging before exposing sensitive actions to non-super-admin operators.
22+
23+
## Non-Goals
24+
25+
- Replacing the current admin console.
26+
- Rebuilding existing user, account, payment, usage, and ops pages as separate CRUD screens.
27+
- Introducing a second frontend application.
28+
- Adding broad automation that changes balances, account scheduling, or payment state without operator review in the initial phase.
29+
30+
## Recommended Product Shape
31+
32+
Add an OP workspace inside the existing Vue admin app, for example under `/admin/op` or `/admin/workbench`.
33+
34+
The workspace should be task-oriented:
35+
36+
- Workbench overview
37+
- User 360
38+
- Account pool health
39+
- Exception queue
40+
- Payment and revenue operations
41+
- Campaign operations
42+
43+
The existing admin pages remain the source of truth for deep configuration. OP pages link into them for advanced editing.
44+
45+
## MVP Scope
46+
47+
### 1. Workbench Overview
48+
49+
Provide a compact daily operations page that aggregates:
50+
51+
- Today's revenue, paid orders, failed orders, and pending manual follow-up
52+
- Today's requests, tokens, actual cost, account cost, and estimated gross margin
53+
- Active users, new users, high-spend users, and abnormal spenders
54+
- Account availability, errored accounts, temporarily unschedulable accounts, and quota-risk accounts
55+
- Open alert events, unresolved request errors, unresolved upstream errors, and system log ingestion health
56+
57+
Most of this can be composed from existing dashboard, payment, account, and ops APIs. If the frontend would otherwise issue many heavy requests, add a backend snapshot endpoint that calls existing services and returns an OP-specific aggregate DTO.
58+
59+
### 2. Exception Queue
60+
61+
Create a single queue for operator handling:
62+
63+
- Alert events
64+
- Client-visible request errors
65+
- Upstream errors
66+
- Account errors
67+
- Payment exceptions
68+
- Risk-control logs that require review
69+
70+
Each item should show severity, status, source, affected user/account/order, first seen, last seen, count, and available actions.
71+
72+
Initial actions:
73+
74+
- Mark resolved or ignored
75+
- Add operator note
76+
- Open related user, account, request, order, or alert detail
77+
- For account issues: clear error, run test, refresh credentials, clear temporary unschedulable status where already supported
78+
- For user issues: open User 360
79+
80+
### 3. User 360
81+
82+
Provide a support-first user detail surface:
83+
84+
- Profile, status, role, groups, custom attributes, auth identities
85+
- Balance, balance history, subscriptions, platform quotas, and RPM status
86+
- API keys and recent usage
87+
- Recent orders, promo/redeem usage, affiliate relationship
88+
- Recent request errors and risk-control logs
89+
- Safe quick actions: adjust balance with reason, replace group, assign/extend subscription, reset platform quota window, unban user, add internal note
90+
91+
All mutation actions should require reason input and write audit logs once audit storage exists.
92+
93+
### 4. Account Pool Health
94+
95+
Provide an operations view for upstream supply:
96+
97+
- Availability by platform, group, channel, and proxy
98+
- Error accounts, rate-limited accounts, quota-risk accounts, and temporarily unschedulable accounts
99+
- Cost, request volume, success rate, latency, and quota usage by account
100+
- Batch actions that already exist: test, refresh, clear error, refresh tier, reset quota, bulk update selected safe fields
101+
102+
This page should guide on-call operators to restore capacity quickly without exposing unrelated credential or routing configuration by default.
103+
104+
## Later Phases
105+
106+
### Payment and Revenue Operations
107+
108+
- Order follow-up queue for unpaid, failed, cancelled, and provider-mismatched orders
109+
- Manual reconciliation status and operator notes
110+
- Revenue, cost, gross margin, ARPU, first-payment conversion, repurchase rate
111+
- Revenue by plan, group, model, platform, and payment provider
112+
113+
### Campaign Operations
114+
115+
- Campaign wrapper around announcements, promo codes, redeem codes, and affiliate settings
116+
- Targeting by group, activity, spend, registration date, and subscription status
117+
- Conversion tracking: sent, viewed, redeemed, paid, retained
118+
119+
### RBAC
120+
121+
Introduce roles before broad OP adoption:
122+
123+
- Super admin: full existing admin access
124+
- Operator: OP workbench, exception queue, user support actions
125+
- Finance: payment, order, revenue, refund/reconciliation actions
126+
- On-call: account pool health, ops alerts, account recovery actions
127+
- Marketing: campaigns, announcements, promo/redeem codes, affiliate settings
128+
129+
Use deny-by-default permissions for dangerous mutations.
130+
131+
### Audit Logs
132+
133+
Add a durable audit log for sensitive actions:
134+
135+
- Actor ID, role, auth method, IP, user agent
136+
- Action, target type, target ID
137+
- Before/after summary for changed fields
138+
- Reason, request ID, created at
139+
140+
Priority actions to audit:
141+
142+
- Balance changes
143+
- Subscription assignment, extension, revocation, and quota reset
144+
- User status, role, group, RPM, and platform quota changes
145+
- Account status, scheduling, error clearing, credential refresh, and quota reset
146+
- Payment order cancellation, manual reconciliation, and refund markers
147+
- Promo/redeem generation and bulk changes
148+
- Risk-control unban and flagged-hash deletion
149+
150+
## Backend Direction
151+
152+
Prefer adding a thin OP aggregation layer over duplicating business logic:
153+
154+
- `backend/internal/server/routes/admin.go`: add an OP route group if new endpoints are needed.
155+
- `backend/internal/handler`: add handlers that return OP-specific aggregate DTOs.
156+
- `backend/internal/service`: add an OP service that composes existing admin, dashboard, payment, account, ops, usage, affiliate, and risk-control services.
157+
- `backend/internal/repository`: only add repository queries when existing service APIs cannot provide the data efficiently.
158+
159+
Potential endpoint shape:
160+
161+
- `GET /api/v1/admin/op/overview`
162+
- `GET /api/v1/admin/op/exceptions`
163+
- `PUT /api/v1/admin/op/exceptions/:type/:id/status`
164+
- `POST /api/v1/admin/op/exceptions/:type/:id/notes`
165+
- `GET /api/v1/admin/op/users/:id/summary`
166+
- `GET /api/v1/admin/op/accounts/health`
167+
168+
The first implementation can also be frontend-composed from existing APIs if performance is acceptable. Backend snapshots should be added when a page requires many calls or expensive joins.
169+
170+
## Frontend Direction
171+
172+
Keep the OP workspace in the existing frontend:
173+
174+
- Add routes under `frontend/src/router/index.ts`.
175+
- Add OP API wrappers under `frontend/src/api/admin/op.ts` only for new backend endpoints.
176+
- Add views under `frontend/src/views/admin/op/`.
177+
- Reuse existing stores, i18n, layout, table, chart, and modal patterns.
178+
- Link to existing admin detail pages for advanced edit flows.
179+
180+
UI should be dense and operational, not marketing-style:
181+
182+
- KPI strip for current state
183+
- Queue tables with filters and saved views
184+
- Detail drawers for quick triage
185+
- Safe action buttons with confirmation and reason fields
186+
- Deep links to existing user/account/order/request pages
187+
188+
## Data and Performance Notes
189+
190+
- Prefer existing aggregated usage/dashboard tables for time-range summaries.
191+
- Avoid scanning raw usage logs for default OP pages.
192+
- Use snapshot endpoints for heavy overview pages.
193+
- Keep exception queue filters indexed by status, severity, created time, user, account, and order where applicable.
194+
- Do not expose secrets in OP DTOs.
195+
196+
## Open Questions
197+
198+
- Should OP users be separate from admins, or should all current admins see the OP workspace initially?
199+
- Which role should be allowed to adjust user balance manually?
200+
- Do payment refunds need to be executed through provider APIs or only recorded as manual markers at first?
201+
- Should operator notes be generic across entities, or only attached to exception queue items in the MVP?
202+
- Should the initial exception queue unify data only in the frontend, or create a backend-normalized queue DTO immediately?
203+
204+
## Suggested Implementation Order
205+
206+
1. Add OP route shell and overview page using existing APIs.
207+
2. Add exception queue read-only view, backed by existing alert/error/risk/payment APIs.
208+
3. Add User 360 read-only summary.
209+
4. Add narrow quick actions with reason fields.
210+
5. Add audit log storage and enforce audit writes for sensitive OP actions.
211+
6. Add RBAC and split operator/finance/on-call/marketing permissions.
212+
7. Expand campaign and revenue operations.

0 commit comments

Comments
 (0)