@antprofuse/saddle-islands-design 0.1.17 → 0.1.19

package/SKILL.md

@@ -5,6 +5,8 @@ description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑
 
 # Saddle Islands 设计
 
+开始先安装并完整阅读 `@antprofuse/saddle-workflow@latest` 的共同规则。所有 Skill 间引用统一从 npm 官方 registry 使用 `@latest`，不写死版本；记录本轮实际解析版本及摘要，同一协作批次保持一致，不在执行途中漂移。引用未发布或无法取得时明确反馈，不能静默使用本地草稿。自身 package 版本和格式版本不受此规则影响。
+
 Spec定义抽象业务，saddle-islands-adapt完成落地语义自洽，本Skill消费两层输入产出后端契约、DB和external-contract-proto。不能让业务Spec为工具格式增加技术字段。后端聚合契约与外部能力契约不是一一对应；适配语义须先确定，但profusecontract实现代码不是设计前置。
 
 ## 选择模块
@@ -43,6 +45,14 @@ external-contract-proto覆盖adapt明确交给profusecontract的Dependency及ext
 
 三类设计完成不等于实现、测试或生产链路完成。不从TODO发明加载、同步或对外调用；不修改profusecontract后面不可控的SOFA协议。
 
+## 交给测试与实现
+
+设计交接应让下游独立得到：当前调用点和物理输入、完整结果/错误合同、来源责任、外部能力协议、持久化结构，以及尚未完成事项所影响的具体边界。真实 SOFA 或 Java 实现尚未完成不自动阻塞前端契约 Mock、后端 Invoke Mock 测试；只有影响当前协议或预期的未定语义才阻塞对应场景。
+
+前端测试消费 Spec/Prototype、adapt、backend-contract；后端测试还消费 DB 与 external-contract-proto。两者根据当前 Islands 正式责任清单分别落实可观察义务，不按设计文件数量反推覆盖。数据库实例、DDL、测试物理名映射、seed 和启动接入由测试建设承担，不塞入 `code/db/`，也不留给产品研发补测试 adapter。
+
+共享协议是唯一真源，但“一致性审查”不授权修改所有消费者。只迁移本次获授权的设计或实现目录，其他消费者差异单独报告；Mock 验收与真实下游兼容验收分别记录。删除 backend 内旧协议副本，不等于需要同步编写 Java 适配实现。
+
 ## 维护边界
 
 当前三个模块为后端契约、DB、external-contract-proto；adapt设计由并列的saddle-islands-adapt负责。版本只递增最末位0.1.x的patch，未经明确要求不升前两位。保持已批准约定，不把单个案例固化成通用设计；保留包外未批准草稿。

package/modules/backend-contract/references/backend-contract-v1.md

@@ -120,14 +120,14 @@ Visual Form 的宽泛类型不自动构成业务类型冲突：应追溯真实
 - kind: flowEntry
   flow: {board: 查询账单, entry: 开始查询}
   ingress:
-    path: example/adapt/ingress.binding.yaml
+    path: example/adapt/ingress/开始查询.binding.yaml
     domain: 示例域
     board: 查询账单
     entry: 开始查询
   inputBindings:
     账户编号:
       ingressField:
-        path: example/adapt/ingress.binding.yaml
+        path: example/adapt/ingress/开始查询.binding.yaml
         domain: 示例域
         board: 查询账单
         entry: 开始查询
@@ -284,7 +284,7 @@ cases:
 # 输入专用；仅source多一个kind，inputBindings.ingressField不带kind。
 source:
   kind: ingressField
-  path: example/adapt/ingress.binding.yaml
+  path: example/adapt/ingress/开始查询.binding.yaml
   domain: 示例域
   board: 查询账单
   entry: 开始查询

package/modules/db/references/db-table-v1.md

@@ -154,7 +154,7 @@ v1 只允许以下封闭类型：
 
 ## 已声明的持久访问责任
 
-accessResponsibilities记录当前输入明确的直接持久操作，不是完整后端执行计划。没有可定位的直接操作可为[]；不代表表不会被访问、没有价值或禁止实现加载。不能因此省略明确的本地持久化表。已知操作不能遗漏，未填写adapt实现不能被猜成按编码查询或同步任务。
+accessResponsibilities记录当前输入明确的直接持久操作，不是完整后端执行计划。没有可定位的直接操作可为[]；不代表表不会被访问、没有价值或禁止实现加载。不能因此省略明确的本地持久化表。已知操作不能遗漏，不凭未填写的适配内容发明查询或同步任务；入口已明确将字段映射为本地实体属性时，等值定位已有依据，不再要求额外 SQL 或查询步骤声明。唯一性、查无与多命中仍按已有合同核对，不任取首项。
 
 每项必需source/operations，可选backendContractId/atomic。source只采用当前Graph/Visual稳定身份：
 

package/modules/external-contract-proto/design.md

@@ -5,7 +5,7 @@
 ## 输入与范围
 
 - 消费Spec、实体承载/扩展/身份、Dependency及external-contract绑定。绑定来源不同，适配协议定义要求相同；不额外包装一层转发RPC。
-- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权并同步双方消费路径，不保留两份真源；Skill升级不自动迁移项目。
+- 确认目标Saddle版本及权威proto，明确业务单元实际值。默认交付code/external-contract-proto，与backend并列。旧目录迁移须获项目授权，不保留两份真源；核对双方消费路径，实际修改限于本次授权范围，其他消费者迁移单列交接，不为 Mock 验收扩大到真实下游实现。Skill升级不自动迁移项目。
 - 用户未提供生成语言不是阻塞。业务方法身份与语言标识符分开，不要求backend先写代码再设计出口协议。
 - 读取已发布的共享协议，不从旧生成代码推导新规范；版本不一致先报告。不能因为仓库里同时存在puc和business_unit就兼容两套身份。
 

package/modules/external-contract-proto/references/runtime.md

@@ -8,7 +8,7 @@
 
 默认目录为 code/external-contract-proto，与backend、backend-contract、db并列。目录树是双方共同输入，包含固定根模板和业务proto；不建聚合proto、手工proto清单、protocol子目录或版本副本。只有带正式method option的RPC进入外部函数索引。
 
-对支持同级目录的Saddle版本，backend可声明 `contract_dir "../external-contract-proto";`，相对应用Cargo.toml所在目录而非shell。构建与CI必须取得固定revision的完整契约树；根目录定位允许上行不代表proto import允许逃逸，目录不得经symlink。具体限制核对选定版本。目录外引用支持与研发Skill停止生成proto是两项独立检查，不能因前者成立就宣称后者完成。
+对支持同级目录的Saddle版本，backend可声明 `contract_dir "../external-contract-proto";`，相对应用Cargo.toml所在目录而非shell。构建与CI消费当前分支同次检出的完整契约树，执行记录可以保留实际提交和摘要用于复现，但不在业务契约中增加 revision 定位字段或另锁历史来源。根目录定位允许上行不代表proto import允许逃逸，目录不得经symlink。具体限制核对选定版本。目录外引用支持与研发Skill停止生成proto是两项独立检查，不能因前者成立就宣称后者完成。
 
 业务proto精确 import "saddle_external_function.proto";，使用 (saddle.profusecontract.external_function)，字段为 puc 与 function。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-design",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "消费自洽 adapt 与 Islands Spec，设计后端契约、数据库表和 external-contract-proto。",
   "license": "MIT OR Apache-2.0",
   "files": ["SKILL.md", "agents", "modules", "references"],

package/references/adapt.md

@@ -4,7 +4,7 @@
 
 ## 输入结构与职责
 
-常见结构为同级spec、adapt、code；adapt含ingress.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml、external-contract/名称.binding.yaml。位置以调用方指定为准，每项独立文件；ingress以目标板块和入口定位条目。不把Islands旧physical.yaml与adapt自动合并，也不由同名猜优先级。发现同范围冲突先反馈。
+常见结构为同级spec、adapt、code；adapt含ingress/<入口名>.binding.yaml、entities/实体名.binding.yaml、dependencies/依赖名.binding.yaml、external-contract/名称.binding.yaml。位置以调用方指定为准，每项独立文件；ingress以业务域、目标板块和入口定位独立文件。不把Islands旧physical.yaml与adapt自动合并，也不由同名猜优先级。发现同范围冲突先反馈。
 
 所有实体都应有显式承载及身份声明。承载与身份属于adapt，不要求Spec理想实体写external、技术主键或外部编码。没有实际写操作不代表不建表；一次对象属性读取也不代表DB或RPC调用。声明缺失先问，不允许消费者隐含推导。
 
@@ -63,17 +63,16 @@
 
 ```yaml
 业务域: 示例域
-入口:
-  - 目标: {板块: 查询账单, 入口: 开始查询}
-    外部入参:
-      subBizType:
-        类型: string
-        可空: false
-    实体映射:
-      缴费账户: {实体: 缴费账户}
-    适配: |
-      subBizType 可映射 @费种(主键=$subBizType)
-      TODO：由用户填写其余适配逻辑。
+目标: {板块: 查询账单, 入口: 开始查询}
+外部入参:
+  subBizType:
+    类型: string
+    可空: false
+实体映射:
+  缴费账户: {实体: 缴费账户}
+适配: |
+  subBizType 可映射 @费种(主键=$subBizType)
+  TODO：由用户填写其余适配逻辑。
 ```
 
 入口描述外部字段到内部实体体系的关系，不是函数返回值。实体映射必须与Spec目标入口类型一致；集合等基数必须有输入声明，不能猜测。适配允许自然语言与上述轻量记号混合，不宣称有可执行表达式解释器。
@@ -97,3 +96,5 @@ Dependency与external-contract只在逻辑锚点上不同：前者目标指向Sp
 本版本的path均为已指定输入仓库根目录相对路径，不是shell工作目录或URL。实体类型在业务域内解析；歧义不能按同名猜。项目关联只解析当前仓库当前分支，不承载跨仓库或跨分支定位。
 
 实体绑定位置用 `{path, domain, entity}`，入口位置用 `{path, domain, board, entry}`，入口字段再加field。路径与语义目标必须同时匹配，不使用数组下标。关联随当前分支的Spec+adapt内容重新核对。
+
+入口按每个绑定一个文件交付，顶层为业务域、目标、外部入参、实体映射、适配，不使用入口数组。文件名优先为入口名.binding.yaml；同名入口冲突时以板块名限定文件名，身份仍由业务域和目标确定。仅接受新形状，迁移时同步所有path引用，不保留旧聚合文件或双读规则；保持既有适配逻辑原文。