{"openapi":"3.1.0","info":{"title":"HeHe App API","version":"1.0.0","description":"HeHe 应用全量 API 文档 — 涵盖认证、支付、商品、任务、营销活动、存储及管理端接口。"},"servers":[{"url":"http://localhost","description":"Local Development Server","variables":{}}],"paths":{"":{"get":{"tags":["App Routes"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/api/admin/analytics/config":{"get":{"tags":["管理·系统-分析"],"parameters":[],"responses":{"200":{"description":"完整埋点配置"},"403":{"description":"非管理员"}},"summary":"管理员：获取多平台埋点完整配置","description":"返回全局 GA4 / Meta Pixel / TikTok Pixel 配置的完整内容，包括各端开关和像素 ID，供管理后台表单回显。","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·系统-分析"],"parameters":[],"responses":{"200":{"description":"配置已更新"},"400":{"description":"参数校验失败"},"403":{"description":"非管理员"}},"summary":"管理员：更新多平台埋点配置","description":"更新全局 GA4 / Meta Pixel / TikTok Pixel 的像素 ID 及各端开关，立即生效。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"isEnabled":{"type":"boolean","description":"全局埋点总开关"},"enableClient":{"type":"boolean","description":"官网端开关"},"enableH5":{"type":"boolean","description":"营销 H5 端开关"},"enableAdmin":{"type":"boolean","description":"管理后台端开关"},"gaMeasurementId":{"type":"string","description":"GA4 衡量 ID（如 G-XXXXXXXXXX）"},"metaPixelId":{"type":"string","description":"Meta (Facebook) Pixel ID"},"tiktokPixelId":{"type":"string","description":"TikTok Pixel ID"}}}}}}}},"/api/admin/apm/simulate":{"post":{"tags":["管理·系统-监控"],"parameters":[],"responses":{"200":{"description":"模拟警报已记录"}},"summary":"管理员：模拟 APM 警报","description":"触发测试警报以验证警报管线（Warning 800ms / Critical 2000ms）。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"level":{"type":"string","enum":["warning","critical"],"default":"warning"},"message":{"type":"string"}}}}}}}},"/api/admin/apm/stats":{"get":{"tags":["管理·系统-监控"],"parameters":[],"responses":{"200":{"description":"APM 统计对象"}},"summary":"管理员：获取 APM 统计数据","description":"返回内存中的 APM 指标（请求数、延迟百分位、警报）。","security":[{"BearerAuth":[]}]}},"/api/admin/audit-logs/archive":{"post":{"tags":["管理·运营-审计"],"parameters":[],"responses":{"200":{"description":"归档操作执行完毕，返回清理的日志条数和备份文件名"},"401":{"description":"鉴权失败"}},"summary":"管理员/定时器：冷热归档审计日志","description":"打包 90 天之前的审计日志并将其归档上传到 Supabase Storage 私有桶，然后物理清理原表数据。","security":[{"BearerAuth":[]}]}},"/api/admin/audit-logs/export":{"get":{"tags":["管理·系统-审计"],"parameters":[{"in":"query","name":"category","schema":{"type":"string"},"description":"筛选类别（ALL 为全部）"},{"in":"query","name":"dateFrom","schema":{"type":"string","format":"date"},"description":"起始日期 (YYYY-MM-DD)"},{"in":"query","name":"dateTo","schema":{"type":"string","format":"date"},"description":"结束日期 (YYYY-MM-DD)"}],"responses":{"200":{"description":"CSV 文件下载"}},"summary":"管理员：导出审计日志（CSV）","description":"导出符合条件的全部审计日志为 CSV 文件。支持按类别和日期范围筛选。","security":[{"BearerAuth":[]}]}},"/api/admin/audit-logs":{"get":{"tags":["管理·系统-审计"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"},{"in":"query","name":"category","schema":{"type":"string"},"description":"筛选类别（ALL 为全部）"},{"in":"query","name":"dateFrom","schema":{"type":"string","format":"date"},"description":"起始日期 (YYYY-MM-DD)"},{"in":"query","name":"dateTo","schema":{"type":"string","format":"date"},"description":"结束日期 (YYYY-MM-DD)"}],"responses":{"200":{"description":"分页活动日志列表（含总数）"}},"summary":"管理员：获取活动日志（分页）","description":"返回所有活动日志条目（分页，按 created_at 降序排列）。支持按类别和日期范围筛选。","security":[{"BearerAuth":[]}]}},"/api/admin/audit-logs/stats":{"get":{"tags":["管理·系统-审计"],"parameters":[{"in":"query","name":"category","schema":{"type":"string"},"description":"筛选类别（ALL 为全部）"},{"in":"query","name":"dateFrom","schema":{"type":"string","format":"date"},"description":"起始日期 (YYYY-MM-DD)"},{"in":"query","name":"dateTo","schema":{"type":"string","format":"date"},"description":"结束日期 (YYYY-MM-DD)"}],"responses":{"200":{"description":"聚合统计数据"}},"summary":"管理员：获取审计日志聚合统计","description":"根据筛选条件返回全量的分类分布、活跃用户 Top 5、今日操作数和总日志数。","security":[{"BearerAuth":[]}]}},"/api/admin/auth/2fa/disable":{"post":{"tags":["管理·安全-2FA"],"parameters":[],"responses":{"200":{"description":"2FA 已关闭"}},"summary":"管理员：关闭 2FA","description":"关闭双因素认证。需要提供当前有效的 TOTP 验证码或备用恢复码。","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"TOTP 6 位验证码或 4 位备用恢复码"}}}}}}}},"/api/admin/auth/2fa/setup":{"post":{"tags":["管理·安全-2FA"],"parameters":[],"responses":{"200":{"description":"包含 secret、qrCode (data URI) 和 backupCodes"}},"summary":"管理员：设置 2FA（生成密钥与 QR Code）","description":"生成 TOTP 密钥、QR Code（data URI）和备用恢复码。第一次调用会覆盖之前未验证的密钥。","security":[{"BearerAuth":[]}]}},"/api/admin/auth/2fa/status":{"get":{"tags":["管理·安全-2FA"],"parameters":[],"responses":{"200":{"description":"2FA 状态信息"}},"summary":"管理员：获取 2FA 状态","description":"返回当前管理员的 2FA 启用状态和验证时间。不会返回密钥。","security":[{"BearerAuth":[]}]}},"/api/admin/auth/2fa/verify":{"post":{"tags":["管理·安全-2FA"],"parameters":[],"responses":{"200":{"description":"2FA 已启用"}},"summary":"管理员：验证并启用 2FA","description":"验证 TOTP 验证码，通过后启用 2FA。验证码错误达 5 次则拒绝。","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"6 位 TOTP 验证码"}}}}}}}},"/api/admin/campaigns/{subdomain}":{"delete":{"tags":["管理·营销-活动"],"parameters":[{"in":"path","name":"subdomain","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"删除成功"},"401":{"description":"未授权"},"404":{"description":"活动不存在"}},"summary":"管理员：删除营销活动","description":"删除指定 subdomain 的营销活动及其关联留资记录（级联）。","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·营销-活动"],"parameters":[{"in":"path","name":"subdomain","required":true,"schema":{"type":"string"},"description":"营销活动子域名"}],"responses":{"200":{"description":"营销活动已更新"}},"summary":"管理员：更新营销活动配置（全字段）","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"subtitle":{"type":"string"},"badge":{"type":"string"},"is_active":{"type":"boolean"},"cta_text":{"type":"string"},"cta_url":{"type":"string","nullable":true},"sort_order":{"type":"integer"},"color_from":{"type":"string"},"color_to":{"type":"string"},"description":{"type":"string","nullable":true}}}}}}}},"/api/admin/campaigns/{subdomain}/status":{"patch":{"tags":["管理·营销-活动"],"parameters":[{"in":"path","name":"subdomain","required":true,"schema":{"type":"string"},"description":"营销活动子域名"}],"responses":{"200":{"description":"活动状态已切换"}},"summary":"管理员：切换营销活动上下线状态","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_active":{"type":"boolean"}},"required":["is_active"]}}}}}},"/api/admin/campaigns":{"get":{"tags":["管理·营销-活动"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":5},"description":"每页条数（最大 100）"}],"responses":{"200":{"description":"分页营销活动列表（含 leads_count 与总数）"}},"summary":"管理员：获取所有营销活动（分页，含留资统计）","security":[{"BearerAuth":[]}]},"post":{"tags":["管理·营销-活动"],"parameters":[],"responses":{"200":{"description":"新建成功，返回创建的活动"},"400":{"description":"参数校验失败或 subdomain 重复"},"401":{"description":"未授权"}},"summary":"管理员：新建营销活动","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subdomain","title","subtitle","badge"],"properties":{"subdomain":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"subtitle":{"type":"string","minLength":1},"badge":{"type":"string","minLength":1},"color_from":{"type":"string"},"color_to":{"type":"string"},"cta_text":{"type":"string"},"cta_url":{"type":"string","nullable":true},"cover_image":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"sort_order":{"type":"integer","minimum":0}}}}}}}},"/api/admin/campaigns/leads/{id}":{"delete":{"tags":["管理·营销-活动"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"留资记录 ID"}],"responses":{"200":{"description":"删除成功"},"401":{"description":"未授权"}},"summary":"管理员：删除特定营销留资预约记录","description":"通过记录 ID 删除一条营销活动留资记录，仅限管理员访问。","security":[{"BearerAuth":[]}]}},"/api/admin/campaigns/leads/export":{"get":{"tags":["管理·营销-活动"],"parameters":[{"in":"query","name":"subdomain","required":false,"schema":{"type":"string"},"description":"活动子域名过滤"}],"responses":{"200":{"description":"CSV 文件流","content":{"text/csv":{}}},"401":{"description":"未授权"}},"summary":"管理员：导出营销留资 CSV","description":"按 subdomain 过滤导出留资记录为 CSV 文件（UTF-8 BOM），不传 subdomain 则导出全量。","security":[{"BearerAuth":[]}]}},"/api/admin/campaigns/leads":{"get":{"tags":["管理·营销-活动"],"parameters":[{"in":"query","name":"subdomain","required":false,"schema":{"type":"string"},"description":"活动子域名过滤"}],"responses":{"200":{"description":"返回留资记录列表"},"401":{"description":"未授权"}},"summary":"管理员：获取所有营销活动预约留资记录","description":"获取全量营销留资记录，支持按子域名过滤，仅限管理员访问。","security":[{"BearerAuth":[]}]}},"/api/admin/config/notifications":{"get":{"tags":["管理端配置"],"parameters":[],"responses":{"200":{"description":"通知网关配置"}},"summary":"获取通知告警机器人配置","description":"管理员可用此端点获取当前的飞书/钉钉/企业微信/Slack 通知机器人 Webhook 链接及事件绑定。","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理端配置"],"parameters":[],"responses":{"200":{"description":"通知配置保存成功"}},"summary":"更新通知告警机器人配置","description":"管理员可用此端点设置飞书/钉钉/企业微信/Slack 机器人 Webhook 地址以及订阅事件源，用于支付、系统与安全告警通知。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["feishu","wechat","dingtalk","slack"]},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"isEnabled":{"type":"boolean"}},"required":["platform","url","events","isEnabled"]}}}}}}},"/api/admin/config/payment":{"get":{"tags":["管理端配置"],"parameters":[],"responses":{"200":{"description":"支付网关配置列表"}},"summary":"获取支付通道公私钥配置","description":"管理员可用此端点获取所有支付通道的启用状态、前端公钥以及脱敏掩码后的私有密钥。","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理端配置"],"parameters":[],"responses":{"200":{"description":"支付网关配置更新成功"}},"summary":"修改特定支付通道的公私钥配置","description":"管理员可用此端点启用/禁用支付提供商，或修改其相关公钥、私密密钥。对于未修改的私钥字段，请传入掩码值（包含*）以防覆盖。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"isEnabled":{"type":"boolean"},"publicKeys":{"type":"object"},"extraMeta":{"type":"object"},"secrets":{"type":"object"}},"required":["provider","isEnabled"]}}}}}},"/api/admin/config/payment/test-connection":{"post":{"tags":["Admin Config"],"parameters":[],"responses":{"200":{"description":"Connection test result"}},"summary":"Test payment provider connection","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"stripe | paypal | google_pay | apple_iap"}},"required":["provider"]}}}}}},"/api/admin/config/status":{"get":{"tags":["管理·系统-监控"],"parameters":[],"responses":{"200":{"description":"系统状态对象","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"services":{"type":"object","properties":{"database":{"type":"object","properties":{"status":{"type":"string"},"latency_ms":{"type":"number"}}},"storage":{"type":"object","properties":{"status":{"type":"string"},"latency_ms":{"type":"number"}}}}},"runtime":{"type":"object","properties":{"node_version":{"type":"string"},"platform":{"type":"string"},"uptime_seconds":{"type":"integer"},"mock_db":{"type":"boolean"}}},"env_config":{"type":"object"}}}}}}}}},"summary":"管理员：获取系统配置与服务健康状态","description":"返回数据库连接状态、Storage 可用性、Node.js 运行时信息及环境变量配置状态（不暴露实际值）。","security":[{"BearerAuth":[]}]}},"/api/admin/orders/{id}":{"patch":{"tags":["管理·运营-订单"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"订单 ID"}],"responses":{"200":{"description":"订单已更新"},"404":{"description":"订单未找到"}},"summary":"管理员：更新订单状态","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","paid","failed","refunded"]}}}}}}}},"/api/admin/orders/%5Bid%5D/refund":{"post":{"tags":["管理端订单"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"订单 ID (UUID)"}],"responses":{"200":{"description":"退款与降级成功完成"},"400":{"description":"订单不满足退款条件"},"404":{"description":"订单未找到"}},"summary":"管理员订单退款与降级（支持部分退款）","description":"管理员可用此端点对已付（paid）订单发起全额或部分退款。如果是周期性计费订阅，全额退款时同步取消 Stripe 的订阅合同并将用户 Profiles 降级为 free 级别。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refundAmount":{"type":"number","minimum":0.01,"description":"部分退款金额，不传则全额退款"}}}}}}}},"/api/admin/orders/%5Bid%5D/transactions":{"get":{"tags":["Admin Orders"],"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"Order UUID"}],"responses":{"200":{"description":"Transaction history list"}},"summary":"Get payment transaction history for a specific order","security":[{"BearerAuth":[]}]}},"/api/admin/orders/export":{"get":{"tags":["管理·运营-订单"],"parameters":[{"in":"query","name":"status","schema":{"type":"string"},"description":"按订单状态过滤"}],"responses":{"200":{"description":"CSV 文件下载"}},"summary":"管理员：导出订单 CSV","description":"将当前筛选条件下的订单列表导出为 CSV 文件（最多 10000 条）。","security":[{"BearerAuth":[]}]}},"/api/admin/orders":{"get":{"tags":["管理·运营-订单"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"},{"in":"query","name":"status","schema":{"type":"string"},"description":"按订单状态过滤"}],"responses":{"200":{"description":"分页订单列表（含总数）"}},"summary":"管理员：获取订单列表（分页）","security":[{"BearerAuth":[]}]}},"/api/admin/products/%5Bid%5D":{"delete":{"tags":["管理端商品"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"商品 ID (UUID)"}],"responses":{"200":{"description":"商品操作完成"},"404":{"description":"商品未找到"}},"summary":"管理员删除商品（软删除保护）","description":"删除商品前检查关联订单。有订单时仅设 is_active=false + archived_at；无订单时物理删除。","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理端商品"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"商品 ID (UUID)"}],"responses":{"200":{"description":"商品信息更新成功"},"404":{"description":"商品未找到"}},"summary":"管理员修改商品信息与上下架","description":"管理员可用此端点修改已有商品的名称、价格、支付映射数据以及是否在售（上下架）状态。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number","minimum":0},"paymentMeta":{"type":"object"},"isActive":{"type":"boolean"}}}}}}}},"/api/admin/products":{"post":{"tags":["管理端商品"],"parameters":[],"responses":{"201":{"description":"商品创建成功"}},"summary":"管理员创建商品","description":"管理员可用此端点在平台全局商品目录中新增商品，并绑定 Stripe Price ID 等支付元数据。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"paymentMeta":{"type":"object"}},"required":["name","price"]}}}}}},"/api/admin/products/sync-stripe":{"post":{"tags":["管理端商品"],"parameters":[],"responses":{"200":{"description":"同步商品目录成功"}},"summary":"管理员同步 Stripe 商品目录","description":"管理员可用此端点连接 Stripe API 拉取最新活跃产品及价格映射，自动导入/更新到本地商品库中。","security":[{"BearerAuth":[]}]}},"/api/admin/profile/password":{"patch":{"tags":["管理·系统-个人"],"parameters":[],"responses":{"200":{"description":"密码更新成功"}},"summary":"管理员：修改密码","description":"通过 Supabase Admin API 更新管理员密码。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"}},"required":["password"]}}}}}},"/api/admin/revenue":{"get":{"tags":["管理·运营-收入"],"parameters":[{"in":"query","name":"days","schema":{"type":"integer","default":30},"description":"回溯天数（最大 365）"}],"responses":{"200":{"description":"收入分析：totalPaymentRevenue、totalRevenue、dailyBreakdown"}},"summary":"管理员：收入分析","description":"支付收入数据分析，包含每日明细与收入快照。","security":[{"BearerAuth":[]}]}},"/api/admin/security/keys/{id}":{"delete":{"tags":["管理·系统-安全"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API Key 已吊销"},"403":{"description":"非管理员"},"404":{"description":"API Key 不存在"}},"summary":"管理员：吊销 API Key（物理删除）","security":[{"BearerAuth":[]}]},"get":{"tags":["Admin Security"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API Key 详情（脱敏）"},"403":{"description":"非管理员"},"404":{"description":"API Key 不存在"}},"summary":"管理员：查看单个 API Key 详情","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·系统-安全"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API Key 已更新"},"400":{"description":"参数校验失败"},"403":{"description":"非管理员"},"404":{"description":"API Key 不存在"}},"summary":"管理员：更新 API Key 配置","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"allowed_endpoints":{"type":"array","items":{"type":"string"},"nullable":true},"rate_limit_override":{"type":"integer","nullable":true},"require_signature":{"type":"boolean"},"is_active":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"/api/admin/security/keys/batch-revoke":{"post":{"tags":["Admin Security"],"parameters":[],"responses":{"200":{"description":"批量吊销结果"},"400":{"description":"参数校验失败"},"403":{"description":"非管理员"}},"summary":"管理员：批量吊销 API Key","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100}}}}}}}},"/api/admin/security/keys":{"get":{"tags":["管理·系统-安全"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"API Key 分页列表（仅展示 key_prefix，不暴露原文）"},"403":{"description":"非管理员"}},"summary":"管理员：列出所有 API Key（脱敏，分页 + 搜索）","security":[{"BearerAuth":[]}]},"post":{"tags":["管理·系统-安全"],"parameters":[],"responses":{"200":{"description":"API Key 已创建（一次性返回明文）"},"400":{"description":"参数校验失败"},"403":{"description":"非管理员"}},"summary":"管理员：创建 API Key（一次性返回明文）","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"allowed_endpoints":{"type":"array","items":{"type":"string"},"nullable":true},"rate_limit_override":{"type":"integer","nullable":true},"require_signature":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}}}},"/api/admin/security/logs":{"get":{"tags":["管理·系统-安全"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":30}},{"name":"eventType","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"安全事件日志分页列表"},"403":{"description":"非管理员"}},"summary":"管理员：查询安全事件日志（分页 + 筛选）","security":[{"BearerAuth":[]}]}},"/api/admin/security/logs/{id}":{"get":{"tags":["Admin Security"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"安全日志详情"},"403":{"description":"非管理员"},"404":{"description":"日志不存在"}},"summary":"管理员：查看单条安全日志详情","security":[{"BearerAuth":[]}]}},"/api/admin/security/logs/export":{"get":{"tags":["Admin Security"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"],"default":"csv"}},{"name":"eventType","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"导出文件"},"403":{"description":"非管理员"}},"summary":"管理员：导出安全日志（CSV / JSON）","security":[{"BearerAuth":[]}]}},"/api/admin/security/overview":{"get":{"tags":["Admin Security"],"parameters":[],"responses":{"200":{"description":"安全概览聚合数据"}},"summary":"安全概览聚合","description":"返回安全评分、拦截统计、API Key 状态、近期威胁等聚合数据"}},"/api/admin/security/policy":{"get":{"tags":["管理·系统-安全"],"parameters":[],"responses":{"200":{"description":"当前安全策略配置（含缓存状态）"},"403":{"description":"非管理员"}},"summary":"管理员：读取 API 安全策略配置","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·系统-安全"],"parameters":[],"responses":{"200":{"description":"策略已更新"},"400":{"description":"参数校验失败"},"403":{"description":"非管理员"}},"summary":"管理员：更新 API 安全策略配置","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rate_limit":{"type":"object"},"ip_policy":{"type":"object"},"country_policy":{"type":"object"},"signature_required":{"type":"boolean"},"endpoint_overrides":{"type":"object"}}}}}}}},"/api/admin/starpath/answers/{id}":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Session ID"}],"responses":{"200":{"description":"Session 详情 + 答案列表"},"404":{"description":"Session 不存在"}},"summary":"获取单个 智能问卷 问卷 session 详情（含所有答案）","description":"管理员查看指定 session 的完整问卷答案和进度。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/answers":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20}},{"in":"query","name":"status","schema":{"type":"string"},"description":"started | in_progress | completed | abandoned"},{"in":"query","name":"search","schema":{"type":"string"},"description":"搜索 session_key 或 full_name"}],"responses":{"200":{"description":"分页 session 列表（含答案统计）"}},"summary":"获取 智能问卷 问卷答案（分页 + Session 聚合）","description":"管理员查看所有 智能问卷 问卷 session，支持按状态和搜索过滤。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/emails":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20}},{"in":"query","name":"search","schema":{"type":"string"},"description":"搜索邮箱地址"}],"responses":{"200":{"description":"分页邮箱列表"}},"summary":"获取 智能问卷 留资邮箱（分页）","description":"管理员查看所有 智能问卷 用户留资邮箱（来自 campaign_registrations），支持搜索和导出。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/export":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"query","name":"type","required":true,"schema":{"type":"string","enum":["answers","emails"]},"description":"导出类型"}],"responses":{"200":{"description":"CSV 文本数据"}},"summary":"导出 智能问卷 数据为 CSV","description":"导出问卷答案或邮箱留资为 CSV 格式。type=answers|emails。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/orders":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"Page number"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"Items per page (max 100)"},{"in":"query","name":"provider","schema":{"type":"string"},"description":"Filter by payment provider"},{"in":"query","name":"status","schema":{"type":"string"},"description":"Filter by order status"}],"responses":{"200":{"description":"Paginated 智能问卷 orders list"}},"summary":"Admin: list 智能问卷-specific orders","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/overview":{"get":{"tags":["Admin 智能问卷"],"parameters":[],"responses":{"200":{"description":"概览统计数据"}},"summary":"获取 智能问卷 概览数据","description":"总会话数、完成率、报告数、留资数等核心指标。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/reports":{"get":{"tags":["Admin 智能问卷"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20}},{"in":"query","name":"status","schema":{"type":"string"},"description":"pending | generating | completed | failed"}],"responses":{"200":{"description":"分页报告列表"}},"summary":"获取 AI 占星报告（分页）","description":"管理员查看所有已生成的 智能问卷 AI 报告，支持状态过滤。","security":[{"BearerAuth":[]}]}},"/api/admin/starpath/reports/trigger":{"post":{"tags":["Admin 智能问卷"],"parameters":[],"responses":{"200":{"description":"报告生成请求已提交（pending 状态）"},"404":{"description":"Session 不存在"}},"summary":"手动触发 AI 报告生成","description":"管理员手动为指定 session 触发生成占星报告。","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string"}}}}}}}},"/api/admin/storage/batch-delete":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"批量删除结果"},"400":{"description":"参数错误"},"403":{"description":"非管理员"}},"summary":"管理员：批量删除媒体库文件","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["bucket","paths"],"properties":{"bucket":{"type":"string","enum":["avatars","campaign-assets","uploads"],"description":"目标 Bucket"},"paths":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"文件路径列表（最多 50 个）"}}}}}}}},"/api/admin/storage/buckets":{"get":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"桶列表 + 文件统计"},"403":{"description":"非管理员"}},"summary":"管理员：列出所有存储桶（系统 + 自定义）","security":[{"BearerAuth":[]}]},"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"创建成功"},"400":{"description":"参数错误"},"403":{"description":"非管理员"},"409":{"description":"桶已存在"}},"summary":"管理员：创建自定义存储桶","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9-]{2,49}$","description":"桶名（slug 格式）"},"public":{"type":"boolean","default":false},"maxSize":{"type":"integer","default":52428800,"description":"单文件大小限制（bytes）"},"allowedMime":{"type":"array","items":{"type":"string"},"description":"允许的 MIME 类型"}}}}}}}},"/api/admin/storage/buckets/{name}":{"delete":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"},"description":"桶名"}],"responses":{"200":{"description":"删除成功"},"403":{"description":"非管理员或系统桶"},"409":{"description":"桶非空"}},"summary":"管理员：删除自定义存储桶（必须为空）","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"path","name":"name","required":true,"schema":{"type":"string"},"description":"桶名"}],"responses":{"200":{"description":"更新成功"},"403":{"description":"非管理员或系统桶"}},"summary":"管理员：更新自定义存储桶配置","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"public":{"type":"boolean"},"maxSize":{"type":"integer"},"allowedMime":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/admin/storage":{"get":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"query","name":"bucket","required":true,"schema":{"type":"string","enum":["avatars","campaign-assets","uploads"]},"description":"目标 Bucket"},{"in":"query","name":"prefix","schema":{"type":"string","default":""},"description":"目录前缀（文件夹导航）"},{"in":"query","name":"limit","schema":{"type":"integer","default":40},"description":"每页条数（最大 100）"},{"in":"query","name":"offset","schema":{"type":"integer","default":0},"description":"分页偏移"},{"in":"query","name":"search","schema":{"type":"string"},"description":"文件名模糊搜索（Supabase 原生）"},{"in":"query","name":"kind","schema":{"type":"string","enum":["image","video","audio","document","other"]},"description":"按文件类型筛选"},{"in":"query","name":"sort","schema":{"type":"string","enum":["updated_at","created_at","name"],"default":"updated_at"},"description":"排序字段"},{"in":"query","name":"order","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"排序方向"}],"responses":{"200":{"description":"文件列表 + 存储统计"},"400":{"description":"参数错误"},"403":{"description":"非管理员"}},"summary":"管理员：获取媒体库文件列表（分页/搜索/筛选）","security":[{"BearerAuth":[]}]}},"/api/admin/storage/move":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"移动成功"},"400":{"description":"参数错误"},"403":{"description":"非管理员"}},"summary":"管理员：移动/重命名文件（支持批量）","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["bucket"],"properties":{"bucket":{"type":"string","description":"源桶名"},"fromPath":{"type":"string","description":"源路径（单文件模式）"},"toPath":{"type":"string","description":"目标路径（单文件模式）"},"items":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"description":"批量移动列表"}}}}}}}},"/api/admin/storage/trash/{id}":{"delete":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"回收站记录 ID"}],"responses":{"200":{"description":"永久删除成功"},"404":{"description":"记录不存在"}},"summary":"管理员：永久删除回收站文件","security":[{"BearerAuth":[]}]}},"/api/admin/storage/trash/{id}/restore":{"post":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"回收站记录 ID"}],"responses":{"200":{"description":"还原成功"},"404":{"description":"记录不存在"}},"summary":"管理员：从回收站还原文件","security":[{"BearerAuth":[]}]}},"/api/admin/storage/trash/batch-delete":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"批量删除结果"}},"summary":"管理员：批量永久删除回收站文件","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":100}}}}}}}},"/api/admin/storage/trash/batch-restore":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"批量还原结果"}},"summary":"管理员：批量还原回收站文件","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":100}}}}}}}},"/api/admin/storage/trash/cleanup":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"清理结果"}},"summary":"管理员/定时器：清理过期回收站文件","description":"清理所有 expires_at 已到期的回收站文件（物理删除存储 + DB 记录）。支持管理员手动触发和 pg_cron 定时自动触发。","security":[{"BearerAuth":[]}]}},"/api/admin/storage/trash/empty":{"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"清空结果"}},"summary":"管理员：清空回收站全部文件","security":[{"BearerAuth":[]}]}},"/api/admin/storage/trash":{"get":{"tags":["管理·营销-媒体库"],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"回收站列表"},"403":{"description":"非管理员"}},"summary":"管理员：列出回收站文件","security":[{"BearerAuth":[]}]},"post":{"tags":["管理·营销-媒体库"],"parameters":[],"responses":{"200":{"description":"软删除成功"},"400":{"description":"参数错误"},"403":{"description":"非管理员"}},"summary":"管理员：软删除文件到回收站","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["bucket","paths"],"properties":{"bucket":{"type":"string"},"paths":{"type":"array","items":{"type":"string"},"maxItems":50}}}}}}}},"/api/admin/subscriptions/{id}/cancel":{"post":{"tags":["管理端订阅"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"订阅 ID (UUID)"}],"responses":{"200":{"description":"订阅取消成功"},"400":{"description":"订阅不满足取消条件或平台不支持"},"404":{"description":"订阅未找到"}},"summary":"管理员：取消订阅","description":"管理员可立即取消订阅或设定周期末取消。按 subscription_provider 分发到对应支付平台。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"immediate":{"type":"boolean","default":false,"description":"true=立即取消并降级, false=周期末取消"}}}}}}}},"/api/admin/subscriptions/{id}/change-plan":{"post":{"tags":["管理端订阅"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"订阅 ID (UUID)"}],"responses":{"200":{"description":"方案变更成功"},"400":{"description":"订阅状态不支持变更或平台不支持"},"404":{"description":"订阅未找到"}},"summary":"管理员：变更订阅方案（升级/降级）","description":"按 subscription_provider 分发到对应支付平台变更订阅方案。支持的平台：Stripe/PayPal。Apple IAP/支付宝/微信支付不支持服务端变更。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"newPriceId":{"type":"string","description":"新的 Price/Plan ID（平台相关标识）"}},"required":["newPriceId"]}}}}}},"/api/admin/subscriptions":{"get":{"tags":["管理端订阅"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"},{"in":"query","name":"status","schema":{"type":"string","enum":["active","trialing","past_due","canceled","unpaid"]},"description":"按订阅状态过滤"}],"responses":{"200":{"description":"分页订阅列表（含用户信息合并）"},"403":{"description":"非管理员"}},"summary":"管理员：获取订阅列表（分页 + 状态筛选）","security":[{"BearerAuth":[]}]}},"/api/admin/tasks/{id}":{"delete":{"tags":["管理·运营-任务"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"任务 ID"}],"responses":{"200":{"description":"任务已删除"}},"summary":"管理员：删除任务","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·运营-任务"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"任务 ID"}],"responses":{"200":{"description":"任务状态已更新"}},"summary":"管理员：切换任务完成状态","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"completed":{"type":"boolean"}},"required":["completed"]}}}}}},"/api/admin/tasks/cron":{"get":{"tags":["管理·运营-任务"],"parameters":[],"responses":{"200":{"description":"定时任务状态列表"},"401":{"description":"未授权"}},"summary":"管理员：获取系统定时任务列表","description":"获取后台挂载的所有 System Cron Jobs，结合审计日志动态算出其上次运行时间，仅管理员可访问。","security":[{"BearerAuth":[]}]}},"/api/admin/tasks":{"get":{"tags":["管理·运营-任务"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"}],"responses":{"200":{"description":"分页任务列表（含总数）"},"403":{"description":"非管理员"}},"summary":"管理员：获取所有任务（分页）","description":"返回所有租户的全部任务（分页），仅管理员可访问。","security":[{"BearerAuth":[]}]},"post":{"tags":["管理·运营-任务"],"parameters":[],"responses":{"201":{"description":"任务创建成功"},"500":{"description":"数据库错误"}},"summary":"管理员：创建任务","description":"管理员创建任务，可选指定 tenant_id，默认使用管理员自身 tenantId。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"tenant_id":{"type":"string","description":"可选，目标租户 ID"}},"required":["title"]}}}}}},"/api/admin/users/{id}":{"delete":{"tags":["管理·营销-用户"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"用户 UUID"}],"responses":{"200":{"description":"用户已删除"},"403":{"description":"禁止删除内置管理员"},"404":{"description":"用户未找到"}},"summary":"管理员：删除用户（级联清理 profile）","security":[{"BearerAuth":[]}]},"patch":{"tags":["管理·营销-用户"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"用户 UUID"}],"responses":{"200":{"description":"用户已更新"},"400":{"description":"参数校验失败"},"404":{"description":"用户未找到"}},"summary":"管理员：编辑用户信息","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["user","admin"]},"plan_status":{"type":"string","enum":["free","pro","enterprise"]},"display_name":{"type":"string","maxLength":100}}}}}}}},"/api/admin/users":{"get":{"tags":["管理·营销-用户"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"},{"in":"query","name":"role","schema":{"type":"string","enum":["user","admin"]},"description":"按角色过滤"},{"in":"query","name":"plan","schema":{"type":"string","enum":["paid"]},"description":"按套餐过滤（paid = pro + enterprise）"},{"in":"query","name":"provider","schema":{"type":"string"},"description":"按认证方式过滤"},{"in":"query","name":"search","schema":{"type":"string"},"description":"按邮箱或显示名模糊搜索"}],"responses":{"200":{"description":"分页用户列表（Auth + Profiles 合并）"},"403":{"description":"非管理员"}},"summary":"管理员：获取用户列表（分页）","security":[{"BearerAuth":[]}]}},"/api/admin/users/stats":{"get":{"tags":["管理·营销-用户"],"parameters":[],"responses":{"200":{"description":"用户统计摘要（全局，非分页）"},"403":{"description":"非管理员"}},"summary":"管理员：获取用户统计摘要","security":[{"BearerAuth":[]}]}},"/api/health":{"get":{"tags":["API Routes"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/api/starpath/email/submit":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"邮箱已保存"},"400":{"description":"参数校验失败"}},"summary":"提交邮箱接收报告","description":"用户完成问卷后提交邮箱，用于接收占星报告。支持触发邮件发送。","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/starpath/payment/card":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"支付已确认"},"400":{"description":"参数校验失败"}},"summary":"信用卡支付确认","description":"确认 智能问卷 信用卡（Stripe）支付，更新订单状态并写入交易流水。","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/starpath/payment/google-pay":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"支付已确认"}},"summary":"Google Pay 支付确认","description":"接收 Google Pay 支付成功后的确认回调，经过策略层验证 token 后更新统一订单表并写入交易流水。"}},"/api/starpath/payment/paypal":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"支付已确认"}},"summary":"PayPal 支付确认","description":"接收 PayPal 支付成功后的确认回调，经过策略层验签后更新统一订单表并写入交易流水。"}},"/api/starpath/payment/webhook/apple-iap":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"Notification 已处理"}},"summary":"Apple IAP Server Notification 接收端点","description":"接收 Apple App Store Server Notifications v2 的订阅状态变更通知。"}},"/api/starpath/payment/webhook/paypal":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"Webhook 已处理"}},"summary":"PayPal Webhook 接收端点","description":"接收 PayPal REST API 的支付状态回调通知（CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.* 等事件）。"}},"/api/starpath/questionnaire/answer":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"答案已记录"},"400":{"description":"参数校验失败"}},"summary":"提交问卷答案（事件溯源模式）","description":"每次提交一个问题答案，以不可变事件流方式存储，支持完整审计与分析。","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/starpath/report":{"get":{"tags":["智能问卷"],"parameters":[{"in":"query","name":"id","schema":{"type":"string"},"description":"报告 ID","required":true}],"responses":{"200":{"description":"报告数据（含 signs, aspects, reading）"},"404":{"description":"报告不存在"}},"summary":"获取 AI 占星报告","description":"根据 ID 从 ai_reports 表获取用户报告。不存在时返回 404。"}},"/api/starpath/subscribe/android":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"订单创建结果"},"400":{"description":"参数校验失败"}},"summary":"创建订阅订单（Android）","description":"处理 Android 平台 智能问卷 订阅下单，写入统一 orders 表。","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/starpath/subscribe/ios":{"post":{"tags":["智能问卷"],"parameters":[],"responses":{"200":{"description":"订单创建结果（含 orderId）"},"400":{"description":"参数校验失败"}},"summary":"创建订阅订单","description":"处理 智能问卷 订阅下单（iOS / Android 通用），写入统一 orders 表。","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/_openapi-meta":{"get":{"tags":["内部"],"parameters":[],"responses":{"200":{"description":"OK"}},"summary":"OpenAPI 元数据"}},"/api/v1/analytics/config":{"get":{"tags":["分析埋点"],"parameters":[],"responses":{"200":{"description":"埋点配置"}},"summary":"获取多平台埋点配置（公开）","description":"返回前端页面所需的 GA4 / Meta Pixel / TikTok Pixel 配置及各端开关，不含敏感信息。"}},"/api/v1/auth/callback":{"get":{"tags":["认证"],"parameters":[{"in":"query","name":"code","schema":{"type":"string"},"description":"OAuth 授权码"},{"in":"query","name":"provider","schema":{"type":"string"},"description":"OAuth 提供者名称"}],"responses":{"302":{"description":"重定向至前端并携带认证令牌"}},"summary":"OAuth 回调处理","description":"处理 Supabase OAuth 回调，交换 code 获取会话令牌并重定向至前端设置 cookie。"}},"/api/v1/auth/link":{"post":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"账户绑定成功"},"401":{"description":"未认证"}},"summary":"匿名用户绑定邮箱","description":"将匿名用户的 identity 绑定到真实邮箱/密码账户，绑定后 is_anonymous 变为 false。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]}}}}}},"/api/v1/auth/login":{"post":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"登录成功 — 返回用户信息 + 会话令牌","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}}},"session":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"expires_at":{"type":"integer"}}}}}}}}}},"401":{"description":"凭证无效"}},"summary":"统一登录入口","description":"支持三种模式：邮箱密码登录、社交 OAuth 跳转（google/facebook/apple）、匿名用户登录（device_id）。","requestBody":{"description":"登录请求 — 三种互斥模式任选其一","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"type":"object","properties":{"provider":{"type":"string","enum":["google","facebook","apple"]},"redirect_to":{"type":"string","format":"uri"},"link":{"type":"boolean"}},"required":["provider"]},{"type":"object","properties":{"anonymous":{"type":"boolean","enum":[true]},"device_id":{"type":"string"}},"required":["anonymous","device_id"]}]}}}}}},"/api/v1/auth/logout":{"post":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"登出成功"}},"summary":"用户登出","description":"通过 Supabase signOut 使当前会话失效并清除认证 cookie。"}},"/api/v1/auth/me":{"get":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"用户档案对象","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"username":{"type":"string"},"display_name":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"role":{"type":"string","enum":["user","admin"]},"auth_provider":{"type":"string"},"is_anonymous":{"type":"boolean"},"email_verified":{"type":"boolean"},"phone":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"未认证"}},"summary":"获取当前用户信息","description":"返回已认证用户的完整档案信息（来自 profiles 表），若 profile 未创建则返回基本信息。","security":[{"BearerAuth":[]}]}},"/api/v1/auth/profile":{"patch":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"档案更新成功"},"401":{"description":"未认证"}},"summary":"更新用户档案","description":"仅允许更新 display_name、avatar_url 和 phone 字段。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string"},"avatar_url":{"type":"string","format":"uri","nullable":true},"phone":{"type":"string","nullable":true}}}}}}}},"/api/v1/auth/register":{"post":{"tags":["认证"],"parameters":[],"responses":{"200":{"description":"注册成功 — 返回用户信息 + 会话"},"400":{"description":"注册失败"}},"summary":"邮箱注册","description":"通过 Supabase Auth signUp 创建新账户，profiles 记录由数据库触发器自动创建。","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"},"username":{"type":"string"}},"required":["email","password"]}}}}}},"/api/v1/campaigns/{subdomain}":{"get":{"tags":["营销活动"],"parameters":[{"in":"path","name":"subdomain","required":true,"schema":{"type":"string"},"description":"营销活动子域名"}],"responses":{"200":{"description":"营销活动对象","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subdomain":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"badge":{"type":"string"},"color_from":{"type":"string"},"color_to":{"type":"string"},"cta_text":{"type":"string"},"is_active":{"type":"boolean"}}}}}}}},"404":{"description":"营销活动未找到"}},"summary":"按子域名获取营销活动","description":"返回指定子域名的营销活动公开配置，无需鉴权。"}},"/api/v1/campaigns/register":{"post":{"tags":["营销活动"],"parameters":[],"responses":{"200":{"description":"预约信息已记录"}},"summary":"营销活动预约注册（H5 表单）","description":"记录来自 H5 营销活动落地页的用户注册/预约信息。","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string"},"email":{"type":"string","format":"email"},"subdomain":{"type":"string"}},"required":["phone","email","subdomain"]}}}}}},"/api/v1/feedback":{"get":{"tags":["反馈"],"parameters":[{"in":"query","name":"subdomain","schema":{"type":"string"},"description":"按营销活动子域名过滤"},{"in":"query","name":"type","schema":{"type":"string","enum":["review","bug","feature","general"]},"description":"按反馈类型过滤"},{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"}],"responses":{"200":{"description":"分页评价列表及统计数据"}},"summary":"获取已审批的用户评价列表（分页）","description":"返回公开已审批的评价列表及统计数据（总数、平均评分、评分分布），支持按子域名和类型过滤。"},"post":{"tags":["反馈"],"parameters":[],"responses":{"201":{"description":"评价已提交"},"401":{"description":"需要登录"}},"summary":"提交评价/反馈","description":"提交一条评价，需要已登录的非匿名用户。type=review 时评分必填。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"campaignSubdomain":{"type":"string"},"type":{"type":"string","enum":["review","bug","feature","general"],"default":"review"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"},"displayName":{"type":"string"}}}}}}}},"/api/v1/orders":{"get":{"tags":["订单"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码（1–100）"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"}],"responses":{"200":{"description":"分页订单列表","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"}}}}}}}}}}},"summary":"获取用户订单列表","description":"返回当前用户的订单列表（分页），按 user_id 进行 RLS 隔离。","security":[{"BearerAuth":[]}]}},"/api/v1/payments/{id}":{"get":{"tags":["支付"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"订单 ID"}],"responses":{"200":{"description":"订单对象"},"403":{"description":"无权访问"},"404":{"description":"订单未找到"}},"summary":"获取单个订单状态","description":"返回订单详情，RLS 限制用户仅可查看自己的订单（管理员除外）。","security":[{"BearerAuth":[]}]}},"/api/v1/payments/config":{"get":{"tags":["支付"],"parameters":[],"responses":{"200":{"description":"返回已启用的支付配置列表"}},"summary":"获取当前可用的支付通道配置","description":"获取全站已启用的支付渠道及其对应的前台公钥/Client ID 配置信息，用于前端按需加载 SDK 并渲染收银台。"}},"/api/v1/payments/confirm":{"get":{"tags":["支付"],"parameters":[{"in":"query","name":"order_id","required":true,"schema":{"type":"string"},"description":"本地订单 ID"},{"in":"query","name":"session_id","required":true,"schema":{"type":"string"},"description":"Stripe Checkout 会话 ID"}],"responses":{"200":{"description":"支付已确认"},"400":{"description":"参数错误或校验失败"},"404":{"description":"订单未找到"}},"summary":"支付确认回调","description":"处理 Stripe 结账后的重定向，验证 session_id 并将订单标记为已支付。"}},"/api/v1/payments/create":{"post":{"tags":["支付"],"parameters":[],"responses":{"200":{"description":"结账会话创建成功 — 返回 orderId、checkoutUrl、sessionId"}},"summary":"创建 Stripe Checkout 会话","description":"创建订单记录并发起 Stripe Checkout 会话，返回结账链接。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"productName":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","default":"USD"}},"required":["productId","productName","amount"]}}}}}},"/api/v1/payments/webhook":{"post":{"tags":["支付"],"parameters":[],"responses":{"200":{"description":"事件已处理 — { received: true }"},"400":{"description":"签名无效或缺少请求体"}},"summary":"Stripe Webhook 处理器","description":"接收 Stripe webhook 事件（checkout.session.completed、charge.refunded），通过 stripe-signature 头部验证。","requestBody":{"description":"Stripe 原始事件 payload","content":{"application/json":{"schema":{"type":"object"}}}}}},"/api/v1/products/{id}":{"delete":{"tags":["商品"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"商品 ID"}],"responses":{"200":{"description":"商品已删除 — 返回 { id }"},"400":{"description":"缺少商品 ID"}},"summary":"删除商品","description":"删除当前租户下的指定商品。","security":[{"BearerAuth":[]}]},"patch":{"tags":["商品"],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"商品 ID"}],"responses":{"200":{"description":"商品更新成功"},"400":{"description":"缺少商品 ID"}},"summary":"更新商品","description":"部分更新商品名称/价格，仅允许白名单字段，tenant_id 由服务端强制校验。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}}}}}},"/api/v1/products":{"get":{"tags":["商品"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1},"description":"页码"},{"in":"query","name":"pageSize","schema":{"type":"integer","default":20},"description":"每页条数（最大 100）"}],"responses":{"200":{"description":"分页商品列表（含总数）"},"500":{"description":"数据库错误"}},"summary":"获取商品列表（分页）","description":"返回当前租户的所有商品（分页），按 created_at 降序排列。","security":[{"BearerAuth":[]}]},"post":{"tags":["商品"],"parameters":[],"responses":{"201":{"description":"商品创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price":{"type":"number"},"tenant_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"500":{"description":"数据库错误"}},"summary":"创建商品","description":"在当前租户下创建新商品，tenant_id 由服务端注入。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"description":{"type":"string"},"image_url":{"type":"string","format":"uri"},"is_active":{"type":"boolean"}},"required":["name","price"]}}}}}},"/api/v1/storage/{path}":{"delete":{"tags":["存储"],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"删除成功"},"400":{"description":"路径格式错误"},"403":{"description":"无权限删除该文件"}},"summary":"删除存储文件","description":"删除指定路径的文件。用户仅可删除自己目录下的文件，管理员可操作 campaign-assets。","security":[{"BearerAuth":[]}]}},"/api/v1/storage/signed-url":{"post":{"tags":["存储"],"parameters":[],"responses":{"200":{"description":"Signed URL 生成成功"},"400":{"description":"参数错误"},"403":{"description":"无权限写入该 Bucket"}},"summary":"生成客户端直传的 Signed Upload URL","description":"获取 signed URL 后客户端可直接 PUT 上传文件至 Supabase Storage，适合大文件（>= 5MB）场景。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["bucket","filename"],"properties":{"bucket":{"type":"string","enum":["avatars","campaign-assets","uploads"]},"filename":{"type":"string","description":"原始文件名"},"contentType":{"type":"string","description":"文件 MIME 类型"}}}}}}}},"/api/v1/storage/signed-url/{path}":{"get":{"tags":["存储"],"parameters":[{"name":"path","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signed URL 生成成功"},"400":{"description":"路径格式错误"},"403":{"description":"无权限访问该文件"}},"summary":"获取私有文件临时访问 URL","description":"为私有 Bucket 中的文件生成临时 signed URL，默认 1 小时有效。用户仅可访问自己目录下的文件。","security":[{"BearerAuth":[]}]}},"/api/v1/storage/upload":{"post":{"tags":["存储"],"parameters":[],"responses":{"200":{"description":"上传成功"},"400":{"description":"参数错误或文件超限"},"403":{"description":"无权限写入该 Bucket"}},"summary":"服务端中转上传文件","description":"小文件（< 5MB）通过服务端中转上传至 Supabase Storage。大文件请使用 signed-url 接口。","security":[{"BearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","bucket"],"properties":{"file":{"type":"string","format":"binary","description":"上传文件"},"bucket":{"type":"string","enum":["avatars","campaign-assets","uploads"],"description":"目标 Bucket"},"path":{"type":"string","description":"自定义路径（可选，默认自动生成）"}}}}}}}},"/api/v1/user/profile":{"get":{"tags":["用户"],"parameters":[],"responses":{"200":{"description":"{ userId, username, role, plan }"}},"summary":"获取用户档案（租户隔离）","description":"返回已认证用户的档案信息，使用会话中的 tenant_id 进行租户隔离，防止水平越权。","security":[{"BearerAuth":[]}]}},"/sitemap_index.xml":{"get":{"tags":["App Routes"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/__sitemap__/{sitemap}":{"get":{"tags":["Internal"],"parameters":[{"name":"sitemap","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/__sitemap__/style.xsl":{"get":{"tags":["Internal"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/sitemap.xml":{"get":{"tags":["App Routes"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/_i18n/{hash}/{locale}/messages.json":{"get":{"tags":["Internal"],"parameters":[{"name":"hash","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/__nuxt_island/{*param1}":{"get":{"tags":["Internal"],"parameters":[{"name":"*param1","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/_ipx/{*param1}":{"get":{"tags":["Internal"],"parameters":[{"name":"*param1","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/_openapi.json":{"get":{"tags":["Internal"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/_scalar":{"get":{"tags":["Internal"],"parameters":[],"responses":{"200":{"description":"OK"}}}},"/_swagger":{"get":{"tags":["Internal"],"parameters":[],"responses":{"200":{"description":"OK"}}}}},"x-tagGroups":[{"name":"管理后台","tags":["管理·运营-任务","管理·运营-订单","管理·运营-收入","管理·营销-活动","管理·营销-用户","管理·营销-媒体库","管理·系统-安全","管理·系统-监控","管理·系统-审计","管理·系统-认证","管理·系统-个人"]},{"name":"公共 API","tags":["认证","支付","商品","任务","存储","营销活动","反馈","订单","用户"]}]}