业务全景架构图
架构总图：《掘金・挖矿小精灵 V1.3‑LD‑M》业务全景架构。 遵循狂潮元理论双流模型；所有外部输入必经异源校验闸门；独立审计通道只观测不干预业务；48h 为唯一快照节拍；业务事件防重不防丢，丢失仅审计，不做业务重试补偿。(全景图代码见文尾注释）
🚀 《掘金・挖矿小精灵》完整产品与系统架构设计（V1.3）
〇、版本修订说明
在 V1.2 基础上，依据元理论审查补齐以下机理缺口（本版只做机理层补全，不改产品创意）： ① 时序版本化 ：矿脉被动返还积分绑定 48h 结算快照版本；沸点驱动的「种草积分 + 体力恢复」两套业务消费同一带版本标准化事件，消除跨窗口错位。 ② 队列竞争仲裁 ：MQ 任务取出执行前二次校验精灵体力，杜绝负体力。 ③ 权限归属收敛 ：「有效沸点」判定逻辑收口到安全审核闸门，原始沸点载荷不下透下游，精灵模块禁止解析原始沸点。 ④ 事件 ACK 与报备 ：矿脉积分返还事件落库 ACK；积分返还、体力变更事件强制进入独立报备审计通道。 ⑤ 能量带上限补齐 ：新增单用户 48h 矿脉积分返还上限、单用户 48h 沸点恢复体力上限，防通胀刷分。 ⑥ 随缘贯彻（关键立场） ：所有事件丢失即丢弃，不做重试补偿，只上报观测------ 契合 "随缘、错过就错过"，不强做强一致性补偿。
一、核心世界观与生态定义（产品定位）
打破传统的 "工具人" 社交，建立一个基于「知识资产（笔记）+ 情绪能量（沸点）+ 赛博宠物（精灵）」的轻量级自治生态。
- 生态法则：简单粗暴。有活跃度（沸点）就有防御力（种草），没有防御力，你的知识资产（笔记）就会被别人的精灵掠夺。
- 随用随灭 ：不建长期社交关系，一切凭缘分。周期以 48 小时为唯一节拍，错过了就错过了------ 不设 "每日必看"" 每日必收 "，你不在线，精灵照常溜达，结果 48h 后自然过期，无人提醒、无人补偿。
- 微循环经济：精灵挖矿成功 → 矿主被动返还基础积分 → 矿主用积分种草护矿 → 降低被挖概率；积分不再单向消耗，形成闭环。
二、核心双流模型映射（底层逻辑）
用《狂潮元理论》统御整个系统，确保高内聚、低耦合，防止状态污染。任何环节（包括 "无 / 空 / 停" 状态）强制拆两条链路，严禁混杂。
📦 权限 - 状态流（资产与状态）
- 笔记资产（矿山）：公开可挖 / 私密不可挖（私密硬锁，绝对不进矿池）。
- 沸点能量 ：转化规则 = 48 小时窗口内沸点活跃度 → 种草积分。
- 精灵状态：Level、心情、体力（上限 5）、当前背包。
- 漂流信箱状态：吐槽包裹、碎片包裹、产生时间戳、署名标记、阅后即焚标记、过期 TTL（48h）。
- 矿脉微循环状态：笔记被成功挖矿的历史标记 + 所属 48h 结算快照版本号。
- 经济事件记录：矿脉积分返还记录、体力变更记录（均绑定快照版本）。
⚙️ 边界 - 执行流（调度与规则）
- 溜达任务调度器：控制精灵何时出门、去哪（异步 MQ 派发）。
- 挖矿与防御判定引擎：计算草量与挖矿成功率。
- 安全审核闸门（含 "有效沸点" 判定）：隔离违规吐槽、判定有效沸点、防污染社区。
- 节拍器（48h）：统一驱动结算、限流窗口、过期销毁、活跃池刷新、体力自动回满。
- 独立报备审计通道：承接所有异常与经济事件上报（不复用业务主链路）。
"无" 状态双流强制拆解：
- 信箱清空：状态流 = 载荷全部销毁；执行流 = 拒绝新读取、允许新写入。
- 精灵体力 = 0 ：状态流 = 体力计数为 0；执行流 = 调度器拒绝派发新溜达任务，且已入队任务取出执行前二次校验，体力不足则 ABORT 返回 IDLE。
- 用户关闭精灵悬浮面板：状态流 = 精灵内存实例保留；执行流 = 前端停止推送气泡，但后端异步溜达任务继续运行（关闭面板 ≠ 停止挖矿）。
- 调度队列为空：状态流 = 任务队列空；执行流 = 调度器休眠，不主动产生新任务。
三、完整功能模块拆解（模块结构）
模块 1：矿洞系统（笔记沉淀）
- 矿山生成：用户发布的公开笔记自动转化为 "矿脉"。
- 高光碎片：系统自动抽取笔记核心金句 / 代码段，作为可被挖走的 "高价值矿石"。
- 私密锁死：标记为私密的笔记绝对不会进入挖矿池（硬编码死锁）。
- 状态变更事件 ：矿山被标记私密 / 删除时，产生事件，调度器消费后终止该矿山的在途溜达任务。
- 挖矿成功事件（微循环触发源）：笔记被成功挖矿时，输出带 48h 快照版本号的事件，供防御系统做被动积分返还。
模块 2：防御系统（沸点联动与种草）
- 能量转化：系统每 48 小时 结算一次用户近 48 小时的沸点发布 / 互动数据，生成 "种草积分"（结算带快照版本号）。
- 种草护矿：用户可将积分消耗在指定笔记上，增加 "草量（防御值）"。
- 防御判定：草量越高，别人家精灵来溜达时被 "弹开" 的概率越大。
- 被动返还（微循环）：接收矿洞挖矿成功事件（带快照版本），按所属周期向矿主返还基础积分；返还落库需 ACK，失败上报审计、丢弃不补偿。
- 上限约束：单用户每 48h 矿脉被动返还积分设置上限，防止通胀。
模块 3：精灵系统（AI 状态机与行为）
- 精灵面板：右下角悬浮气泡，点开查看精灵状态、战利品、操作面板。
- 体力系统：上限 5；每次溜达消耗 1 点；两种恢复途径 ------48h 节拍自动回满 / 消费安全闸门输出的「有效沸点」标准化事件 +1 点。
- 溜达机制（漂流演化）：精灵定期（异步）离开主页，随机去往另一个活跃用户矿洞。
- 行为触发：
- 挖矿成功：叼回别人未被草覆盖的笔记碎片。
- 吐槽投递：把你的匿名情绪（一键生成吐槽），扔给对方。
- 溜达频次上限 ：单个精灵每 48 小时溜达上限 5 次（与体力上限联动）。
- 恢复上限：单用户每 48h 沸点恢复体力设上限（可大于体力上限 5），防止批量刷沸点拉满体力。
模块 4：漂流信箱（匿名情绪交互）
- 匿名接收：只展示精灵带回的吐槽内容和挖到的知识碎片，绝对不显示对方是谁（除非对方主动署名）。
- 极简回响：接收方可选「点赞 / 踩 / 收入我的笔记 / 阅后即焚」。
- 杜绝骚扰：不提供评论 / 私信功能。
- 生命周期（统一 48h） ：信箱内的吐槽与碎片保留 48 小时 ；用户 "阅后即焚" 或超时后，物理删除。48h 内未领取的漂流，过期即焚，不通知、不补偿。
四、精灵行为状态机（核心运转逻辑）
每一次行动经过严格状态流转（防并发死锁），并带超时 ABORT 兜底 + 下游 ACK 确认：
- IDLE（闲置）：精灵待在用户主页。
- WANDERING（溜达中） ：后台异步任务，从活跃池随机抽取目标用户 A（取出执行前二次校验体力，不足即 ABORT 返回 IDLE）。
- CHECKING（判定中） ：
- 检索 A 的公开笔记，计算总草量（防御值）。
- 计算己方精灵挖矿成功率（按发起方近 48h 沸点活跃度）。
- 超时兜底：CHECKING 超过 5s 未完成 → 强制 ABORT 返回 RETURNING。
- MINING（挖矿 / 投信） ：
- 前置二次私密校验：再次确认目标笔记仍为公开，封堵并发窗口。
- 判定成功：获取 A 一枚笔记碎片 + 将吐槽包裹留在 A 的信箱。
- 判定失败（被草弹开）：空手而归，只留吐槽包裹。
- 写入 ACK：信箱写入成功后返回 ACK 给调度任务；ACK 失败则任务标记异常，进入报备审计。
- 触发微循环：挖矿成功 → 输出带快照版本的挖矿成功事件 → 防御系统被动返还积分（落库 ACK，失败上报、不重试）。
- 超时兜底：MINING 超过 5s 未完成 → 强制 ABORT 返回 RETURNING。
- RETURNING（回归）：状态切回 IDLE，前端弹气泡："你家小精灵挖矿回来了 / 被揍了"。
五、安全与风控架构（护城河）
- UGC 审核前置 ：吐槽必须过掘金敏感词审核 API + 本系统二次最小校验（长度、基础格式），不通过拦截在本地。
- 有效沸点判定收口 ：判定逻辑统一放在安全审核闸门，输出带快照版本的标准化沸点事件 （供种草积分、体力恢复两套业务消费）；原始沸点载荷不向下游透传。
- 防骚扰限流（随 48h 节拍统一） ：
- 单精灵 48 小时溜达上限 5 次（与体力联动）。
- 同一对用户之间，48 小时内最多互相溜达 1 次。
- 隐私隔离：实名信息、浏览记录严禁经精灵对外泄露。
- 数据销毁（统一 48h） ：漂流吐槽与碎片保留 48 小时；"阅后即焚" 或超时后物理删除，绝不永久留存。
- 异源校验闸门 ：外部输入（笔记原文、沸点统计、掘金敏感词 API 返回）均视为有毒异源潜在输入 ，必须经独立安全审核闸门做二次最小校验；校验主体必须与业务模块结构相异，严禁精灵业务模块自己校验外部异源输入。
六、底层技术架构支撑（系统设计）
前端（Web / 插件）
- Vue/React 轻量组件；Canvas 渲染精灵动画，不阻塞主页面渲染。
- 皮肤独立渲染层：皮肤层仅做视图渲染，禁止篡改业务状态；为后续商业化皮肤预留隔离边界。
后端（微服务）
- Spring Boot / Go
- 网关层：鉴权 + 限流。
- 业务层：积分计算服务、笔记服务、精灵交互服务。
- 异步调度：RabbitMQ / Kafka，处理精灵溜达高并发异步派发。
- 存储层：Redis 缓存活跃池与精灵状态（TTL 过期销毁）；MySQL 存积分账本与持久笔记映射。
能量带（资源上限）
- MQ 任务：定义最大并发、任务最大存活时长、过载暂停策略、重试上限（防隐形叠权）。
- 信箱：单用户最大包裹数量上限。
- 批量结算（每 48h 沸点统计）：限速，防打垮上游掘金原始库。
- 经济上限：单用户每 48h 矿脉被动返还积分上限；单用户每 48h 沸点恢复体力上限。
数据一致性
- 积分结算携带快照版本号：结算期间产生的新沸点进入下一轮快照，避免新旧统计混杂回灌。
- 矿脉挖矿成功事件携带所属 48h 快照版本号：返还逻辑只匹配对应周期快照，防跨窗口重复 / 漏发。
- 沸点双业务快照对齐：安全闸门输出带快照版本的标准化沸点事件，种草积分与体力恢复两套逻辑消费同一事件源。
- Redis 活跃池与 MySQL 状态：双副本带版本标识，写 MySQL 时主动失效 Redis 缓存，防读过期数据。
可观测性
- 建立独立事件报备通道 ，不复用业务主链路：投递失败、审核拦截、任务丢弃、缓存不一致、矿脉积分返还、体力变更等事件统一上报，支持归并降采样，避免日志风暴。
- 随缘立场：事件丢失即丢弃，只上报观测，不做重试补偿，契合产品哲学。
七、权限原子化协议（六维约束）
每个核心模块定义「核心职责 / 私有状态 / 可公开状态 / 允许接收输入 / 允许发出输出 / 越界黑名单」。
模块 3（精灵系统）
- 核心职责：管理精灵实例状态机、体力与溜达行为。
- 私有状态：精灵内部状态机、体力值、心情、背包、今日溜达计数（外部禁止读写）。
- 可公开状态：当前状态（IDLE/WANDERING...）、战利品摘要、体力值（标准化事件推送，禁止外部直接写）。
- 允许接收输入：溜达任务派发事件、挖矿判定结果事件、安全闸门输出的有效沸点标准化事件（用于体力恢复）。
- 允许发出输出：挖矿任务请求、回归提示事件、体力变更事件。
- 越界黑名单：禁止直接写漂流信箱；禁止修改笔记原文、用户沸点数据；禁止解析原始沸点内容；禁止自行判定 "有效沸点"。
模块 2（防御系统）
- 核心职责：48h 沸点结算、种草积分账本、草量防御值管理、矿脉被动返还积分。
- 私有状态：积分账本、结算快照、矿脉挖矿成功事件记录（含快照版本号）（外部禁止读写）。
- 可公开状态：当前种草积分、草量防御值（标准化事件推送）。
- 允许接收输入：沸点标准化统计事件（经异源闸门校验）、矿洞挖矿成功事件（带快照版本）。
- 允许发出输出：种草积分变更事件、草量更新事件、积分返还落库 ACK。
- 越界黑名单：禁止直接读取 / 改写用户笔记原文；禁止覆盖结算快照版本；禁止直接接收原始沸点载荷，只能接收经异源闸门输出的标准化事件。
模块 1（矿洞系统）
- 核心职责：公开笔记→矿山映射、高光碎片抽取、私密硬锁、挖矿成功事件输出。
- 私有状态：矿山映射表、私密锁名单、碎片原始内容、挖矿成功历史标记。
- 可公开状态：可挖矿山清单、高光碎片、挖矿成功事件（标准化事件推送）。
- 允许接收输入：笔记发布 / 修改 / 私密化事件（来自掘金异源，经闸门校验）。
- 允许发出输出：矿山状态变更事件、碎片供给、挖矿成功事件（带快照版本）。
- 越界黑名单：禁止修改用户原始笔记、禁止对外泄露私密笔记、禁止跨用户读取笔记、禁止直接写积分账本（只输出事件）。
模块 4（漂流信箱）
- 核心职责：吐槽 / 碎片包裹的匿名存取、48h 过期销毁、阅后即焚。
- 私有状态：信箱载荷、产生时间戳、TTL 标记（外部禁止读写）。
- 可公开状态：接收方可读的匿名消息（阅后即焚后即销毁）。
- 允许接收输入：精灵投递包裹（带 ACK）、用户操作（点赞 / 踩 / 收入笔记 / 即焚）。
- 允许发出输出：写入成功 ACK、消息展示事件。
- 越界黑名单：禁止显示发送方实名、禁止超期保留数据、禁止评论 / 私信。
八、五类耦合遍历（旺 - 生 - 休 - 克 - 死）
- 生（单向供给）：矿洞系统→判定引擎（矿山 / 碎片 / 挖矿成功事件）；防御系统→判定引擎（草量）；溜达调度器→精灵系统（派发任务）。✅矿洞只输出事件，不写积分账本；防御只消费标准化事件，不读原始沸点。
- 旺（双向增益） ：
- 精灵系统 ↔ 漂流信箱（精灵写包裹、信箱状态回影响回归展示；ACK + 超时 ABORT 兜底）。
- 精灵系统 ↔ 防御系统（新增）：精灵挖矿触发防御积分返还；防御产出种草积分反向改变草量，影响挖矿成功率。⚠️账本故障会反向影响挖矿判定，需积分变更事件进报备观测。
- 克（约束压制） ：安全闸门克精灵（拦截吐槽）；限流克调度器（48h 计数上限压制派发）；TTL 过期克信箱；体力 = 0 克调度器（拒绝新派发 + 已入队任务取出前二次校验 ABORT）。
- 休（休眠≠删除）：精灵 IDLE、体力 = 0（实体仍在、不可出行）、信箱为空。
- 死（破坏前置依赖）：笔记置私密→矿山移除；产生事件终止在途任务 + MINING 阶段二次私密校验拦截（双保险）。
九、五类运行工况预判（稳态→偏移→冲突→分裂→崩溃）
- 稳态：负载适中，48h 限流与体力约束生效，缓存版本对齐，信箱未满，经济闭环正常。
- 偏移态：个别 ACK 丢包、少量积分返还漏发 / 重复、体力异常；不自愈，依赖运维观测。
- 冲突态：挖矿事件跨结算窗口积分重复返还；批量刷沸点导致体力溢出；多任务并发造成负体力。
- 分裂态（多实例）：Redis 缓存体力、积分状态与 MySQL 账本视图割裂，不同调度器看到不同精灵体力。
- 崩溃态：MQ 任务爆炸、信箱打爆、积分 / 体力异常蔓延，生态经济模型失效。
工况驱动诱因提示：引入微循环经济后，经济模型漏洞（通胀 / 通缩）可将系统直接从稳态推向冲突态，是本版本最值得监控的故障源。
十、同源 - 叠权专项分析（同源自噬公理体系）
- 同源回流点位更新 ：
- 精灵战利品、漂流包裹写回背包 / 信箱再展示（轻量回流）；48h 过期销毁缩短脏数据滞留期。
- 微循环闭环：挖矿成功→返还积分→种草护矿→降低被挖概率，系统输出再次输入形成同源闭环。若挖矿成功事件为脏数据（误判成功），会同源连锁扰动整个防御经济体系。缓解：挖矿成功事件必须带完整元数据 + 进入独立报备审计。
- 隐形叠权风险更新 ：
- MQ 重试上限已约束。
- 批量沸点刷体力：若未设恢复上限，高频事件形成隐形叠权，绕过体力约束；V1.3 已补单 48h 恢复上限。
- 异源输入扩展：沸点数据流同时驱动「种草积分」与「精灵体力恢复」两条链路，全部经独立异源校验闸门；两套业务消费同一带快照版本的标准化事件，防时序错位。
十一、范式固有缺陷（可缓解不可根除）
- MQ 异步溜达，网络抖动必然小概率丢消息；以 ACK + 报备缓解，无法 100% 消除（随缘立场：丢失即丢弃，不补偿）。
- 多实例部署，分布式限流、体力计数天然存在微小时间窗口偏差（48h 窗口边缘可能偏差数十秒）。
- 依赖掘金笔记库、沸点统计接口性能；大流量下对上游掘金服务产生读取压力，属外部载体约束。
十二、闭环复审结论
✅本版机理补全完成：
- 时序版本化：结算、矿脉返还、沸点双业务均绑定 48h 快照，消除跨窗口错位。
- 队列仲裁：体力耗尽对已入队任务做取出前二次校验，杜绝负体力。
- 权限收敛：有效沸点判定收口到安全闸门，原始沸点不下透，精灵禁解析。
- 事件 ACK 与报备：积分返还落库 ACK，经济事件强制进独立审计通道。
- 能量带上限：补矿脉返还上限、沸点恢复体力上限，防通胀刷分。
- 随缘贯彻：事件丢失即丢弃，只观测不补偿，与产品哲学一致。
- 死耦合双保险：私密变更终止在途 + MINING 二次校验。
- 皮肤独立渲染层边界保留，为商业化预留。
⚠️仍存在的固有缺陷（只能缓解）：异步消息小概率丢失、分布式限流窗口偏差、上游载体读取压力。 ⚠️核心监控点：微循环经济的通胀 / 通缩是 V1.3 最需观测的工况切换诱因，建议运营期重点盯矿脉返还积分与沸点恢复体力的上限参数。
《掘金・挖矿小精灵》V1.3‑LD‑M 落地工程设计文档（封档版）
封档标记：V1.3‑LD‑M 封档日期：________ 审查依据：狂潮元理论【从零架构骨架设计子流程】 封档规则：文档内核冻结不再修改；业务参数调优、P2 功能新增、运维配置变更，统一通过后续变更附录记录，不直接修改本封档正文。
📌 P1 待落地约束（开发评审 / 运维阶段落实，不修改文档正文）
MQ 事件信封元数据与 payload 隔离依靠代码 CR 约束，无运行时强制隔离；
scheduler 节拍器为全局业务单点，重点监控 step 执行状态并配置告警；
mailbox sender_ref HMAC 密钥严格服务端保管，禁止外泄；
上游熔断窗口跳过不补偿，需要产品签字确认。
📌 P2 待实现（记录在文档第十四节，不在 MVP 实现）
- event_ledger 7 天定时归档至冷表 / 对象存储；
- 精灵皮肤独立渲染商业化边界仅预留接口，MVP 不实现。
- 版本：V1.3-LD-M
- 定位：原稿工程细节 + 修订版 8 项机理补丁 + P0/P1 修订清单合并，可直接进开发排期
- 核心立场：48h 唯一节拍；事件丢失只 audit、不业务重试；ACK 仅用于落库确认与审计，不做重试补偿；防重不防丢；巡检发现不一致只告警观测、不自动强修。
〇、合并说明 本版合并三份输入：
- V1.3-LD 原稿：工程细节基底（接口清单、Lua 伪代码、参数默认值、成功率公式、数据表）。
- V1.3-LD 修订版：8 项机理补丁（限流绑快照、缓存巡检、活跃池加锁、碎片校验、节拍分步、熔断降级、审计补全、黑名单补全）。
- 修订清单：4 个 P0 + 8 个 P1 + 3 个 P2。 P0 已全部修入；P1 已修入 P1-1/2/3/4/5/6/7/8；P2 记录在第十四节。
一、系统总体架构
markdown
┌────────────────────────────────────────────┐
│ 前端（Web / 插件） │
│ 悬浮精灵组件 · 皮肤独立渲染层(view-model) │
└───────────────────┬────────────────────────┘
│ HTTPS
┌───────────────────▼────────────────────────┐
│ gateway-service │
│ 鉴权 · 路由 · 统一限流入口 │
└───────────────────┬────────────────────────┘
┌───────────────────────┬───────┴───────┬───────────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌────────────────┐ ┌──────────────┐ ┌──────────────┐
│ note-service │ │ gate-service │ │spirit-service│ │mailbox-service│
│ 矿洞/碎片 │ │ 异源校验闸门 │ │ 精灵状态机 │ │ 漂流信箱 │
│ 挖矿事件 │ │ 有效沸点判定 │ │ 体力/溜达 │ │ 48h销毁/即焚 │
└──────┬───────┘ └──────┬─────────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
└────────────┬────────┴─────────────────────┴─────────────────────┘
▼
┌───────────────┐ ┌──────────────────────┐
│defense-service│ │ scheduler │
│ 积分/草量/返还 │ │ 48h 节拍器 · 派发 │
└───────┬───────┘ └──────────┬───────────┘
│ │
┌───────▼───────────────────────────▼──────────┐
│ audit-service（独立审计通道） │
│ 经济事件全量上报 · 异常降采样 · 告警指标 │
└──────────────────────────────────────────────┘数据层： Redis ------ 运行时权威状态（精灵体力 / 限流计数 / 活跃池，TTL） MySQL ------ 异步持久快照（业务账本 / 事件表 / 快照窗口 / 审计） MQ ------ 事件总线（RabbitMQ/Kafka，事件信封携带版本元数据） 关键设计决策： ・运行时权威状态在 Redis，MySQL 仅做异步持久快照；Redis 未命中回填策略见 §2.4。 ・外部异源输入全部经 gate-service 统一校验闸门。 ・audit-service 独立 topic，不复用业务主链路。
・事件信封统一携带 event_id + snapshot_version + trace_id，与 payload 隔离。
二、数据模型设计
2.1 MySQL 核心表
scss
-- 矿山映射
CREATE TABLE mineral_mine (
id VARCHAR(64) PRIMARY KEY,
user_id VARCHAR(64) NOT NULL,
note_id VARCHAR(64) NOT NULL,
status VARCHAR(16) NOT NULL, -- public / private / deleted
fragment_id VARCHAR(64),
fragment_content TEXT,
fragment_len INT NOT NULL DEFAULT 0,
mine_version BIGINT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL,
UNIQUE KEY uk_note (note_id),
KEY idx_user_status (user_id, status)
);
-- 高光碎片存储（长度硬上限校验）
CREATE TABLE fragment_content (
fragment_id VARCHAR(64) PRIMARY KEY,
mine_id VARCHAR(64) NOT NULL,
content TEXT NOT NULL,
length INT NOT NULL, -- 硬上限校验，超限拒绝
created_at DATETIME NOT NULL,
KEY idx_mine (mine_id)
);
-- 精灵持久快照
CREATE TABLE spirit_state (
user_id VARCHAR(64) PRIMARY KEY,
level INT NOT NULL DEFAULT 1,
mood VARCHAR(16) NOT NULL DEFAULT 'NORMAL',
energy INT NOT NULL DEFAULT 5,
backpack JSON,
state VARCHAR(16) NOT NULL DEFAULT 'IDLE',
wander_count_48h INT NOT NULL DEFAULT 0,
stamina_recovered_48h INT NOT NULL DEFAULT 0,
state_version BIGINT NOT NULL DEFAULT 0,
version BIGINT NOT NULL DEFAULT 0,
updated_at DATETIME NOT NULL
);
-- 种草积分账本
CREATE TABLE defense_ledger (
user_id VARCHAR(64) PRIMARY KEY,
points BIGINT NOT NULL DEFAULT 0,
snapshot_version VARCHAR(32) NOT NULL,
version BIGINT NOT NULL DEFAULT 0,
updated_at DATETIME NOT NULL
);
-- 草量防御值（按笔记）
CREATE TABLE grass_balance (
note_id VARCHAR(64) PRIMARY KEY,
grass_total BIGINT NOT NULL DEFAULT 0,
version BIGINT NOT NULL DEFAULT 0,
updated_at DATETIME NOT NULL
);
-- 种草分配明细
CREATE TABLE grass_allocation (
id VARCHAR(64) PRIMARY KEY,
user_id VARCHAR(64) NOT NULL,
note_id VARCHAR(64) NOT NULL,
points BIGINT NOT NULL,
snapshot_version VARCHAR(32) NOT NULL,
created_at DATETIME NOT NULL,
KEY idx_note (note_id)
);
-- 矿脉被动返还记录（event_id 唯一幂等）
CREATE TABLE passive_return_ledger (
id VARCHAR(64) PRIMARY KEY,
event_id VARCHAR(64) NOT NULL,
mine_id VARCHAR(64) NOT NULL,
owner_id VARCHAR(64) NOT NULL,
points BIGINT NOT NULL,
snapshot_version VARCHAR(32) NOT NULL,
ack_status VARCHAR(16) NOT NULL, -- ACKED / AUDIT_FAILED / CAP_HIT
created_at DATETIME NOT NULL,
UNIQUE KEY uk_event (event_id),
KEY idx_owner_sv (owner_id, snapshot_version)
);
-- 沸点统计快照
CREATE TABLE bp_stat (
user_id VARCHAR(64) NOT NULL,
snapshot_version VARCHAR(32) NOT NULL,
active_count INT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
PRIMARY KEY (user_id, snapshot_version)
);
-- 48h 结算窗口（含分步执行状态）
CREATE TABLE snapshot_window (
window_id VARCHAR(64) PRIMARY KEY,
snapshot_version VARCHAR(32) NOT NULL,
start_time DATETIME NOT NULL,
end_time DATETIME NOT NULL,
settle_status VARCHAR(16) NOT NULL, -- INIT / SETTLING / DONE / FAILED
exec_step INT NOT NULL DEFAULT 0,
step_ack_map JSON, -- {"1":{"ack":true,"ts":...}, ...}
created_at DATETIME NOT NULL,
UNIQUE KEY uk_sv (snapshot_version)
);
-- 事件审计明细（保留 7 天，定时归档）
CREATE TABLE event_ledger (
id VARCHAR(64) PRIMARY KEY,
event_id VARCHAR(64) NOT NULL,
event_type VARCHAR(32) NOT NULL,
trace_id VARCHAR(64) NOT NULL,
snapshot_version VARCHAR(32) NOT NULL,
payload_summary TEXT,
status VARCHAR(16) NOT NULL,
created_at DATETIME NOT NULL,
UNIQUE KEY uk_event (event_id),
KEY idx_created (created_at)
);
-- 审计事件
CREATE TABLE audit_event (
id VARCHAR(64) PRIMARY KEY,
event_type VARCHAR(64) NOT NULL,
level VARCHAR(16) NOT NULL,
trace_id VARCHAR(64),
detail TEXT,
sampled TINYINT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
KEY idx_type_time (event_type, created_at)
);
-- 信箱持久表（48h 物理删除、即焚、审计都需要）
CREATE TABLE mailbox_package (
package_id VARCHAR(64) PRIMARY KEY,
task_id VARCHAR(64) NOT NULL,
receiver_id VARCHAR(64) NOT NULL,
sender_ref VARCHAR(128) NOT NULL, -- HMAC-SHA256(server_key, sender_uid)，可审计不可展示
package_type VARCHAR(16) NOT NULL, -- COMPLAINT / FRAGMENT
payload TEXT NOT NULL,
burn_after_read TINYINT NOT NULL DEFAULT 0,
ttl_at DATETIME NOT NULL,
created_at DATETIME NOT NULL,
UNIQUE KEY uk_task_type (task_id, package_type),
KEY idx_receiver_ttl (receiver_id, ttl_at)
);2.2 Redis Key 设计（限流 key 绑快照版本）
表格
| Key 模式 | 用途 | TTL |
|---|---|---|
| spirit:{uid} | 精灵运行时状态（体力权威） | 关联 48h |
| spirit:stamina:lock:{uid} | Lua 原子校验 / 扣减 | 短 TTL |
| limit:wander:{uid}:{snapshot_version} | 精灵溜达计数 | 随版本废弃 |
| limit:pair:{min(uidA,uidB)}:{max(uidA,uidB)}:{snapshot_version} | 两两互访计数（有序） | 随版本废弃 |
| limit:bp_recover:{uid}:{snapshot_version} | 沸点恢复体力上限计数 | 随版本废弃 |
| limit:return:{uid}:{snapshot_version} | 矿脉返还上限计数 | 随版本废弃 |
| active_pool:{snapshot_version} | 活跃用户池（Set） | 随版本废弃 |
| mailbox:count:{uid} | 信箱包裹数上限 | 48h |
| snapshot:current | 当前快照版本 | 常驻 |
| lock:active_pool_refresh | 活跃池刷新分布式锁（Redisson） | lease 30s |
规则： ・限流 key 一律携带 snapshot_version，新窗口版本变化即生成新 key，旧 key 自然废弃，不单纯依赖 TTL。 ・pair key 必须 min (uidA,uidB) 在前、max 在后，保证 A→B 与 B→A 命中同一 key。
2.3 MQ 事件信封规范
json
{
"event_id": "uuid-v4",
"event_type": "mining_success | passive_return | spirit_wander | mailbox_write | spirit_energy_change | bp_standardized | ...",
"snapshot_version": "SNP-1735689600",
"trace_id": "uuid-v4",
"producer": "note-service",
"occurred_at": "ISO8601",
"payload": {}
}・幂等键统一为 event_id；trace_id 仅追踪，不得作为幂等键。 ・元数据与 payload 分离，编码约束禁止在 payload 解析时混入执行逻辑。 ・消费时 snapshot_version 不匹配当前窗口 → 拒绝并上报对应审计事件（如 mining_success_drop）。
2.4 Redis 故障回填策略 ・Redis 未命中 → 读 MySQL spirit_state 回填。 ・回填时 state 强制 IDLE，体力取 min (MySQL.energy, 5)。 ・回填事件上报 audit cache_refill。 ・回填不得让体力倒挂（若 Redis 存在更高体力，以 Redis 为准，不回填覆盖）。
三、服务职责与权限原子化（六维约束）
3.1 note-service（矿洞系统）
- 核心职责：公开笔记→矿山映射、高光碎片抽取、私密硬锁、挖矿成功事件输出。
- 私有状态：矿山映射表、私密锁名单、碎片原始内容、挖矿成功历史标记。
- 可公开状态：可挖矿山清单、高光碎片、挖矿成功事件。
- 允许接收输入：笔记发布 / 修改 / 私密化事件（经 gate 校验）。
- 允许发出输出：矿山状态变更事件、碎片供给、mining_success_event（带快照）。
- 越界黑名单：禁止修改用户原始笔记；禁止泄露私密笔记；禁止跨用户读笔记；禁止直接写积分账本；禁止输出未做长度 / 畸形校验的碎片内容。
3.2 gate-service（异源校验闸门）
- 核心职责：外部异源输入二次校验、有效沸点判定、标准化事件输出。
- 私有状态：校验规则、有效沸点判定逻辑、闸门配置。
- 可公开状态：标准化事件（带快照版本）。
- 允许接收输入：掘金笔记元数据、沸点原始流、掘金敏感词 API 返回、用户 UGC。
- 允许发出输出：标准化沸点事件、标准化笔记事件、标准化吐槽事件。
- 越界黑名单：禁止透传原始沸点载荷；禁止透传畸形 / 超限碎片；拒绝 payload 超限事件。
3.3 spirit-service（精灵系统）
- 核心职责：精灵实例状态机、体力、溜达行为。
- 私有状态：状态机内部态、体力值、心情、背包、今日溜达计数。
- 可公开状态：当前状态、战利品摘要、体力值。
- 允许接收输入：溜达任务派发事件、挖矿判定结果、gate 输出的有效沸点标准化事件。
- 允许发出输出：挖矿任务请求、回归提示、体力变更事件。
- 越界黑名单：禁止直接写漂流信箱；禁止修改笔记 / 沸点原始数据；禁止解析原始沸点内容；禁止自行判定有效沸点。
3.4 defense-service（防御系统）
- 核心职责：48h 沸点结算、种草积分账本、草量防御值、矿脉被动返还积分。
- 私有状态：积分账本、结算快照、矿脉挖矿成功事件记录（含快照版本）。
- 可公开状态：当前种草积分、草量防御值。
- 允许接收输入：沸点标准化统计事件、矿洞挖矿成功事件（带快照）。
- 允许发出输出：积分变更事件、草量更新事件、积分返还落库 ACK。
- 越界黑名单：禁止读写用户笔记原文；禁止覆盖结算快照版本；禁止直接接收原始沸点载荷。
3.5 mailbox-service（漂流信箱）
- 核心职责：吐槽 / 碎片包裹匿名存取、48h 过期销毁、阅后即焚。
- 私有状态：信箱载荷、产生时间戳、TTL 标记（不存发送方明文 user_id）。
- 可公开状态：接收方可读的匿名消息。
- 允许接收输入：精灵投递包裹（带 ACK）、用户操作（点赞 / 踩 / 收入笔记 / 即焚）。
- 允许发出输出：写入成功 ACK、消息展示事件。
- 越界黑名单：禁止显示发送方实名；禁止超期保留数据；禁止评论 / 私信。
3.6 scheduler（48h 节拍器 / 派发器）
- 核心职责：窗口推进、批量结算、体力回满、活跃池刷新、任务派发、过期清理。
- 私有状态：快照窗口、节拍执行进度、分布式锁状态。
- 可公开状态：窗口版本、执行状态摘要。
- 允许接收输入：各服务状态变更事件、定时触发。
- 允许发出输出：结算事件、任务派发事件、窗口状态变更事件。
- 越界黑名单：禁止直接写业务账本（只发事件）；禁止绕过限流直接派发；禁止执行中覆盖已关闭窗口。
3.7 audit-service（审计）
- 核心职责：独立通道承接经济事件与异常上报、降采样、告警指标。
- 私有状态：审计明细、采样配置。
- 可公开状态：审计查询结果。
- 允许接收输入：全服务 audit 事件。
- 允许发出输出：告警、审计查询响应。
- 越界黑名单：禁止反向写业务状态；禁止参与业务决策。
四、精灵行为状态机与并发防护
4.1 状态机
markdown
IDLE → WANDERING → CHECKING → MINING → RETURNING → IDLE
↘(超时>5s) ABORT ↙・任何阶段超时（CHECKING/MINING > 5s）强制 ABORT → RETURNING → IDLE，杜绝卡死中间态。 ・状态机单流转，禁止跨状态跳转。 ・前端皮肤层仅访问 view-model，禁止修改业务状态。
4.2 Lua 原子脚本（取出执行前校验 + 扣减）
lua
-- KEYS[1] = spirit:state:{uid}
-- ARGV[1] = snapshot_version
-- ARGV[2] = wander_limit (默认 5)
-- ARGV[3] = task_id
local state = redis.call('HMGET', KEYS[1], 'stamina', 'wander_count', 'state')
local stamina = tonumber(state[1] or 0)
local count = tonumber(state[2] or 0)
if stamina <= 0 then
return {0, 'NO_STAMINA'}
end
if count >= tonumber(ARGV[2]) then
return {0, 'WANDER_LIMIT'}
end
redis.call('HINCRBY', KEYS[1], 'stamina', -1)
redis.call('HINCRBY', KEYS[1], 'wander_count', 1)
redis.call('HSET', KEYS[1], 'state', 'WANDERING', 'last_task', ARGV[3])
return {1, stamina - 1}・派发时只校验不扣体力；取出执行时原子扣减。 ・失败则任务 ABORT，不进入 WANDERING，不产生负体力，上报 audit task_abort。 ・任务过期直接丢弃并上报审计。
4.3 MINING 私密二次校验
MINING 开始前查 MySQL 主库：is_private=0 AND status=ACTIVE。不满足则 ABORT，不写碎片，可留吐槽包裹。封堵 "置私密与挖矿并发窗口"。
4.4 MQ 消费幂等
・幂等键 = event_id，唯一键挡重。 ・防重不防丢：重复投递被幂等拦截；丢失事件只进 audit，不业务重试。
五、安全与风控
5.1 UGC 审核前置
・吐槽必须过掘金敏感词审核 API + 本系统二次最小校验（长度、基础格式）。 ・不通过拦截在本地，不进入下游。
5.2 有效沸点判定收口
・判定逻辑统一放在 gate-service；输出带快照版本的标准化沸点事件。 ・原始沸点载荷不下透；种草积分与体力恢复两套业务消费同一带版本事件源。
5.3 防骚扰限流（48h 节拍统一）
・单精灵 48h 溜达上限 5 次（与体力上限联动）。 ・同一对用户 48h 内最多互访 1 次，pair key 有序。 ・全部限流 key 绑定 snapshot_version。
5.4 隐私隔离
・实名信息、浏览记录严禁经精灵泄露。 ・mailbox-service 不存发送方明文 user_id，只存 HMAC‑SHA256 (server_key, sender_uid)，可审计不可展示。
5.5 数据销毁（统一 48h）
・漂流吐槽与碎片保留 48h；"阅后即焚" 或超时后物理删除，绝不永久留存。 ・48h 内未领取漂流，过期即焚，不通知、不补偿。
5.6 碎片异源载荷校验
・碎片抽取设最大长度硬上限（默认 500 字），超限直接截断 / 丢弃并上报 audit fragment_oversize_reject。 ・过滤畸形 HTML / 脚本载荷，拒绝危险载荷向下游传递，防 XSS。 ・校验主体为 gate‑service，禁止业务模块自校验。
六、48h 节拍器流程（分步执行 + 断点续跑）
6.1 快照版本生成规则（定死）
ini
唯一生成方：scheduler 在 Step1/Step2 生成并写入 snapshot_window，同时广播。
只读方：其余服务只读事件信封中的 snapshot_version，禁止自行计算。
公式（兜底一致性）：
window_start = floor(epoch_ms / 172800000) * 172800000
snapshot_version = "SNP-" + window_start_unix
跨窗口事件处理：消费时 snapshot_version != 当前窗口 → 拒绝并上报对应审计事件。6.2 节拍流程拆分
ini
Step1 关闭旧窗口
Step2 新建快照窗口
Step3 结算沸点（限速，调用掘金上游）
Step4 体力回满至 5，wander_count_48h=0，stamina_recovered_48h=0
Step5 刷新 active_pool（带分布式锁）
Step6 清理过期信箱（物理删除 ttl_at <= now()）
Step7 打开新窗口・每步执行完成，写入 snapshot_window.exec_step + step_ack_map。 ・进程崩溃后，下次调度从断点继续，不从头完整重跑。 ・任一步失败：记录 audit scheduler_step_fail，已完成的步骤不重复执行。
6.3 重试边界声明（P0‑4）
diff
重试边界：
- 基础设施级断点续跑（仅限 scheduler 节拍器 7 步流程）：允许。进程崩溃后从 exec_step 续跑，已 ACK 步骤不重复。
- 业务事件级（积分返还、体力变更、信箱写入、沸点消费）：禁止重试。失败即 audit，丢弃不补偿。
- 判定口诀：scheduler 内部步骤可续跑；跨服务业务事件只防重、不重试。
- 跨窗口版本不匹配不属于业务异常，按上面矩阵做丢弃 / 归入新窗口；**依然禁止业务层重试，仅靠审计记录事件原始去向。**6.4 活跃池刷新（分布式锁）
・Redisson RLock，tryLock (wait=0, lease=30s)。 ・锁竞争失败直接放弃本轮刷新，等待下一个节拍，上报 audit active_pool_refresh_fail。 ・杜绝多 scheduler 实例无锁写乱活跃用户池。
6.5 上游接口熔断降级
・对掘金笔记、沸点、敏感词接口配置熔断器。 ・上游不可用时，本窗口部分任务跳过，记录 audit upstream_breaker_open，等待下一个 48h 窗口。 ・不阻塞整个系统崩溃，降级而非停滞。 ・产品确认项：熔断窗口跳过，用户少一轮种草 / 体力恢复，接受不补偿（需产品签字）。
6.6 跨窗口事件归属、处理矩阵 & 经济闭环设计意图
① 为什么需要（重要程度：P0）
48h 快照窗口切换时刻存在时间缝隙，事件产生时刻、MQ 投递消费时刻会落在不同窗口。 原方案仅描述 "版本不匹配直接拒绝"，缺失拒绝之后事件归属去向；容易出现：
- 挖矿、积分相关事件无明确归宿，审计只能看到被拒绝，但不知道这条事件应当归属于旧窗口还是直接丢弃；
- 团队容易对微循环经济产生误解，把「挖矿获取积分增益」当成程序 Bug；
- 没有矩阵，开发人员凭主观写判断逻辑，各服务处理不一致，引入隐性 bug。
② 经济闭环的设计意图说明（厘清：越挖越强是特性，非 bug）
特性定位：「越挖越强」属于产品刻意设计的微循环正向反馈特性，不是程序缺陷。 业务逻辑：笔记被他人挖矿成功 → 矿主获得被动返还种草积分 → 消耗积分提升笔记草量防御，降低后续被挖矿概率。 完整链条拆解：
- 用户产出公开知识笔记（知识输出）；
- 被其他精灵挖矿成功，代表这份内容产生社区互动价值；
- 系统给予少量种草积分作为产出激励；
- 用户拿积分给笔记加高防御，保护自己这份知识资产少被掠夺。
边界约束（防止特性走向恶性通胀）：
- 设置单用户 48h 矿脉返还积分硬上限，封顶，无限叠加被扼制；
- 积分来源仅限「自己笔记被别人挖」，自己出去挖矿不会给自己产生返还积分；
- 积分只能用于增加笔记防御，不能兑换体力、不能流通交易，没有代币化。
误区提示： ❌错误理解：挖的越多，我无敌。 ✔正确理解：输出越多高质量公开笔记，获得有限防御 buff；buff 有上限，无法无限膨胀。是对知识输出者的小额防御奖励，不是战斗力无限膨胀。
③ 事件信封 snapshot_version 不匹配完整处理矩阵
判定前提：
event_sv：事件自身携带的快照版本（事件产生那一刻的窗口）current_sv：节拍器此刻对外广播的当前快照版本- 窗口已经关闭定义：
event_sv对应的snapshot_window.settle_status = DONE
表格
| 事件类型 | 场景 | 处理动作 | 拒绝后归属去向 | 审计事件标识 |
|---|---|---|---|---|
| mining_success（挖矿成功事件） | event_sv == current_sv | 正常消费，执行积分返还 | - | - |
| mining_success | event_sv 窗口已关闭（旧窗口，DONE） | 直接丢弃，不归属新窗口 | 这条挖矿发生在上一个已经结算完毕的周期，周期已归档，不再执行返还；事件彻底丢弃 | mining_success_drop |
| passive_return（积分返还） | event_sv == current_sv | 正常消费落库 | - | - |
| passive_return | event_sv 窗口已关闭 | 直接丢弃 | 旧窗口结算闭环完成，不二次补发返还 | passive_return_ack_fail |
| bp_standardized（标准化沸点事件） | event_sv == current_sv | 正常消费，计入本窗口积分、体力恢复 | - | - |
| bp_standardized | event_sv 窗口已关闭 | 允许归属新窗口消费 | 沸点行为真实发生，只是消费落在窗口切换缝隙，归入当前最新窗口统计；受 48h 恢复上限约束，不会无限累加 | bp_event_roll_new_window |
| spirit_energy_change（体力变更） | event_sv == current_sv | 正常消费 | - | - |
| spirit_energy_change | event_sv 窗口已关闭 | 直接丢弃 | 体力是窗口周期资源，过期作废，不回溯补体力 | spirit_energy_drop |
| mailbox_write（信箱投递） | event_sv == current_sv | 正常执行写入信箱 | - | - |
| mailbox_write | event_sv 窗口已关闭 | 允许归属新窗口执行投递 | 投递行为只做匿名消息存储，不属于周期结算经济数据；消息允许跨窗口落地，TTL 依旧 48h 从写入时刻开始计时 | mailbox_event_roll_new_window |
矩阵执行总规则（编码必须遵守）
- 经济结算类事件（挖矿成功、积分返还、体力变更）：旧窗口一旦标记 DONE 归档，一律丢弃，绝不回溯旧周期做补发。
契合产品 "随缘，错过就错过"，不做历史补偿。
- 纯行为载体事件（沸点统计、信箱投递）：无历史结算副作用，可以归属当前新窗口执行，但依旧要受对应窗口上限硬约束，防止刷量。
- 所有发生版本不匹配的分支，无论丢弃还是归入新窗口，100% 必须上报 audit‑service 审计，不能静默吞掉事件。
七、可观测性与审计
7.1 独立审计通道
・audit‑service 独立 topic，不复用业务主链路。 ・经济事件（矿脉返还、体力变更、积分变更）全量上报。 ・异常事件降采样上报，避免日志风暴。
7.2 强制上报审计清单
表格
| 事件类型 | 触发条件 |
|---|---|
| mailbox_write_ack_fail | 信箱写入 ACK 失败 |
| mining_success_drop | 挖矿成功事件跨窗口被拒 |
| passive_return_ack_fail | 积分返还落库 ACK 失败 |
| spirit_energy_change | 体力变更（全量） |
| task_abort | 任务超时 / 体力不足 ABORT |
| cache_inconsistent | Redis‑MySQL 状态不一致 |
| cache_refill | Redis 未命中回填 |
| active_pool_refresh_fail | 活跃池刷新失败 / 锁竞争放弃 |
| fragment_oversize_reject | 碎片超限 / 畸形被拒 |
| scheduler_step_fail | 节拍器分步执行失败 |
| upstream_breaker_open | 掘金上游接口熔断 |
| economy_cap_hit | 经济上限命中 |
7.3 缓存一致性巡检
・后台低频轻量巡检任务，抽样比对 Redis‑MySQL 精灵状态。 ・发现不一致写入 audit cache_inconsistent，不自动强制修复（只观测，符合随缘立场）。
7.4 核心监控指标
表格
| 指标 | 告警建议 |
|---|---|
| 单用户 48h 返还积分 | 接近上限 |
| 单用户 48h 恢复体力 | 接近上限 |
| 负体力次数 | 0 即 P0 |
| 跨快照重复返还 | 0 即 P0 |
| 私密笔记挖矿成功 | 0 即 P0 |
| 信箱过期未删 | 0 即 P1 |
| ACK 失败率 | 突增告警 |
| 节拍器 step 执行状态 | 卡住告警 |
八、接口清单
8.1 前端 API
表格
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/spirit/panel | 精灵状态、体力、战利品摘要 |
| GET | /api/mine/list | 可挖矿山清单，不含私密 |
| POST | /api/defense/grass | 种草，指定 note_id + points |
| GET | /api/mailbox | 匿名包裹列表 |
| POST | /api/mailbox/{id}/action | 点赞 / 踩 / 收入笔记 / 阅后即焚 |
8.2 内部接口
表格
| 路径 | 说明 |
|---|---|
| POST /internal/gate/ugc/validate | 吐槽二次校验 |
| POST /internal/gate/bp/validate | 有效沸点判定，输出标准化事件 |
| POST /internal/gate/fragment/validate | 碎片长度 / 畸形校验 |
| POST /internal/mailbox/write | 精灵投递包裹，返回 ACK |
| POST /internal/mining/recheck‑private | MINING 二次私密校验 |
前端皮肤层只读 view model，禁止写业务 store；Canvas 渲染不阻塞主页面。
九、幂等、ACK 与 "不重试" 语义
表格
| 场景 | 幂等键 | ACK 语义 | 失败处理 |
|---|---|---|---|
| 挖矿成功事件 | event_id | defense 落库 ACK | 失败进 audit，丢弃 |
| 积分返还 | event_id UNIQUE | 落库 ACK | 失败 audit，不重试 |
| 沸点标准化事件 | event_id+consumer | 消费成功即 ACK | MQ 异常审计后 ACK，不主动重试 |
| 信箱写入 | task_id+package_type | mailbox 返回 package_id ACK | ACK 失败任务异常审计，不重试 |
| 体力变更 | 每次变更 audit 全量 | 不要求业务 ACK | 丢失只观测 |
关键说明：MQ 自身可能因进程崩溃重投，消费端必须用唯一键挡住；这是 "防重"，不是 "补偿重试"。业务失败不抛异常重试，记 audit 后 ACK。
十、默认参数表（建议默认，待运营确认）
表格
| 参数 | 建议默认 | 说明 |
|---|---|---|
| 体力上限 | 5 | 固定 |
| 48h 溜达上限 | 5 | 与体力联动 |
| 同对用户 48h 互相溜达 | 1 | 限流 |
| CHECKING 超时 | 5s | ABORT |
| MINING 超时 | 5s | ABORT |
| 信箱 TTL | 48h | 物理删除 |
| 单用户信箱最大包裹数 | 50 | 待确认 |
| 矿脉返还上限 | 100 积分 / 48h | 防通胀，待运营 |
| 沸点恢复体力上限 | 8 点 / 48h | 可大于 5，防刷 |
| 单条有效沸点恢复 | +1 体力 | 受总上限约束 |
| UGC 吐槽最大长度 | 200 字 | 二次最小校验 |
| 碎片最大长度 | 500 字 | gate 硬上限 |
| 基础返还 | 2 积分 / 次挖矿成功 | 受上限约束 |
| 挖矿成功率公式 | clamp(0.1+0.6attack‑0.5defense, 0.05, 0.85) | attack=min(1,valid_bp_48h/10)，defense=grass/(grass+100) |
| 节拍结算限速阈值 | 待定 | 防打垮上游 |
| 上游熔断阈值 | 待定 | 熔断器配置 |
十一、缺陷与风险声明
11.1 范式固有缺陷（可缓解，不可根除）
- MQ 异步溜达，网络抖动小概率丢事件；只 audit、不业务重试（契合随缘定位）。
- Redis 运行时权威、MySQL 异步快照，二者天然存在短暂时间窗口不一致。
- 48h 快照窗口边缘存在数十秒偏差。
11.2 载体资源缺陷 强依赖掘金上游笔记、沸点、敏感词接口可用性；已配置熔断降级缓解，但无法根除外部载体约束。
十二、MVP 切分与验收
12.1 第一阶段（MVP）
・精灵悬浮气泡 + 溜达挖矿 + 吐槽投递 + 漂流信箱 + 48h 过期销毁。 ・种草积分 + 草量防御 + 基础挖矿判定。 ・有效沸点体力恢复 + 48h 体力回满。 ・审计通道 + 限流。 ・建议：一阶段至少产生 mining_success 事件并落 event_ledger + audit，返还入账放二阶段，保证经济模型可观测。
12.2 第二阶段
・矿脉被动返还积分微循环 + 经济上限。 ・节拍器分步断点续跑 + 缓存一致性巡检。 ・上游熔断降级。
12.3 验收测试清单（开发完成后逐项实测，不预勾）
☐ 状态机无卡死（超时 ABORT 全场景） ☐ 并发挖矿无负体力（Lua 原子校验） ☐ 限流跨窗口无污染（snapshot_version 绑定） ☐ pair key 有序，A→B 与 B→A 命中同一限流 ☐ 私密笔记双保险（在途终止 + MINING 二次校验） ☐ 信箱 48h 物理删除 + 即焚 ☐ 幂等挡重（event_id 唯一） ☐ 节拍器崩溃断点续跑 ☐ 碎片超限 / 畸形拦截 ☐ Redis 未命中回填不导致体力倒挂 ☐ 审计事件全量 / 降采样正确 ☐ 关闭精灵面板后后端溜达任务继续
十三、待确认业务参数（交产品 / 运营灰度调参）
- 单用户 48h 矿脉被动返还积分上限（建议 100）
- 单用户 48h 沸点恢复体力上限（建议 8）
- 体力上限 5 是否调整
- 48h 溜达上限 5 次是否调整
- 单用户信箱最大包裹数（建议 50）
- 碎片抽取最大长度（建议 500 字）
- 节拍结算限速阈值
- 上游熔断降级阈值
- 熔断窗口跳过不补偿，产品是否接受（需签字）
十四、P2 记录（延后但不可消失）
- event_ledger 保留 7 天，定时归档到冷表 / 对象存储，主表按 created_at 清理。
- step_ack_map 格式建议 JSON：{"step":1,"ack":true,"ts":...}，每步一写。
- 验收清单不预勾，开发完成后实测。
- 皮肤独立渲染层商业化边界仅预留，不在 MVP 实现。
十五、合并检查表
- ☑ 数据模型：含 mailbox_package、grass_balance、spirit_state 新字段、passive_return_ledger.event_id UNIQUE
- ☑ 事件信封：含 event_id，幂等键 = event_id
- ☑ 快照版本：生成方 / 只读方 / 跨窗口拒绝规则
- ☑ 重试边界声明：节拍器续跑 vs 业务不重试
- ☑ 默认参数表（标注待确认）
- ☑ Redis key：pair key 排序、active_pool 带版本
- ☑ 接口清单 + Lua 伪代码 + 成功率公式
- ☑ 审计清单含 cache_inconsistent、cache_refill、active_pool_refresh_fail、fragment_oversize_reject
- ☑ 缺陷声明 + 熔断产品确认项
- ☑ HMAC sender_ref、Redis 回填、Redisson 锁、event_ledger 归档
闭环复审结论
✅本合并定稿版已吸收全部 8 项机理补丁，修掉 4 个 P0 与 8 个 P1，保留 P2 记录，同时严格守住元理论约束：
-
48h 唯一节拍、防重不防丢、ACK 仅审计不重试、丢失即丢弃只观测；
-
服务权限原子化六维完整，异源闸门统一，私密双保险，皮肤层隔离；
-
节拍器分步断点续跑、限流绑定快照版本、活跃池加锁、碎片载荷校验、缓存巡检告警、上游熔断降级全部落地。
-
⚠️固有缺陷（异步丢消息、快照窗口偏差、外部载体约束）仍存在，只能缓解不可根除。
-
⚠️运营期核心监控点：微循环经济通胀 / 通缩、节拍器分步执行状态、缓存一致性。
判定：P0 全部修入，P1 关键项已修入，可进开发排期。 剩余 P1‑7（熔断产品确认）需产品签字后关闭；P2 项在详细设计阶段补 TODO，不得消失。
注释：全景架构总图代码
flowchart LR subgraph userLayer"用户层-掘金前端环境" A["用户浏览器
悬浮精灵气泡面板
皮肤仅视图层，禁止改业务状态"] end
rust
subgraph gateLayer["网关与异源校验闸门｜gate-service"]
GATE["gate-service<br/>🔒唯一异源校验闸门<br/>•UGC吐槽校验<br/>•有效沸点判定<br/>•碎片畸形/长度过滤<br/>输出标准化带snapshot_version事件"]
end
subgraph bizLayer["核心业务域"]
NOTE["note-service矿洞系统<br/>矿山映射｜高光碎片<br/>私密笔记硬锁<br/>输出mining_success挖矿成功事件"]
SPIRIT["spirit-service精灵系统<br/>状态机｜体力｜溜达行为<br/>消费标准化沸点事件恢复体力"]
DEF["defense-service防御系统<br/>种草积分｜草量防御<br/>矿脉被动积分返还<br/>消费挖矿成功事件"]
MAIL["mailbox-service漂流信箱<br/>匿名包裹｜48h-TTL阅后即焚<br/>写入返回ACK，不存发送方明文"]
end
subgraph schedLayer["调度与观测域"]
SCHE["scheduler 48h节拍器<br/>•快照版本生成<br/>•体力周期回满<br/>•活跃池刷新<br/>•过期数据清理<br/>分步断点续跑"]
AUDIT["audit-service独立审计通道<br/>❗不复用业务主链路<br/>经济事件全量｜异常降采样上报<br/>只观测，禁止修改业务状态"]
end
subgraph extLayer["外部异源输入（全部过gate闸门）"]
EXT1["掘金笔记元数据"]
EXT2["沸点发布&互动数据流"]
EXT3["掘金敏感词审核API"]
end
subgraph storeLayer["数据存储分层"]
REDIS[("Redis<br/>运行时权威状态<br/>精灵体力｜限流计数｜活跃池<br/>限流Key绑定snapshot_version")]
MYSQL[("MySQL<br/>异步持久快照<br/>账本｜事件｜快照窗口｜审计记录")]
MQ(("MQ事件总线<br/>统一事件信封<br/>event_id｜snapshot_version｜trace_id元数据与payload分离"))
end
%% 用户流向
A --> GATE
A --> SPIRIT
A --> MAIL
A --> DEF
%% 外部异源全部流入闸门
EXT1 --> GATE
EXT2 --> GATE
EXT3 --> GATE
%% 闸门向下输出标准化事件
GATE --> NOTE
GATE --> SPIRIT
GATE --> DEF
%% 业务域内部事件流转
NOTE -->|"mining_success事件"| DEF
SPIRIT -->|"投递请求"| MAIL
SPIRIT <--> MQ
NOTE <--> MQ
DEF <--> MQ
MAIL <--> MQ
%% 调度驱动
SCHE -.->|"派发溜达任务"| SPIRIT
SCHE -.->|"窗口驱动"| REDIS
SCHE -.->|"窗口驱动"| MYSQL
%% 全部异常、经济事件流向审计
NOTE -.->|"异常事件"| AUDIT
SPIRIT -.->|"异常事件"| AUDIT
DEF -.->|"异常事件"| AUDIT
MAIL -.->|"异常事件"| AUDIT
SCHE -.->|"执行异常"| AUDIT
%% 存储挂载
SPIRIT <--> REDIS
DEF <--> REDIS
NOTE <--> REDIS
MAIL <--> REDIS
SPIRIT <--> MYSQL
DEF <--> MYSQL
NOTE <--> MYSQL
MAIL <--> MYSQL
SCHE <--> MYSQL
AUDIT <--> MYSQL