sapbuddy-dsh 0.0.7 → 0.0.9

package/skills/sap-fs/references/example-enhancement.md

@@ -0,0 +1,163 @@
+<!-- 示例文件：需求、数据、对象名均为虚构，仅用于演示填写方式与详略程度。
+     其中的数值和技术对象未在真实系统验证，不能作为任何项目的设计依据。 -->
+
+# FS：采购订单保存校验（增强）
+
+状态：草稿 · 待确认 4 项 · 更新 2026-10-28
+项目 / 模块：示例项目 · MM-PUR ｜ 系统与客户端：DEV / 100 ｜ 需求提出人：采购部
+
+## 1. 需求与范围
+
+**背景与问题**
+采购订单由多人分头维护，保存时既不校验行项目交货日期与抬头凭证日期的先后，也不识别大额订单。结果有两类问题：交货日期早于凭证日期的订单进入系统，后续 MRP 交期推算出负数；超过 10 万元的订单未走高额审批，靠财务事后抽查发现。
+
+**业务目标**
+保存时拦截日期倒挂的订单；超过阈值时要求补审批标识。上线后不再新增这两类错误数据。
+
+**在范围内**
+ME21N / ME22N 的保存动作，行项目层面，公司代码 1000 与 2000。
+
+**不在范围内**
+已保存订单的历史数据修正；审批流本身（沿用既有工作流）；采购申请。
+
+**依赖与前置条件**
+审批标识的存放字段未定（Q-02）；接口创建采购订单是否同样校验未定（Q-03）。
+
+## 2. 现状与差异
+
+| 环节 | 系统当前行为 | 依据 |
+| --- | --- | --- |
+| ME21N 保存 | 不校验 EKPO-EINDT 与 EKKO-BEDAT 的先后，日期倒挂可正常保存 | E-01 |
+| 大额订单 | 无金额阈值判断，也没有审批标识相关校验 | E-02 |
+| 增强点候选 | 候选 BAdI `ME_PROCESS_PO_CUST` 的 CHECK 方法，尚未验证本系统是否实现及其调用时点 | E-03 |
+
+**差异说明**：两条校验在现状中都不存在，属于新增；既有字段校验、编号分配、后续审批流保持不变。
+
+## 3. 增强设计
+
+### 3.1 改变的行为
+
+| 动作 | 现状 | 目标 | 保持不变 |
+| --- | --- | --- | --- |
+| 保存采购订单 | 校验通过即写库 | 先执行 R-01、R-02，不通过则不写库 | 既有字段校验、订单编号分配、审批流触发 |
+
+**实施方式**：两条都是保存前的阻断式校验，标准配置无法覆盖，走增强。CHECK 方法是否在写库前调用，待技术确认（E-03）。
+
+### 3.2 触发点
+
+| 入口 | 时点 | 触发前状态 | 取得的数据 |
+| --- | --- | --- | --- |
+| ME21N / ME22N 保存 | 抬头与行项目校验阶段，写库之前 | 订单未保存 | 用户当前输入值，含尚未落库的修改 |
+| 接口 / 后台创建订单 | 待确认（Q-03） | — | — |
+
+- **覆盖入口**：前台确定覆盖；接口与后台未确认。
+- **新旧值**：使用当前输入值，不使用数据库旧值；修改行项目后重新校验。
+- **未保存数据**：新增行项目的 EINDT 尚未落库，以屏幕输入为准。
+- **派生值**：标准逻辑在保存时会重新计算净价与税额，不影响本规则的判断字段。
+
+### 3.3 适用与排除
+
+| 项目 | 定义 |
+| --- | --- |
+| 命中条件 | 公司代码 1000 / 2000；订单类型 NB |
+| 排除条件 | 退货订单是否排除待定（Q-04）；当前按不排除处理 |
+| 与其它规则的优先级 | R-01 先于 R-02；两条都不通过时先报 R-01 |
+| 不命中时 | 维持原有保存行为 |
+| 既有校验先失败时 | 不再执行本增强，用户先处理标准报错 |
+
+### 3.4 处理逻辑
+
+保存触发后，逐行项目执行 R-01；全部行通过后按整单执行 R-02。任一规则不通过即中止保存，消息中指出具体行号。变量取值、精度与舍入口径见各规则的「条件」。
+
+### 3.5 重复触发与事务
+
+| 场景 | 期望 |
+| --- | --- |
+| 同一操作多次触发 | 校验无写入副作用，可重复执行 |
+| 保存后再次修改 | 重新校验全部行，不沿用上次结论 |
+| 标准动作最终失败 | 本增强不产生独立数据，无需回滚 |
+| 已调用外部系统 | 不适用：本增强不调用外部系统 |
+
+### 3.6 停用与回归
+
+- **停用后**：恢复原有保存行为；已保存数据不回滚，也不批量修复。
+- **在途业务**：不适用：校验不产生在途状态。
+- **回归范围**：正常保存、行项目增删改、既有字段校验、审批流创建、公司代码 1000 与 2000 之外的订单不受影响。
+
+## 4. 业务规则
+
+### R-01 交货日期不得早于凭证日期
+
+- **条件**：行项目 EKPO-EINDT < 抬头 EKKO-BEDAT，按行项目逐条判断；两个字段都是日期，比较到日，不含时间。
+- **结果**：阻止保存，输出 M-01，消息中带出行号。
+- **异常**：任一日期为空视为未填，不参与比较，交回标准逻辑处理；两个日期相同时视为通过。
+- **依据**：业务确认（2026-10-27 需求确认会），确认口径为"相等不算倒挂"。
+- **验收**：T-01、T-02
+
+### R-02 大额订单需补审批标识
+
+- **条件**：整单金额 > 100,000.00。币种、含税口径、按整单还是行项目计算均未确定（Q-01）；当前按"整单含税人民币"计算，标【建议】。
+- **结果**：输出 M-02 提示补审批标识；阻断保存或仅提示，待定（Q-01），当前按【建议：阻断】处理。
+- **异常**：金额缺失或无法换算时不判断，避免把缺失当成 0；仅提示不阻断时仍记录日志。
+- **依据**：业务提出阈值 10 万元，口径未确认（Q-01、Q-02）。
+- **验收**：T-03、T-04
+
+## 5. 权限、消息与运行
+
+**权限**
+沿用标准采购订单维护权限，不新增权限对象；校验对所有能保存该订单类型的用户生效，不设例外放行。
+
+**消息**
+
+| 编号 | 触发条件 | 用户看到的文案 |
+| --- | --- | --- |
+| M-01 | R-01 不通过 | 第 &1 行交货日期早于凭证日期（&2），请修改后保存 |
+| M-02 | R-02 不通过 | 订单金额超过 10 万元，请补充审批标识后再保存 |
+
+**运行**
+前台保存时同步执行，单次涉及行项目通常少于 50 行；无特殊时效要求。
+
+## 6. 验收
+
+### T-01 交货日期早于凭证日期
+
+- **前置**：可创建 NB 类型订单的用户，公司代码 1000。
+- **输入**：凭证日期 2026-10-20，某行交货日期 2026-10-19。
+- **预期**：不能保存，M-01 提示该行行号。
+
+### T-02 日期相同（边界）
+
+- **前置**：同 T-01。
+- **输入**：凭证日期与交货日期均为 2026-10-20。
+- **预期**：可以保存。
+
+### T-03 金额恰好等于阈值（边界）
+
+- **前置**：同 T-01。
+- **输入**：整单含税金额 100,000.00。
+- **预期**：不提示、可保存（当前建议：整单含税人民币、等于阈值不触发）。依赖 Q-01；结论变化则本用例失效。【阻塞：Q-01 未关闭】
+
+### T-04 金额超过阈值
+
+- **前置**：同 T-01。
+- **输入**：整单含税金额 100,000.01。
+- **预期**：输出 M-02，并阻止保存（当前建议：阻断）。依赖 Q-01；结论变化则本用例失效。【阻塞：Q-01 未关闭】
+
+## 7. 待确认
+
+| 编号 | 问题 | 谁来定 | 影响 |
+| --- | --- | --- | --- |
+| Q-01 | 阈值按含税还是不含税、整单还是行项目、是否换算人民币、等于阈值是否触发 | 采购部 | R-02、T-03 |
+| Q-02 | 审批标识放在哪个字段，是否需要新增字段 | 采购部 + 技术 | R-02 能否实现、M-02 的判断依据 |
+| Q-03 | 接口与后台创建订单是否同样校验 | 采购部 | 3.2 覆盖入口、T 用例范围 |
+| Q-04 | 退货订单是否排除 | 采购部 | 3.3 排除条件 |
+
+## 附录 A 取证记录
+
+| 编号 | 查了什么 | 结果 | 限制与结论 |
+| --- | --- | --- | --- |
+| E-01 | `get_abap_object_info` 查 EKKO、EKPO 字段结构 | EINDT 为 DATS(8)，BEDAT 为 DATS(8)，字段存在且类型一致 | 只证明字段存在；未验证标准保存逻辑里是否已有同类校验 |
+| E-02 | `execute_data_query` 查近 3 个月公司代码 1000 的订单币种与净额分布，限 200 行 | 出现 CNY 与 USD 两种币种；其中 2 单净额超过 10 万 | 限 200 行，不代表全量与历史；未覆盖其它公司代码 |
+| E-03 | `search_abap_objects` 查 `ME_PROCESS_PO_CUST` 相关对象 | 返回增强实现类候选 | 未验证调用时点、是否在写库前、是否覆盖全部入口；需技术确认 |
+
+Generated by SapBuddy

package/skills/sap-fs/references/fs-contract.md

@@ -0,0 +1,64 @@
+# FS 合同（编号、状态、字段、证据）
+
+## 状态行
+
+```
+状态：草稿 · 待确认 <N> 项 · 更新 <YYYY-MM-DD>
+项目 / 模块：… ｜ 系统与客户端：… ｜ 需求提出人：…
+```
+
+`<N>` 必须等于正文「待确认」表中 Q 的实际条数。
+
+## 编号（本文件内唯一，不重排）
+
+| 前缀 | 含义 | 出现位置 |
+| --- | --- | --- |
+| R | 业务规则 | 第4节 |
+| T | 验收用例 | 第6节 |
+| Q | 待确认问题 | 第7节；正文可用【待确认 Q-xx】 |
+| E | 取证记录 | 附录 A；正文「依据」列引用 |
+| M | 消息 | 第5节消息表 |
+
+不使用旧编号：`REQ` / `BR` / `EV` / `TC` 等。
+
+## 字段写法
+
+- 用**业务名**，就地写清：类型、必填、取值来源与格式、空值含义。
+- 同一字段在不同位置格式不同时，各自写清换算。
+- 不发明跨文档人造字段键（field/source/action/…）。
+
+## 规则与验收
+
+每条 R 必须有：条件 / 结果 / 异常 / 依据 / 验收（至少一个 T）。
+每条 T 必须有：前置 / 输入 / **可核对**的预期（不是「成功」）。
+依赖未关闭 Q 的用例：预期写清当前建议值，并标注「依赖 Q-xx；结论变化则本用例失效」；必要时标【阻塞】。
+
+## 依据列
+
+- 系统取证 → `E-xx`
+- 业务口述 / 会议确认 → 写「需求确认（日期或场合）」，**不要**伪装成 E
+- 未核实建议 → 标【建议】
+
+## 标记
+
+- 未知：【待确认 Q-xx】
+- 不适用：【不适用：原因】
+- 建议未确认：【建议】
+
+## 增强类章节分工
+
+- 第2节：业务流程**整体**现状（含未改变部分）
+- 第3节：只写**本次改变**的动作
+
+## 证据
+
+证据在附录 A（查了什么 / 结果 / 限制与结论）。正文引用编号，不把证据详情塞进第2/3节。
+修订历史：默认**不**进 FS 正文（版本由交付/流转平台承载）。若项目要求文档内签署追溯，再加「修订记录」小节——需产品确认后启用。
+
+## 页脚
+
+可保留 `Generated by SapBuddy`。生成后删除模板顶部 `<!-- 写作约定 -->` 注释块。
+
+## HTML 与接口 JSON
+
+定稿后必须按 `archive-html.md` 产出无 logo 的 `FS.html`；接口类必须附样例 JSON（正文 + 独立文件）。

package/skills/sap-fs/references/grilling-integration.md

@@ -0,0 +1,26 @@
+# 与 grilling 集成
+
+## 怎么加载
+
+1. 需要追问业务决策时：用 Skill 工具加载 **`grilling`**（用户说 grill me / 拷问 / 追问决策时同样加载它，不再经别名）。
+2. 若宿主无法加载技能：在对话中**按 grilling 合同**执行（设计树、按 frontier 分轮、每问带推荐答案），并在答复里说明已降级。
+3. 不要把 grilling 全文复制进 FS；不要在 sap-fs 内另写一套追问算法。
+
+## 问什么 / 不问什么
+
+- **问**：业务决策（阈值、含税口径、是否阻断、覆盖哪些入口、排除哪些场景…）。
+- **不问**：能从系统查到的事实（表名、字段、现有逻辑）——先取证。
+
+## 与 FS 编号的映射
+
+| grilling 结果 | 写入 FS |
+| --- | --- |
+| 用户确认的决定 | 落到对应 R / 第3节字段，依据写需求确认 |
+| 用户说不知道 | `Q-xx`，继续做不依赖部分 |
+| 推荐答案被同意 | 可写入正文；若仍弱确认可标【建议】直至正式确认 |
+
+每轮结束后把已定决策写回草稿结构，避免只留在对话里。
+
+## 停止条件
+
+grilling 的 frontier 为空，且用户确认已达成共识 → 再进入生成与自检。未确认前不假装 FS 已定稿。

package/skills/sap-fs/references/review-checklist.md

@@ -0,0 +1,13 @@
+# 交付前检查
+
+1. 每条 R 有条件 / 结果 / 异常 / 依据 / 验收，且可判真假。
+2. 每个 T 有前置、输入、可核对预期；依赖 Q 的用例已标注依赖/阻塞。
+3. 每个 Q 有「谁来定」和「影响哪条规则」；状态行待确认数 = Q 条数。
+4. 每条 E 有限制；正文引用的 E 都存在；口述依据未伪装成 E。
+5. 第2节与第3节不矛盾；未改变部分写明保持原样。
+6. 无残留 `<...>` / `{{...}}` 槽位（示例文件里的尖括号示范也不得出现在交付稿）。
+7. 无训诫句；无旧编号；有 M 时与消息表一致。
+8. 查询/功能报表写了「实现方式与取舍」（标准功能 vs 自建）。
+9. 未授权任何 SAP 写入；落盘路径在允许范围（默认 `output/fs/...`）。
+10. 已产出 `FS.html`，无 logo、无 `{{...}}` 占位符。
+11. 接口类：正文 3.6 与 `io-request.json` / `io-response.json` 一致且可解析。

package/skills/sap-fs/references/system-verification.md

@@ -0,0 +1,30 @@
+# 系统取证
+
+## 连接
+
+1. 连接不明确 → 先 `get_connected_systems`。
+2. 用户已指定 → 只用指定连接，不要默认第一个。
+3. 切换连接后 → 再次 `get_connected_systems` 确认后再查。
+
+## 可用工具（只读）
+
+`get_sap_system_info`、`search_abap_objects`、`get_abap_object_info`、`get_abap_object_lines`、`execute_data_query`、`read_table_contents`、`find_where_used`。
+
+查询限定组织、日期与字段；只取少量样本。返回行数上限 ≠ 扫描范围小。
+
+## 记录四种状态
+
+已取得 / 零行 / 部分取得 / 失败。
+
+- 零行 ≠ 对象不存在
+- 失败 ≠ 没有该功能
+- 字段存在 ≠ 逻辑可用
+- 对象存在 ≠ 调用时点与入口已验证
+
+每种限制写进附录 E 的「限制与结论」。
+
+## 边界
+
+- 本流程不创建、不激活、不修改 SAP 对象。
+- abap_wiki / 知识库仅作定位；必须与系统查询分开标注。
+- 未核实的对象名标「候选，待验证」，写入 E 或 Q，不写进已确认口径。

package/skills/sap-fs/references/types/enhancement.md

@@ -0,0 +1,21 @@
+# 类型：增强
+
+**判定**：在现有流程某时点补充或改变行为。
+
+## 取证重点
+
+- 入口事务/接口、候选增强点调用时点（未验证则 E + Q）
+- 相关字段与标准校验是否已覆盖部分规则
+- 其它增强是否改同一字段
+
+## 追问方向
+
+- 覆盖哪些入口（前台/后台/接口）
+- 命中与排除条件、优先级
+- 停用后与在途、回归范围
+
+## 专项检查
+
+- 模板：`assets/templates/enhancement.md`
+- 第2节整体现状 vs 第3节只写本次改变
+- 详略对照：`references/example-enhancement.md`

package/skills/sap-fs/references/types/functional-report.md

@@ -0,0 +1,22 @@
+# 类型：功能报表
+
+**判定**：会改变业务状态（创建、过账、审批、重处理等）。
+
+## 取证重点
+
+- 候选对象与可处理状态
+- 现有校验/锁定/日志
+- 标准功能能否覆盖
+
+## 追问方向
+
+- 执行单元与部分成功策略
+- 重复判定键（不能用每次新批次号）
+- 结果未知时的核对顺序
+- 试运行能力边界
+
+## 专项检查
+
+- 模板：`assets/templates/functional-report.md`
+- 3.2 表有实际字段行（非空表头）
+- 实现方式与取舍已写

package/skills/sap-fs/references/types/interface.md

@@ -0,0 +1,27 @@
+# 类型：接口
+
+**判定**：数据在系统之间进出。
+
+## 取证重点
+
+- 现有接口对象、消息结构、日志与对账表（若有）
+- 业务键、增量水位、重复请求处理线索
+- 候选技术对象标「待验证」
+
+## 追问方向（交给 grilling）
+
+- 成功标志：传输到达 / 已受理 / 业务完成 各自证据
+- 全量 vs 增量、迟到与空批次
+- 部分成功原子单元、超时后如何核对再重试
+- 对账键、容差、责任方
+
+## 专项检查
+
+- 第3节用 `assets/templates/interface.md`
+- 结论层次不得互相替代
+- 备选方案与取舍已填写（无则写「无」）
+
+## 归档
+
+- 必出 3.6 样例 JSON，并写 `io-request.json` / `io-response.json`。
+- HTML 中原样收录样例，无 logo。

package/skills/sap-fs/references/types/query-report.md

@@ -0,0 +1,21 @@
+# 类型：查询报表
+
+**判定**：只读；筛选、展示、导出。若操作会改业务状态 → 改用功能报表。
+
+## 取证重点
+
+- 来源表/视图、关联基数、排除状态
+- 选择条件与权限相关字段
+- 标准报表/事务能否覆盖（写入「实现方式与取舍」）
+
+## 追问方向
+
+- 一行代表什么、业务唯一键
+- 空条件含义、最小筛选范围
+- 币种/单位/舍入与对账依据
+- 数据量与时效上限
+
+## 专项检查
+
+- 模板：`assets/templates/query-report.md`
+- 一对多关联后金额是否重复放大已说明