cunkebao_v3/SuperAdmin/lib/api-docs-index.ts

/**
 * AI 中心 · 接口文档 Tab 静态索引（§2.8）
 *
 * MD 真源：开发文档/5、接口/SuperAdmin_四端对接接口索引.md（9 类 · 含官网对外）
 * 路由/接口变更时只改 MD 真源 + route.php，再同步本文件（§2.8.5 D5）。
 */

export interface ApiEndpoint {
  /** 域：如「客户池」「设备」「AI 协助」 */
  domain: string;
  method: string;
  path: string;
  /** 鉴权：JWT / X-API-KEY / 签名 */
  auth: string;
  /** 摘要 */
  desc?: string;
}

export interface ApiDocCategory {
  id: string;
  /** 分类名 */
  name: string;
  /** 消费端 */
  consumer: string;
  /** Base URL */
  baseUrl: string;
  /** 鉴权方式说明 */
  authNote: string;
  /** 完整文档链接（仓库相对路径或 URL） */
  docs: { label: string; href: string }[];
  /** 摘要表（每类最少展示，§2.8.4） */
  endpoints: ApiEndpoint[];
}

/** 对接铁律（§2.8.5 D3 顶栏固定展示） */
export const DOCS_RULES = [
  "只对接 HTTP 接口，不改兄弟仓库业务代码",
  "设备写操作走 /v1/workphone/*；业务 URL 不变",
  "Webhook / 全局配置按 companyId 隔离，跨公司客资绝不推送",
];

/** 超管 Token 说明（§2.8.5 D3） */
export const SUPERADMIN_TOKEN_NOTE =
  "超管 BFF 全部走 JWT：登录 /v1/admin/auth/login 取 token，后续请求 Header: Authorization: Bearer <token>";

export const API_DOC_CATEGORIES: ApiDocCategory[] = [
  {
    id: "superadmin",
    name: "超管 BFF",
    consumer: "SuperAdmin 3103",
    baseUrl: "/api/v1/admin（反代 cunkebao-server）",
    authNote: "JWT · Authorization: Bearer <token>",
    docs: [
      { label: "SuperAdmin开放API_20260528.md", href: "../../5、接口/SuperAdmin开放API_20260528.md" },
      { label: "SuperAdmin_四端对接接口索引.md", href: "../../5、接口/SuperAdmin_四端对接接口索引.md" },
    ],
    endpoints: [
      { domain: "鉴权", method: "POST", path: "/v1/admin/auth/login", auth: "公开", desc: "管理员登录取 JWT" },
      { domain: "仪表盘", method: "GET", path: "/v1/admin/dashboard/overview", auth: "JWT", desc: "平台 KPI 总览" },
      { domain: "项目管理", method: "GET", path: "/v1/admin/company/list", auth: "JWT", desc: "项目（公司）列表" },
      { domain: "项目工作台", method: "GET", path: "/v1/admin/project/workspace/:id", auth: "JWT", desc: "项目工作台只读 BFF" },
      { domain: "设备", method: "GET", path: "/v1/admin/devices/list", auth: "JWT", desc: "全平台设备（按项目分组）" },
      { domain: "客户池", method: "GET", path: "/v1/admin/trafficPool/list", auth: "JWT", desc: "全平台客资" },
      { domain: "客户池", method: "POST", path: "/v1/admin/trafficPool/migrate", auth: "JWT", desc: "客资批量迁移" },
      { domain: "内容库", method: "GET", path: "/v1/admin/content-library/grouped", auth: "JWT", desc: "全平台内容库（按项目分组）" },
      { domain: "算力", method: "GET", path: "/v1/admin/power-billing/settings", auth: "JWT", desc: "兑换比例" },
      { domain: "AI 中心", method: "GET", path: "/v1/admin/ai-center/config", auth: "JWT", desc: "AI 接口配置（脱敏）" },
      { domain: "AI 中心", method: "POST", path: "/v1/admin/ai-center/providers", auth: "JWT", desc: "新增提供商" },
      { domain: "工作手机方案", method: "GET", path: "/v1/admin/company/workphone-provider", auth: "JWT", desc: "项目对接方案 A/B" },
    ],
  },
  {
    id: "cunkebao",
    name: "存客宝 H5",
    consumer: "Cunkebao 3100",
    baseUrl: "/api（反代 cunkebao-server :8082）",
    authNote: "JWT（用户登录态）",
    docs: [
      { label: "存客宝API全量索引.md", href: "../../5、接口/存客宝API全量索引.md" },
      { label: "03-业务板块接口/", href: "../../5、接口/03-业务板块接口/README.md" },
    ],
    endpoints: [
      { domain: "算力", method: "GET", path: "/v1/tokens/rules", auth: "JWT", desc: "扣费目录与余额" },
      { domain: "内容库", method: "GET", path: "/v1/content-library/list", auth: "JWT", desc: "内容库条目" },
      { domain: "场景获客", method: "GET", path: "/v1/plan/list", auth: "JWT", desc: "获客计划" },
    ],
  },
  {
    id: "touchkebao",
    name: "触客宝 PC",
    consumer: "Touchkebao 3101",
    baseUrl: "/api（反代 cunkebao-server :8082 · chukebao 模块）",
    authNote: "JWT（坐席登录态）",
    docs: [
      { label: "触客宝PC接口对接索引.md", href: "../../5、接口/02-存客宝对接/触客宝PC接口对接索引.md" },
    ],
    endpoints: [
      { domain: "AI 协助", method: "POST", path: "/v1/kefu/ai/assist", auth: "JWT", desc: "AI 候选回复（走 AI Gateway）" },
      { domain: "AI 聊天", method: "POST", path: "/v1/kefu/ai/chat", auth: "JWT", desc: "AI 客服对话" },
      { domain: "快捷语", method: "GET", path: "/v1/kefu/quick-reply/list", auth: "JWT", desc: "快捷语库" },
    ],
  },
  {
    id: "aistaff",
    name: "AI数智员工",
    consumer: "3104",
    baseUrl: "经存客宝 BFF / 开放 API",
    authNote: "JWT / X-API-KEY",
    docs: [
      { label: "AI数智员工 · 12-接口", href: "AI数智员工/开发文档/5、接口/" },
      { label: "13-BFF · 14-终端", href: "AI数智员工/开发文档/5、接口/" },
    ],
    endpoints: [
      { domain: "数智员工", method: "POST", path: "/v1/ai/chat/completions", auth: "JWT", desc: "经 AI Gateway 统一出口" },
    ],
  },
  {
    id: "open",
    name: "开放对接",
    consumer: "第三方",
    baseUrl: "/api（开放平台域）",
    authNote: "X-API-KEY + 签名",
    docs: [
      { label: "08-存客宝开放对接平台/", href: "../../5、接口/08-存客宝开放对接平台/README.md" },
      { label: "对外获客与开放接口.md", href: "../../5、接口/对外获客与开放接口.md" },
    ],
    endpoints: [
      { domain: "线索获客", method: "POST", path: "/v1/open/lead/push", auth: "X-API-KEY + 签名", desc: "第三方推送线索" },
    ],
  },
  {
    id: "tokens",
    name: "算力 · 计费",
    consumer: "四端",
    baseUrl: "/api · /v1/admin/power-billing",
    authNote: "JWT",
    docs: [
      { label: "存客宝_进行中 §六", href: "../1、需求/修改/存客宝_进行中_20260530.md" },
    ],
    endpoints: [
      { domain: "扣费规则", method: "GET", path: "/v1/tokens/rules", auth: "JWT", desc: "全平台扣费目录" },
      { domain: "扣费配置", method: "PUT", path: "/v1/admin/power-billing/catalog/:slug", auth: "JWT", desc: "改单价即时生效" },
    ],
  },
  {
    id: "gateway",
    name: "AI Gateway",
    consumer: "四端 AI",
    baseUrl: "/api/v1/ai",
    authNote: "JWT（内网/各端只读 config 脱敏）",
    docs: [
      { label: "本文 §2.5", href: "../1、需求/修改/SuperAdmin_进行中_20260530.md" },
    ],
    endpoints: [
      { domain: "网关配置", method: "GET", path: "/v1/ai/gateway/config", auth: "JWT", desc: "脱敏配置（不含 Key）" },
      { domain: "统一补全", method: "POST", path: "/v1/ai/chat/completions", auth: "JWT", desc: "slug / tier? / messages[] / companyId" },
    ],
  },
  {
    id: "workphone",
    name: "工作手机 BFF",
    consumer: "设备控制",
    baseUrl: "/api/v1/workphone",
    authNote: "JWT + 项目对接方案 A/B（companyId 路由）",
    docs: [
      { label: "02-存客宝与工作手机对接/", href: "../../5、接口/02-存客宝与工作手机对接/README.md" },
      { label: "06-映射总表", href: "../../5、接口/02-存客宝与工作手机对接/06-业务接口与工作手机一对一映射总表.md" },
    ],
    endpoints: [
      { domain: "设备同步", method: "POST", path: "/v1/admin/devices/sync", auth: "JWT", desc: "委托 Adapter（方案 A SDK / 方案 B S2）" },
      { domain: "对接方案", method: "POST", path: "/v1/admin/company/workphone-provider", auth: "JWT", desc: "按项目切 A/B" },
    ],
  },
  {
    id: "official-site",
    name: "官网对外留资",
    consumer: "官网 / 落地页 / AI 生成站",
    baseUrl: "https://ckbapi.quwanzhi.com（生产）",
    authNote: "apiKey + sign + timestamp（planId 779 · 不参与签名：portrait）",
    docs: [
      {
        label: "07-官网统一留资接口_20260531.md",
        href: "../1、需求/官网/07-官网统一留资接口_20260531.md",
      },
      {
        label: "10-官网对外接口文档_20260531.md",
        href: "../1、需求/官网/10-官网对外接口文档_20260531.md",
      },
      { label: "对外获客与开放接口.md", href: "../../5、接口/对外获客与开放接口.md" },
    ],
    endpoints: [
      {
        domain: "官网留资",
        method: "POST",
        path: "/v1/api/scenarios",
        auth: "apiKey + sign",
        desc: "唯一留资入口；tags/siteTags 自动打标；重复手机号合并 siteTags",
      },
      {
        domain: "鉴权说明",
        method: "—",
        path: "sign = MD5(MD5(排序值拼接) + apiKey)",
        auth: "timestamp ±300s",
        desc: "intent: trial|consult|basic|pro|enterprise",
      },
    ],
  },
];