@antprofuse/saddle-islands-backend-test 0.0.0-stage → 0.1.1

package/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: saddle-islands-backend-test
+description: 基于 Islands Spec、正式physical输入、backend-contract、DB 和 external-contract-proto 建设 Saddle 后端黑盒业务验收测试。负责真实入口、隔离数据库、按项目协议选择的外部 gRPC Mock、请求与结果断言和测试设施，不实现产品业务或真实 Java/SOFA 适配。
+---
+
+# Saddle Backend Test
+
+先完整阅读本轮冻结的 saddle-islands-workflow 及本 Skill 原始包。按 workflow 的传播规则消费已提交并推送的 Git 包，核仓库、完整 commit、版本和逐文件摘要；同批保持一致，运行中不静默替换。npm 仅作发布备份，不要求安装 latest 或等待 registry。缺失正文或引用文件须修复交接，不能凭版本号相同认定内容一致。
+
+测试目标是后端交付制品：真实公开 HTTP 入口 → 真实 Saddle 业务进程 → 设计要求的隔离数据库及外部 gRPC Mock → 完整后端契约响应与副作用。不能以直接调用 handler、Mock 数据库函数或替代 backend 验收业务。
+
+## 起点与必读
+
+沿用用户指定的当前分支及业务范围。最小输入为 Spec 项目（含 Prototype 和正式测试责任）、正式physical输入、`code/backend-contract/`、`code/db/`、本轮指定的上游生成协议位置，交付默认 `code/backend-tests/`，均允许用户指定位置。不要求 backend 先实现；产品可执行制品位置是运行参数，不是预期来源。
+
+先完整读 [责任与用例](<references/coverage.md>) 和 [黑盒接入与设施](<references/runtime.md>)。读取对应 Islands 公开指南、当前 `test list` / `test show` 以及所选范围的完整输入。消费当前分支的共享协议，不从 backend 旧副本或 Java 生成代码反推协议。
+
+先按当前项目锁定的框架版本选择对应正式 Saddle Skill，记录实际包版本及摘要；项目未指定且无法从依赖锁确定时，先明确兼容目标。外呼模式由项目声明、共享协议与该版本框架共同确定，不能把 ProfuseContract Invoke 当成所有项目的固定传输。标准 gRPC 项目读取框架的 standard-grpc 参考，直接 Mock 生成协议的 Service/Method；ProfuseContract 项目才使用 Invoke 边界，不为迁就测试新增协议 options 或改写生成协议。
+
+完整阅读与项目依赖锁匹配的正式框架Skill及入口、外部协议、部署配置、数据库、响应和验证参考，固定实际版本及文件摘要。版本缺失或不兼容属于输入缺口，不自动升级产品依赖、不在执行中漂移。
+
+## 设计顺序
+
+1. 从当前官方责任清单取得完整分母，将原型/业务测试的前置世界、动作、结果和禁止副作用逐项分配到后端可观察义务。保留纯客户端和未能推导的责任，不删除它们制造全覆盖。
+2. 把实体世界按正式physical输入 转成入口、可信身份、真实表数据、静态数据预期和外部答复。非持久化实体不 seed 成本地表；Spec 样例身份不是生产 uid，也不能把预期外部答复提前存库替代调用。
+3. 以 backend-contract 定义完整请求与成功/失败断言，以共享 proto 定义期望外呼实参、次数和答复。类型、presence、金额、时间、对象归属及错误语义有依据才写；缺失设计返回对应层，不能随意补错误码、舍入或重试规则。
+4. 建设并实测隔离实例、DDL/映射/seed、真实外部 gRPC Mock、公开启动/HTTP runner、审计与清理。测试建设拥有这些设施，不给 backend 研发留下待实现的测试 adapter。
+5. 用设施正反例验证错误请求、漏调用、错误响应断言、写入审计、超时及清理确实会失败。设施探针不算业务场景，也不以构造一个符合答案的假产品替代真实验收。
+6. 真实制品可用时先验证启动和首条场景，再完整执行全部场景。记录 `passed / failed / skipped / notRun` 与具体失败阶段；修设施不改业务预期，产品失败交研发，不越权修改产品代码。
+
+## 组织与交付
+
+`cases/` 保存稳定场景 ID、独立夹具、预期和公开动作序列；独立工具集的后端模块提供公开进程、HTTP、严格外部 gRPC、类型断言、日志关联、执行证据、清理及通用设施自检；项目 `harness/` 只保存业务契约映射、字段匹配、受控场景动作、覆盖支持映射及薄接入；提供单一覆盖索引和可列举的 runner。可以按实际责任分文件，必须能从来源责任反查每个场景，不能把共享循环或设施测试数冒充业务覆盖。
+
+交付可执行安装、设施自检、列举、单场景和全量运行命令，明确系统依赖、制品、配置和仓库外输出目录。工具选择可以沿用已验证的 Node.js runner、gRPC 和 MySQL 客户端，不强制后端使用 Playwright，也不绑定某业务的端口、包名、数据库版本或用例数量。
+
+代码交付包含测试源码、可维护夹具、配置生成及覆盖关联；报告、实际数据、SQL/请求证据与日志写仓库外本地目录，不打包、不入 Git。只用合成测试身份与凭据，证据不记录数据库密码等 secret。失败和中断也保留证据且关闭自己启动的资源。
+
+## 预期审查与漏测复盘
+
+按 workflow 的变更闭环复核当前测试，不能以历史全绿或来源 ID 覆盖代替正确性。将各来源义务落实到入口响应、外呼与存储副作用的实际观察，检查各层组合后仍保持身份、数据归属与失败语义。对已发现漏测补有依据的错误结果反例，确认断言能拒绝它；输入不清则反馈其所有者，不用产品现状生成答案。项目回归留测试目录，通用机制沉淀所属参考，不把业务特值写成 Skill 默认规则。
+
+## 验收与停止边界
+
+- 测试准备完整：来源义务落到可执行断言，设施正反例及真实运行接入已验证。没有产品时可交先行用例，但接入实测仍标待完成，由测试建设继续负责；不能把脚本可发现等同设施完整。
+- 后端黑盒通过：本次真实产品已执行全部已声明业务场景且通过，无遗漏与未解释 skip；响应、外呼和数据库责任共同满足。Rust 单测、Gate、编译、fixture 自检分别报告，不计入该通过数。
+- 真实联调通过：还需真实 profusecontract 组件/宿主及实际下游证据。此项不属于 Mock 后端测试的前置，Mock 通过也不证明此项。
+
+输入已明确而工具无法执行，归设施/框架接入问题；Spec 本身矛盾、正式绑定缺事实、协议不足分别反馈。独立部分继续推进，不以默认成功掩盖未定条件。严格复核合同已有含义，只有确实缺少决策才问用户。
+
+测试任务不授权编写或迁移 Java、改变共享协议、弱化断言、添加业务查询来迁就框架映射，或直接读取产品内部状态作验收。引用已知外部能力的正常调用组装由 backend 实现，不要求先交另一份编排程序。
+
+提交、推送与 npm 发布分别遵守用户授权。推送前需要 review 时，展示相对实际远端的文件树，范围变化重新确认；报告不进入待推历史。只递增最末版本号，不自动修改用户起手消息模板。
+
+## 契约身份交接
+
+消费本轮冻结 Git 原始包 saddle-islands-design 的后端契约格式及独立工具集随附的语义身份规范，记录仓库、完整 commit、版本及文件摘要。契约 identity/id 由设计工具生成，研发/测试不得重新命名或自行实现摘要。读取同版本只追加登记表，校验全部当前契约及可信 Git 基线；不同页面语义起点独立契约，同起点可聚合。旧项目未批准迁移时保留原交付，不混用当前格式规则。
+
+身份验收核对契约 ID 与后端静态注册逐字一致，并从真实请求日志验证入口 operation 与请求关联。覆盖两个入口不串身份、失败请求保留已建立关联、未知路由不冒充合法契约；客户端额外身份不能覆盖服务器归属。下游 operation 可为外部方法，用实际请求关联核对，不能要求全部 operation 字段等于契约 ID。仅 grep 源码常量不足以证明日志接线。
+
+后端契约不再包含 coverage。测试阶段直接消费 Spec 正式起点、分支及结果与契约身份，独立建立覆盖分母、链路归一化及测试关联；不得从契约内旧 coverage 或既有脚本反推分母。case 定义与覆盖策略遵循共同规则；身份算法不在各测试包内重复实现。
+
+## 固定边界 case 与覆盖策略
+
+设计、复用、拆分任务或独立审查测试前，完整读取本轮冻结 Git 原始包 `saddle-islands-workflow` 的 `references/case-coverage.md`。先冻结源责任及确定性分区，再逐区物化完整固定边界的 case；通常一次触发并止于人为中断；仅影响局部且无条件分叉的确定操作序列允许合验。在每个 case 内充分断言。每个完整 case 只归属一个编写节点，禁止按断言维度拆多人。报告来源义务、case 和运行结果三种不同计数，并按变更影响增量复用。
+
+先界定本层被测对象及直接边界，再生成 case；边界之外的内部路径变化不能单独增加本层 case。跨层来源只作投影关联，不把下游实现路径乘入本层分母。
+
+## 独立工具与职责交接
+
+消费本轮冻结的独立工具集后端公开入口、API与随附说明。工具实现不随Skill分发；项目显式提供输入根、适配、真实制品、可信工具清单和仓外输出。依赖锁与安装方法以工具说明为准，不回退旧harness，不另写runner、断言或报告。
+
+测试建设负责有来源的case、Mock计划、业务契约映射与薄接入；公共工具维护者负责执行、断言、资源回收与报告机制。业务service、字段匹配、operation映射、并发及重入动作留项目。跨批公共缺陷交统一工具维护者，某批准备或期望错误由原测试负责人检查整批同因，其他批次继续。
+
+同一Agent承担多个阶段也须遵守职责与交接。测试交付后等待产品消费；产品自主运行并修复实现。测试任务不因执行者兼任而获得修改产品答案的权限。
+
+
+## 统一交付门禁
+
+交付前必须使用本轮指定的公开工具入口执行交付门禁；门禁未通过，不得作成功交付。保留实际结果到本地任务信息目录，失败按责任修复后重新执行。具体检查项及参数由冻结工具版本提供，见 `tools/docs/iteration.md`，任务不重复列举或自行裁剪检查项。

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@antprofuse/saddle-islands-backend-test",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "消费Islands正式输入、设计与上游协议，建设后端独立黑盒测试和业务接入，使用独立公共工具验证真实制品。",
+  "license": "MIT OR Apache-2.0",
+  "files": [
+    "SKILL.md",
+    "references",
+    "resources"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@code.alipay.com/profuse/saddle-islands.git",
+    "directory": "skills/backend-test"
+  }
+}

package/references/coverage.md

@@ -0,0 +1,43 @@
+# 从原始责任到黑盒场景
+
+## 覆盖分母
+
+读取当前 Islands 公开清单和每项执行合同，不解析旧作者脚本或缓存文件数量恢复分母。责任 ID 沿官方身份保留，关联来源路径、领域、公开动作、具体要求及本地场景 ID。实例数、测试脚本数、责任数和实际通过数分别统计。
+
+一项责任可能分属客户端与后端，也可能需要多个场景。后端通过不能给纯客户端义务记通过；纯客户端项明确不由此套件证明。`analysis-incomplete` 保留为分析缺口，不直接判 Spec 错或删掉。契约不提供 coverage；直接消费当前源责任清单，并按 workflow 的固定边界 case 策略建立本层分母。
+
+不要求业务制品导出 Islands 内部 trace、Row 句柄或执行节点。将原有业务事实落实为可观察的请求/响应、外部调用与持久状态；这种转译应保留关系与副作用保证，不能仅以 HTTP 200 或经过入口代替原 ASSERT。
+
+## 每个场景的独立事实
+
+场景应明确：
+
+- 前置数据及同实体干扰项；正式physical绑定确定其在本地、静态代码、入口还是外部 Mock。
+- 公开操作及完整请求，包括框架提供的可信用户身份与业务参数的分界。
+- 期望外呼的能力身份、具体实体字段值、调用次数及答复。独立调用不强制顺序；存在因果依赖或源合同要求时才断言时序。
+- 完整后端结果，包括成功信封或失败码、字段集合、null、合法分支、精确值与实例归属。
+- 允许的全部持久变化与禁止的变化，以及结束条件和必须留存的证据。
+
+预期必须来自 Spec+physical+设计，不能调用产品的格式化、投影、校验函数生成答案。复用官方协议 codec 是编码复用，不得用被测产品结果反写预期。
+
+对于已确定的精确十进制数，可按合同作数值等价比较而不用浮点；只有合同允许才忽略无意义补零。标识符、编码、户号不做数值归一或 trim。单位转换和舍入必须有明示依据。
+
+## 增强测试的依据
+
+在正式义务之外，按已确认合同选取有区分力的合法输入与反例：零值/空值/非空、精度、UTF-8 容量、结果分支、非法协议数据、等待、重入及跨主体隔离。记录扩展所依据的契约字段或 invariant，不为没有错误政策的输入猜响应。
+
+Mock 正常返回要先验证符合 proto 和注释中的业务约束；负例则显式声明破坏哪一条，不让普通夹具绕过校验。可解码却违反必填/联合规则的响应，与无法解码的 wire、框架技术失败及合法业务失败分开。
+
+等待场景先证明请求已到 Mock，再受控暂缓答复；判断未提前响应或写入，最后释放并检查终态。只 sleep 不证明依赖实际发生。跨账户/用户场景在同一产品进程按公开请求连续执行，检查各步完整结果和外呼身份，避免每步重启消除缓存污染。仅在源要求的范围内设计并发/幂等，不从读业务推导写事务政策。
+
+## 数据库证明
+
+持久表按正式 DB 设计完整创建；业务动作前 seed，seed 的管理连接与产品连接身份分离。动作后观察全表差量和目标/干扰数据，不能只查看一个预期行。
+
+对只读要求，前后快照相同不足以证明未写入：更新后回滚也可能快照不变。补充数据库侧产品会话的 Query/Execute 审计，先验证其能捕获回滚写入；不把 PREPARE 或 `SELECT ... FOR UPDATE` 单独误判为写入。不宣称简单文本检测器能审计任意存储过程/动态 SQL。
+
+对有写入的业务，断言允许变化集合、提交或回滚的真实持久结果以及无越权副作用。不能把只读套件的“禁止一切写入”固化为所有后端业务，也不能只凭框架错误名宣布已回滚。系统时间列的自动变化按表设计与测试环境解释，不把它们当业务值随意补齐。
+
+## 完成审查
+
+逐项重走前置世界 → 公开动作 → 外呼 → 结果 → 副作用，检查断言可否发现错对象、漏调用、提前成功、错误分支与多写。设施失败、产品失败和未执行到的断言分别列出。只有当前制品和当前输入的完整执行才能形成通过证据，新增源责任或协议变化后重核覆盖，不能沿用历史数量宣称当前全过。

package/references/runtime.md

@@ -0,0 +1,60 @@
+# 后端黑盒设施
+
+这里定义测试建设责任，不复制某一版本的 Saddle 部署协议。安装并完整阅读选定的正式 Saddle Skill；入口、所选外呼 wire、模板、配置、健康检查和数据库支持以实包公开合同为准。记录工具、依赖、制品与输入摘要用于复现，不在业务契约里增加跨仓库/revision 定位。
+
+## 真实入口和进程
+
+通过交付项目的正常构建得到真实制品，使用公开启动参数与隔离配置启动。应用身份来自正式部署声明，接口标识来自 backend-contract，不从目录名称猜测。通过框架公开 readiness 等待启动，随后向固定 ProfuseGW HTTP 入口发送真实网络请求；不另建业务 URL 或直接调用 handler。
+
+框架要求的 request/call identity、deadline、部署凭据及上下文由测试在其公开边界提供，业务 payload 严格遵循后端契约。可信用户不能通过客户端业务字段覆盖。套件不自动重试业务请求以隐藏失败；启动探测重试与业务重试分开。
+
+测试负责产品启动、依赖就绪、业务超时、信号中断和所有资源关闭；用 finally 收集当前证据，再按依赖顺序关闭。端口为隔离配置，不能占用或停止其他 workspace 的进程。
+
+没有产品时仍可建设全部测试设施。使用正式框架样例或最小接入探针验证协议/生命周期时，明确其非业务验收；不能把探针实现为预期结果服务器来证明场景通过。真实产品可用后仍须重新执行。
+
+## 隔离数据库的运维准备
+
+测试建设方完成安装来源、运行依赖、实例初始化、凭据、DDL、物理表列名映射和 seed。业务 code/db 只提供逻辑表契约，生产运维不被测试改变。默认只创建套件自己的临时实例；明确授权的测试库另行核对范围，绝不清空现有业务库。
+
+按 DB 设计保留完整物理表与系统列。逻辑→物理映射只改名字，物理名称选择不改变列类型、默认值、主键或业务约束；以同一份表/列对应数据驱动 DDL、seed、查询观测和运行时映射，避免四份手写清单漂移。
+
+区分“完整表结构”与“当前运行时要求的映射集合”。本体系数据库维护 `gmt_create/gmt_modified`，已确认它们不进入当前业务映射时，仅过滤运行时映射项，DDL、seed、快照和审计保留原列与物理对应。以后有真实业务消费或框架合同变化时重新核对，不能永久假设它们不可被读取。不得通过删除物理列、伪造产品 SQL 或猜测过滤任意未引用列过启动检查。
+
+读取选定版本的公开数据库要求并实测实际实例参数，涵盖网络/凭据、映射、字符与时间行为、packet 等启动边界。数据库独立可连不等于 Saddle 可启动。须预先校验运行时兼容配置，不把某次环境的具体数值固化为所有业务默认。
+
+没有公开 manifest/导出机制时，不消费 `__private`、doc(hidden) 或解析产品 SQL 伪造稳定部署协议。给出最小配置、精确差集及实测错误，向框架方/用户确认缺口。源码推断可用于定位，不能当成受支持 API。
+
+隔离实例先建立凭据再开放回环 TCP；不对公网监听。自检完整表和系统默认值、映射命名、实际启动参数、产品凭据连接、无密码访问被拒、seed/快照/审计及超时清理。不要通过全局安装、更改系统数据库配置来完成测试准备。
+
+## 外呼模式选择与标准 gRPC Mock
+
+先核对当前项目的框架依赖锁、公开配置、共享协议与同版本框架参考，再选择一种传输。已有标准 gRPC 项目不得因本 Skill 的 Invoke 示例切换协议；两种模式的字段、身份传播和错误映射不能混用。
+
+标准 gRPC 模式在真实回环服务器注册官方生成协议中的完整 Service/Method，直接解码请求并编码响应。消费共享 descriptor，不另造 Invoke envelope，不添加 ProfuseContract 的业务单元/函数 options。方法注册、框架 metadata、身份、deadline、错误映射及配置以同版本 Saddle 的 standard-grpc 参考为准。测试覆盖精确方法、参数/presence/单位、请求关联、调用次数、漏调用、多调用与技术失败；即使业务捕获错误，Mock 的审计错误也必须传递到最终结果。
+
+仅 DB 设计存在持久化义务时准备相应表和数据；不为非持久化实体建立答案库。框架启动本身需要的依赖按公开要求提供，与业务存储覆盖分开报告。
+
+## ProfuseContract Invoke Mock（仅声明此模式的项目）
+
+Mock 在真实回环 gRPC 服务上承载选定 Saddle 的固定 `ProfuseContractBoundary/Invoke`，接收业务单元、函数身份、技术上下文与 protobuf payload。业务 proto 的 service/rpc 是能力声明，不意味着网络端点与其同名；不能改成直接调用 Java 方法或业务 typed gRPC 服务。
+
+业务 schema 直接消费指定的唯一上游协议制品；固定 Invoke 网络协议取自选定实包。按 method option 建能力索引，具体字段用共享 descriptor 解码/编码，不复制另一份业务 schema。
+
+接收请求时独立验证：
+
+- 业务单元、函数逐字匹配；未知能力拒绝。
+- request identity 与当前 HTTP 请求关联，call identity 和 deadline/trace/LDC 按公开合同传播；多步场景不得复用上一请求身份。
+- payload 字段集合、presence、值、单位及对象归属与场景期望匹配；不先纠正请求再比较。protobuf 默认忽略未知字段时，补 wire 守卫验证未知、重复或截断字段等已选严格边界，守卫正反例单独测试。
+- 调用次数和被允许的因果顺序；漏调用、多调用、错误实参即使被产品吞掉也在最终断言失败。
+
+返回具体业务结果或框架技术失败，保留这两类含义；通用技术 context 不添加业务用户字段。只有共享业务 request 已声明需要用户身份，才断言 backend 显式传入其值。
+
+外部 Mock 不实现账户查询等真实下游业务，也不连接 SOFA。它不要求 Java 已开发；Java 消费协议不一致属于后续真实联调问题，记录但不越权迁移。
+
+## 失败分类与证据
+
+准备/启动失败先保留配置（去 secret）、进程 stderr、正式日志、数据库连接记录与 Mock 记录，说明实际走到哪一阶段。只见总括错误时不得先断言框架 bug 或产品错；先独立验证配置边界。外呼记录为空只证明未观察到所选外呼方法，不证明从未建立 TCP 连接。
+
+进程启动成功、首场景通过、全量业务通过分别举证；框架 Gate/单测通过不代替黑盒。修复设施后重新跑设施正反例及受影响业务，最后对交付制品跑完整套件。
+
+结果输出支持仓库外目录，清理只停止/删除本次明确拥有的资源，保留失败诊断而不把报告加入 Git。脚本应检查异常、中断与正常退出；关不掉进程也是设施失败，不能报告 clean。严禁自动启动生产联调、自动发布或推送来“完成闭环”。

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.