@chenmk/superflow 0.1.1 → 0.1.3

package/assets/brand/superflow-banner.svg

@@ -0,0 +1,80 @@
+<svg width="1600" height="420" viewBox="0 0 1600 420" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">SuperBridge Flow banner</title>
+  <desc id="desc">A dark technical banner for SuperBridge Flow, connecting OpenSpec and Superpowers through a bridge-shaped workflow.</desc>
+  <defs>
+    <radialGradient id="blueGlow" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(328 205) rotate(18) scale(502 230)">
+      <stop stop-color="#67e8f9"/>
+      <stop offset="0.34" stop-color="#2563eb" stop-opacity="0.86"/>
+      <stop offset="1" stop-color="#020617" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="greenGlow" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(1110 218) rotate(160) scale(430 210)">
+      <stop stop-color="#22c55e" stop-opacity="0.9"/>
+      <stop offset="0.42" stop-color="#0891b2" stop-opacity="0.64"/>
+      <stop offset="1" stop-color="#020617" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="flow" x1="174" y1="256" x2="1360" y2="126" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#60a5fa"/>
+      <stop offset="0.46" stop-color="#a78bfa"/>
+      <stop offset="1" stop-color="#34d399"/>
+    </linearGradient>
+    <filter id="softGlow" x="-40%" y="-40%" width="180%" height="180%" color-interpolation-filters="sRGB">
+      <feGaussianBlur stdDeviation="10" result="blur"/>
+      <feColorMatrix in="blur" type="matrix" values="0 0 0 0 0.28 0 0 0 0 0.65 0 0 0 0 1 0 0 0 0.9 0"/>
+      <feBlend in="SourceGraphic" mode="screen"/>
+    </filter>
+    <pattern id="dotGrid" width="22" height="22" patternUnits="userSpaceOnUse">
+      <circle cx="2" cy="2" r="1.4" fill="#38bdf8" opacity="0.28"/>
+    </pattern>
+  </defs>
+
+  <rect width="1600" height="420" rx="18" fill="#020617"/>
+  <rect width="1600" height="420" rx="18" fill="url(#blueGlow)"/>
+  <rect width="1600" height="420" rx="18" fill="url(#greenGlow)"/>
+  <rect x="0" y="0" width="1600" height="420" fill="url(#dotGrid)" opacity="0.72"/>
+
+  <path d="M94 310C250 136 405 106 568 214C734 324 884 319 1039 181C1159 74 1298 56 1488 112" stroke="url(#flow)" stroke-width="8" stroke-linecap="round" filter="url(#softGlow)"/>
+  <path d="M122 338C298 210 438 205 584 282C743 365 936 308 1054 214C1184 111 1318 103 1476 154" stroke="#e0f2fe" stroke-width="2" stroke-linecap="round" opacity="0.78"/>
+  <path d="M126 282C298 68 513 80 664 196C808 307 966 273 1092 146C1214 23 1374 32 1502 72" stroke="#93c5fd" stroke-width="2" stroke-linecap="round" opacity="0.42"/>
+
+  <g opacity="0.86">
+    <path d="M280 304H1320" stroke="#64748b" stroke-width="2"/>
+    <path d="M360 304C430 218 500 178 570 178C650 178 710 304 790 304C875 304 935 178 1025 178C1100 178 1168 222 1240 304" stroke="#cbd5e1" stroke-width="5" stroke-linecap="round"/>
+    <path d="M422 304V252M528 304V207M635 304V207M742 304V252M858 304V252M965 304V207M1072 304V207M1178 304V252" stroke="#cbd5e1" stroke-width="5" stroke-linecap="round"/>
+  </g>
+
+  <g>
+    <rect x="94" y="84" width="230" height="52" rx="8" fill="#0f172a" stroke="#38bdf8" stroke-opacity="0.45"/>
+    <text x="118" y="118" fill="#bae6fd" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="24" letter-spacing="2">OpenSpec / SDD</text>
+    <rect x="94" y="148" width="230" height="40" rx="8" fill="#020617" stroke="#334155"/>
+    <text x="118" y="174" fill="#94a3b8" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="18">WHAT + contracts</text>
+  </g>
+
+  <g>
+    <rect x="1276" y="238" width="230" height="52" rx="8" fill="#052e2b" stroke="#34d399" stroke-opacity="0.52"/>
+    <text x="1300" y="272" fill="#bbf7d0" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="24" letter-spacing="2">Superpowers</text>
+    <rect x="1276" y="302" width="230" height="40" rx="8" fill="#020617" stroke="#334155"/>
+    <text x="1300" y="328" fill="#94a3b8" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="18">HOW + verification</text>
+  </g>
+
+  <g>
+    <text x="522" y="132" fill="#f8fafc" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="72" font-weight="800" letter-spacing="6">SUPERFLOW</text>
+    <text x="528" y="179" fill="#cbd5e1" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="28" letter-spacing="5">SUPERBRIDGE FLOW</text>
+    <text x="531" y="224" fill="#60a5fa" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="24" letter-spacing="3">FROM REQUIREMENT TO VERIFIED DELIVERY</text>
+  </g>
+
+  <g fill="#e2e8f0" font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="17" opacity="0.9">
+    <text x="506" y="355">docs</text>
+    <text x="638" y="355">design</text>
+    <text x="800" y="355">implement</text>
+    <text x="990" y="355">verify</text>
+    <text x="1136" y="355">archive</text>
+  </g>
+
+  <g fill="#38bdf8" filter="url(#softGlow)">
+    <circle cx="486" cy="304" r="7"/>
+    <circle cx="624" cy="304" r="7"/>
+    <circle cx="782" cy="304" r="7"/>
+    <circle cx="960" cy="304" r="7"/>
+    <circle cx="1118" cy="304" r="7"/>
+  </g>
+</svg>

package/assets/context-templates/business-rules.md

@@ -1,98 +1,65 @@
 # 业务规则
 
-> **初始版来源**：`sdd-cli/assets/skills/` 抽出的散落业务引用 + SDD 方法论规则
-> **维护方**：业务/产品 + 开发
-> **自动化率**：30-50%（验证逻辑可挖，产品 PRD 规则需人工补）
+> **用途**：沉淀当前项目的长期业务规则、边界条件、状态流转和验收口径。
+> **维护方**：产品负责人 / 业务负责人 / 开发负责人
+> **更新方式**：`superflow init` 生成初始模板后，由项目团队按真实业务补充。
 
-## 1. 充电业务核心规则
+## 1. 核心业务对象
 
-### 1.1 套餐业务
+| 对象 | 业务含义 | 唯一性规则 | 生命周期状态 | 关键约束 |
+|------|----------|------------|--------------|----------|
+| `<业务对象 A>` | `<说明>` | `<唯一键/去重规则>` | `<状态流>` | `<边界条件>` |
+| `<业务对象 B>` | `<说明>` | `<唯一键/去重规则>` | `<状态流>` | `<边界条件>` |
 
-- **运营商边界**：套餐不跨运营商，创建/查询时必须按运营商隔离
-  - 历史事故：CDPT-165 套餐运营商筛选不匹配（修复 commit 见 [incidents.md](./incidents.md)）
-- **适用站点**：套餐可绑定多个站点，已开通记录的适用站点应随套餐变更同步更新
-  - 历史事故：CDPT-192 修改适用站点后记录未同步
-- **同名限制**：同一站点不允许创建相同名称的优惠套餐
-  - 历史事故：CDPT-171
-- **有效时段**：允许跨天（如 22:00-06:00）
-  - 历史事故：CDPT-158
-- **同车牌规则**：同车牌不同套餐、不同有效时间段允许同时开通
-  - 历史事故：CDPT-175
+## 2. 状态流转规则
 
-### 1.2 计费 / 退款 / 对账
+| 状态 | 进入条件 | 允许操作 | 禁止操作 | 退出条件 |
+|------|----------|----------|----------|----------|
+| `<状态 A>` | `<触发条件>` | `<操作>` | `<操作>` | `<条件>` |
+| `<状态 B>` | `<触发条件>` | `<操作>` | `<操作>` | `<条件>` |
 
-- **停车月票退款同步**：充电套餐退款后，停车月票权益在 BEM 也必须同步退款
-  - 历史事故：CDPT-186
-- **三方对账**：发布前必须对齐 ① 源码/Mapper 读写字段 ② 开发库结构 ③ 测试库现状 + 版本总 SQL 执行后结构
-  - 测试库已有字段不得重复 ADD
-  - 类型/注释不一致时生成 MODIFY 或写明不采纳理由
-- **SQL 收口对账表**：每个 DB 相关 P/CR 任务必须输出
+维护要求：
 
-  | P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论 |
+- 修改状态字段、枚举值、派生字段时，必须反查所有读取、写入、查询条件、
+  导出、定时任务、回调和跨仓同步位置。
+- 状态派生规则必须写清楚真实来源，禁止凭字段名猜测。
+- 兼容旧状态或 fallback 逻辑必须写明 owner、移除条件和观测方式。
 
-### 1.3 车位 / 设备
+## 3. 关键业务规则
 
-- **车位枪启停**：站点未绑定车位枪时，【启用车位枪】按钮不允许打开
-  - 历史事故：CDPT-199
+| 编号 | 规则 | 适用场景 | 反例/边界 | 验收方式 |
+|------|------|----------|-----------|----------|
+| BR-001 | `<规则描述>` | `<页面/API/任务>` | `<容易遗漏的情况>` | `<测试/联调/人工验收>` |
+| BR-002 | `<规则描述>` | `<页面/API/任务>` | `<容易遗漏的情况>` | `<测试/联调/人工验收>` |
 
-## 2. 批量操作规则
+## 4. 数据与权限边界
 
-### 2.1 批量开通 / 续费 / 退款
+| 维度 | 规则 | 核验入口 |
+|------|------|----------|
+| 租户 / 组织 / 项目 | `<隔离规则>` | `<源码/配置/数据表>` |
+| 用户角色 | `<权限规则>` | `<菜单/接口/鉴权点>` |
+| 数据可见性 | `<查询范围>` | `<Mapper/API/页面>` |
+| 数据修改权 | `<写入限制>` | `<Service/事务/审计>` |
 
-- **手机号格式**：支持 1 个或 2 个手机号，逗号分隔（如 `18666666666,19888888888`）
-  - 历史事故：CDPT-185
-- **错误提示**：遇错误/异常数据必须明确指出"哪一行、哪个字段异常"，整批不插入
-  - 历史事故：CDPT-180
-- **必填标记**：模板中必填字段必须标【必填】
-  - 历史事故：CDPT-178
-- **当天 1 天有效期**：批量开通当天 + 1 天有效期时，记录显示已过期（页面显示生效中）
-  - 历史事故：CDPT-179 — 需验证时区与日期边界
-- **空模板检测**：导入空 Excel 模板应报错，不应提示成功
-  - 历史事故：CDPT-181
+## 5. 批量、导入导出和异常规则
 
-### 2.2 批量导入
+- 批量操作必须定义部分成功/全部失败策略。
+- 导入模板必须定义必填、格式、枚举、重复数据和空文件行为。
+- 导出字段必须和页面/接口字段语义一致；如不一致，需记录原因。
+- 错误提示必须能定位到对象、行号、字段或可操作的修复建议。
 
-- **车位枪文件格式错误**：错误提示需优化（具体到行列）
-  - 历史事故：CDPT-198
-- **车位枪文件类型错误**：提示需优化
-  - 历史事故：CDPT-181
+## 6. 真实验收要求
 
-## 3. 扫码充电
+涉及外部系统、数据库、异步任务、消息队列、支付、文件、权限或状态流的
+需求，不能只用 mock 单元测试作为完成证据。`test-report.md` 至少应记录：
 
-- **扫码后无套餐**：开通充电套餐后扫码开启充电，无套餐可用
-  - 历史事故：CDPT-163 — 需核对套餐状态/有效时段
-- **扫码开票提示**：已退款的优惠套餐订单，扫码开票提示需优化
-  - 历史事故：CDPT-189
-
-## 4. 数据权限 / 字段约束
-
-- **最近操作人**：开通套餐记录中"最近操作人"取值错误（admin 后台开通时显示为前端用户）
-  - 历史事故：CDPT-164
-- **导出 Excel**：
-  - 套餐开通记录导出，剩余充电额度为不限额时导出内容错误（CDPT-188）
-  - 套餐开通记录导出，**不合并**不连续的有效期（CDPT-177）
-  - 创建套餐页面，导出 Excel 中的使用站点列展示错误（CDPT-166）
-  - 批量开通记录导出，手机号 / 车牌应支持模糊查询（CDPT-173）
-- **页面不显示但后端必填**：标记为 backend default 或 backend-derived（SDD 硬规则）
-- **过设计字段**：UI 不展示但后端要写，标 backend default；UI 展示但后端不需要，标 over-designed
-
-## 5. 状态流转
-
-- **开票 / 退款 / 续费 状态**：套餐开通 → 生效中 → 退款 / 续费 / 过期，状态字段派生后消费仓查询条件必须同步迁移
-  - 不允许继续按旧字段过滤
-- **有效期 / 充电额度**：派生字段（从持久化状态 / JSON 快照计算），消费仓同步改用派生表达式
-
-## 6. 上游系统交互（占位 — 详见 [external-systems.md](./external-systems.md)）
-
-- **BEM（停车月票权益）**：退款 / 续费双向同步
-- **Lark / 飞书**：需求来源、文档协作
-- **B 站？财务对账**：定期对账
-
----
+- 真实入口：页面、API、消息、定时任务或外部回调。
+- 真实参数：请求体、消息体、文件样本或测试账号。
+- 真实结果：响应、数据库记录、日志、下游回调或页面状态。
+- 断言：期望值与实际值的对比。
 
 ## 7. 维护提示
 
-- 本文件是**初始版**，由 superflow init Step 5 自动生成 + 人工补全
-- 后期跟 LLM 沟通解释业务系统时，可让 LLM 把新规则追加到本文件
-- 每条规则建议标注：**事故编号（如 CDPT-XXX）| 修复 commit | 验证日期**
-- 自动化补充：可以用 `superflow scan` 让 LLM 重扫项目，对比本文件并提示遗漏
+- 本文件只记录项目自己的业务事实，不写通用流程口号。
+- 新增事故、返工或联调问题后，把可复用规则补回这里。
+- 不确定的规则标为 `待确认`，并写清需要谁确认、确认入口是什么。

package/assets/context-templates/decisions.md

@@ -1,153 +1,67 @@
-# 团队设计决策
+# 架构与工程决策
 
-> **初始版来源**：sdd-cli 散落的项目约定（端口、命名、工作流）+ evcharge-operator-api 现有架构
-> **维护方**：架构 / 研发 lead
-> **自动化率**：30-50%（commit "refactor" 可挖，ADR 文件不一定存在）
+> **用途**：沉淀当前项目的长期架构选择、工程约定和取舍原因。
+> **维护方**：架构负责人 / 技术负责人 / 模块 owner
+> **推荐格式**：ADR（Architecture Decision Record）
 
-格式：ADR 风格（Why / Alternatives / Consequence）
+## ADR-001: <决策标题>
 
----
-
-## 1. 工程约定
-
-### ADR-001: worktree 启动端口 = base port + P/CR 编号
-
-- **状态**：已确立
-- **背景**：多 worktree 并行开发时，端口冲突会导致调试互相干扰
-- **决策**：每个 worktree 启动端口 = `base server.port + P/CR 编号`
-  - 例：P50 任务 base 9250 → 启动端口 9300
-  - 冲突时 fallback 找下一个可用端口
-- **原因**：
-  - 可预测（看 P 编号就知道端口）
-  - 不需要中心化端口分配
-  - CI / 健康检查 URL 可以静态配置
+- **状态**：拟定 / 已采纳 / 已废弃 / 被替代
+- **日期**：YYYY-MM-DD
+- **背景**：为什么需要这个决策，原问题是什么。
+- **决策**：最终选择的方案。
 - **替代方案**：
-  - 动态分配（每次启动随机空闲端口）— 失去可预测性
-  - 集中注册表（K8s Service / Port Registry）— 引入新组件，过重
-- **后果**：
-  - worktree prompt 必须显式写出推导端口 + 启动命令 + curl URL
-  - 端口用尽时（极端情况）需要扩 base
-
-### ADR-002: P 编号 / CR 编号命名
-
-- **状态**：已确立
-- **背景**：实现任务需要可追溯编号
-- **决策**：
-  - 主任务 `PXX`（大版本下递增），如 P50、P64、P65
-  - 联调 / 集成后追加项 `CR` 或 `PX`（同 P 编号空间）
-  - prompt 文件名 `pXX-xxx.md`（小写 p + 横线）
-  - batch 内嵌在 `embedded-changes/pXX-*` 目录
-- **后果**：
-  - 已执行的 batch prompt 不修改，新增 CR/Px
-  - 不允许把无关改动混进当前 P 编号
-  - 平行 worktree 只更新自己 `pXX-*` 内的交付文档，不动顶层聚合文档
-
-### ADR-003: SQL 总 SQL 文件作为版本合同
-
-- **状态**：已确立
-- **背景**：研发 agent 经常忘记执行增量 SQL，导致字段缺失 / 默认值缺失，最终绕过数据库问题产生隐蔽 bug
-- **决策**：
-  - **写代码前必须先检查数据库**：对照 design/api/spec/tasks 中涉及的表/字段/索引/默认值/枚举值/初始化数据，连接开发库执行 DESC / SHOW CREATE TABLE 确认实际结构
-  - **独立 P/CR 任务必须回写版本总 SQL**：开发库已有 + 局部 SQL 执行过 + agent 回复里写过 SQL，都不等于交付完成。源码/Mapper 依赖的表结构或初始化数据，必须确认版本总 SQL 包含对应变更
-  - **任务完成必须有 SQL 收口对账表**：`P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论`
-  - **发布前必须做三方对账**：① 源码/Mapper 读写字段 ② 开发库结构 ③ 测试库现状 + 版本总 SQL 执行后结构
-- **后果**：
-  - 数据库相关任务必须有"数据库验证"步骤（`SHOW CREATE TABLE` / `SELECT`）
-  - "开发库已经有" 不算交付完成
-  - 测试库已有字段不得重复 ADD；类型/注释不一致时 MODIFY 或写明不采纳理由
-
-### ADR-004: 跨仓对账规则
-
-- **状态**：已确立
-- **背景**：实体 / Mapper / SQL 漂移会导致业务行为不一致
-- **决策**：需求涉及共享表时必须做 7 步对账：
-  1. 指定表结构真源：哪个 SQL 文件 / 哪个库的 SHOW CREATE TABLE / 哪个仓库模型
-  2. 列出全部消费仓：直接 CRUD 仓库、互联互通仓库、定时任务、回调服务、导入导出服务、测试端点
-  3. 对每个消费仓做字段对账：`@TableName` 实体字段、`BaseMapper` 默认查询列、Mapper XML/resultMap、手写 SQL、查询条件 vs `information_schema.columns` / `SHOW CREATE TABLE`
-  4. 派生字段迁移：状态派生后查询条件必须同步
-  5. test-report 记录跨仓对账表：`表 | 真源结构 | 消费仓 | 实体/Mapper/SQL 字段 | 实际库字段 | 处理结论 | 验证证据`
-- **后果**：
-  - 修改共享表的需求必须先列消费仓清单
-  - 改完一处必须全仓同步验证
-
-## 2. SDD 工作流约定
-
-### ADR-005: SDD 硬门禁
-
-- **状态**：已确立
-- **决策**：
-  - **understand-anything 必须先扫**：SDD 任何澄清 / 实现前，check `.understand-anything/` 等产物，不存在则先跑索引
-  - **既有代码 / 数据关系核实顺序**：understand-anything graph → source/Mapper/XML 锚点 → 只读数据库检查（源码不足时）
-  - **关系仍不清楚**：停下来问用户，标 `Blocked`，禁止凭字段名猜测设计
-  - **process one feature at a time**：按产品文档顺序，逐个 feature 串行
-  - **未确认前不生成 spec/design/tasks/tests/prompt**
-  - **不做"single-agent only" implementation prompt**：必须含 Worker + 独立 Tester + Reviewer + Leader
-- **后果**：
-  - 实现 prompt 必含"superpower 团队 prefix" + "understand-anything 平台级影响分析" + "既有代码 / 数据关系核实" + "worktree 启动端口" 4 段
-  - 缺任意一段 → 标 Blocked
-
-### ADR-006: 实现完成判定（不是 BUILD SUCCESS）
-
-- **状态**：已确立
-- **决策**：批量完成必须验证：
-  - prompt 交叉链接（prompt/implementation.md 引用 → tasks.md 引用 → traceability-matrix.md 引用 → tests/test-report.md 验证项）
-  - Markdown handoff 链接：所有引用的 `.md` 文件是相对路径可点击链接
-  - understand-anything 影响证据（test-report.md 含 受影响模块/接口/表 + 回归验证）
-  - 既有代码 / 数据关系证据（按核实顺序留痕）
-  - 编译/构建输出
-  - **测试**真的跑过（BUILD SUCCESS ≠ 测试通过）
-  - 引用 SDK / 同源项目版本号升级（1.0.8-SNAPSHOT → 1.0.9-SNAPSHOT）
-  - 三层门禁：`.sdd-enforced` / `.db-verified` hook 标记 + `superflow-verify-integration.sh` + `superflow-delivery-check.sh`
-  - 数据库相关任务：版本总 SQL 已更新 + SQL 收口对账表
-  - L3/L4 测试：curl + 真实请求参数（来源标注）+ 响应 + 断言 + DB 证据 + 日志
-  - Bug 修复：Red-Green 证据（修复前失败的 curl/test，修复后同样路径通过）
-- **后果**：
-  - 单元测试只能作为辅助证据
-  - placeholder / mock-only / skipped / 缺测试数据 — 不算通过
-  - "问要不要启动 app" — 不算有效闭环
-  - 必须跑或请求 `openspec validate <change-id> --strict`
-
-### ADR-007: 平行 worktree 不许动顶层聚合文档
-
-- **状态**：已确立
-- **决策**：
-  - Worker prompt 只更新自己 `embedded-changes/pXX-*` 内的 `tasks.md` / `test-report.md` / `sdd-quality-gate.md` 等 P-local 文档
-  - **禁止**编辑顶层聚合文档（root `tasks.md` / `test-report.md` / `traceability-matrix.md` / `sdd-quality-gate.md` / `tests.md`）
-  - 聚合文档更新由 Leader closeout worktree 单独 commit（创建 `.sdd-aggregate-closeout` 标记）
-- **原因**：避免平行 worktree 合并冲突
-- **后果**：
-  - `superflow-delivery-check.sh` 会 block 顶层文档改动，worker 必须移除
-  - 顶层文档改动只有 Leader worktree 能做
-
-## 3. 业务架构决策
-
-### ADR-008: 套餐适用站点的真源是 site 关系表
-
-- **状态**：已确立（CDPT-165 修复后）
-- **背景**：原版按 `t_package.operator_id` 直接过滤，未走 site 关系表，导致运营商边界漏掉
-- **决策**：套餐分页/导出按运营商查询时，**改为按站点关系表过滤**（关联到 `t_site` / `t_site_operator` 等关系表）
-- **原因**：
-  - 套餐适用站点是中间关系，不是直属于运营商
-  - 直查 `t_package.operator_id` 会漏掉"该运营商的站点绑定了别运营商套餐"的情况
-- **后果**：
-  - 涉及运营商边界的查询必须 join 站点关系表
-  - 套餐分页 / 导出接口需要走同一过滤逻辑
-- **相关**：CDPT-165 修复 commit
-
-### ADR-009: 状态字段派生化（从持久化到 JSON/计算）
-
-- **状态**：演进中
-- **背景**：单字段（如 `plot_id`）切换到 JSON / 多站点快照字段
-- **决策**：
-  - 状态 / 时段 / 额度 等"派生属性"改为计算字段或 JSON 快照，不再单字段持久化
-  - 消费仓查询条件必须同步迁移（不能继续按旧字段过滤）
-- **后果**：
-  - 跨仓对账时派生字段要明确标注
-  - 派生 vs 持久化边界由需求阶段决定
-
-## 4. 维护提示
-
-- 本文件是**初始版**，由 superflow init Step 5 + 人工补全
-- 后期可让 LLM 通过 git log + commit message 挖掘团队决策（"重构因为..."、"refactor: 改用 X"）
-- 重要架构变更（影响 ≥ 2 个模块）必须追加 ADR，不允许只在 commit message 里说
-- 决策**可被推翻**，但推翻时必须在本文件追加新 ADR 并说明旧 ADR 为何不再适用
+  - 方案 A：优点、缺点。
+  - 方案 B：优点、缺点。
+- **影响范围**：涉及的仓库、模块、表、接口、任务或部署方式。
+- **后果**：带来的收益、成本、风险和后续约束。
+- **验证方式**：如何确认决策被正确执行。
+
+## 1. 项目结构约定
+
+| 主题 | 当前约定 | 真源位置 | 备注 |
+|------|----------|----------|------|
+| 模块边界 | `<说明>` | `<目录/文档/配置>` | `<备注>` |
+| 分层方式 | `<说明>` | `<目录/代码入口>` | `<备注>` |
+| 命名规范 | `<说明>` | `<README/代码示例>` | `<备注>` |
+| 配置管理 | `<说明>` | `<application/env/secret>` | `<备注>` |
+
+## 2. 数据库与持久化约定
+
+| 主题 | 当前约定 | 强制门禁 |
+|------|----------|----------|
+| 表结构真源 | `<SQL 文件/迁移工具/线上结构>` | 修改前先核实真源 |
+| 版本 SQL / migration | `<规则>` | 代码依赖字段必须进入发布物 |
+| 共享表消费方 | `<仓库/模块清单>` | 修改字段必须反查所有消费方 |
+| 软删除 / 多租户 | `<规则>` | Mapper/XML 查询必须显式对齐 |
+
+## 3. API 与集成约定
+
+| 主题 | 当前约定 | 验证方式 |
+|------|----------|----------|
+| API 风格 | `<REST/RPC/GraphQL/消息>` | `<契约测试/联调>` |
+| 鉴权方式 | `<说明>` | `<测试账号/权限矩阵>` |
+| 错误码 | `<说明>` | `<接口文档/测试>` |
+| 外部系统调用 | `<说明>` | `<真实环境/沙箱/模拟器>` |
+
+## 4. 测试与交付约定
+
+- 单元测试验证局部逻辑，不等价于真实链路通过。
+- 涉及外部入口的任务必须留下真实入口证据。
+- 涉及数据库的任务必须留下表结构、数据写入或查询证据。
+- 涉及异步链路的任务必须留下消息、日志、状态推进或重试证据。
+- 声明完成前必须执行 Superflow guard 和项目自己的验证命令。
+
+## 5. Superflow 使用约定
+
+- OpenSpec/SDD 负责 WHAT 和合同。
+- Superpowers 负责源码级 HOW、TDD 顺序、review 和验证纪律。
+- `.sdd/state.yaml` 和 `.sdd/handoff/` 是防止上下文漂移的状态真源。
+- Worker 并行开发时，必须明确各自只修改的文档和代码范围。
+- 如果文档、代码或测试报告发生变化，必须刷新 handoff hash。
+
+## 6. 废弃决策
+
+| 原决策 | 废弃原因 | 替代决策 | 日期 |
+|--------|----------|----------|------|
+| `<ADR 编号>` | `<原因>` | `<ADR 编号>` | `YYYY-MM-DD` |