飞创 Fitron

主题

管理后台 — 外部券码管理 ​

上级文档：管理后台 Web

模块概述 ​

外部券码管理用于管理在抖音、美团等外部平台发行的兑换券码批次。管理员在此创建券码批次、生成券码、导出 CSV 上传至平台后台，并查看各批次的核销数据。

页面路由 ​

路由页面说明
/voucher-batches券码批次列表所有批次管理，含核销统计
/voucher-batches/new新建批次创建新券码批次并生成券码
/voucher-batches/:id批次详情批次信息、券码列表、核销记录
/voucher-batches/:id/records核销记录该批次下所有券码的核销详情

券码批次列表 ​

列表字段定义 ​

列名字段 key类型说明
批次名称nameString如「抖音 3 月团购-月卡」
平台platformEnum抖音 / 美团 / 自定义渠道
对应产品productNameString券码兑换后开通的产品
总量totalCountInt批次券码总数
已核销usedCountInt已成功核销数量
核销率—String已核销/总量 百分比
过期时间expiresAtDateTime?批次过期时间
状态—Enum启用 / 已过期 / 已停用
创建时间createdAtDateTime—

筛选条件 ​

筛选项类型说明
关键词输入框批次名称模糊搜索
平台多选抖音 / 美团 / 自定义
状态多选启用 / 已过期 / 已停用

新建券码批次 ​

表单字段 ​

字段组件必填校验规则说明
批次名称文本输入✅2-50 字符如「抖音 3 月团购-月卡」
平台单选✅枚举抖音 / 美团 / 自定义渠道
自定义渠道名文本输入条件必填平台=自定义时必填—
对应产品下拉选择✅已上架的产品券码兑换后开通的产品
券码数量数字输入✅≥ 1本批次生成多少个券码
券码前缀文本输入❌2-6 字母/数字如 DY2503，用于区分批次
过期时间日期时间❌—批次过期后券码不可核销

生成规则 ​

  • 券码格式：{前缀}-{6 位随机大写字母+数字}
  • 默认前缀规则：抖音=DY，美团=MT，自定义=CS
  • 示例：DY2503-A7X9KL
  • 全部唯一，数据库唯一索引保证

创建成功后 ​

  1. 跳转到批次详情页
  2. 列表展示所有生成的券码
  3. 提供「导出 CSV」按钮
  4. CSV 格式：券码 一列，每行一个券码

批次详情页 ​

页面结构 ​

Tab 1：批次信息 ​

字段说明
批次名称—
平台抖音/美团/自定义
对应产品产品名称 + 类型
总量 / 已核销 / 剩余数字统计
核销率百分比 + 进度条
过期时间—
创建时间—
创建人管理员账号

Tab 2：券码列表 ​

列名字段说明
券码code唯一标识
状态status未使用 / 已核销 / 已过期 / 已停用
核销用户redeemedUserId已核销时显示用户昵称，可跳转
核销时间redeemedAt—

操作：

  • 搜索券码（精确匹配）
  • 按状态筛选
  • 导出券码列表（含核销状态）
  • 单个停用（将状态设为 DISABLED）

Tab 3：核销记录 ​

列名字段说明
券码code—
核销用户用户昵称 + 手机号可跳转用户详情
核销时间redeemedAt—
生成的订单redeemedOrderId订单编号，可跳转订单详情
会员权益—展示开通/续期的具体内容

权限控制 ​

操作老板财务店长客服说明
查看批次列表✅✅✅（只读）❌—
新建批次✅✅❌❌—
导出券码 CSV✅✅❌❌敏感数据，限制权限
查看核销记录✅✅✅✅客服处理核销问题时查看
停用批次✅❌❌❌—
停用单个券码✅❌❌✅客服处理异常时

用户故事 ​

US-VOUCHER-01：运营创建抖音团购券码批次 ​

作为运营人员，我想创建一批抖音团购月卡券码，生成后导出 CSV 上传到抖音活动后台。

验收标准：

  • [ ] 填写平台、对应产品、数量后一键创建
  • [ ] 创建后自动生成所有券码，每个唯一
  • [ ] 可导出 CSV（仅含券码列，每行一个）
  • [ ] 券码格式清晰可辨认（含平台前缀）

US-VOUCHER-02：财务查看券码核销数据 ​

作为财务人员，我想查看各批次的核销率和核销详情，以便与平台对账。

验收标准：

  • [ ] 批次列表展示核销率和已核销数量
  • [ ] 核销记录可按时间段筛选
  • [ ] 核销记录关联到具体用户和订单
  • [ ] 支持导出核销明细

US-VOUCHER-03：客服停用异常券码 ​

作为客服，我需要停用被异常使用的券码，防止损失。

验收标准：

  • [ ] 在券码列表中可搜索具体券码
  • [ ] 可将单个券码状态设为「已停用」
  • [ ] 停用操作写入操作日志
  • [ ] 已停用券码不可再被核销

API 接口规划 ​

# 批次列表
GET /api/v1/admin/voucher-batches
  Query: { keyword?, platform[], status[], page, pageSize }
  Response: { items: VoucherBatch[], total: number }

# 创建批次
POST /api/v1/admin/voucher-batches
  Body: { name, platform, productId, totalCount, codePrefix?, expiresAt? }
  Response: VoucherBatch { ...全部字段, codes: VoucherCode[] }

# 批次详情
GET /api/v1/admin/voucher-batches/:id
  Response: VoucherBatch { ...全部字段, usedCount, remainingCount }

# 导出券码 CSV
GET /api/v1/admin/voucher-batches/:id/codes/export
  Response: CSV file download (券码列)

# 停用批次
PATCH /api/v1/admin/voucher-batches/:id/disable
  Response: { success: boolean }

# 券码列表（某批次下）
GET /api/v1/admin/voucher-batches/:id/codes
  Query: { code?, status[], page, pageSize }
  Response: { items: VoucherCode[], total: number }

# 停用单个券码
PATCH /api/v1/admin/voucher-codes/:codeId/disable
  Response: { success: boolean }

# 核销记录
GET /api/v1/admin/voucher-batches/:id/records
  Query: { startDate?, endDate?, page, pageSize }
  Response: { items: VoucherRedeemRecord[], total: number }

# 批次统计
GET /api/v1/admin/voucher-batches/:id/stats
  Response: { totalCount, usedCount, redeemedCount, rate,
              dailyStats: { date, count }[] }

飞创 Fitron 内部规划文档