官网表单“明明提交成功，销售却说没收到”，还重复两条？询盘线索防丢防重的前端兜底与后端幂等实战

// 进入填写页就生成一次幂等令牌，同一份填写反复提交都是同一个键
const formKey = 'lead_' + Date.now() + '_' + Math.random().toString(36).slice(2, 8);
const pendingKey = 'pending_lead';
const btn = document.querySelector('#submit');
let submitting = false;

async function submitLead(data) {
  if (submitting) return;          // 防连点
  submitting = true;
  btn.disabled = true;
  const payload = { ...data, idemKey: formKey };
  try {
    const res = await fetch('/api/lead', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': formKey },
      body: JSON.stringify(payload),
    });
    if (!res.ok) throw new Error('http ' + res.status);
    localStorage.removeItem(pendingKey);   // 只有确认成功才清本地
    alert('提交成功，我们会尽快联系您');
  } catch (e) {
    // 弱网/超时：先落地本地，恢复后补发，绝不让客户白填
    localStorage.setItem(pendingKey, JSON.stringify(payload));
    scheduleRetry();
  } finally {
    submitting = false;
    btn.disabled = false;
  }
}

// 网络恢复或定时轮询时补发；后端靠 idemKey 去重，补发也不会产生两条
function scheduleRetry() {
  window.addEventListener('online', retryPending);
  setInterval(retryPending, 30000);
}
async function retryPending() {
  const raw = localStorage.getItem(pendingKey);
  if (!raw || !navigator.onLine) return;
  const payload = JSON.parse(raw);
  const res = await fetch('/api/lead', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Idempotency-Key': payload.idemKey },
    body: JSON.stringify(payload),
  });
  if (res.ok) localStorage.removeItem(pendingKey);
}

-- 线索表：幂等键加唯一约束，同一次提交无论重放几次只落一条
CREATE TABLE customer_lead (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  idem_key    VARCHAR(64) NOT NULL COMMENT '前端生成的幂等令牌',
  name        VARCHAR(50),
  phone       VARCHAR(20),
  content     VARCHAR(1000),
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY uk_idem_key (idem_key)
);

-- 幂等记录表：先占坑再处理，处理结果可复用
CREATE TABLE idempotent_record (
  idem_key    VARCHAR(64) PRIMARY KEY,
  status      TINYINT COMMENT '0处理中 1成功 2失败',
  response    VARCHAR(1000),
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post('/api/lead')
def create_lead():
    idem = request.headers.get('Idempotency-Key') or request.json.get('idemKey')
    if not idem:
        return jsonify(msg='missing idempotency key'), 400

    # 已处理过：重放直接返回首次结果，不再插入
    cached = get_idempotent(idem)
    if cached and cached['status'] == 1:
        return jsonify(data=cached['response'], duplicated=True)

    # 占坑失败说明正在并发处理或重放
    if not try_insert_idempotent(idem, status=0):
        return jsonify(msg='processing, retry later'), 409

    try:
        lead_id = insert_lead(request.json)   # 数据库唯一键是最后一道闸
        resp = {'lead_id': lead_id}
        mark_idempotent(idem, 1, resp)
        return jsonify(data=resp)
    except DuplicateKeyError:
        return jsonify(data=get_idempotent(idem)['response'], duplicated=True)
    except Exception as e:
        mark_idempotent(idem, 2, str(e))
        raise

location /api/lead {
    proxy_pass http://backend;
    proxy_next_upstream off;        # 失败不切换、不重放 POST
    proxy_connect_timeout 5s;
    proxy_read_timeout 15s;
    # 失败交给前端带着幂等键安全重试，网关自己绝不重放
}
client_body_timeout 15s;