@chenmk/superflow 0.1.1 → 0.1.2

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` |

package/assets/context-templates/external-systems.md

@@ -1,166 +1,69 @@
-# 上游系统约定
+# 外部系统与集成约定
 
-> **初始版来源**：sdd-cli 散落的对账/跨仓规则 + openspec/changes/v1.1-add-charging-package-suite 涉及的外部系统引用
-> **维护方**：架构 / 集成开发
-> **自动化率**：80-95%（MQ topic 常量、API client 调用点静态可挖）
+> **用途**：记录当前项目依赖的外部系统、接口、消息、文件、账号和联调方式。
+> **维护方**：集成负责人 / 模块 owner / 测试负责人
 
-## 1. 系统拓扑概览
+## 1. 系统拓扑
 
+```text
+<当前系统>
+  ├─ HTTP / RPC -> <外部系统 A>
+  ├─ MQ / Event -> <外部系统 B>
+  ├─ File / Object Storage -> <外部系统 C>
+  └─ Webhook / Callback <- <外部系统 D>
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│ evcharge-operator-api (本服务)                                  │
-│   Spring Boot 2.x                                               │
-│   base port: 9250（worktree 派生端口 = 9250 + P/CR 编号）         │
-│   职责：充电套餐核心业务 + 站点 / 设备管理 + 计费对账              │
-└─────────────────────────────────────────────────────────────────┘
-        ↕ (HTTP / MQ / 定时任务 / 回调)
-        ├── BEM (停车月票权益服务)
-        ├── 财务对账系统（定期对账）
-        ├── Lark / 飞书（需求 / 文档 / 通知）
-        ├── 云效 / 钉钉（CI / 任务协作 / bug tracker）
-        ├── 车位 / 设备 IoT（扫码 / 充电桩事件）
-        └── 支付 / 退款通道（第三方）
-```
 
-## 2. 上游系统清单
-
-### 2.1 BEM（停车月票权益服务）
-
-- **职责**：管理停车月票权益，与充电套餐权益互斥 / 同步
-- **集成方式**：HTTP API（同步）+ MQ 事件（异步）
-- **关键事件**：
-  - 充电套餐退款 → BEM 同步退款（CDPT-186 历史事故：同步缺失）
-  - 充电套餐续费 → BEM 续费月票（CDPT-169 历史事故：续费缺失）
-- **数据流向**：
-  - 出：本服务发退款 / 续费请求到 BEM
-  - 入：BEM 回调停车权益变化（webhook / MQ）
-- **失败处理**：BEM 调用失败必须重试 + 告警，不能静默成功
-- **占位**（待人工补）：API 路径、MQ topic、SDK 版本号、对账窗口期
-
-### 2.2 财务对账系统
-
-- **职责**：充电订单 / 退款 / 套餐开通 / 续费 的财务对账
-- **集成方式**：定时任务拉取对账文件 + T+1 对账
-- **关键字段**：
-  - 订单号、金额、支付渠道、退款单号、套餐 ID、站点 ID、运营商 ID
-- **三方对账要求**（见 [decisions §1 ADR-003](./decisions.md#adr-003-sql-总-sql-文件作为版本合同)）：
-  - ① 源码/Mapper 读写字段
-  - ② 开发库结构
-  - ③ 测试库现状 + 版本总 SQL 执行后结构
-- **占位**（待人工补）：对账文件格式、对账时间窗、差异处理流程
-
-### 2.3 Lark / 飞书
-
-- **职责**：
-  - 需求来源（产品文档 / 截图 / 原型 / 会议纪要）
-  - 文档协作（API 文档 / 设计文档 / 验收记录）
-  - 通知（事故告警 / 部署通知 / 周报）
-- **集成方式**：
-  - 文档：人工导入（云文档链接）
-  - 通知：webhook 推送到飞书群机器人
-  - 部分自动化：openspec proposal 生成后同步到飞书文档（待定）
-- **占位**（待人工补）：webhook URL、群机器人 token、文档空间 ID
-
-### 2.4 云效 / 钉钉
-
-- **职责**：
-  - 任务协作（产品 / 开发 / 测试 / 运维）
-  - bug tracker（CDPT-XXX 编号）
-  - CI（自动跑测试 / 构建 / 部署）
-  - 代码托管（gitee / gitlab）
-- **集成方式**：
-  - 任务 / bug：人工操作（云效网页）
-  - CI：webhook 触发
-  - 事故编号命名规范：`CDPT-XXX`
-- **占位**（待人工补）：gitee 仓库地址、CI 配置位置
-
-### 2.5 车位 / 设备 IoT
-
-- **职责**：扫码充电触发、车位枪状态、充电事件
-- **集成方式**：
-  - 扫码：HTTP API（前端 → 本服务 → IoT 网关）
-  - 车位枪状态：MQ 事件（IoT → 本服务）
-  - 充电事件：MQ 事件（IoT → 本服务 → 财务对账）
-- **关键事件**：
-  - 扫码开启充电（CDPT-163 历史事故：开不了）
-  - 车位枪启用 / 停用（CDPT-199 历史事故：未绑定时按钮可点）
-- **占位**（待人工补）：MQ topic、IoT 网关 API、事件 schema
-
-### 2.6 支付 / 退款通道
-
-- **职责**：套餐购买支付、退款、续费扣款
-- **集成方式**：HTTP API（同步）+ webhook 回调
-- **关键流程**：
-  - 支付成功 → 开通套餐 → 同步 BEM
-  - 退款发起 → 支付通道退款 → 同步 BEM → 更新本地状态
-- **占位**（待人工补）：支付渠道（微信 / 支付宝 / 银联）、回调地址
-
-## 3. MQ 约定（占位 — 待人工补实际 topic）
-
-| Topic 模式 | 生产者 | 消费者 | 用途 |
-|-----------|--------|--------|------|
-| `evcharge.charging.event.v1` | 充电桩 / IoT | 本服务 | 充电事件（开始 / 停止 / 故障） |
-| `evcharge.billing.refund.v1` | 本服务 | BEM | 退款事件 |
-| `evcharge.billing.renew.v1` | 本服务 | BEM | 续费事件 |
-| `evcharge.billing.sync.v1` | BEM | 本服务 | 停车月票权益变化 |
-| `evcharge.finance.reconcile.v1` | 财务对账系统 | 本服务 | 对账差异推送 |
-
-> **占位说明**：上述 topic 是命名规范示例，**实际 topic 需从代码常量 / 配置文件核对**（grep `RocketMQTemplate` / `KafkaTemplate` / `@RocketMQMessageListener` 等）
-
-## 4. 共享表 / 跨仓约定
-
-### 4.1 跨仓对账清单（占位 — 待人工补）
-
-| 表 | 真源 | 消费仓 1 | 消费仓 2 | 消费仓 3 |
-|----|------|---------|---------|---------|
-| `t_package` | 本服务 | BEM（只读） | 财务对账 | 定时任务 |
-| `t_package_order` | 本服务 | BEM | 财务对账 | 退款通道 |
-| `t_site` | 本服务 | BEM | IoT 网关 | 第三方平台 |
-| `t_operator` | 本服务 | BEM | 财务对账 | 第三方平台 |
-
-> **占位说明**：实际表名 / 字段 / 关系 需从 `src/main/resources/sql/` 和 `application-*.yml` 核对
-
-### 4.2 关键表（占位 — 待人工补详细 schema）
-
-- `t_package` — 套餐主表
-- `t_package_order` — 套餐开通 / 续费 / 退款记录
-- `t_package_site` — 套餐与站点关系表（**注意：这是 CDPT-165 修复后引入的"中间表"，运营商边界过滤必须走这里**）
-- `t_site` — 站点表
-- `t_operator` — 运营商表
-- `t_site_operator` — 站点与运营商关系表
-
-> **占位说明**：详细字段、索引、外键、默认值需查 `sql/` 目录
-
-## 5. API 约定
-
-### 5.1 REST 风格
-
-- URL：`/api/v1/<resource>/<action>`
-- 鉴权：JWT / Session（占位，待补）
-- 错误码：4xx 业务错误 + 5xx 系统错误（占位，待补错误码表）
-- 分页：统一 `{ page, size, total }` 格式（占位）
-
-### 5.2 关键 API（占位 — 待人工补路径）
-
-| API | 方法 | 用途 | 关联事故 |
-|-----|------|------|---------|
-| 创建套餐 | POST | 运营商创建套餐 | CDPT-165 / CDPT-171 |
-| 套餐分页查询 | GET | 按运营商过滤 | CDPT-165 |
-| 套餐开通 | POST | 用户购买 / 批量开通 | CDPT-179 / CDPT-180 |
-| 套餐续费 | POST | 续费停车月票 | CDPT-169 |
-| 套餐退款 | POST | 单笔 / 批量退款 | CDPT-186 |
-| 套餐适用站点修改 | PUT | 修改适用站点 | CDPT-192 |
-| 扫码充电 | POST | 触发充电 | CDPT-163 |
-| 导出 Excel | GET | 各种导出 | CDPT-166 / CDPT-188 / CDPT-177 |
-
-> **占位说明**：实际 API 路径 / 入参 / 出参 需查 `src/main/java/` 的 Controller
-
-## 6. 维护提示
-
-- 本文件是**初始版**，superflow init Step 5 + 人工补全
-- **自动化补充重点**：
-  - 用 `superflow scan` 让 LLM 扫代码常量 → 自动填 MQ topic、API 路径、表名
-  - grep `RocketMQTemplate` / `KafkaTemplate` / `@RestController` 拿实际接口
-  - 读 `application.yml` 拿数据库连接 / Redis / MQ 连接配置
-- **不要在事故没复盘前**补充根因 — 留空让负责人填
-- 重要变更（升级支付渠道 / 接入新 IoT）必须追加本文件相关章节
+## 2. 外部系统清单
+
+| 系统 | 职责 | 集成方式 | 环境 | owner | 失败处理 |
+|------|------|----------|------|-------|----------|
+| `<系统 A>` | `<职责>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<负责人>` | `<重试/告警/补偿>` |
+| `<系统 B>` | `<职责>` | `<HTTP/MQ/SDK/File>` | `<dev/test/prod>` | `<负责人>` | `<重试/告警/补偿>` |
+
+## 3. API / SDK 约定
+
+| 系统 | API/SDK | 调用方 | 鉴权 | 超时/重试 | 真实联调入口 |
+|------|---------|--------|------|-----------|--------------|
+| `<系统 A>` | `<路径/方法/SDK 方法>` | `<模块>` | `<方式>` | `<策略>` | `<curl/控制台/模拟器>` |
+
+维护要求：
+
+- 真实 API 路径、参数和响应以源码、官方文档或联调记录为准。
+- 不允许凭历史经验补字段；字段语义不确定时必须回到事实源。
+- 新增、删除或重命名字段时，要反查所有调用方、DTO、Mapper、日志和测试。
+
+## 4. 消息与异步链路
+
+| Topic / Queue / Event | 生产者 | 消费者 | Payload 真源 | 幂等键 | 验证方式 |
+|-----------------------|--------|--------|--------------|--------|----------|
+| `<事件名>` | `<系统>` | `<系统>` | `<schema/代码>` | `<字段>` | `<日志/DB/消费记录>` |
+
+异步任务完成证据至少包含：
+
+- 生产侧日志或发送记录。
+- 消费侧日志或处理记录。
+- 状态推进、数据库落库或下游回调。
+- 重试、死信或补偿策略说明。
+
+## 5. 文件、对象存储和批处理
+
+| 文件/任务 | 来源 | 格式 | 存储位置 | 触发方式 | 验证方式 |
+|-----------|------|------|----------|----------|----------|
+| `<文件/任务>` | `<来源>` | `<CSV/XLSX/JSON>` | `<路径/桶>` | `<手动/定时/API>` | `<样本/日志/结果>` |
+
+## 6. 环境与凭据
+
+| 环境 | 地址 | 凭据来源 | 测试账号 | 注意事项 |
+|------|------|----------|----------|----------|
+| dev | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+| test | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+| prod | `<地址>` | `<env/secret manager>` | `<账号>` | `<说明>` |
+
+不要把真实 secret、token、private key 写入本文件。只记录凭据来源和申请方式。
+
+## 7. 联调与验收要求
+
+- 有可用沙箱或测试环境时，不能只提交 mock 结果。
+- 如果真实联调暂不可用，必须写明阻塞原因、owner、恢复条件和临时替代验证。
+- `test-report.md` 必须包含实际请求、实际响应、日志或数据证据。
+- 对外部系统的兼容逻辑必须可观测，不能静默吞错。