EULA用户协议同意管理：版本快照、幂等落库与审计

简介：这是一份面向 Minecraft 服务端搭建者与运维入门者的配置资源包，围绕电子用户许可协议（EULA）的合规使用展开，同时提供开服所需的参数模板。对于初次架设服务器、需要确认许可条款与核心配置项的用户，可借此理清授权范围、使用限制与各配置文件之间的对应关系，避免因误改参数或忽略条款导致服务无法正常启动。压缩包共 9 个文件，约 6.17MB，以 yml 配置（4 个）、properties 参数文件和 txt 说明文本为主，分别对应服务端核心设置、世界与插件参数及条款标注；另含 2 个 zip 归档用于整合备份，1 个 png 为服务器图标素材，可直接替换使用。已有 284 人学习下载，可作为开服与排错的参照。读者能获得一套可对照使用的服务端配置骨架、EULA 合规要点梳理，以及理解各配置项作用与依赖关系的思路，适合需要快速跑通服务端的中初级用户查漏补缺。

1. EULA 不是一张弹窗：从「点一下同意」到可审计的链路

某公司的 App 上线三个月，业务方临时要一份数据：某用户在 3 月 12 日点同意的时候，看到的是哪一版条款。工程团队翻了一圈数据库，只找到一个 agreed 布尔字段和一个被覆盖过的时间戳，剩下全是黑匣子。这是 EULA 在代码里最常见的处境——大家都当它是个弹窗，其实它是一条链。

EULA 落到工程上要回答四件事：用户看到哪一版文本、从哪个入口进来、什么时候点的同意、这条记录能不能证明没被改过。断一环，后面补都要动数据模型。下面按这条链走：先把条款文本变成可管理的对象，再做前端拦截与点击同意，再落库、查询，最后是版本升级时的灰度重同意与排查。适合正在做客户端首启流程、注册页、SDK 集成验收的同学。

2. 把 EULA 变成可管理对象：版本号、文本快照与哈希

这一章解决的是数据模型问题。很多团队做 EULA 的顺序是反的：先写弹窗组件，再想怎么存。结果组件写完了，发现数据库里没地方放「用户同意的是哪一版」，只能加字段、洗数据、再补一次弹窗。先把文本侧的对象定义清楚，后面所有环节都能少返工。

2.1 只存一个 agreed 布尔值，会丢失哪三样东西

布尔字段的问题不在于它错，而在于它是不可解释的。当业务方拿着一个用户 ID 来问「他到底同意了没有」，你能回答「是」，但回答不了「他同意的是什么」——而后者才是真正被追问的部分。具体丢的是三样东西。

第一是文本版本。条款改过一次措辞，布尔值不会变，你无法区分这个 true 是在旧版上点的还是新版上点的。第二是时间与上下文。被 UPDATE 覆盖过的时间戳等于没有；没有记录入口来源、设备、IP 归属地这类上下文，事后复盘时连「是不是弹窗 bug 导致他误点」都判断不了。第三是不可篡改性。一行可以被 UPDATE 的记录，在审计场景下的证明力接近于零，因为没人能证明它没被改过。

一块布尔值撑不起这些，所以最小可用字段集至少是这样：文档标识、文档版本、文档内容哈希、用户标识、同意发生时间（服务端时间）、入口标识（哪个页面或哪个启动路径）、客户端时区偏移、幂等键。这些字段后面几章会反复用到，先把它们当成一个整体记住。

提示：不要指望「以后再加字段」。同意流水一旦开始积累，补历史数据的成本远高于一开始就把字段留出来，哪怕前几个月只写不读。

2.2 文本快照与规范化哈希：让「同意的是哪一版」可证明

最常见的偷懒做法是数据库里只存一个条款页面的 URL，或者只存一个版本字符串。URL 会失效、页面会被覆盖发布、CDN 缓存会让同一 URL 在不同时间返回不同内容，一旦出现争议，你手里什么都没有。正确做法是每次发布都做一次全文快照：把渲染前的纯文本整段存进文档表，同时算一个内容哈希。

哈希这里有一个经典的坑：不同平台、不同编辑器产出的文本，肉眼一样但字节不同。Windows 换行是\r\n，macOS/Linux 是\n，从 Word 或富文本编辑器粘贴时还可能带 BOM、不间断空格（\u00a0）、行尾多余空格。如果不做规范化就直接哈希，同一份条款在两条发布流水线上会算出两个不同的值，后面按哈希比对时就会莫名其妙地「判定为新版本」，导致全员重弹。

下面这段脚本就是发布流水线里做快照和哈希的那一步，规范化规则必须固定下来并写进注释，否则半年后没人说得清当时的规则是什么。

import hashlib import re import unicodedata def normalize_text(raw: str) -> str: """把任意来源的条款文本规范化为可直接哈希的形态。 规则一旦上线就不能随便改，改了会导致同一份文本算出不同哈希。 """ # 1. 统一换行符：CRLF / CR 一律转成 LF text = raw.replace("\r\n", "\n").replace("\r", "\n") # 2. 去掉 UTF-8 BOM text = text.lstrip("\ufeff") # 3. 不间断空格、全角空格统一成普通空格 text = text.replace("\u00a0", " ").replace("\u3000", " ") # 4. Unicode 归一化，消除「同一个字两种码位」的情况 text = unicodedata.normalize("NFC", text) # 5. 每行去掉行尾空白，避免编辑器自动 trim 造成差异 text = "\n".join(line.rstrip() for line in text.split("\n")) # 6. 压缩连续空行，但保留段落分隔 text = re.sub(r"\n{3,}", "\n\n", text) # 7. 去掉首尾空白，末尾统一补一个换行，保证拼接安全 return text.strip() + "\n" def snapshot(raw: str) -> dict: text = normalize_text(raw) digest = hashlib.sha256(text.encode("utf-8")).hexdigest() return { "content": text, # 存快照正文，不存 URL "content_hash": digest, # 长度 64 的十六进制串 "char_count": len(text), }

这段代码的产出要整段入库，不要只存content_hash。哈希只负责证明「这份内容没变」，快照才负责回答「用户当时看到的是什么」。参数上要注意两点：char_count不是冗余字段，后面做「文本是否异常短」的发布校验时会用到；哈希算法固定用 SHA-256，不要用什么自研的短哈希，碰撞概率和可解释性都不划算。

2.3 版本号语义：哪些改动必须重新弹窗

有了快照，下一个问题是：改到什么时候需要让用户重新同意。如果按「哈希变了就重弹」来做，改一个错别字就会触发全量重弹，转化率会非常难看，这是血泪经验。哈希只适合做完整性校验，不适合做业务判断。

真正该做业务判断的是一个由业务方打标的字段，比如needs_reaccept。工程侧只认这个标志位，不认哈希是否变化。这样做的价值在于：判断权留在内容侧，工程代码不用因为条款措辞调整而发版。

版本号建议用两段式主.次，比如3.2，不要用日期戳。日期戳看起来省事，但它不表达「是否需要重弹」的语义，后期做灰度和回滚时你会希望版本号是有序且可比较的。另外文档表里要保留「上一版指向」，这样查询时能一眼看出某次改动是从哪一版演进过来的，做条款差异对比时直接用得上。

3. 前端同意门禁：首启拦截、滚动到底与键盘路径

文本侧准备好了，接下来是把用户挡在门外的那道闸。门禁设计的目标不是「弹出来」，而是「在正确的时间、正确的层级弹出来，并且能拿到一个可信的同意信号」。这一章讲三个东西：闸门放在哪、组件怎么写、滚动到底这种交互细节怎么不翻车。

3.1 闸门放在哪一层：路由守卫、首屏接口还是原生启动页

三种常见位置，各有取舍，选错了后面很难改。

路由守卫（前端）：实现最省事，一个全局前置守卫查本地缓存，没同意就跳转到同意页。缺点是完全依赖客户端，用户清理缓存或被篡改的客户端绕过它毫无难度。适合纯 Web 且风险不高的场景。

首屏接口拦截（服务端）：任何业务接口在返回数据前先校验该用户是否有当前版本的有效同意记录，没有就返回一个特定状态码，前端据此跳转。这是最可靠的一层，因为它不依赖客户端自觉。代价是每个业务接口都要过一遍校验，通常做成中间件，并加一层短 TTL 的缓存（比如 60 秒）避免每次请求都查库。

原生启动页（客户端）：在 App 启动的最早期、甚至在 WebView 加载之前完成拦截，体验最干净，也最难绕过。适合有原生壳的产品。

我一般的做法是两层配合：客户端启动页或 Web 路由守卫做体验层的快速拦截，服务端中间件做兜底层的真实校验。这样用户不会看到一闪而过的内容，同时客户端被绕过也不会产生脏数据。

有一个硬性约束：门禁必须卡在「任何写操作之前」。如果用户在未同意状态下已经产生了一条业务数据，事后你既不能说这条数据无效，也不能假装他同意过，处理起来非常难受。所以注册、下单、上传这类接口，校验要放在最前面。

3.2 一个可复用的同意弹窗组件与提交逻辑

组件要处理的事情比想象中多：加载文本、判断是否已滚到底、勾选后才能提交、提交失败要能重试、提交中要防重复点击。下面是一个不依赖框架的实现，用原生 DOM 写清楚状态机，套到任何框架里都只是换写法。

// 同意弹窗：文本加载 -> 滚动判定 -> 勾选 -> 提交 -> 失败重试 export function mountConsentDialog({ docVersion, textUrl, onSubmit }) { const state = { loaded: false, reachedEnd: false, checked: false, submitting: false, }; const root = document.createElement('div'); root.className = 'consent-mask'; root.innerHTML = ` <div class="consent-panel" role="dialog" aria-modal="true" aria-labelledby="consent-title"> <h2 id="consent-title">条款确认</h2> <div class="consent-body" tabindex="0" aria-label="条款正文"></div> <label class="consent-check"> <input type="checkbox" disabled /> 我已阅读并同意上述条款 </label> <button class="consent-submit" disabled>确认</button> <p class="consent-tip"></p> </div>`; const body = root.querySelector('.consent-body'); const checkbox = root.querySelector('input[type=checkbox]'); const submit = root.querySelector('.consent-submit'); const tip = root.querySelector('.consent-tip'); // 1. 拉取正文。用纯文本接口，不要直接塞 HTML，避免样式污染和注入风险 fetch(textUrl, { credentials: 'same-origin' }) .then((r) => r.text()) .then((text) => { body.textContent = text; state.loaded = true; // 内容不足以产生滚动条时，直接视为已读完，否则用户永远点不了 if (body.scrollHeight <= body.clientHeight + 4) { state.reachedEnd = true; checkbox.disabled = false; } }) .catch(() => { tip.textContent = '条款加载失败，请检查网络后重试'; }); // 2. 滚动判定：留 4px 容差，处理缩放和小数像素 const onScroll = () => { const remain = body.scrollHeight - body.scrollTop - body.clientHeight; if (remain <= 4 && !state.reachedEnd) { state.reachedEnd = true; checkbox.disabled = false; } }; body.addEventListener('scroll', onScroll, { passive: true }); // 3. 勾选后才允许提交 checkbox.addEventListener('change', () => { state.checked = checkbox.checked; submit.disabled = !(state.checked && state.reachedEnd); }); // 4. 提交：防重复点击，失败可重试，幂等键交给上层生成 submit.addEventListener('click', async () => { if (state.submitting || !state.checked) return; state.submitting = true; submit.disabled = true; tip.textContent = '提交中…'; try { await onSubmit({ docVersion }); root.remove(); } catch (err) { // 失败不销毁弹窗，用户的选择要保留，只放开按钮 tip.textContent = '提交失败，请重试'; state.submitting = false; submit.disabled = false; } }); document.body.appendChild(root); body.focus(); return root; }

逻辑上要说明几点。第一，正文用textContent而不是innerHTML，条款文本属于外部输入，走 HTML 渲染就是在给自己找麻烦。第二，滚动判定写成函数而不是内联，是因为后面还要在ResizeObserver里复用，字体异步加载会改变scrollHeight，只监听scroll会漏掉这种情况。第三，提交失败时不能销毁弹窗，用户的勾选状态必须保留，否则重试成本会让人直接退出。

参数上，onSubmit由调用方传入，它负责生成幂等键并调用接口，组件本身不关心后端地址和鉴权方式，这样同一个组件在注册流程、设置页、SDK 授权页都能复用。docVersion必须原样传给服务端，服务端据此判断用户同意的是不是当前生效版本，不能信任前端自己判断。

3.3 滚动到底判定：像素容差与无障碍的三个细节

滚动判定是玄学重灾区。scrollTop + clientHeight === scrollHeight这种写法在真机上大概率永远不成立，因为浏览器缩放、系统字体缩放、设备像素比都会让这几个值带小数。必须用容差比较，remain <= 4是个经验值，高分屏上偶尔要给到 8。

第二个坑是动态高度。条款里有图片、有异步加载的字体、有折叠展开的附录章节，scrollHeight在加载过程中会变。只监听scroll事件，用户可能在高度还没稳定时就滑到了底部，然后判定不通过，体验很差。加一个ResizeObserver监听正文容器，高度变化时重新计算一次。

第三个是键盘与读屏路径。用户可能全程用键盘操作，Tab聚焦到正文容器后按End键跳到末尾，这种情况下scroll事件在多数浏览器会触发，但 Safari 上偶有不触发的情况。稳妥做法是同时监听keydown，捕获End、PageDown时主动调用一次判定函数。正文容器要加tabindex="0"才能被聚焦，同时aria-label要写清楚这是条款正文，否则读屏用户不知道这个可聚焦区域是什么。

还有一个容易忽略的边界：条款极短时容器没有滚动条，此时scrollHeight === clientHeight，如果不做特殊处理，用户永远无法勾选，弹窗会变成一个死锁。上面代码里在文本加载完成时做了这一层判断，这个分支一定要留。

注意：不要用「等 3 秒自动解锁勾选框」这类替代方案。它既不能证明用户读过，也会在审计时变成一条说不清的设计。

4. 后端落库与审计：一次同意一条记录，永不 UPDATE

前端拿到同意信号之后，真正的证明力在后端。这一章的核心原则只有一句：一次同意一条记录，只插入，不更新，不删除。所有看起来需要「更新同意状态」的需求，本质上都应该用「再插一条新记录」来表达。

4.1 两张表的表结构：文档快照表与同意流水表

文档表存版本和快照，流水表存每一次同意行为。两张表通过content_hash关联，而不是通过自增 ID，因为哈希是内容本身的身份，天然支持跨环境比对。

-- 条款文档表：每发布一版插一条，永不修改 CREATE TABLE eula_document ( id BIGSERIAL PRIMARY KEY, doc_key VARCHAR(64) NOT NULL, -- 文档标识，如 'user_agreement' version VARCHAR(32) NOT NULL, -- 两段式版本号，如 '3.2' prev_version VARCHAR(32), -- 上一版版本号，便于做差异对比 content TEXT NOT NULL, -- 规范化后的全文快照 content_hash CHAR(64) NOT NULL, -- SHA-256，十六进制 needs_reaccept BOOLEAN NOT NULL DEFAULT FALSE, published_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (doc_key, version) ); -- 同意流水表：只允许 INSERT，不允许 UPDATE / DELETE CREATE TABLE eula_acceptance ( id BIGSERIAL PRIMARY KEY, user_id BIGINT NOT NULL, doc_key VARCHAR(64) NOT NULL, doc_version VARCHAR(32) NOT NULL, content_hash CHAR(64) NOT NULL, accepted_at TIMESTAMPTZ NOT NULL DEFAULT now(), -- 服务端时间，不信客户端 entry_point VARCHAR(64) NOT NULL, -- 'app_first_launch' / 'signup' ... tz_offset_min SMALLINT NOT NULL DEFAULT 0, -- 客户端时区偏移，分钟 device_id VARCHAR(128), request_id VARCHAR(64) NOT NULL, -- 幂等键 UNIQUE (request_id) ); CREATE INDEX idx_acceptance_user_doc ON eula_acceptance (user_id, doc_key, accepted_at DESC);

几个设计点值得说。accepted_at用TIMESTAMPTZ并且由数据库now()生成，客户端传上来的时间只能作为参考字段另存，绝不能作为审计依据——跨时区、设备时间被手动修改，都会让记录失真。tz_offset_min单独存，是为了还原「用户当时本地是几点」，这个在客诉沟通时非常有用。

request_id上的唯一索引是整个幂等机制的基石。网络抖动导致客户端重试、用户连点两次、消息队列重复投递，这些场景都会被这个唯一约束挡在门外，不会产生重复流水。

至于「不可篡改」，光靠自律是不够的。执行层面至少做两件事：数据库账号层面收回流水表的UPDATE/DELETE权限，应用只持有INSERT和SELECT；关键业务再加一层触发器，任何更新尝试直接抛异常。

-- 兜底触发器：任何更新或删除都拒绝 CREATE OR REPLACE FUNCTION reject_acceptance_mutation() RETURNS TRIGGER AS $$ BEGIN RAISE EXCEPTION 'eula_acceptance is append-only'; END; $$ LANGUAGE plpgsql; CREATE TRIGGER trg_acceptance_no_update BEFORE UPDATE OR DELETE ON eula_acceptance FOR EACH ROW EXECUTE FUNCTION reject_acceptance_mutation();

这段触发器看起来有点武断，但它换来的是审计时的一句「这张表改不了」。真需要「撤销同意」这类业务语义时，正确做法是插入一条action_type = 'revoke'的新记录，而不是去改历史行。视图层再做一次聚合，取每个用户每个文档的最新有效状态。

4.2 写入接口：幂等键、服务端时间与失败重试

接口层要做的校验有四条：doc_key和doc_version必须在文档表里存在且哈希一致；该用户在该文档上是否已有同版本记录（有就返回成功，不报错）；幂等键是否重复；用户是否处于可同意状态（比如账号未被冻结）。

from datetime import datetime, timezone from fastapi import APIRouter, HTTPException, Header from pydantic import BaseModel, Field router = APIRouter() class AcceptPayload(BaseModel): doc_key: str = Field(..., max_length=64) doc_version: str = Field(..., max_length=32) entry_point: str = Field(..., max_length=64) tz_offset_min: int = Field(0, ge=-840, le=840) # UTC-14 ~ UTC+14 device_id: str | None = Field(None, max_length=128) @router.post("/eula/accept", status_code=201) def accept_eula( payload: AcceptPayload, user_id: int, x_request_id: str = Header(..., alias="X-Request-Id"), ): # 1. 幂等：同一个 request_id 直接返回已有记录，不重复写 existing = db.fetch_one( "SELECT id FROM eula_acceptance WHERE request_id = %s", (x_request_id,) ) if existing: return {"ok": True, "acceptance_id": existing["id"], "duplicated": True} # 2. 校验文档存在，并拿到服务端可信的哈希（不信客户端传的哈希） doc = db.fetch_one( "SELECT content_hash FROM eula_document WHERE doc_key = %s AND version = %s", (payload.doc_key, payload.doc_version), ) if not doc: raise HTTPException(status_code=409, detail="unknown_document_version") # 3. 已同意过同版本，直接视为成功，避免重复弹窗 dup = db.fetch_one( """SELECT id FROM eula_acceptance WHERE user_id = %s AND doc_key = %s AND doc_version = %s LIMIT 1""", (user_id, payload.doc_key, payload.doc_version), ) if dup: return {"ok": True, "acceptance_id": dup["id"], "duplicated": True} # 4. 插入流水，时间由数据库 now() 生成，客户端时间不入审计字段 row = db.fetch_one( """INSERT INTO eula_acceptance (user_id, doc_key, doc_version, content_hash, entry_point, tz_offset_min, device_id, request_id) VALUES (%s, %s, %s, %s, %s, %s, %s, %s) RETURNING id""", (user_id, payload.doc_key, payload.doc_version, doc["content_hash"], payload.entry_point, payload.tz_offset_min, payload.device_id, x_request_id), ) return {"ok": True, "acceptance_id": row["id"], "duplicated": False} @router.get("/eula/status") def eula_status(user_id: int, doc_key: str): """返回该用户当前生效版本是否已同意，供前端决定是否弹窗。""" latest = db.fetch_one( """SELECT version, content_hash FROM eula_document WHERE doc_key = %s ORDER BY published_at DESC LIMIT 1""", (doc_key,), ) if not latest: raise HTTPException(status_code=404, detail="no_document") accepted = db.fetch_one( """SELECT id, accepted_at FROM eula_acceptance WHERE user_id = %s AND doc_key = %s AND doc_version = %s ORDER BY accepted_at DESC LIMIT 1""", (user_id, doc_key, latest["version"]), ) return { "doc_key": doc_key, "current_version": latest["version"], "accepted": bool(accepted), "accepted_at": accepted["accepted_at"] if accepted else None, }

说明一下几个参数选择。tz_offset_min用分钟而不是小时，是因为存在半小时和 45 分钟时区的用户，用小时会丢精度；范围限制在 ±840 是 UTC±14 的边界。幂等键走请求头而不是 body，方便网关和客户端统一注入，也避免业务字段混进业务体。

重试策略上，客户端拿到 5xx 或超时就该重试，但必须复用同一个X-Request-Id。如果重试时换了新的幂等键，唯一约束就形同虚设。反过来，服务端返回 409 表示版本不存在，这是不可重试的错误，客户端应该重新拉一次状态接口并刷新弹窗内容。

/eula/status这个接口看似简单，但它是整个前端门禁的数据源。它必须返回「当前生效版本」和「是否已同意当前版本」两个信息，而不是返回一个笼统的agreed布尔值。前端不要把版本判断逻辑写死在代码里，那样每次改条款都要发版。

4.3 审计查询：怎么回答「某用户在某时同意了什么」

审计查询通常有两类。一类是「某用户当前状态」，一类是「某个时间点的历史快照」。前者是上面那个 status 接口，后者需要一个按时间窗口查询的 SQL。

-- 查询某用户在指定时间点前，对某文档的最后一次有效同意 SELECT a.doc_version, a.content_hash, a.accepted_at, a.entry_point, a.tz_offset_min, d.content -- 当时的条款全文，用于取证 FROM eula_acceptance a JOIN eula_document d ON d.doc_key = a.doc_key AND d.version = a.doc_version WHERE a.user_id = %(user_id)s AND a.doc_key = %(doc_key)s AND a.accepted_at <= %(at_time)s ORDER BY a.accepted_at DESC LIMIT 1;

这条 SQL 的价值在于第三列和第六列同时出现：accepted_at回答「什么时候」，content回答「同意的是什么」。两者结合，才算把「可审计」这件事做完整了。如果只关联出doc_version，一旦文档表用的是软删除或版本被覆盖，取证时还得再翻备份。

另一个常用查询是版本维度的统计：某个版本发布后，各入口的同意转化率、平均同意时长、放弃率。这类查询走流水表按doc_version和entry_point分组就行，注意排除duplicated的重试记录，否则转化率会虚高。做这件事的前提是流水表里有entry_point，这也是为什么前面强调入口字段不能省。

5. 避坑与排查：EULA 上线后最容易翻车的 5 个点

这一章的每一条都来自真实会发生的场景，按「现象 → 原因 → 解决」写，遇到对得上的直接照方抓药。

5.1 同一用户多端反复弹窗：本地缓存键设计踩空

现象：同一个账号在 Web 端点过同意，换到 App 端又被弹一次，来回切几次每次都弹。

原因：本地缓存的 key 里带了端标识、渠道号、甚至构建版本号，各端各存一份，服务端从来没被当作权威数据源。前端逻辑是「本地没有就弹」，而不是「服务端说没同意才弹」。

解决：把/eula/status作为唯一判据，本地缓存只做一次启动内的加速，key 统一成doc_key + user_id，不带任何端相关前缀。App 冷启动时先读本地缓存命中就直接放行，同时异步请求 status 做一次校正，不一致时以服务端为准并覆盖本地缓存。这个「先用缓存、后校正」的写法能兼顾体验和正确性。

5.2 改个错别字全员重弹：把哈希当成了版本判据

现象：运营改了一个错别字，第二天全量用户弹窗，注册转化掉了几个点，客服被打爆。

原因：判断是否需要重弹的逻辑写成了「当前文档哈希 ≠ 用户记录的哈希」，哈希一变就弹。而哈希对任何字节变化都敏感，标点、空格、换行都算。

解决：改成看needs_reaccept标志位，同时判断doc_version是否已经存在于用户的同意记录中。哈希只用于校验快照完整性，不参与业务判断。发布流程里再加一条校验：如果needs_reaccept = false但版本的主版本号变了，直接卡住发布，强制发布人确认这是否是真的不需要重弹。

5.3 记录写进去了审计时不认：UPDATE 覆盖与客户端时间

现象：业务方要求出具某用户的历史同意记录，导出后发现时间戳比用户实际操作时间差了几个小时，甚至出现「同意时间早于注册时间」。

原因：accepted_at用的是客户端传上来的本地时间，且写入时用了ON CONFLICT DO UPDATE覆盖旧记录，导致历史被抹掉。跨时区用户的时间直接错位。

解决：审计字段一律用服务端时间（数据库now()或应用服务器 UTC 时间），客户端时间单独存一个client_reported_at作为参考。写入方式改为纯INSERT，冲突处理只做「已存在则跳过」不做「覆盖」。再加一个约束：accepted_at不得早于用户注册时间，异常数据在写入时就暴露出来。

5.4 滚动到底不触发：浮点像素与动态高度

现象：部分安卓机型和浏览器缩放到 110% 时，用户明明滑到了底部，勾选框还是灰的，客诉集中在特定机型。

原因：判定用了严格相等，而scrollHeight - scrollTop - clientHeight在这种环境下算出的是 0.5 或 1.2 这种小数。另外条款里有异步加载的图片，scrollHeight在滑动过程中还在增长。

解决：容差比较，remain <= 4起步，极端机型给到 8。同时用ResizeObserver监听正文容器，高度变化后重新判定一次。再加一条兜底：如果用户点击勾选框时判定仍未通过，但remain小于 20，直接放行并记录一条埋点，观察这个分支的触发频率，用数据反推容差是否合适。

5.5 离线同意联网后丢失：没有补签队列

现象：用户在弱网或飞行模式下完成了同意，恢复网络后重新打开又弹一次。

原因：提交请求失败后只在前端弹了「提交失败」，没有本地持久化待提交记录，用户关掉页面就彻底丢了。

解决：提交失败时把{doc_key, doc_version, entry_point, tz_offset_min, request_id}写进本地持久化存储（不要放内存），标记为待补签。应用启动或网络恢复时重放队列，复用同一个request_id保证幂等。重放成功后清掉队列项，服务端返回duplicated: true也视为成功。这个队列要有上限（比如 20 条）和过期时间（比如 7 天），避免长期堆积。

注意：补签队列里的request_id必须在首次生成时就固定下来并持久化，重放时重新生成会让幂等约束失效。

6. 灰度重同意：版本升级时怎么让老用户不被弹窗劝退

needs_reaccept = true的版本发布，通常是产品最紧张的时刻之一。全量弹窗的代价是实打实的：如果同意率掉 10%，等于凭空少了一批活跃用户。我一般的做法是分三批放量，每一批观察四个指标：弹窗触达率、同意完成率、平均停留时长、放弃后 7 日回访率。前三批的节奏大致是 5% → 25% → 全量，每批之间至少留 24 小时，避开周末和业务大促。

分批的维度不要随机打散，按用户 ID 哈希取模比较稳，既保证同一用户始终落在同一批，也避免新老用户分布偏差。第一批建议排除高价值用户和刚注册 7 天内的新用户，前者影响面大，后者本来就处在流失边缘。

6.1 一条 SQL 兜住「无有效同意仍在产生数据」的漏网用户

灰度期间最怕的不是弹窗多，而是有人绕过了门禁还在写数据。巡检脚本每天跑一次，找出「当前生效版本需要重新同意、但该用户已经在版本发布后产生了业务数据」的人。这批人要么是门禁漏洞，要么是补签队列没重放成功，都值得单独看。

-- 找出需要重新同意、但在新版发布后仍产生业务数据的用户 WITH latest AS ( SELECT doc_key, version, published_at FROM eula_document WHERE doc_key = 'user_agreement' AND needs_reaccept = TRUE ORDER BY published_at DESC LIMIT 1 ) SELECT o.user_id, COUNT(*) AS order_cnt, MIN(o.created_at) AS first_order_at, l.version AS required_version FROM orders o CROSS JOIN latest l WHERE o.created_at >= l.published_at AND NOT EXISTS ( SELECT 1 FROM eula_acceptance a WHERE a.user_id = o.user_id AND a.doc_key = l.doc_key AND a.doc_version = l.version ) GROUP BY o.user_id, l.version ORDER BY order_cnt DESC LIMIT 200;

orders换成实际的业务表即可，要点是CROSS JOIN最新版本、NOT EXISTS反查同意记录、时间窗口从版本发布时间开始。结果里order_cnt排序靠前的用户优先人工核查，如果数量级很大，说明门禁中间件压根没生效，先回去查中间件的注册顺序，而不是一条条补数据。

另外，重同意的文案值得单独打磨。同一份条款，入口页写「条款已更新，请确认后继续使用」，比写「请重新阅读并同意用户协议」的完成率通常高不少，前者给了一个理由。这个 A/B 测试成本极低，值得在灰度第一批就做掉。

我自己在这个方向上最大的教训，是早期把 EULA 当成一个 UI 需求排期，字段设计交给了「后面再补」，结果第一版只存了布尔值，半年后为了应付一次审计，团队花了三周做数据回捞和历史重建，期间还发现有一批记录的客户端时间戳是错的，根本没法用来举证。从那以后我的习惯是：任何涉及「用户声明」的功能，先把流水表的字段和不可变约束定下来，UI 反而可以慢慢改。希望帮到你。

本文还有配套的精品资源，点击获取