Admin console

Document version: 0.7 Status: Confirmed (key admin-console decisions are set); OpenClaw-related items now follow in-house runtime operations in the root docs/产品规格.md; §3.8 System knowledge base aligned with the current implementation (2026-05-22); model enablement and evaluation moved to the router operations console (2026-08-20); §6 Time display defaults to Beijing time (2026-07-14) Wording: Explanations for admin users always follow user-facing language (see the header of root docs/产品规格.md); UI and help copy should be natural and actionable. Related documents:

• docs/后端与Web设计.md
• docs/产品规格.md (primary)

---

1. Goal and place

The admin console supports Cadau platform operations and governance, covering:

• User and permission management
• Agent-market review and listing governance
• Trading, settlement, and take-rate management (platform take 20%)
• Risk, audit, compliance, and appeal handling
• Health and metrics for the in-house agent runtime and LLM gateway (mainly read-only): conversation/tool-call error rate, latency, rate-limit hits; memory index and self-evolution background jobs (§3.6) queues and failure rates, and similar (fields follow the final implementation)
• System knowledge base (§3.8): global notes the help assistant uses, maintained in the admin console (same editor and AI index rebuild as workspace/agent knowledge)
• Agent memory maintenance (§3.9): overnight/manual tidy of user-agent personal memory (dedupe, expire daily notes); you can view run history; separate from memory forging (the knowledge overlay)

The admin console does not connect to model-vendor secrets, and does not operate runtime files inside a user’s workspace; every capability goes through the Go backend /api/v1/admin/*.

---

2. Roles and permissions (RBAC)

Suggested first-phase roles:

1. Super Admin

- Full permissions, role assignment, critical configuration changes, emergency bans

1. Ops Admin

- User management, market operations, campaign configuration, announcements

1. Review Admin

- Template review, reject, unpublish, violation handling

1. Finance Admin

- Orders, split accounting, settlement, refunds, invoice-related status

1. Support Admin

- Tickets, appeals, ban review, read-only troubleshooting information

Admin accounts: separate from the ordinary user system (independent admin account table and login flow).

Suggested permission grain:

• user.read / user.update / user.ban
• template.review / template.publish / template.unpublish
• order.read / order.refund / settlement.export
• risk.read / risk.decision
• ops.config.update (high risk)

---

3. Feature modules

3.1 Dashboard

• Core metrics:

- DAU / WAU / MAU - New registrations, paid conversion - Templates listed, review pass rate - Order volume, platform take, creator earnings - Training-job success rate, average duration

• Risk overview:

- Pending review volume, high-risk hits, ban count - LLM/runtime call error rate, timeout rate (optionally by vendor-routing dimension)

3.2 User management

• Search the user list (mobile / email / ID / display name)
• User detail (basic info, level, agent count, order summary, risk records)
• User status:

- Active / limited / banned - Ban duration and reason

• User quotas:

- Agent-creation cap (overridden by level) - Training quota, call quota (optional)

3.3 Agent market management

• Template review workbench:

- Pending, pass, reject, re-review - Auto-review hit tags + human conclusion

• List / unlist:

- Publish, unpublish, throttle exposure, featured slots

• Content governance:

- Handle violating content - Freeze a template (policy for already-purchased users must be configured separately)

• Categories and tags:

- Categories (sites, people, attendance, payroll, finance, and so on) - Platform featured, sort weight

3.4 Training and tool governance

• Training job center:

- Queue status (queued/running/succeeded/failed/cancelled) - Cluster failure reasons - Retry and cancel

• Tool/workflow allowlist:

- Catalog of available tools - Tool permission policy (by template category or user level)

• Knowledge-base content review (optional first-phase simplification):

- Upload type and size policy - View risk-content detection results

3.5 Trading and settlement (platform take 20%)

• Order management:

- Query free / buyout / subscription orders - Payment status, entitlement status, refund status

• Split accounting:

- Split per order: gross, platform_fee(20%), creator_income

• Settlement:

- Creator settlement cycle (weekly/monthly) - Export settlement statements, reconciliation status

• Refunds:

- Refund request, review, execute, roll back entitlement

3.6 Risk and audit

• Operation audit log (full trace of admin actions):

- who/when/what/before/after/request_id

• Risk policy:

- Fake orders, abnormal training, violating template publishes

• Penalties and appeals:

- Ban / unban - Template restore and re-review flow

3.7 Model service (not on this console)

Wording: Which Cadau suite is enabled, plan quotas, list prices, and model evaluation are handled on the Model console (router operations console), not on the Cadau admin console. Admins here only maintain users, knowledge, and memory for this deployment.

Help: help/admin-ops/model-routing.md.

3.9 Agent memory maintenance (implemented)

Wording: On the admin console, view site-wide idle tidy results for personal memory, and run a round immediately; do not change the canonical help/workspace knowledge.

Help: help/admin-ops/agent-memory-maintain.md; mechanism: docs/core-mechanisms/智能体记忆.md.

3.8 System knowledge base (implemented)

This is the global knowledge base in root docs/产品规格.md: static notes mounted at deploy time, mainly retrieved by the help assistant (the Messages assistant when no workspace is selected).

What admins can do

• Open the System knowledge base workspace in the admin console (route /system-knowledge), the same way you maintain “workspace knowledge / agent knowledge”:

- Browse folders and Markdown, index.json - Create/edit/delete/move documents and topic folders - Regenerate the index with AI (two-level index.json; rules in docs/core-mechanisms/AI重建知识索引规则.md; optional paths field for documents injected only when they relate to an attachment/message path — see help/admin-ops/system-knowledge-index.md)

• After you change body text, rebuild the index; otherwise the help assistant may still retrieve from old summaries.

Relation to main-site knowledge layers

Product notes can live under topics such as help/knowledge-layers/ so the help assistant can explain the three-layer split to people.

Implementation notes (ops / integration)

• Disk root: help_docs.dir / HELP_DOCS_DIR (default repo help/); root index file help_docs.index_file / HELP_DOCS_INDEX_FILE (default index.json)
• Index-change fingerprint (optional): {paths.runtime_dir}/help_docs/reindex_sources.sha256
• Write-audit event types: admin.system_knowledge.write, admin.system_knowledge.reindex, admin.system_knowledge.reindex_fingerprint
• Conversation injection: main-site POST /api/v1/chat in help mode is retrieved by backend helpdocs.BuildPrompt; the frontend does not send full text through this section’s API

---

4. Admin APIs (suggested summary)

Suggested namespace: /api/v1/admin/*

• GET /admin/dashboard/metrics
• GET /admin/users
• PATCH /admin/users/:id/status
• PATCH /admin/users/:id/quota
• GET /admin/templates/review-queue
• POST /admin/templates/:id/review (approve/reject)
• POST /admin/templates/:id/publish
• POST /admin/templates/:id/unpublish
• GET /admin/orders
• POST /admin/orders/:id/refund
• GET /admin/settlements
• POST /admin/settlements/:id/close
• GET /admin/risk/events
• POST /admin/risk/events/:id/decision
• GET /admin/runtime/health (or GET /admin/llm/health; naming follows the implementation)
• GET /admin/runtime/metrics

4.1 Implemented (early landing)

Matches current code; requires admin JWT (AuthAdmin):

Auth (implemented): POST /admin/auth/login, /admin/auth/refresh, /admin/auth/logout.

Errors and response shape follow the existing convention: error/code/request_id/details and 2xx request_id.

---

5. Page information architecture (suggested)

1. Overview (including an entry into the System knowledge base)
2. Users
3. Template review
4. Market operations
5. Training center
6. Trade orders
7. Settlement and splits
8. Risk and audit
9. Runtime / LLM / index and evolution jobs (ops wallboard)
10. System settings (Super Admin only)
11. System knowledge base (full-screen knowledge workspace, implemented; reachable from Overview)

---

6. Non-functional requirements

• Security:

- Strong admin authentication (admin accounts separate from ordinary users) - Two-factor policy: required only for high-privilege roles (Super Admin, Finance Admin) - Second confirmation for sensitive operations - IP allowlist (optional)

• Audit:

- Every admin operation must be traceable

• Performance:

- Paginated lists, filter and export

• Availability:

- Key flows can roll back (unlist, unban, undo)

• Time display:

- Dashboard, audit events, running-job start times, and similar UI times default to Beijing time (UTC+8); the server still stores UTC (same as main-site docs/产品规格.md §1.5.4). This phase of the admin console does not offer a separate time-zone preference; Beijing time is uniform.

---

7. Phasing

P1 (must)

• RBAC (at least Super/Ops/Review/Finance)
• User management + template review + list/unlist
• Order query + split display (20%)
• Audit log
• Creator credit score (ships in phase one)
• System knowledge base maintenance and AI index rebuild (implemented, see §3.8)

P2 (enhance)

• Training-job operations board
• Automated refunds and automated settlement
• Deeper runtime and LLM routing diagnostics (including index and evolution job pipelines)

---

8. Confirmed key decisions (item by item)

1. Admin sign-in: separate (independent admin account system).
2. Admin two-factor: required only for high-privilege roles (Super Admin / Finance Admin).
3. Refund policy: buyout and subscription both support refunds; after a refund, entitlement is kept until the current billing period ends.
4. Template review SLA: finish review within 72 hours.
5. Admin approval flow: no two-person review (one person with permission executes).
6. Creator settlement cycle: monthly.
7. Creator credit score: ships in phase one, used for review priority and market exposure.

8.1 Follow-on landing rules (from confirmed decisions)

• Entitlement expiry after refund:

- buyout: after refund, switch to “expire at period end” (if a period field exists); if there is no period field, define a minimum service window at the order layer, then expire. - subscription: after refund, expire at the end of the current settlement period.

• Review-deadline governance:

- After a template is submitted it enters pending_review; the system records review_due_at = submitted_at + 72h. - The dashboard shows overdue reviews and alerts.

• Credit-score mechanism (phase one) suggested fields:

- credit_score (0-100) - credit_level (A/B/C) - credit_factors (pass rate, violation rate, user complaint rate, refund rate) - Credit-score effects: review-queue priority, upper bound on market recommendation weight.

---

9. Database table draft (PostgreSQL, admin console)

Note: suggested new/extended tables in the admin domain; they can evolve alongside existing business tables.

9.1 Admin accounts and permissions

1) admin_users

• id (bigserial, pk)
• username (varchar(64), unique, not null)
• email (varchar(255), unique, not null)
• password_hash (varchar(255), not null)
• role (varchar(32), not null) // super_admin / ops_admin / review_admin / finance_admin / support_admin
• status (varchar(16), not null, default active) // active / disabled / locked
• two_factor_enabled (boolean, not null, default false)
• two_factor_type (varchar(16), null) // totp / sms / email
• last_login_at (timestamp, null)
• created_at / updated_at

2) admin_audit_logs

• id (bigserial, pk)
• admin_user_id (bigint, not null, fk -> admin_users.id)
• action (varchar(128), not null) // e.g. template.review.approve
• resource_type (varchar(64), not null) // user/template/order/settlement...
• resource_id (varchar(128), not null)
• before_json (jsonb, null)
• after_json (jsonb, null)
• request_id (varchar(64), null)
• ip (varchar(64), null)
• user_agent (varchar(512), null)
• created_at (timestamp, not null, default now())

9.2 Market review and operations

3) agent_template_reviews

• id (bigserial, pk)
• template_id (varchar(128), not null)
• submitter_user_id (bigint, not null)
• status (varchar(24), not null) // pending_review / approved / rejected
• auto_review_result (varchar(24), null) // pass / risk / block
• auto_review_tags (jsonb, null)
• reviewer_admin_id (bigint, null)
• reject_reason (text, null)
• submitted_at (timestamp, not null)
• review_due_at (timestamp, not null) // submitted_at + 72h
• reviewed_at (timestamp, null)
• created_at / updated_at

4) market_exposure_configs

• id (bigserial, pk)
• template_id (varchar(128), not null, unique)
• is_featured (boolean, not null, default false)
• sort_weight (int, not null, default 0)
• category_override (varchar(64), null)
• updated_by_admin_id (bigint, not null)
• updated_at (timestamp, not null, default now())

9.3 Trading, splits, and settlement

5) orders (extension suggestions)

• New fields:

- pricing_mode (varchar(16), not null) // free / buyout / subscription - gross_amount (numeric(12,2), not null, default 0) - currency (varchar(8), not null, default 'CNY') - status (varchar(24), not null) // pending / paid / refunded / closed - billing_period_end_at (timestamp, null) // used for “expire at period end after refund”

6) order_settlements

• id (bigserial, pk)
• order_id (varchar(128), not null, unique)
• template_id (varchar(128), not null)
• creator_user_id (bigint, not null)
• gross_amount (numeric(12,2), not null)
• platform_fee_rate (numeric(5,2), not null, default 20.00)
• platform_fee_amount (numeric(12,2), not null)
• creator_income_amount (numeric(12,2), not null)
• settlement_cycle (varchar(16), not null, default 'monthly')
• settlement_status (varchar(24), not null) // pending / settled / frozen
• settled_at (timestamp, null)
• created_at / updated_at

7) refund_requests

• id (bigserial, pk)
• order_id (varchar(128), not null)
• applicant_user_id (bigint, not null)
• reason (text, null)
• status (varchar(24), not null) // pending / approved / rejected / executed
• reviewed_by_admin_id (bigint, null)
• review_note (text, null)
• effective_at (timestamp, null) // takes effect at period end
• created_at / updated_at

9.4 Creator credit scores

8) creator_credit_scores

• id (bigserial, pk)
• creator_user_id (bigint, not null, unique)
• credit_score (int, not null, default 60) // 0-100
• credit_level (varchar(8), not null, default 'B') // A/B/C
• approval_rate (numeric(5,2), not null, default 0)
• violation_rate (numeric(5,2), not null, default 0)
• complaint_rate (numeric(5,2), not null, default 0)
• refund_rate (numeric(5,2), not null, default 0)
• last_calculated_at (timestamp, null)
• updated_at (timestamp, not null, default now())

---

10. Admin API field definitions (/api/v1/admin/*)

Shared constraints:

• Auth: admin JWT (issued separately)
• 2xx top level includes request_id
• Error body: error/code/request_id/details

10.1 User management

1) GET /api/v1/admin/users

Query parameters:

• q (fuzzy email/mobile/display name)
• status (active/limited/banned)
• limit, cursor

Response sketch:

{
  "items": [
    {
      "user_id": 1001,
      "email": "u@example.com",
      "phone": "138****0000",
      "level": "free",
      "agent_quota": 3,
      "agent_used": 2,
      "status": "active",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "request_id": "srv_xxx"
}

2) PATCH /api/v1/admin/users/:id/status

Request:

{
  "status": "banned",
  "reason": "Listed violating content",
  "ban_until": "2026-05-01T00:00:00Z"
}

10.2 System knowledge base (implemented)

Auth: admin JWT. Path prefix /api/v1/admin/system-knowledge. Request/response fields align with workspace and agent knowledge APIs (items[].path, items[].dir, content, and so on); only .md and index.json are allowed.

1) GET .../items — response { "items": [ { "path", "dir?", "size_bytes" } ] }

2) GET .../content?path= — response { "path", "content" }

3) PUT .../content — request { "path", "content" }

4) DELETE .../content?path=

5) PATCH .../file — request { "from", "to" }

6) POST .../dir / DELETE .../dir?path= / PATCH .../dir

7) GET .../reindex/preview — response includes top_dirs, steps_total, llm_configured, sources_unchanged_since_reindex, and similar

8) POST .../reindex/root | .../reindex/sub | .../reindex — backend must have an LLM configured; success includes paths_written, model (step APIs also have progress)

Writes and full/stepwise index rebuilds are written to admin_audit_events (see §3.8 event types).

10.3 Template review (planned)

1) GET /api/v1/admin/templates/review-queue

Query parameters:

• status=pending_review
• risk_level (low/medium/high)
• limit, cursor

2) POST /api/v1/admin/templates/:id/review

Request:

{
  "decision": "approve",
  "note": "Content is compliant; publish allowed"
}

decision values: approve | reject

3) POST /api/v1/admin/templates/:id/publish

Request may be empty; the backend checks that the template has already passed review.

4) POST /api/v1/admin/templates/:id/unpublish

Request:

{
  "reason": "Under violation remediation"
}

10.4 Orders and refunds

1) GET /api/v1/admin/orders

Query parameters:

• status, pricing_mode, creator_user_id
• created_from, created_to
• limit, cursor

2) POST /api/v1/admin/orders/:id/refund

Request:

{
  "decision": "approve",
  "reason": "User appeal upheld"
}

Rules:

• After approval, create/update refund_requests
• Entitlement expires at billing_period_end_at (takes effect at period end)

10.5 Settlement

1) GET /api/v1/admin/settlements

Query parameters:

• cycle=2026-04
• status=pending|settled|frozen
• creator_user_id

2) POST /api/v1/admin/settlements/:id/close

Request:

{
  "note": "Monthly settlement complete"
}

Effect:

• settlement_status from pending -> settled
• Record an operation audit log

10.6 Risk and credit scores

1) GET /api/v1/admin/risk/events

• Returns the risk-event list and handling status

2) POST /api/v1/admin/risk/events/:id/decision

{
  "decision": "ban_template",
  "note": "Hit high-risk keywords"
}

3) GET /api/v1/admin/creators/credit-scores

• View creator credit score, level, and contributing factors

4) PATCH /api/v1/admin/creators/:id/credit-score

{
  "score_delta": -10,
  "reason": "Repeated violation rejections"
}

10.7 Runtime and model routing

1) GET /api/v1/admin/runtime/health (path follows the implementation)

• Aggregate LLM-gateway reachability, health of key dependencies (index/queue), recent error summary

2) GET /api/v1/admin/runtime/metrics

• Metrics: request volume, P95 latency, timeout rate, error rate by model route; optional evolution-job and index-job counts

---

11. Key business rules (admin console)

1. Platform take is fixed at 20%, stored explicitly in order_settlements.
2. After a refund, entitlement “takes effect at period end”; no immediate hard cut.
3. Template review SLA is 72 hours; overdue items must enter the alert list.
4. No two-person review; one person with permission executes, but an audit log is required.
5. High-privilege roles must enable 2FA.
6. Creator credit score ships in phase one and affects review priority and exposure weight.

---

12. Admin account ops script (implemented)

Note: the following path assumes a Go backend exists in the repo; if only docs remain, check the path after the project is rebuilt.

To avoid “super admin can be initialized only on first start”, the backend provides an admin-account tool:

• Path: backend/scripts/adminctl/main.go
• Role: create or update an admin account (upsert by email); supports setting role and the 2FA switch

Example:

cd backend
go run ./scripts/adminctl --username admin --email admin@example.com --password "ChangeMe123" --role super_admin --enable-2fa true

Parameters:

• --username (required)
• --email (required)
• --password (required)
• --role: super_admin/ops_admin/review_admin/finance_admin/support_admin
• --enable-2fa: true/false

---

Appendix A: Day-to-day operations (current implementation)

The following matches repo client/admin (default http://localhost:3001) and /api/v1/admin/*; it aligns with §3.8 System knowledge base and the §4.1 implemented APIs. Planned batch review, CSV export, and similar are in body §3; do not operate from older admin-web docs before those land.

A.1 Access and sign-in

• Frontend: client/admin → npm install → npm run dev (port 3001)
• Sign-in: POST /api/v1/admin/auth/login (independent admin accounts; not shared with ordinary-user JWT)
• Main site: client/web defaults to 3000; sign-in state and ports are separate

A.2 Pages available now

After admin sign-in you get a left-nav shell: the sidebar opens each page; the bottom can open the main site or sign out.

A.3 Maintaining system knowledge

1. Sign in to the admin console → sidebar System knowledge base (or visit /system-knowledge).
2. After editing Markdown / folders, use “Regenerate the index with AI” (the backend needs an LLM configured). Conditional documents can add a paths glob on index entries (for example **/*.tsx); see help/admin-ops/system-knowledge-index.md.
3. Writes are recorded in admin_audit_events (admin.system_knowledge.*).

After a release / help change: follow the checklist at the end of help/admin-ops/system-knowledge-index.md — at least force-regenerate the index once, and spot-check with the help assistant.

A.4 FAQ

• 401: admin token expired → sign in again.
• Help assistant still answers old content: confirm index.json under help/ was rebuilt, and help_docs.dir points at the right directory.
• A conditional document never appears: if the index has paths, it is injected only when a user message or attachment path matches; do not fill paths on general materials.
• LLM index fails: check whether this deployment’s model-service token is enabled on the router side, and whether quota is exhausted (same gateway as main-site agent conversation).