管理员后台
管理员后台用于处理用户权益、礼品码订单、模型目录和操作审计。所有操作均需管理员权限。
后台功能模块
管理员后台包含四大核心模块，覆盖用户运营和系统配置的全部需求。
礼品码管理
管理员可以批量生成、导出和管理礼品码，是最核心的运营工具。
批量生成
在后台指定套餐层级、权益类型、次数、批次名称和销售平台，一次性生成多张礼品码。支持自定义前缀。
CSV 导出
生成的礼品码可导出为 CSV 文件，方便上传到自动发货平台（淘宝、拼多多等）。
状态追踪
每个礼品码有三种状态：new（未兑换）、redeemed（已兑换）、disabled（已禁用）。后台可实时查看状态分布。
售后处理
管理员可搜索已兑换的礼品码，查看兑换者信息，支持手动调整权益或禁用问题码。
模型目录管理
模型目录决定桌面端可以使用哪些 AI 模型和 Provider。
Provider 目录
每个 Provider 代表一个 AI 服务商（如 OpenAI、Anthropic）。管理员配置 API 地址、认证方式、推理格式（none / deepseek / anthropic）和额外请求头。Provider 下可挂载多个具体模型。
推理格式是关键配置：决定了桌面端如何解析模型返回的 reasoning 内容。错误的格式会导致思考过程显示异常。
免费模型
免费模型由平台代理，用户无需提供 API Key。管理员配置模型的 Provider、API 地址和加密存储的 API Key。桌面端请求免费模型时，API 地址会被替换为平台代理地址。
安全设计：free_models 表的 API Key 使用加密存储，RLS 策略禁止普通用户读取，只有 service_role 可以访问。
权限与安全
管理员后台的安全机制和权限控制说明。
- 管理员权限通过 profiles 表的 role 字段控制（admin 或 super_admin）
- 所有管理员 API 在服务端做角色校验，不依赖前端路由守卫
- 管理员权限检查使用 is_admin() 数据库函数
- 非管理员访问 /admin 页面会显示权限不足提示
如何获得管理员权限
管理员权限不会自动授予，需要超级管理员手动操作。
权限等级
user（普通用户）
默认角色，可使用桌面端和网页端的用户功能。
admin（管理员）
可访问管理后台，执行用户管理、礼品码管理、模型目录管理等操作。
super_admin（超级管理员）
最高权限，可以授予/撤销其他用户的管理员角色，可执行所有操作。
授权方式
方式一：通过管理后台
超级管理员在后台搜索用户，将角色从 user 修改为 admin。这是推荐的方式。
方式二：通过 Supabase SQL
在 Supabase 控制台执行：
UPDATE profiles SET role = 'admin' WHERE email = 'user@example.com';
仅在后台无法使用时采用此方式。
礼品码生命周期管理
从创建到售后的完整礼品码管理流程。
创建批次
管理员在后台指定套餐层级（standard/ultra/max）、权益类型（counted/permanent）、次数、批次名称和销售平台。
- 批次名称建议包含日期和用途，如「2024-06-淘宝标准版」
- 一次可生成 1-1000 张码，生成后不可修改批次信息
- 每张码的状态初始为 new，可立即导出使用
导出 CSV
生成完成后，点击导出按钮下载 CSV 文件。文件包含批次中所有礼品码。
- CSV 格式：礼品码 | 套餐 | 类型 | 次数 | 批次 | 状态
- 导出前确认码的数量和状态无误
- 妥善保管 CSV 文件，避免泄露
上传到销售平台
将 CSV 文件上传到自动发货平台（淘宝、拼多多等），或通过闲鱼/微信手动发货。
- 淘宝/拼多多：使用「自动发货」功能，上传卡密文件
- 闲鱼/微信：逐个发送给买家，建议保留发货记录
- 不同平台建议使用不同批次，便于追踪和管理
用户兑换
用户在 /redeem 页面输入礼品码，系统校验并写入权益。
- 兑换后礼品码状态变为 redeemed，记录兑换者和时间
- 权益立即写入 entitlements 表，用户可立即使用
- 兑换记录可在后台查看，支持按批次筛选
售后与审计
管理员可以查看兑换记录、禁用问题码、手动调整用户权益。
- 支持按礼品码、用户邮箱、批次搜索
- 可以查看每张码的完整生命周期记录
- 所有操作写入审计日志，可追溯
用户售后处理流程
当用户遇到兑换或权益问题时，按以下流程排查和处理。
搜索用户
在后台用户管理页面，输入用户的邮箱地址搜索。支持模糊搜索。
- 搜索结果显示用户的基本信息：邮箱、昵称、注册时间、当前角色
- 如果用户不存在，可能是邮箱拼写错误或用户尚未注册
- 点击用户行进入详情页
查看权益汇总
在用户详情页查看该用户的所有权益记录，包括套餐层级、类型、剩余次数和到期时间。
- 权益按时间倒序排列，最新的在最前面
- 每条权益显示来源（礼品码兑换 or 管理员发放）
- 如果权益来自礼品码，可点击跳转到该礼品码的详情
识别问题
根据用户描述和系统数据判断问题类型。
- 常见问题：兑换后权益未显示 → 检查是否登录了正确账号
- 常见问题：次数不对 → 检查是否有重复扣次或权益被覆盖
- 常见问题：功能无法使用 → 检查权益层级是否满足功能要求
手动发放或调整
使用 admin_grant 功能手动为用户发放权益，或调整现有权益。
- 选择套餐层级、权益类型和次数
- 填写发放原因（必填），写入审计日志
- 发放后权益立即生效，用户无需刷新
- 手动发放的权益同样受扣次规则约束
模型目录更新流程
当需要添加新的 AI Provider 或模型时，按以下流程操作。
创建 Provider
在模型目录管理页面新增一个 Provider，填写基本信息。
- Provider 名称：如 OpenAI、Anthropic、DeepSeek
- API 基础地址：如 https://api.openai.com/v1
- 认证方式：API Key（Header 或 Query 参数）
- 推理格式（Reasoning Format）：选择 none、deepseek 或 anthropic
- 额外请求头：如有需要，添加自定义 HTTP Header
添加模型
在 Provider 下新增具体模型，配置模型的详细信息。
- 模型 ID：如 gpt-4o、claude-3.5-sonnet、deepseek-chat
- 显示名称：用户在桌面端看到的名称
- 分类标签：如 general、coding、reasoning
- 多模态支持：是否支持图片输入（影响截图解题功能）
- 推理格式继承自 Provider，可单独覆盖
配置推理格式
推理格式决定了桌面端如何解析模型返回的 reasoning（思考过程）内容。
- none：模型不返回思考过程，不需要特殊解析
- deepseek：解析 DeepSeek 格式的 thinking 标签
- anthropic：解析 Anthropic 格式的 thinking block
- 错误的格式会导致思考过程显示异常或丢失
配置免费模型（可选）
如果需要让用户无需 API Key 就能使用，配置为免费模型。
- 在免费模型管理页面新增记录
- 关联已有的 Provider 和模型
- 配置平台代理地址（用户请求会转发到此地址）
- 加密存储 API Key（仅 service_role 可读取）
- 免费模型的 API Key 通过环境变量或加密字段管理
测试验证
配置完成后，在桌面端使用该模型进行一次完整的功能测试。
- 确认模型可以正常调用并返回结果
- 确认推理格式正确（如果模型支持 thinking）
- 确认多模态功能正常（如果配置了图片支持）
- 确认免费模型的代理地址工作正常
审计日志查询
所有管理员操作都会被记录，便于事后追溯和问题排查。
审计日志字段
operator_id执行操作的管理员 user_idoperator_email管理员邮箱，便于快速查看action操作类型，如 grant_entitlement、disable_code、create_batchtarget_type目标类型，如 user、gift_code、entitlement、providertarget_id目标 ID（user_id、gift_code_id 等）details操作详情 JSON，包含变更前后的内容created_at操作时间（UTC）ip_address操作者 IP 地址常用查询场景
查询某用户被谁发放了权益
筛选 target_type=user 且 action=grant_entitlement，找到目标用户 ID 的记录。
查询某批次礼品码的操作记录
筛选 target_type=gift_code，根据 batch_name 或码 ID 范围定位。
排查权限变更
筛选 action=change_role，查看所有角色变更记录，包括操作者和目标用户。
追踪模型配置变更
筛选 target_type=provider 或 target_type=model，查看模型目录的所有修改历史。
常见管理员操作 FAQ
管理员在日常工作中最常遇到的问题和解决方案。
如何批量退款？
目前不支持批量退款操作。需要逐个处理：搜索用户 → 查看权益 → 撤销对应权益 → 记录退款原因。建议在操作前导出用户列表作为备份。
用户说兑换码无效但我查是 new 状态？
可能原因：1) 用户登录了错误的账号；2) 用户输入时多了空格或字符；3) 码的格式不对。让用户截图错误提示和礼品码，与后台记录比对。
如何查看某批次的兑换率？
在礼品码管理页面，按批次名称筛选，查看状态分布。兑换率 = redeemed 数量 / 总数量。建议定期检查兑换率，发现异常及时排查。
添加新 Provider 后桌面端不显示？
桌面端的模型目录有缓存。用户需要在设置中点击「刷新模型列表」或重启应用。如果是免费模型，还需要确认代理地址配置正确且可访问。
审计日志保留多久？
审计日志目前永久保留，不做自动清理。如果数据量增长过快，可联系技术团队讨论归档策略。日志仅允许读取，不可修改或删除。
进入管理后台
使用管理员账号登录后，访问管理后台处理日常运营事务。