@antprofuse/saddle-islands-design 0.1.20 → 0.1.21

package/modules/backend-contract/assets/backend-contract.template.yaml

@@ -8,7 +8,10 @@ identity:
 id: api_91d5e0b55164bb5b60240fa030519c23
 binding:
   type: mobilegw
-  operationType: api_91d5e0b55164bb5b60240fa030519c23
+  operationType: profuse.mgw.invoke
+  target:
+    app: saddle # 必须核项目实际deployment_app，不从business猜
+    interfaceId: api_91d5e0b55164bb5b60240fa030519c23
 callSites:
   - kind: visualPageLoad
     page: 查账结果

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

@@ -6,7 +6,7 @@
 
 使用受限 YAML：UTF-8 编码、与 JSON 兼容的数据值；禁止 alias、anchor、tag、merge key 和重复 key。
 
-线上对象只包含声明字段，所有字段必须出现，nullable仅允许显式null而非省略。type/ref/来源/invariants均为设计元数据，不是线上字段。文件内模型独立，不跨契约复用业务类型；types为空合法，不强迫请求结果起额外类型名。
+响应对象只包含声明字段，所有响应字段必须出现，nullable仅允许显式null而非省略。请求中nullable:true允许省略或显式null，均表示未设置；nullable:false仍必填且非null。不得把额外请求字段拒绝升级为源头未要求的业务验收或框架前置。type/ref/来源/invariants均为设计元数据，不是线上字段。文件内模型独立，不跨契约复用业务类型；types为空合法，不强迫请求结果起额外类型名。
 
 ## 必需的顶层结构
 
@@ -20,7 +20,10 @@ identity:
   trigger: /页面/页面初始化事务
 binding:
   type: mobilegw
-  operationType: api_91d5e0b55164bb5b60240fa030519c23
+  operationType: profuse.mgw.invoke
+  target:
+    app: saddle
+    interfaceId: api_91d5e0b55164bb5b60240fa030519c23
 callSites: []
 input: {type: object, nullable: false, fields: {}}
 output: {type: object, nullable: false, fields: {}}
@@ -36,7 +39,7 @@ types: {}
 
 identity 必须且仅有 kind/business/domain/page/trigger 五个字符串，kind 固定 backend_contract。归一化及校验由公共工具执行；id 为 `api_` 加32位小写十六进制摘要。页面和触发标识必须有真实 Spec 依据，不通过文案重新翻译。
 
-文件名 `<id>.backend-contract.yaml`、后端 `operations/<id>/`、Rust 模块及静态注册 operation_type 原样使用 id；binding.operationType 必须等于 id。它是内部目标接口，不能替代外层 profuse.mgw.invoke 转发通道，也不从 business 猜 deployment_app。
+文件名 `<id>.backend-contract.yaml`、后端 `operations/<id>/`、Rust 模块及静态注册 operation_type 原样使用 id；后端静态 operation_type 及 binding.target.interfaceId 必须等于 id。MobileGW 外层 binding.operationType 为 profuse.mgw.invoke，binding.target.app 消费项目已确定的 deployment_app，不从 business 猜。不得把内部接口身份直接当成外层网关 operationType。
 
 callSites 非空，每项必需 triggerSource（按 workflow 身份规范的 explicit 或 languageDefault 封闭形状）及 trigger 且等于 identity.trigger，每项 page 必须等于 identity.page。调用位置定位相同语义事件的不同载体；不同页面或不同语义起点必须独立契约。一个起点内按业务连续性聚合读取，不按实体机械拆分；中断后的后续请求使用源头正式续接位置作为新的触发起点，不增加自由命名职责。
 
@@ -426,3 +429,17 @@ source:
 校验必须同时证明：当前 callSites 的页面触发确实调用该事务；该参数存在且类型来自正式声明；Visual 的 `传入` 实际绑定该参数并可由前端取得；业务边界以内的参数传递无未经定义的转换。inputBindings 继续使用真实 actionInput/pageRead 等表达，不能只给 source 不检查当前值。类型映射沿统一规则（金额精确元字符串），不按样例或物理 execute 的 Java 类型反推业务类型。
 
 这不允许向客户端索要可信用户身份/服务端时间，不允许将任意局部变量、内部函数参数、物理实现参数声明为业务来源；也不要求 Spec 新增实体去承载本来合法的事务参数。physicalExecuteParameter 的 RequestContext 入口限定保持不变。
+
+## 当前页面内分阶段执行的有限来源
+
+项目已经以同一页面起点承接多个确定执行阶段时，保留一个契约身份及封闭stage集合；不同页面起点仍独立。stage用于选择本契约已声明的处理阶段，不接受任意方法名、类名或下游路由，不因返回形状类似跨起点共享身份。必须核每个阶段的实际调用、前置结果和独立失败语义，不预取源条件不成立的阶段。
+
+现有physical阶段元数据的封闭形状：
+
+- `physicalExecuteStage`：`{kind, path, execute}`，path定位实际physical绑定，execute逐字匹配唯一正式execute函数。只用于stage的单值enum及对应判别分支，不作为业务实体字段。inputBindings中同阶段技术标签为`{executeStage: <同一正式函数名>}`。这是上述判别联合字段来源规则的技术阶段特例，不扩大业务枚举来源。
+- `physicalExecuteResult`：`{kind, path, execute, field, protocol}`，field逐段对应正式返回DTO；protocol为`{path, service, method, field}`，精确关联官方生成proto的真实Service/Method/结果字段，数组项按实际DTO元素类型核对。不得猜命名映射、使用旧协议伪证新字段，或把未返回的数据作为投影。该来源只适用于此项目已经确定的物理执行结果交付方式；业务实体投影仍可使用原来源形状。
+- 请求业务字段仍须追溯实体、正式事务或入口参数。不能因为存在一个execute参数就从客户端索要可信用户或系统时刻，也不向客户端暴露任意execute调用能力。仅适用RequestContext入口的physicalExecuteParameter限制保持不变。
+
+前端JSON外层网关、后端契约信封、官方gRPC结果是三层不同结构，必须逐字段核对。原物理字符串单位以源声明和实际赋值链为准：不能把分字符串因名称含Amount就标为元；业务金额按统一精确元字符串规则，两者的转换位置不得重复或遗漏。
+
+维护这些规范时，先核已确认的项目约定和实际消费者。只有新增来源形状或迁移范围已明确，才修改校验与生成器；文档支持不冒充现有工具已自动实现。开工前用项目当前契约做兼容核对，不把Skill滞后当作源业务问题，也不静默收紧已有请求可空或网关包装行为。

package/package.json

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