@antprofuse/saddle-islands-design 0.1.20 → 0.1.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/SKILL.md +1 -1
- package/modules/backend-contract/assets/backend-contract.template.yaml +4 -1
- package/modules/backend-contract/design.md +1 -1
- package/modules/backend-contract/references/backend-contract.md +21 -4
- package/modules/external-contract-proto/references/runtime.md +1 -1
- package/package.json +1 -1
package/SKILL.md
CHANGED
|
@@ -5,7 +5,7 @@ description: 消费 Islands Spec 与自洽 adapt，设计后端契约、逻辑
|
|
|
5
5
|
|
|
6
6
|
# Saddle Islands 设计
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
先完整阅读本轮冻结的 saddle-workflow 及本 Skill 原始包。按 workflow 的传播规则消费已提交并推送的 Git 包，核仓库、完整 commit、版本和逐文件摘要；同批保持一致，运行中不静默替换。npm 仅作发布备份，不要求安装 latest 或等待 registry。缺失正文或引用文件须修复交接，不能凭版本号相同认定内容一致。
|
|
9
9
|
|
|
10
10
|
当项目明确由上游Spec工具生成既有gRPC协议时，该协议是只读输入；本Skill只设计前后端契约与DB，不另建业务proto、不添加Saddle专有option。协议缺口回报上游，Java实现与部署不纳入范围。下述external-contract-proto模块仅适用于用户明确委托本阶段设计外部协议的项目。
|
|
11
11
|
|
|
@@ -8,7 +8,10 @@ identity:
|
|
|
8
8
|
id: api_91d5e0b55164bb5b60240fa030519c23
|
|
9
9
|
binding:
|
|
10
10
|
type: mobilegw
|
|
11
|
-
operationType:
|
|
11
|
+
operationType: profuse.mgw.invoke
|
|
12
|
+
target:
|
|
13
|
+
app: saddle # 必须核项目实际deployment_app，不从business猜
|
|
14
|
+
interfaceId: api_91d5e0b55164bb5b60240fa030519c23
|
|
12
15
|
callSites:
|
|
13
16
|
- kind: visualPageLoad
|
|
14
17
|
page: 查账结果
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
## 推演顺序
|
|
6
6
|
|
|
7
7
|
1. 核对指定 Spec/Prototype 的交互、展示与结果需求。覆盖分母和链路算法由后续测试阶段产出，不在契约设计阶段提前生成。Spec其他内容用于解释实体与业务，不据此扩展接口范围；不要求Spec预先声明物理服务接口。
|
|
8
|
-
2. 先读取
|
|
8
|
+
2. 先读取 本轮冻结的 saddle-workflow 原始包 的语义身份规范，用公共工具生成并登记 identity/id，证明唯一页面语义起点；不同起点独立契约，同起点内聚合。找到实际页面动作，沿业务逻辑走到下次用户参与或交付结果的边界。中间无需用户补充输入的关联读取可以归并一次调用；不按实体数、Logic数或Dependency数机械拆接口，也不强制所有业务只有一个查询。
|
|
9
9
|
3. 输入逐字段追溯实体属性（含adapt扩展）、正式外部入口字段或正式命名事务入口参数（transactionInput）。后端不能从系统取得才向前端索要；系统当前用户不出现在input或context。入口字段可直接向后传递，不强制归属实体属性。
|
|
10
10
|
4. 输出是具体线上字段的实体投影，不是让前后端各自解释的抽象Row。说明本次实体实例根和关联路径，不能仅凭字段同名认定来源正确。不为仅传递对象制造uid、token或身份映射。
|
|
11
11
|
5. 选择最小充分的结果结构：对象+可空成员已完整表达时无需case；存在真实互斥形状时用联合。完整枚举来自声明，不来自样例。确认的跨字段、实例归属及空值语义写入invariants，不以过程说明代替正式约束。
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
使用受限 YAML：UTF-8 编码、与 JSON 兼容的数据值；禁止 alias、anchor、tag、merge key 和重复 key。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
响应对象只包含声明字段，所有响应字段必须出现，nullable仅允许显式null而非省略。请求中nullable:true允许省略或显式null，均表示未设置；nullable:false仍必填且非null。不得把额外请求字段拒绝升级为源头未要求的业务验收或框架前置。type/ref/来源/invariants均为设计元数据，不是线上字段。文件内模型独立，不跨契约复用业务类型；types为空合法，不强迫请求结果起额外类型名。
|
|
10
10
|
|
|
11
11
|
## 必需的顶层结构
|
|
12
12
|
|
|
@@ -20,7 +20,10 @@ identity:
|
|
|
20
20
|
trigger: /页面/页面初始化事务
|
|
21
21
|
binding:
|
|
22
22
|
type: mobilegw
|
|
23
|
-
operationType:
|
|
23
|
+
operationType: profuse.mgw.invoke
|
|
24
|
+
target:
|
|
25
|
+
app: saddle
|
|
26
|
+
interfaceId: api_91d5e0b55164bb5b60240fa030519c23
|
|
24
27
|
callSites: []
|
|
25
28
|
input: {type: object, nullable: false, fields: {}}
|
|
26
29
|
output: {type: object, nullable: false, fields: {}}
|
|
@@ -32,11 +35,11 @@ types: {}
|
|
|
32
35
|
|
|
33
36
|
## 契约身份与唯一页面起点
|
|
34
37
|
|
|
35
|
-
使用
|
|
38
|
+
使用 `本轮冻结的 saddle-workflow 原始包` 的 包内 `references/semantic-identity.md`及 scripts/semantic_identity.py，设计阶段生成，研发直接消费。不自行重写摘要。
|
|
36
39
|
|
|
37
40
|
identity 必须且仅有 kind/business/domain/page/trigger 五个字符串，kind 固定 backend_contract。归一化及校验由公共工具执行；id 为 `api_` 加32位小写十六进制摘要。页面和触发标识必须有真实 Spec 依据，不通过文案重新翻译。
|
|
38
41
|
|
|
39
|
-
文件名 `<id>.backend-contract.yaml`、后端 `operations/<id>/`、Rust 模块及静态注册 operation_type 原样使用 id
|
|
42
|
+
文件名 `<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。
|
|
40
43
|
|
|
41
44
|
callSites 非空，每项必需 triggerSource（按 workflow 身份规范的 explicit 或 languageDefault 封闭形状）及 trigger 且等于 identity.trigger，每项 page 必须等于 identity.page。调用位置定位相同语义事件的不同载体；不同页面或不同语义起点必须独立契约。一个起点内按业务连续性聚合读取，不按实体机械拆分；中断后的后续请求使用源头正式续接位置作为新的触发起点，不增加自由命名职责。
|
|
42
45
|
|
|
@@ -426,3 +429,17 @@ source:
|
|
|
426
429
|
校验必须同时证明：当前 callSites 的页面触发确实调用该事务；该参数存在且类型来自正式声明；Visual 的 `传入` 实际绑定该参数并可由前端取得；业务边界以内的参数传递无未经定义的转换。inputBindings 继续使用真实 actionInput/pageRead 等表达，不能只给 source 不检查当前值。类型映射沿统一规则（金额精确元字符串），不按样例或物理 execute 的 Java 类型反推业务类型。
|
|
427
430
|
|
|
428
431
|
这不允许向客户端索要可信用户身份/服务端时间，不允许将任意局部变量、内部函数参数、物理实现参数声明为业务来源；也不要求 Spec 新增实体去承载本来合法的事务参数。physicalExecuteParameter 的 RequestContext 入口限定保持不变。
|
|
432
|
+
|
|
433
|
+
## 当前页面内分阶段执行的有限来源
|
|
434
|
+
|
|
435
|
+
项目已经以同一页面起点承接多个确定执行阶段时，保留一个契约身份及封闭stage集合；不同页面起点仍独立。stage用于选择本契约已声明的处理阶段，不接受任意方法名、类名或下游路由，不因返回形状类似跨起点共享身份。必须核每个阶段的实际调用、前置结果和独立失败语义，不预取源条件不成立的阶段。
|
|
436
|
+
|
|
437
|
+
现有physical阶段元数据的封闭形状：
|
|
438
|
+
|
|
439
|
+
- `physicalExecuteStage`：`{kind, path, execute}`，path定位实际physical绑定，execute逐字匹配唯一正式execute函数。只用于stage的单值enum及对应判别分支，不作为业务实体字段。inputBindings中同阶段技术标签为`{executeStage: <同一正式函数名>}`。这是上述判别联合字段来源规则的技术阶段特例，不扩大业务枚举来源。
|
|
440
|
+
- `physicalExecuteResult`：`{kind, path, execute, field, protocol}`，field逐段对应正式返回DTO；protocol为`{path, service, method, field}`，精确关联官方生成proto的真实Service/Method/结果字段，数组项按实际DTO元素类型核对。不得猜命名映射、使用旧协议伪证新字段，或把未返回的数据作为投影。该来源只适用于此项目已经确定的物理执行结果交付方式；业务实体投影仍可使用原来源形状。
|
|
441
|
+
- 请求业务字段仍须追溯实体、正式事务或入口参数。不能因为存在一个execute参数就从客户端索要可信用户或系统时刻，也不向客户端暴露任意execute调用能力。仅适用RequestContext入口的physicalExecuteParameter限制保持不变。
|
|
442
|
+
|
|
443
|
+
前端JSON外层网关、后端契约信封、官方gRPC结果是三层不同结构，必须逐字段核对。原物理字符串单位以源声明和实际赋值链为准：不能把分字符串因名称含Amount就标为元；业务金额按统一精确元字符串规则，两者的转换位置不得重复或遗漏。
|
|
444
|
+
|
|
445
|
+
维护这些规范时，先核已确认的项目约定和实际消费者。只有新增来源形状或迁移范围已明确，才修改校验与生成器；文档支持不冒充现有工具已自动实现。开工前用项目当前契约做兼容核对，不把Skill滞后当作源业务问题，也不静默收紧已有请求可空或网关包装行为。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 运行时协议依据
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
框架Skill使用用户指定或当前项目锁对应的官方精确版本，完整记录发布方来源、版本和摘要；不查询latest来隐式升级既有项目。完整阅读该版实际提供的协议与消费、验证参考文件和模板，不能假定各版本路径相同。官方包与旧资料冲突以已选定实包为准；协议变化单独反馈。包不可取得时不手写替代。工程Skill传播遵循workflow的Git原始包规则，不能把官方框架私改后冒充官方版本。
|
|
4
4
|
|
|
5
5
|
## 固定模板和共享目录
|
|
6
6
|
|