折扣码生成系统

• 本系统负责本地折扣码生成、校验、使用标记和状态管理。
• 外部后台系统通过 API Client 调用本系统开放接口。
• 本系统不负责在任何外部平台创建、同步或停用折扣码。

• Admin 在“API 接口配置”中为不同外部系统创建独立 Client，并按需配置 Allowed IPs。
• API Key 只在创建或重置后展示一次，列表页不会再次展示明文 key。
• API Key 应保存在外部系统服务端，不得暴露在前端页面、客户端应用、公开仓库或日志中。

请求头与 HMAC

• 所有外部接口必须带 X-API-Key: <api_key>。
• 默认 API_REQUIRE_HMAC=false 时，只发送 X-API-Key 即可调用。
• 当 API_REQUIRE_HMAC=true，或请求带了任意 HMAC 相关头时，必须同时带 X-API-Timestamp 和 X-API-Signature。
• 签名明文格式为 timestamp.POST.path.rawBody，算法为 HMAC-SHA256，secret 使用当前 API Key 本身，输出 hex digest。
• rawBody 必须是实际发送的请求体字符串；签名前后不要重排 JSON 字段。
• 不启用 HMAC 时，不要发送 X-API-Timestamp 或 X-API-Signature，否则会触发 HMAC 校验。
• API Key、时间戳和签名都不应放入 JSON body。
• 如配置 Allowed IPs，只有白名单 IP 可调用；多个 IP 用逗号分隔。

1710000000.POST./api/v1/discount-codes/validate.{"code":"RC-XXXXXXXX","external_customer_id":"customer_001","product_option_id":"option_1000","checkout_amount_usd":891,"recharge_mode":"preset"}

折扣码状态说明

同一客户邮箱存在 active 折扣码时，系统会阻止再次生成；used 或 voided 状态不阻止重新生成。

mark-used 幂等规则

• active 折扣码首次 mark-used 成功后返回 {"ok":true,"idempotent":false}。
• 同一 external_order_id 重复调用已 used 折扣码时返回 {"ok":true,"idempotent":true}。
• 已 used 但订单号不同会返回 code_already_used_by_another_order。

常见错误码

旧字段兼容

• 新接入方应使用通用字段；旧字段仅为历史调用方兼容保留。
• shopify_customer_id 兼容映射到 external_customer_id。
• shopify_order_id 兼容映射到 external_order_id。
• product_variant_id 兼容映射到 product_option_id。
• shopify_variant_id 也作为历史字段兼容映射到 product_option_id。
• 新旧字段同时传入时，通用字段优先。本轮不做数据库列重命名迁移，代码内部或数据库层仍可能存在历史列名。

外部接口联调工具

• 后台提供“外部接口联调工具”，可填写 API Key、code、external_customer_id、product_option_id、external_order_id 调试接口。
• 工具支持仅发送 X-API-Key，也支持可选生成 HMAC 签名头。
• 工具不会把 API Key、时间戳或签名写入 JSON body，也不会持久化 API Key。

开发注意事项

• 后端权限必须以后端校验为准，前端只负责隐藏不该出现的入口。
• 涉及登录、权限、折扣码状态、外部 API 或飞书回调的改动，需要补充 HTTP 测试。
• 生产部署前先备份被覆盖文件或数据库；部署后检查 /login、/health 和最近日志。
• 公开文档、GitHub 和截图中不要出现真实密码、TOTP Secret 或 API Key。