Cadau 管理员端功能规格（Admin Console）

文档版本: 0.5 状态: 已确认（管理员端关键决策已定）；OpenClaw 相关条目已按根目录 docs/产品规格.md 改为自研运行时运维；§3.8 系统知识文档 已与当前实现对齐（2026-05-22）；§6 时间显示 默认北京时间（2026-07-14） 表述：面向 管理员用户 的说明 一律以用户表达为准（见根 docs/产品规格.md 页眉）；界面与帮助文案用自然、可执行用语。 关联文档:

• docs/后端与Web设计.md
• docs/产品规格.md（首要）

---

1. 目标与定位

管理员端用于支撑 Cadau 的平台运营与治理，覆盖：

• 用户与权限管理
• 智能体市场审核与上架治理
• 交易、结算与抽成管理（平台抽成 20%）
• 风控、审计、合规与申诉处理
• 自研智能体运行时 与 LLM 网关 的健康与指标（只读为主）：对话/工具调用错误率、延迟、限流命中；记忆索引与 自进化后台任务（§3.6）队列与失败率等（字段以最终实现为准）
• 系统知识文档（§3.8）：供帮助智能体使用的全局说明，在管理端维护（与工作区/智能体知识同一套编辑器与 AI 重建索引）
• 智能体记忆维护（§3.9）：夜里/手动整理用户智能体 个人记忆（去重、过期日笔记）；可查看执行历史；与记忆锻造（知识叠加层）分离

管理员端不直连模型供应商密钥，不操作用户工作区内的运行时文件；所有能力统一经 Go 后端 /api/v1/admin/*。

---

2. 角色与权限模型（RBAC）

建议首期角色：

1. Super Admin（超级管理员）

- 全量权限、角色分配、关键配置变更、紧急封禁

1. Ops Admin（运营管理员）

- 用户管理、市场运营、活动配置、公告管理

1. Review Admin（审核管理员）

- 模板审核、驳回、下架、违规处理

1. Finance Admin（财务管理员）

- 订单、分账、结算、退款、发票相关状态

1. Support Admin（客服管理员）

- 工单、申诉、封禁复核、只读排障信息

管理员账号体系：与普通用户体系分离（独立管理员账号表与登录流程）。

权限建议颗粒度：

• 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（高危）

---

3. 功能模块清单

3.1 仪表盘（Dashboard）

• 核心指标：

- 日活/周活/月活 - 新增注册数、付费转化率 - 模板上架数、审核通过率 - 订单额、平台抽成、创作者收益 - 训练任务成功率、平均耗时

• 风险概览：

- 待审核量、高风险命中量、封禁数量 - LLM/运行时 调用错误率、超时率（按供应商路由维度可选）

3.2 用户管理

• 用户列表检索（手机号/邮箱/ID/昵称）
• 用户详情（基本信息、等级、智能体数量、订单摘要、风险记录）
• 用户状态管理：

- 正常/限制/封禁 - 封禁时长与原因

• 用户配额管理：

- 可创建智能体上限（按等级覆盖） - 训练额度、调用额度（可选）

3.3 智能体市场管理

• 模板审核工作台：

- 待审、通过、驳回、复审 - 自动审核命中标签 + 人工结论

• 上下架管理：

- 发布、下架、限流曝光、推荐位

• 内容治理：

- 违规内容处理 - 模板冻结（不影响已购用户使用策略需单独配置）

• 分类与标签管理：

- 类目（网站、人事、考勤、薪资、财务等） - 平台精选、排序权重

3.4 训练与工具治理

• 训练任务中心：

- 队列状态（queued/running/succeeded/failed/cancelled） - 失败原因聚类 - 重试与取消

• 工具/工作流白名单：

- 可用工具目录 - 工具权限策略（按模板类目或用户等级）

• 知识库内容审查（可选首期简化）：

- 上传文档类型与大小策略 - 风险内容检测结果查看

3.5 交易与结算（平台抽成 20%）

• 订单管理：

- 免费/买断/订阅订单查询 - 支付状态、授权状态、退款状态

• 分账管理：

- 订单维度拆分：gross、platform_fee(20%)、creator_income

• 结算管理：

- 创作者结算周期（周/月） - 结算单导出、对账状态

• 退款管理：

- 退款申请、审核、执行、回滚授权

3.6 风控与审计

• 操作审计日志（管理员操作全量留痕）：

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

• 风险策略：

- 恶意刷单、异常训练、违规模板发布

• 处罚与申诉：

- 封禁/解封 - 模板恢复与复核流程

3.7 运行时与模型路由运维（只读 + 受控运维）

• 运行态看板（建议指标，可分期）：

- LLM 网关：按路由/模型的 错误率、P95 延迟、429/限流命中 - 记忆检索 / 索引：重建队列、失败任务数（与 memory_search 依赖的索引一致） - 自进化后台任务（§3.6）：队列深度、成功/失败比、最近失败原因聚类

• 受控诊断动作（建议需二次确认 + 审计）：

- 触发只读 健康探针（网关、索引服务、任务队列） - 禁止在管理端执行任意 Shell；禁止直接读写用户或工作区范围内的 运行时 Workspace 落盘文件（见根 docs/产品规格.md §3.5）

3.9 智能体记忆维护（已实现）

表述：管理端查看全站个人记忆闲时整理结果，并可立刻跑一轮；不改帮助/工作区知识正本。

帮助：help/admin-ops/agent-memory-maintain.md；机制：docs/core-mechanisms/智能体记忆.md。

3.8 系统知识文档（已实现）

对应根 docs/产品规格.md 中的 全局知识文档目录：部署侧挂载的静态说明，主要供 帮助智能体（未选工作区时的消息助手）检索作答。

用户能做什么

• 在管理端打开 系统知识文档 工作区（路由 /system-knowledge），像维护「工作区知识 / 智能体知识」一样：

- 浏览文件夹与 Markdown、index.json - 新建/编辑/删除/移动文档与主题文件夹 - 用 AI 重新生成索引（两层 index.json，规则见 docs/core-mechanisms/AI重建知识索引规则.md；可选 paths 字段用于「仅在与附件/消息路径相关时注入」的条件文档，详见 help/admin-ops/system-knowledge-index.md）

• 改完正文后应重建索引，否则帮助智能体仍可能按旧摘要检索。

与主站知识分层的关系

产品说明可写在 help/knowledge-layers/ 等主题下，便于帮助智能体向用户解释三层分工。

实现对照（运维 / 对接）

• 磁盘根目录：help_docs.dir / HELP_DOCS_DIR（默认仓库 help/）；根索引文件 help_docs.index_file / HELP_DOCS_INDEX_FILE（默认 index.json）
• 索引变更指纹（可选）：{paths.runtime_dir}/help_docs/reindex_sources.sha256
• 写操作审计事件类型：admin.system_knowledge.write、admin.system_knowledge.reindex、admin.system_knowledge.reindex_fingerprint
• 对话注入：主站 POST /api/v1/chat 在帮助模式下由后端 helpdocs.BuildPrompt 检索，不经本节 API 由前端传全文

---

4. 管理端 API（建议摘要）

建议新增命名空间：/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（或 GET /admin/llm/health，命名以实现为准）
• GET /admin/runtime/metrics

4.1 已实现（早期落地）

与当前代码一致、需管理员 JWT（AuthAdmin）：

认证（已实现）：POST /admin/auth/login、/admin/auth/refresh、/admin/auth/logout。

错误与响应格式沿用现有统一规范：error/code/request_id/details 与 2xx request_id。

---

5. 页面信息架构（建议）

1. 概览（含进入 系统知识文档 的入口）
2. 用户
3. 模板审核
4. 市场运营
5. 训练中心
6. 交易订单
7. 结算分账
8. 风控审计
9. 运行时 / LLM / 索引与进化任务（运维大屏）
10. 系统设置（仅超级管理员）
11. 系统知识文档（全屏知识工作区，已实现；可从概览进入）

---

6. 非功能要求

• 安全：

- 管理员强认证（管理员账号与普通用户体系分离） - 二步验证策略：仅高权限角色强制开启（Super Admin、Finance Admin） - 敏感操作二次确认 - IP 白名单（可选）

• 审计：

- 所有管理操作必须可追溯

• 性能：

- 列表分页、筛选导出

• 可用性：

- 关键流程可回滚（下架、解封、撤销）

• 时间显示：

- 仪表盘、审计事件、运行中任务开始时间等界面时间 默认按北京时间（东八区） 展示；服务端存盘仍为 UTC（与主站 docs/产品规格.md §1.5.4 一致）。管理员端本期不单独提供时区偏好，统一北京时间。

---

7. 分期建议

P1（必须）

• RBAC（最少 Super/Ops/Review/Finance）
• 用户管理 + 模板审核 + 上下架
• 订单查询 + 分账展示（20%）
• 审计日志
• 创作者信用分（首期上线）
• 系统知识文档维护与 AI 重建索引（已实现，见 §3.8）

P2（增强）

• 训练任务运营看板
• 退款自动化与结算自动化
• 运行时与 LLM 路由深度诊断（含索引与进化任务流水线）

---

8. 已确认关键决策（逐条）

1. 管理员登录方式：分离（独立管理员账号体系）。
2. 管理员二步验证：仅高权限角色强制（Super Admin / Finance Admin）。
3. 退款策略：买断与订阅均支持退款；退款后授权保留至当前计费周期结束。
4. 模板审核 SLA：72 小时内完成审核。
5. 管理员审批流：不引入二人复核流（单人权限执行）。
6. 创作者结算周期：按月结算。
7. 创作者信用分：首期上线，用于审核优先级与市场曝光。

8.1 补充落地规则（依据已确认决策）

• 授权失效规则（退款）：

- buyout：退款后改为“周期结束失效”策略（如存在周期字段）；若无周期字段，需在订单层定义最短服务窗口后失效。 - subscription：退款后至当前结算周期结束时失效。

• 审核时限治理：

- 模板提交后进入 pending_review，系统记录 review_due_at = submitted_at + 72h。 - 仪表盘展示超时审核列表并告警。

• 信用分机制（首期）建议字段：

- credit_score（0-100） - credit_level（A/B/C） - credit_factors（通过率、违规率、用户投诉率、退款率） - 信用分影响：审核队列优先级、市场推荐权重上限。

---

9. 数据库表草案（PostgreSQL，管理员端）

说明：以下为管理员域新增/扩展表建议，可与现有业务表协同演进。

9.1 管理员账号与权限

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) // 例如 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 市场审核与运营

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 交易、分账与结算

5) orders（扩展建议）

• 新增字段：

- 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) // 用于“退款后周期结束失效”

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) // 周期结束生效
• created_at / updated_at

9.4 创作者信用分

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. 管理端 API 字段定义（/api/v1/admin/*）

统一约束：

• 鉴权：管理员 JWT（独立签发）
• 2xx 顶层包含 request_id
• 错误体：error/code/request_id/details

10.1 用户管理

1) GET /api/v1/admin/users

查询参数：

• q（邮箱/手机号/昵称模糊）
• status（active/limited/banned）
• limit、cursor

响应示意：

{
  "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

请求：

{
  "status": "banned",
  "reason": "违规上架内容",
  "ban_until": "2026-05-01T00:00:00Z"
}

10.2 系统知识文档（已实现）

鉴权：管理员 JWT。路径前缀 /api/v1/admin/system-knowledge。 请求/响应字段与工作区、智能体知识 API 对齐（items[].path、items[].dir、content 等）；仅允许 .md 与 index.json。

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

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

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

4) DELETE .../content?path=

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

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

7) GET .../reindex/preview — 响应含 top_dirs、steps_total、llm_configured、sources_unchanged_since_reindex 等

8) POST .../reindex/root | .../reindex/sub | .../reindex — 需后端已配置 LLM；成功时含 paths_written、model（分步接口另有 progress）

写操作与全量/分步重建索引会写入 admin_audit_events（见 §3.8 事件类型）。

10.3 模板审核（规划）

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

查询参数：

• status=pending_review
• risk_level（low/medium/high）
• limit、cursor

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

请求：

{
  "decision": "approve",
  "note": "内容合规，允许发布"
}

decision 取值：approve | reject

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

请求可空；后端校验模板已审核通过。

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

请求：

{
  "reason": "违规整改中"
}

10.4 订单与退款

1) GET /api/v1/admin/orders

查询参数：

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

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

请求：

{
  "decision": "approve",
  "reason": "用户申诉成立"
}

规则：

• 批准后生成/更新 refund_requests
• 授权到 billing_period_end_at 失效（周期结束生效）

10.5 结算

1) GET /api/v1/admin/settlements

查询参数：

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

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

请求：

{
  "note": "月结完成"
}

效果：

• settlement_status 从 pending -> settled
• 记录操作审计日志

10.6 风控与信用分

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

• 返回风险事件列表与处置状态

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

{
  "decision": "ban_template",
  "note": "命中高风险关键词"
}

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

• 查看创作者信用分、等级与构成因子

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

{
  "score_delta": -10,
  "reason": "连续违规驳回"
}

10.7 运行时与模型路由

1) GET /api/v1/admin/runtime/health（路径以实现为准）

• 聚合 LLM 网关可达性、关键依赖（索引/队列）健康、最近错误摘要

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

• 指标：按模型路由的请求量、P95 延迟、超时率、错误率；可选进化任务与索引任务计数

---

11. 关键业务规则（管理员端）

1. 平台抽成固定 20%，通过 order_settlements 显式落库。
2. 退款后授权“周期结束生效”，不做立即硬切。
3. 模板审核 SLA 为 72 小时，逾期必须进入告警列表。
4. 不启用二人复核流，单人权限执行，但必须记录审计日志。
5. 高权限角色必须启用 2FA。
6. 创作者信用分首期上线，并影响审核优先级与曝光权重。

---

12. 管理员账号运维脚本（已实现）

说明：以下路径以 仓库中存在 Go 后端 为前提；当前若仅保留文档，重建工程后请核对路径。

为避免“仅首次启动可初始化 super admin”的限制，后端提供管理员账号工具：

• 路径：backend/scripts/adminctl/main.go
• 作用：创建或更新管理员账号（按邮箱 upsert），支持设置角色与 2FA 开关

示例：

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

参数：

• --username（必填）
• --email（必填）
• --password（必填）
• --role：super_admin/ops_admin/review_admin/finance_admin/support_admin
• --enable-2fa：true/false

---

附录 A：日常运维（当前实现）

以下与仓库 client/admin（默认 http://localhost:3001）及 /api/v1/admin/* 一致；与 §3.8 系统知识文档、§4.1 已实现接口对齐。规划中的批量审核、CSV 导出等见正文 §3，未落地前勿按旧版 admin-web 文档操作。

A.1 访问与登录

• 前端：client/admin → npm install → npm run dev（端口 3001）
• 登录：POST /api/v1/admin/auth/login（独立管理员账号，与普通用户 JWT 不共享）
• 主站：client/web 默认 3000，登录态与端口均分离

A.2 当前可用页面

管理端登录后为 左侧导航壳：侧栏进入各页；底部可打开主站或退出。

A.3 系统知识维护

1. 登录管理端 → 侧栏 系统知识文档（或访问 /system-knowledge）。
2. 编辑 Markdown / 文件夹后，使用 「用 AI 重新生成索引」（需后端配置 LLM）。条件类文档可在索引中为条目增加 paths glob（如 **/*.tsx），详见 help/admin-ops/system-knowledge-index.md。
3. 写操作记入 admin_audit_events（admin.system_knowledge.*）。

发版 / 改 help 后：按 help/admin-ops/system-knowledge-index.md 末尾 检查清单 执行——至少 强制重新生成索引 一次，并用帮助智能体抽问验证。

A.4 常见问题

• 401：管理员 token 过期 → 重新登录。
• 帮助智能体仍答旧内容：确认已重建 help/ 下 index.json，且 help_docs.dir 指向正确目录。
• 某篇条件文档从不出现：若索引含 paths，需用户消息或附件路径命中才会注入；通用材料勿填 paths。
• LLM 索引失败：检查 OPENAI_API_KEY 等配置（与主站智能体对话相同网关）。