@chenguangyao/devflow-kit 0.1.43

package/skills/tech-spec/references/rollout-and-rollback.md

@@ -0,0 +1,203 @@
+# tech-spec / rollout-and-rollback
+
+灰度 / 回滚 / 双写的模板与决策树。design.md §10 的写作依据。
+
+---
+
+## 核心原则
+
+1. **不能回滚 = 不能上线**。没有回滚预案的设计不允许进入 plan。
+2. **灰度要有停止条件**,不是"先 1% 再说"。
+3. **数据迁移要有对账**,不依赖"应该没问题"。
+4. **上线前演练过回滚**(至少在 staging 演练一次)才算真的能回滚。
+
+---
+
+## 灰度策略选择
+
+| 方式 | 粒度 | 典型场景 |
+| --- | --- | --- |
+| **Feature flag**(按配置开关) | 布尔全局 / 按百分比 / 按标签 | 接口新逻辑、UI 新功能 |
+| **按用户 hash 分流** | 按 userId % N | 新旧路径对比实验、A/B test |
+| **按机房 / 可用区分流** | 整机房 | 基础设施 / 中间件替换 |
+| **按版本分流** | 客户端版本号 | 客户端兼容切换 |
+| **按环境灰度** | dev → staging → prod 前哨 → prod 全量 | 全新功能 |
+
+选哪种决定于**变更的粒度 + 回滚速度需求**:
+
+- 秒级回滚 → Feature flag(改配置即可)
+- 分钟级回滚 → 按百分比分流(改分流比例)
+- 小时级回滚 → 灰度机房切换(运维介入)
+
+---
+
+## Feature flag 模板
+
+```yaml
+# Apollo / config center
+feature.coupon.batch.enabled: false   # 默认关
+feature.coupon.batch.whitelist:        # 白名单灰度
+  - operator_id_001
+  - operator_id_002
+feature.coupon.batch.percent: 0        # 百分比灰度(0-100)
+```
+
+**代码里**:
+
+```java
+if (!flagService.isEnabled("coupon.batch.enabled", operatorId)) {
+    throw new ServiceUnavailableException("SERVICE_DISABLED");
+}
+// 新逻辑
+```
+
+**关键**:
+
+- flag 读取要**缓存**(不要每请求读远程)
+- flag 变更**立即生效**(≤ 30 秒)
+- flag 有**默认值**(远程不可用时降级到默认)
+
+---
+
+## 灰度阶段模板
+
+```markdown
+## 灰度计划
+
+### 阶段 0:预发(staging)
+- 在预发跑 smoke + e2e,内部 QA 验收
+- 条件:通过 → 进入阶段 1
+
+### 阶段 1:内部白名单(5 账号)
+- flag: `whitelist: [opr001, opr002, opr003, opr004, opr005]`
+- 观测:5 个账号的**使用反馈** + **指标**(error_rate, P99)
+- 时长:≥ 24h(至少覆盖一个工作日高峰)
+- 条件:无阻塞性问题 → 阶段 2
+
+### 阶段 2:1% 灰度
+- flag: `percent: 1`
+- 观测:error_rate < 0.1%,P99 < 3s,对照组无退化
+- 时长:≥ 2h
+- 条件:通过 → 阶段 3
+
+### 阶段 3:10% 灰度
+- flag: `percent: 10`
+- 观测:同上
+- 时长:≥ 4h,涵盖一次发券峰值
+- 条件:通过 → 阶段 4
+
+### 阶段 4:50% 灰度
+- flag: `percent: 50`
+- 观测:同上
+- 时长:≥ 12h
+- 条件:通过 → 全量
+
+### 阶段 5:100% 全量
+- flag: `percent: 100`
+- 观测:同上
+- 保持 flag 1 周不移除,方便紧急回滚
+
+### 清理(灰度完成后 1 周)
+- 删除 flag 分支代码 + 移除 flag 配置
+- 清理检查清单见:<清理任务列表>
+```
+
+---
+
+## 回滚预案(必写)
+
+每个设计至少要写:
+
+1. **触发条件**:什么情况下触发回滚
+2. **回滚步骤**:具体命令 / 按钮 / 操作
+3. **回滚影响**:回滚后的用户看到什么、数据状态什么样
+4. **回滚耗时**:从触发到生效多久
+
+### 模板
+
+```markdown
+## 回滚预案
+
+### 触发条件(任一命中)
+- error_rate > 1% 持续 5min
+- P99 > 5s 持续 10min
+- 收到运营侧 P0 反馈(影响 > 5 个业务场景)
+
+### 回滚步骤(按严重度从轻到重)
+#### 软回滚(改配置)
+  1. Apollo 设置 `coupon.batch.enabled=false`
+  2. 等待 30 秒生效
+  3. 验证:新请求返回 503 SERVICE_DISABLED
+  耗时:1 分钟
+
+#### 硬回滚(切回旧版本 tag)
+  1. Jenkins 触发回滚作业 `coupon-service-rollback` 指定上一 tag
+  2. 观察 5 分钟确认服务 healthy
+  耗时:10 分钟
+
+### 回滚影响
+- 用户看到:批量接口返回 503,提示"暂不可用,请稍后";前端提示降级到单发操作
+- 数据:已发放的券不回收;正在处理中的批次(极少,因为是同步)可能写了部分 grant_log,但不影响兼容(batch_id 列可为 NULL)
+- 指标:回滚后 `coupon.batch.traffic` 掉到 0
+
+### 回滚验证
+- 回滚后 30 分钟内,对照旧单发接口的基线指标,所有指标应回归基线 ±5%
+```
+
+---
+
+## 双写 / 数据迁移模板
+
+### 场景:从旧表 old_coupon 迁到新表 coupon
+
+**不要**:一次性 stop-the-world 迁移。
+
+**要**:
+
+```
+阶段 0:新表建好 + 新代码只写新表(开关 write_new=true)
+阶段 1:新表 + 旧表双写(write_both=true);读仍旧表
+阶段 2:跑历史数据回填(backfill job),把旧表数据同步到新表
+阶段 3:对账 job 跑 24-72 小时,确认 diff_count ≤ 阈值
+阶段 4:读切新表(read_new=true);旧表仍双写(防紧急回滚)
+阶段 5:观察 ≥ 1 周 → 停旧表写入(write_old=false)
+阶段 6:归档旧表(不删,至少保留 1 个月)
+```
+
+**关键**:
+
+- 每个阶段的**切换动作**是可秒级回滚的(改 flag)
+- 对账是**必须的**,不是 "看起来没问题就切"
+- 数据迁移的**验证条件**要量化(count 差异 / 字段 hash 对比)
+
+---
+
+## 监控面板(灰度期强制)
+
+灰度期必有一个**专用 dashboard**:
+
+- **流量分布**:新 / 旧路径的 QPS 百分比(应符合 flag 比例)
+- **错误率对照**:新 / 旧路径的 error_rate 对比
+- **延迟对照**:新 / 旧路径的 P50 / P99 对比
+- **业务指标**:发券量、退款量、投诉量(漂移要告警)
+- **日志异常**:新路径的 log.error 数量
+
+无对照 dashboard = 灰度形同虚设。
+
+---
+
+## 回滚演练
+
+L3 任务建议上线前在 staging 做一次**完整回滚演练**:
+
+1. 在 staging 部署新版本并灰度到 50%
+2. 人为触发异常(如关闭下游 RiskService)
+3. 执行回滚步骤
+4. 验证:指标回归基线、无数据丢失 / 错位
+5. 记录演练报告 → `devflow/changes/<slug>/rollback-drill.md`
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了灰度 / 回滚的硬规则("L2/L3 必须有可操作的灰度步骤和回滚预案")。本文给完整模板 + 阶段划分 + 双写流程 + 监控要求 + 演练流程。tech-spec 写 §10 时应以本文为模板。

package/skills/tech-spec/references/spec-delta-conventions.md

@@ -0,0 +1,250 @@
+# tech-spec / spec-delta-conventions
+
+OpenSpec 风格的 spec delta 写作规范。delta 在 archive 阶段会合入 `devflow/specs/<业务域>/spec.md`。
+
+---
+
+## 什么是 OpenSpec Delta
+
+OpenSpec delta 是机器可读 + 人类可读的能力变更描述文件。它记录"系统能**做什么**"，而不是"代码**怎么写**"。
+
+OpenSpec delta 的价值：
+
+- `SHALL/MUST/SHOULD` 明确系统承诺，可直接支撑验收和测试
+- `Scenario` 描述关键业务场景，避免 spec 退化成接口字段流水账
+- 按业务域聚合到 `specs/<域>/spec.md`，同域能力持续沉淀到一个真源
+- `REJECTED Alternatives` 记录决策背景，防止未来重蹈覆辙
+
+---
+
+## 什么时候要写 delta
+
+只有在本次改动**改变了系统对外能力**时才写：
+
+| 场景 | 是否写 delta |
+| --- | --- |
+| 新增一个对外接口 / 新模块 / 新事件 | 是（ADDED） |
+| 改变现有接口的行为语义（字段 / 错误码 / SLO 变了） | 是（MODIFIED） |
+| 废弃 / 删除现有接口 | 是（REMOVED） |
+| 只改实现、不改契约（重构 / 性能优化） | 否 |
+| 改文案 / UI 微调 / 加日志 / 加指标 | 否 |
+| 紧急 bug 修复（恢复本来就应该的行为） | 否 |
+
+---
+
+## 文件位置与目标 spec 路径
+
+delta 文件位置：
+```
+devflow/changes/<slug>/delta/
+├── <capability-a>.md        ← 顶层文件
+├── added/
+│   └── <capability-b>.md   ← 可用子目录分类（不影响落盘路径）
+└── modified/
+    └── <capability-c>.md
+```
+
+**落盘路径由 frontmatter `capability` 字段决定**（不是文件名）：
+
+| frontmatter                      | 落盘目标                          |
+|----------------------------------|-----------------------------------|
+| `capability: coupon/grant`       | `specs/coupon/spec.md`            |
+| `capability: order/create`       | `specs/order/spec.md`             |
+| `capability: payment/alipay/v2`  | `specs/payment/spec.md`           |
+| 无 `capability` 字段             | `specs/<文件名>.md`（兜底）       |
+
+这样不同业务域的 spec 自动分目录存放，不会堆在同一层：
+
+```
+devflow/specs/
+├── coupon/
+│   └── spec.md
+├── order/
+│   └── spec.md
+└── payment/
+    └── spec.md
+```
+
+规则：
+- 一个 capability 一个 delta file
+- 一个 change 可产生多个 delta file（涉及多个 capability）
+- delta 子目录（`added/`、`modified/`）仅用于可读性分类，不影响 archive 行为
+
+---
+
+## OpenSpec Delta 完整格式
+
+```markdown
+---
+slug: <change-slug>
+capability: <capability-name>
+---
+
+# delta: ADDED specs/<domain>/spec.md
+
+> OpenSpec 风格 delta — `devflow archive` 时按业务域落盘到 `devflow/specs/<domain>/spec.md`。
+
+## ADDED Requirements
+
+### Requirement: <业务能力名>
+
+系统 SHALL <描述该业务能力对外承诺>。
+
+1. 系统 MUST <约束 1>
+2. 系统 MUST <约束 2>
+3. 系统 SHOULD <约束 3>
+
+#### Scenario: <场景名>
+
+- **WHEN** <触发条件>
+- **THEN** 系统 MUST <结果>
+- **AND** <补充断言>
+
+## MODIFIED Requirements
+
+### Requirement: <既有业务能力名>
+
+<!-- heading 必须与 specs/<domain>/spec.md 中的 ### 一字不差 -->
+- ~~旧约束~~
+- 新约束
+
+## REMOVED Requirements
+
+### Requirement: <废弃业务能力名>
+
+下线原因：...
+下线时间：YYYY-QX
+
+## REJECTED Alternatives
+
+### 备选方案名称
+
+**否决原因**：...
+```
+
+---
+
+## 三类标记详解
+
+### ADDED Requirements
+
+新增能力，archive 后 **append** 到目标 spec 文件。
+
+每个 `### Requirement: <业务能力名>` 块必须包含：
+- 一句 `系统 SHALL ...` 总体能力承诺
+- 若干条 `系统 MUST/SHOULD ...` 约束
+- 至少一个 `#### Scenario: ...`，使用 `WHEN/THEN/AND` 描述验收场景
+- 接口、错误码、幂等、SLO 如影响对外契约，可写入对应 Requirement 的约束或 Scenario
+
+### MODIFIED Requirements
+
+修改现有能力。archive 时**替换**目标 spec 中对应的 `### heading` 块。
+
+**关键规则**：
+- `### heading` 必须与目标 spec **一字不差**（含空格、标点、大小写）
+- 要删除的旧内容用 `~~strikethrough~~`，archive 时真正删除
+- **不要**直接改 heading 文字；heading 改名 = REMOVED 旧 + ADDED 新
+
+**反例**：
+```markdown
+# specs/order.md 里是：
+### `order.create`
+
+# delta 里写成：
+### `order.create` v2   <!-- heading 改了 → delta_conflict! -->
+### `order.create`      <!-- 正确 -->
+```
+
+### REMOVED Requirements
+
+废弃现有能力，archive 时**整段删除**目标 spec 中对应块。
+
+必须注明下线原因和时间，便于历史追溯。
+
+---
+
+## REJECTED Alternatives
+
+记录**否决的备选方案**，目的是让后人理解为什么没选另一条路。
+
+每个否决方案写：
+- 方案名（`### 方案描述`）
+- **否决原因**（具体、可验证）
+
+archive 后会合入 spec 文件的 `## REJECTED Alternatives` 段，成为永久设计记录。
+
+---
+
+## heading 对齐规则（关键）
+
+MODIFIED / REMOVED 的 `### <heading>` 必须与目标 spec **一字不差**（含空格、标点）。
+
+**对齐失败 → archive 报 `delta_conflict`，停止合并。**
+
+推荐做法：
+1. 先读 `devflow/specs/<域>/spec.md`，复制现有 heading 粘贴到 delta
+2. 不改 heading 的大小写、空格、标点
+3. 改 heading 文字的需求 → 拆成 `REMOVED 旧 heading` + `ADDED 新 heading`
+
+---
+
+## 接口契约补充写法（可选）
+
+- 只有当字段级契约会影响验收或兼容性时，才在 Requirement 下补充 JSON Schema draft-07（`type`, `required`, `properties`, `enum`, `format`, `$ref`）
+- 每个字段加 `description`，明确语义和约束
+- 枚举值用 `enum`（不要写成字符串描述）
+- 日期时间用 `{ "type": "string", "format": "date-time" }`
+- 数字类型区分 `integer` / `number`
+
+```json
+{
+  "type": "object",
+  "required": ["userId", "channel"],
+  "properties": {
+    "userId":  { "type": "string", "minLength": 1, "description": "用户 ID" },
+    "channel": { "enum": ["APP", "H5", "MINI"], "description": "来源渠道" },
+    "amount":  { "type": "integer", "minimum": 1, "description": "金额（分）" }
+  }
+}
+```
+
+---
+
+## SLO 写作要点
+
+SLO 必须是**可量化、可验证**的数字，不写"系统应尽快响应"这类模糊描述：
+
+```markdown
+#### SLO
+- P95 < 50ms，P99 < 100ms（不含网络延迟）
+- 可用率 ≥ 99.95%（单 region，滚动 30 天）
+- 错误率 ≤ 0.01%（不含业务 4xx）
+- 吞吐量：峰值 ≥ 1000 QPS
+```
+
+---
+
+## archive 合并语义
+
+`devflow archive` 做：
+
+- `ADDED Requirements` → append 到 `specs/<域>/spec.md` 的 `## Requirements`
+- `MODIFIED Requirements` → 按 heading **替换**目标段落（删旧加新）
+- `REMOVED Requirements` → 按 heading **整段删除**
+- `REJECTED Alternatives` → append 到 spec 的 `## REJECTED Alternatives` 段
+
+合并失败场景：
+- heading 未找到 → 冲突，停止合并，报告 `delta_conflict`
+- 并行 change 同时 MODIFY 同一 heading → 需人工合并
+
+---
+
+## 完整示例
+
+参见 `examples/coupon-grant-api/devflow/changes/coupon-grant-api/delta/added/coupon-grant.md`。
+
+---
+
+## 与 SKILL.md 的关系
+
+SKILL.md 给了触发时机与阶段入口。本文给：何时写 delta、格式规范（OpenSpec Requirements）、heading 对齐硬规则、场景写法、合并语义。

package/skills/tech-spec/references/transaction-patterns.md

@@ -0,0 +1,212 @@
+# tech-spec / transaction-patterns
+
+事务 / 并发 / 一致性的决策矩阵。design.md §8 的写作依据。
+
+---
+
+## 先问两个问题
+
+1. **一致性要求多强**?(强一致 / 读写一致 / 最终一致 / 容忍丢失)
+2. **涉及几个边界**?(单 DB / 多 DB / 跨服务 / 跨数据中心)
+
+答案组合决定用哪种 pattern。
+
+---
+
+## Pattern 矩阵
+
+| 一致性 \ 边界 | 单 DB | 多 DB | 跨服务 |
+| --- | --- | --- | --- |
+| 强一致(严格 ACID) | 本地事务 ✓ | 不可能(除非 XA;极少用) | 不可能 |
+| 读写一致(线性化) | 本地事务 + 隔离级别 RR | 2PC / XA / Calvin | Saga + 一致性窗口 |
+| 最终一致(BASE) | 事件驱动 + 重试 | 事件驱动 / CDC | Saga / 消息 + 补偿 |
+| 容忍丢失(补偿 ok) | at-least-once | at-least-once | at-least-once + 对账 |
+
+---
+
+## 本地事务(@Transactional / BEGIN...COMMIT)
+
+**适用**:同库同连接,整笔操作要么全成要么全失败。
+
+**硬约束**:
+
+- 事务内**不要**调**外部 RPC**(RPC 慢 → 长事务 → 行锁积压)。把 RPC 移出事务前后。
+- 事务内**不要**调**阻塞 I/O**(文件、网络,除数据库本身)。
+- 事务越短越好:大批量 / 循环放在事务外,事务内只做必要的读写。
+
+**常见陷阱**:
+
+| 陷阱 | 描述 | 对策 |
+| --- | --- | --- |
+| Spring @Transactional 失效 | self-invocation、非 public 方法、非 proxy 调用 | 用 TransactionTemplate / AOP 代理调用 |
+| 嵌套事务 | Propagation 默认 REQUIRED,回滚牵连父事务 | 明确 REQUIRES_NEW 或 NESTED |
+| 长事务 | 循环调外部 API 在事务内 | 拆分:读在事务外,写在事务内 |
+| 异常吞没 | catch 了异常但事务不回滚 | rollbackFor=Exception.class 或主动 setRollbackOnly |
+| 隔离级别误选 | 用 READ_COMMITTED 期待 REPEATABLE_READ 效果 | 明确隔离级别 + 说明理由 |
+
+---
+
+## 幂等(Idempotency)
+
+**适用**:任何"客户端可能重试"的接口,特别是 POST(钱 / 券 / 订单)。
+
+**实现手段**:
+
+| 手段 | 适用 | 实现 |
+| --- | --- | --- |
+| 唯一键 upsert | 有天然唯一 key | `INSERT ... ON DUPLICATE KEY UPDATE` / `ON CONFLICT DO NOTHING` |
+| 请求 nonce / requestId | 无天然唯一 key | 客户端带 requestId;服务端 Redis/DB 存"已处理",过期 1-7 天 |
+| 版本号 / CAS | 更新类 | `UPDATE t SET v=v+1, ... WHERE id=? AND v=?` |
+| 状态机 | 状态流转类 | 前置状态校验,非法转移直接返回 |
+
+**常见陷阱**:
+
+- 幂等 key 用 userId 而不是 orderId → 同一用户第 2 单被误拒
+- Redis 标记与 DB 事务不一致:Redis 写了 DB 失败 → 死锁。先 DB 后 Redis,或用可回滚的"预留"
+- TTL 太短:用户/系统真的过很久重试 → 被当新请求处理
+
+---
+
+## 乐观锁(Optimistic Locking)
+
+**适用**:低冲突(并发改同一行概率小)。
+
+**实现**:
+
+```sql
+UPDATE account SET balance = balance - 100, version = version + 1
+WHERE id = ? AND version = ?
+-- if affected rows == 0 → retry or return 409
+```
+
+**对比悲观锁**:
+
+- 乐观锁:不阻塞;冲突时重试;适合低冲突读多写少
+- 悲观锁(SELECT ... FOR UPDATE):阻塞;适合高冲突(如秒杀);注意死锁与超时
+
+---
+
+## 分布式锁
+
+**适用**:多实例 / 跨进程 互斥(如"同一批次只能有一个 consumer 处理")。
+
+**实现**:
+
+| 实现 | 优 | 劣 |
+| --- | --- | --- |
+| Redis SET NX + PX | 快、部署简单 | 主从切换可能丢锁;需要 Redlock 才完美 |
+| Zookeeper / etcd | 强一致 | 运维成本;延迟高 |
+| 数据库(SELECT FOR UPDATE) | 无额外依赖 | 性能差;锁粒度和事务绑定 |
+
+**硬约束**:
+
+- **必须带 TTL**(防持锁者崩溃后永不释放)
+- **释放要验持锁者**(value=uuid,释放前 CAS 比对,防止错误释放别人的锁)
+- **锁期间业务逻辑不能超过 TTL**,否则锁可能被下一个抢走还没释放
+
+**Redis 锁模板**:
+
+```
+SET lock:<key> <uuid> NX PX 30000   -- 30s TTL
+-- 执行业务
+-- 释放(Lua script 原子执行)
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+end
+```
+
+---
+
+## Saga / 补偿事务
+
+**适用**:跨服务的业务事务(如"下单=扣库存+扣余额+发消息"),不能用 XA。
+
+**两种模式**:
+
+- **Choreography**(协同):每服务监听事件、决定下一步,无中心协调器。松耦合、难调试。
+- **Orchestration**(编排):有中心 saga 引擎,调各参与者。易追踪、可观测性好、有单点。
+
+**必须设计**:
+
+- 每步**都有一个补偿操作**(Cancel / Refund)
+- **补偿必须幂等**(重复补偿不出错)
+- 支持**超时**(某步超过 N 分钟 → 触发补偿)
+- 记录**完整 saga 轨迹**(发生过的 step + pending / compensating)
+
+**Saga 模板**(Orchestration 伪代码):
+
+```
+saga = new Saga(sagaId)
+try:
+  result1 = inventoryService.reserve(...)   # step 1
+  result2 = balanceService.deduct(...)       # step 2
+  result3 = notification.send(...)           # step 3
+  saga.markCompleted()
+except Exception:
+  if step3 failed:
+    balanceService.refund(result2)
+    inventoryService.release(result1)
+  elif step2 failed:
+    inventoryService.release(result1)
+  saga.markFailed()
+```
+
+---
+
+## 批量 / 分片 / 限流
+
+### 批量发放的事务策略(以 `add-coupon-batch-grant` 为例)
+
+**反例**:外层 @Transactional 包 1000 条 INSERT → 长事务 + 行锁风暴
+
+**正例**:
+
+```java
+for (String userId : userIds) {
+  try {
+    grantOneInNewTx(userId);    // @Transactional(propagation=REQUIRES_NEW)
+    succeeded.add(userId);
+  } catch (RiskRejectedException e) {
+    failed.add(new FailedUser(userId, "RISK_HIT", e.getHitCode()));
+  } catch (Exception e) {
+    failed.add(new FailedUser(userId, "SYSTEM_ERROR", e.getMessage()));
+    log.error("grant fail user={}", userId, e);
+  }
+}
+```
+
+- 每个 userId 独立短事务 → 不互相拖累
+- 单个失败不影响整批
+- 失败按类型归类,返回给前端
+
+---
+
+## 最终一致 + 对账
+
+跨系统最终一致的常见设计:
+
+1. **双写**:本地 DB + 发消息 / 写另一系统
+2. **消息重试**:失败消息入死信 → 告警 + 人工介入
+3. **定时对账**:T+1 跑对账 job,不一致部分重发 / 补偿 / 告警
+4. **监控**:对账差异 > 阈值 → P1 告警
+
+**关键**:"最终一致"不代表"不一致也 OK";要有清晰的 **RPO(可容忍数据丢失时间)/ RTO(恢复时间)**。
+
+---
+
+## 隔离级别速查
+
+| 级别 | 读到的问题 |
+| --- | --- |
+| READ_UNCOMMITTED | 脏读 / 不可重复读 / 幻读 |
+| READ_COMMITTED | 不可重复读 / 幻读 |
+| REPEATABLE_READ(MySQL InnoDB 默认) | 幻读(MySQL 的 gap-lock 实际上也避免了幻读) |
+| SERIALIZABLE | 无,但性能差 |
+
+通常用 RC 或 RR;选 RR 时注意 gap lock 对并发插入的影响。
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了事务 pattern 的表(单库 / 分布式 / 幂等 / 乐观锁 / 分布式锁)。本文给每种 pattern 的**硬约束**、**常见陷阱**、**伪代码模板**。tech-spec 写 §8 时对每个事务边界按本文逐条过。