内容 API：幂等 slug 与凭证

#先说结论

内容 API 的价值不在"能写入"，在"重复调用不出错"。做外贸站群或 ERP 对接时，重试是常态。

#幂等怎么做

用 slug 作为业务主键：

POST /api/v1/products
{ "slug": "high-speed-door", "title": "...", ... }

• slug 不存在 → 创建
• slug 已存在 → 更新
• 相同 payload 重复调用 → 结果不变

这样网络抖动导致的重试不会产生重复内容。

#凭证设计

• 安装时自动生成：dcm_ + 48 位十六进制
• 存 configs.api_token，可后台查看/重置
• 请求头：Authorization: Bearer dcm_xxx
• 重置后旧凭证立即失效

为什么不签 JWT：客户环境没有统一的密钥分发，长期凭证 + 可重置更实用。

#权限与审计

• 写接口单独开关（后台可关）
• 每次调用记录：时间、IP、端点、结果
• 敏感操作（删除）单独权限

#典型用途

#接口设计的三个细节

1. 返回完整对象：创建后直接返回 id 与 URL，调用方不用再查
2. 字段可选：只传变化的字段，其余保持
3. 错误码稳定：400 参数错、401 未授权、409 冲突、429 限流

典型对接是 ERP：产品主数据变更后每 15 分钟推一次，日均 200 次左右调用。遇到的坑是并发写同一个 slug——两个请求同时判断「不存在」，然后都去创建。解法是给 slug 加唯一索引，捕获重复键后转为更新。