@chenmk/superflow 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# SuperBridge Flow
+
+[中文文档](./README.zh-CN.md)
+
+SuperBridge Flow is a workflow CLI for bringing OpenSpec/SDD and Superpowers
+together in real software delivery.
+
+- OpenSpec/SDD owns **WHAT**: requirements, API contracts, database and field
+  semantics, tests, real-entry acceptance, and quality gates.
+- Superpowers owns source-level **HOW**: technical design, TDD order,
+  worktree/team execution, review, and verification discipline.
+- The full lifecycle is `docs -> design -> implement -> verify -> archive`.
+
+The CLI installs skills, hooks, rules, scripts, handoff state, and dependency
+guards for Claude Code and Codex.
+
+## Install
+
+```bash
+npm install -g @chenmk/superflow
+```
+
+Then initialize a project:
+
+```bash
+superflow init
+```
+
+Interactive init lets you select:
+
+- target agent tools: Claude Code, Codex, or both
+- language: English or Chinese
+- install scope: global or project
+
+Non-interactive usage:
+
+```bash
+superflow init --yes
+superflow init --language en --yes
+superflow init --language zh --yes
+```
+
+## What Init Installs
+
+`superflow init` installs and configures:
+
+- OpenSpec CLI, then runs `openspec init <project> --tools ...`
+- Superpowers for the selected agent tools
+- SuperBridge Flow/OpenSpec skills
+- hooks, scripts, and anti-drift rules
+- Codex prompt aliases
+- optional understand-anything integration checks
+- `docs/sdd-context/` project context scaffolding
+
+OpenSpec and Superpowers are hard dependencies. understand-anything is
+best-effort and does not block initialization.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `superflow init` | Install and configure SuperBridge Flow interactively |
+| `superflow update` | Refresh installed skills, hooks, scripts, and rules |
+| `superflow update --with-package` | Also update `@chenmk/superflow`, OpenSpec, and Superpowers |
+| `superflow doctor` | Diagnose installed assets and project state |
+| `superflow status` | Show active changes, current phase, next command, and risks |
+| `superflow pipeline` | Check pipeline skill deployment |
+| `superflow docs` | Check docs-phase skill deployment |
+| `superflow design` | Check design-phase skill deployment |
+| `superflow implement` | Check implement-phase skill deployment |
+| `superflow verify` | Check verify-phase skill deployment |
+| `superflow archive` | Check archive-phase skill deployment |
+
+## Agent Usage
+
+In Codex:
+
+```text
+Use $superflow-pipeline to analyze this requirement and drive the full workflow.
+```
+
+In Claude Code:
+
+```text
+/superflow-pipeline
+```
+
+For large requirements, ask the agent to read one section or one feature at a
+time. SuperBridge Flow will route through clarification, OpenSpec docs,
+Superpowers technical design, implementation prompts, verification, and archive.
+
+## Automatic Update Checks
+
+After hooks are registered, SuperBridge Flow checks core dependency updates once
+per new session and throttles real network checks to once every 6 hours by
+default.
+
+Default behavior is **check only**. It reports available updates but does not
+install them. Run this to update explicitly:
+
+```bash
+superflow update --with-package
+```
+
+Environment controls:
+
+```bash
+# Default: check and report
+export SUPERFLOW_AUTO_UPDATE=check
+
+# Disable automatic checks
+export SUPERFLOW_AUTO_UPDATE=0
+
+# Optional for personal machines: install automatically when updates are found
+export SUPERFLOW_AUTO_UPDATE=apply
+
+# Minimum check interval in seconds; default is 21600
+export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
+```
+
+## Language Support
+
+SuperBridge Flow supports English and Chinese installation modes.
+
+- `--language en`: deploys English-facing SuperBridge Flow skills and CLI
+  prompts where available.
+- `--language zh`: deploys the original Chinese full-detail skill set.
+
+The Chinese skill set currently contains the most detailed operational
+templates. The English skill set is designed as a practical public beta and
+keeps the same workflow contracts.
+
+## Requirements
+
+- Node.js 20+
+- Claude Code or Codex
+- npm access to install OpenSpec and Superpowers
+- Git Bash or a compatible shell on Windows for hook scripts
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,117 @@
+# SuperBridge Flow
+
+[English](./README.md)
+
+通用 SDD 开发工作流 CLI，支持 Claude Code 和 Codex。
+
+把 SuperBridge Flow 技能和配套 hook 脚本整合为单一 npm 包，通过 CLI 自动部署到：
+
+- Claude Code：`~/.claude/skills/`、`~/.claude/scripts/`，并注册 `~/.claude/settings.json` hook
+- Codex：`~/.codex/skills/`、`~/.codex/hooks/`
+
+## 安装
+
+```bash
+npm install -g @chenmk/superflow
+```
+
+完整安装、初始化和日常使用教程见 [INSTALL.md](./INSTALL.md)。
+
+## 快速开始
+
+```bash
+# 交互式选择 Claude Code / Codex（可多选）
+superflow init
+
+# 非交互模式，默认同时安装 Claude Code + Codex
+superflow init --yes
+
+# 跳过 hook 注册（手工管理）
+superflow init --no-hooks
+
+# 只打印计划不执行
+superflow init --dry-run
+
+# 从失败步骤继续
+superflow init --resume
+
+# 验证安装
+superflow doctor
+```
+
+## SDD 分工
+
+- OpenSpec/SDD 负责 WHAT 和合同：需求、API、DB、SQL、字段语义、tests、真实入口验收和质量门禁。
+- Superpowers 负责 HOW：源码级技术详设、TDD/RED 顺序、团队分工、worktree/端口并行、review/tester 编排和验证闭环。
+- 完整流程是 `docs -> design -> implement -> verify -> archive`。Superpowers 技术详设落到 `docs/superpowers/specs/*-technical-design.md`，并记录到 `.sdd/state.yaml` 的 `technical_design`，避免长会话压缩后漂移。
+- Codex 侧通常用自然语言或 `$superflow-pipeline` 触发；Claude Code 侧可以直接用 `/superflow-pipeline`、`/superflow-docs`、`/superflow-design` 等 slash command。
+- 飞书、语雀等在线文档读取工具不内置在 SuperBridge Flow CLI 中；可自行用 `lark-cli` 等外部工具读取，再通过 `/superflow-pipeline` 或 `$superflow-pipeline` 分段分析指定小节。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `superflow init` | 一站式安装；交互终端中可多选 Claude Code / Codex |
+| `superflow init --yes` | 非交互安装，默认 `--agent both` |
+| `superflow init --dry-run` | 只打印计划不执行 |
+| `superflow init --resume` | 从失败步骤继续 |
+| `superflow init --no-hooks` | 只装技能 + 脚本，跳过 Codex/Claude hook 注册 |
+| `superflow init --no-openspec-init` | 跳过当前项目 OpenSpec 原生初始化 |
+| `superflow doctor` | 诊断 CLI / 第三方 / 脚本 / skills |
+| `superflow doctor --agent codex` | 只诊断 Codex 侧 |
+| `superflow clarify [feature]` | 校验 SuperBridge Flow clarify 阶段技能部署 |
+| `superflow docs [change]` | 校验 SuperBridge Flow docs 阶段技能部署 |
+| `superflow design [change]` | 校验 SuperBridge Flow design 阶段技能部署 |
+| `superflow implement [task]` | 校验 SuperBridge Flow implement 阶段技能部署 |
+| `superflow pipeline` | 校验 SuperBridge Flow pipeline 阶段技能部署 |
+
+## 系统支持
+
+- macOS 10.15+
+- Linux（Ubuntu 20.04+ / 其它主流发行版）
+- Windows 10+（CLI 本体支持；hook 脚本需要 Git Bash 或兼容 shell）
+
+## 依赖
+
+- Node.js 20+
+- Claude Code 或 Codex（按 `--agent` 选择）
+- 第三方（`superflow init` 自动装）：
+  - openspec CLI（硬依赖，npm 全局）并在当前项目执行 `openspec init --tools ...`
+  - superpowers（硬依赖，Claude Code / Codex 对应插件）
+  - understand-anything（尽力安装，失败只警告）
+  - api-doc-changelog（辅助 skill，复制到目标 agent skills 目录）
+
+## 自动检查更新
+
+注册 hook 后，Superflow 会在新会话开始时轻量检查核心依赖更新：
+
+- `@chenmk/superflow`
+- `@fission-ai/openspec`
+- Claude Code / Codex 的 Superpowers 插件
+
+推荐策略是“自动检查，手动更新”：默认只提示，不自动安装；执行
+`superflow update --with-package` 才会统一更新。
+同一会话只检查一次，并且默认至少间隔 6 小时才真正访问 npm/plugin 源。
+
+```bash
+# 默认：只检查并提示
+export SUPERFLOW_AUTO_UPDATE=check
+
+# 关闭自动检查
+export SUPERFLOW_AUTO_UPDATE=0
+
+# 个人机器可选：检查到新版本后自动安装
+export SUPERFLOW_AUTO_UPDATE=apply
+
+# 调整最小检查间隔，默认 21600 秒（6 小时）
+export SUPERFLOW_UPDATE_MIN_INTERVAL_SECONDS=21600
+```
+
+## 设计文档
+
+- 详细设计：`~/cmk-project/code-cli-config/sdd-cli-design.md`
+- 实施 plan：`~/cmk-project/code-cli-config/sdd-cli-plan.md`
+
+## 许可证
+
+MIT

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

@@ -0,0 +1,98 @@
+# 业务规则
+
+> **初始版来源**：`sdd-cli/assets/skills/` 抽出的散落业务引用 + SDD 方法论规则
+> **维护方**：业务/产品 + 开发
+> **自动化率**：30-50%（验证逻辑可挖，产品 PRD 规则需人工补）
+
+## 1. 充电业务核心规则
+
+### 1.1 套餐业务
+
+- **运营商边界**：套餐不跨运营商，创建/查询时必须按运营商隔离
+  - 历史事故：CDPT-165 套餐运营商筛选不匹配（修复 commit 见 [incidents.md](./incidents.md)）
+- **适用站点**：套餐可绑定多个站点，已开通记录的适用站点应随套餐变更同步更新
+  - 历史事故：CDPT-192 修改适用站点后记录未同步
+- **同名限制**：同一站点不允许创建相同名称的优惠套餐
+  - 历史事故：CDPT-171
+- **有效时段**：允许跨天（如 22:00-06:00）
+  - 历史事故：CDPT-158
+- **同车牌规则**：同车牌不同套餐、不同有效时间段允许同时开通
+  - 历史事故：CDPT-175
+
+### 1.2 计费 / 退款 / 对账
+
+- **停车月票退款同步**：充电套餐退款后，停车月票权益在 BEM 也必须同步退款
+  - 历史事故：CDPT-186
+- **三方对账**：发布前必须对齐 ① 源码/Mapper 读写字段 ② 开发库结构 ③ 测试库现状 + 版本总 SQL 执行后结构
+  - 测试库已有字段不得重复 ADD
+  - 类型/注释不一致时生成 MODIFY 或写明不采纳理由
+- **SQL 收口对账表**：每个 DB 相关 P/CR 任务必须输出
+
+  | P编号 | 表 | 字段/索引/数据 | 源码引用 | 总SQL位置 | 开发库状态 | 测试库状态 | 处理结论 |
+
+### 1.3 车位 / 设备
+
+- **车位枪启停**：站点未绑定车位枪时，【启用车位枪】按钮不允许打开
+  - 历史事故：CDPT-199
+
+## 2. 批量操作规则
+
+### 2.1 批量开通 / 续费 / 退款
+
+- **手机号格式**：支持 1 个或 2 个手机号，逗号分隔（如 `18666666666,19888888888`）
+  - 历史事故：CDPT-185
+- **错误提示**：遇错误/异常数据必须明确指出"哪一行、哪个字段异常"，整批不插入
+  - 历史事故：CDPT-180
+- **必填标记**：模板中必填字段必须标【必填】
+  - 历史事故：CDPT-178
+- **当天 1 天有效期**：批量开通当天 + 1 天有效期时，记录显示已过期（页面显示生效中）
+  - 历史事故：CDPT-179 — 需验证时区与日期边界
+- **空模板检测**：导入空 Excel 模板应报错，不应提示成功
+  - 历史事故：CDPT-181
+
+### 2.2 批量导入
+
+- **车位枪文件格式错误**：错误提示需优化（具体到行列）
+  - 历史事故：CDPT-198
+- **车位枪文件类型错误**：提示需优化
+  - 历史事故：CDPT-181
+
+## 3. 扫码充电
+
+- **扫码后无套餐**：开通充电套餐后扫码开启充电，无套餐可用
+  - 历史事故：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 站？财务对账**：定期对账
+
+---
+
+## 7. 维护提示
+
+- 本文件是**初始版**，由 superflow init Step 5 自动生成 + 人工补全
+- 后期跟 LLM 沟通解释业务系统时，可让 LLM 把新规则追加到本文件
+- 每条规则建议标注：**事故编号（如 CDPT-XXX）| 修复 commit | 验证日期**
+- 自动化补充：可以用 `superflow scan` 让 LLM 重扫项目，对比本文件并提示遗漏

package/assets/context-templates/decisions.md

@@ -0,0 +1,153 @@
+# 团队设计决策
+
+> **初始版来源**：sdd-cli 散落的项目约定（端口、命名、工作流）+ evcharge-operator-api 现有架构
+> **维护方**：架构 / 研发 lead
+> **自动化率**：30-50%（commit "refactor" 可挖，ADR 文件不一定存在）
+
+格式：ADR 风格（Why / Alternatives / Consequence）
+
+---
+
+## 1. 工程约定
+
+### ADR-001: worktree 启动端口 = base port + P/CR 编号
+
+- **状态**：已确立
+- **背景**：多 worktree 并行开发时，端口冲突会导致调试互相干扰
+- **决策**：每个 worktree 启动端口 = `base server.port + P/CR 编号`
+  - 例：P50 任务 base 9250 → 启动端口 9300
+  - 冲突时 fallback 找下一个可用端口
+- **原因**：
+  - 可预测（看 P 编号就知道端口）
+  - 不需要中心化端口分配
+  - CI / 健康检查 URL 可以静态配置
+- **替代方案**：
+  - 动态分配（每次启动随机空闲端口）— 失去可预测性
+  - 集中注册表（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 为何不再适用

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

@@ -0,0 +1,166 @@
+# 上游系统约定
+
+> **初始版来源**：sdd-cli 散落的对账/跨仓规则 + openspec/changes/v1.1-add-charging-package-suite 涉及的外部系统引用
+> **维护方**：架构 / 集成开发
+> **自动化率**：80-95%（MQ topic 常量、API client 调用点静态可挖）
+
+## 1. 系统拓扑概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 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）必须追加本文件相关章节