docs(spec): SYNC_ARCHITECTURE.md L3 段停止宣传字段映射的值转换能力 (#6384) - #6395
Merged
Conversation
`FieldMapping.transform` —— 作者面上写作 `connector.fieldMappings[].transform` 与 `externalLookup.fieldMappings[].transform` —— 连同整个五成员 `FieldMappingTransform` 联合(`constant` / `cast` / `lookup` / `javascript` / `map`)已在 @objectstack/spec 17.0.0 按 #5552 / ADR-0049 退役:五个成员没有任何 一个有执行器,`javascript` 成员还在推荐 #3278 已退役的 `js` dialect。文档 L303 示例块的墓碑注释早已写对,散文却没跟着改 —— 与 #5554 / PR #6388 同型,只是换了 一次退役。 正文点名一处(Key Features 打勾行),实测为四处,全部改为如实说法: - L198 Key Features:打勾行 `With transformations and data type conversion` —— `data type conversion` 那半是真的(`dataType`),`With transformations` 那半不是。⛔ 未删行,改为 `dataType` 目标类型 + `syncMode` 逐字段方向,并在 行内显式写出 **no value transformation**,另加引用块。这里用显式否定而非静默 删除:删掉只是不再重复该断言,消不掉读者已经形成的"连接器字段映射能做值转换" 这一信念 —— 而这个信念比编译不过更贵,它会把值转换逻辑规划到一个不执行它的面上。 - L287 示例块内注释:`// Field Mappings with Transformations.` —— 与 15 行后 自己的墓碑注释直接矛盾。改为 `dataType` / `syncMode`,并指向那条墓碑。 - L387 Decision Matrix:⛔ 未删行(joins/aggregations → L2 那半是对的)。原行只 问 `complex transformations`,想做逐字段值转换的作者不会把自己读进"complex", 于是落到 L3 —— 正是本 issue 描述的失败路径。改写为"是否需要转换值(无论复杂 与否)",并写明 **Not** L3。 - L430 Migration Guide L3→L2 引导语:同上,`complex transformations` → "需要转换值(joins/aggregations,或 `fieldMappings` 做不到的逐字段转换)"。 措辞全部复用 `shared/mapping.zod.ts:89` 墓碑现成句,不另造第二种说法(同一次 退役出现两种描述,正是它们日后互相矛盾的成因)。 保留的每一条都对着 schema 核过,不是假定: - `ConnectorFieldMappingSchema`(`connector.zod.ts:121`)= `BaseFieldMappingSchema .extend({ dataType, required, syncMode })`,新增的确实只有这三个键;基类 `FieldMappingSchema`(`shared/mapping.zod.ts:72`)的 `transform` 是 `retiredKey(...)` 墓碑。故行文只说 schema **declares** `dataType`,不宣称运行时 执行 —— 无 `connector` liveness 记录可支撑执行侧断言。 - 墓碑指定的去处真实存在:`MappingSchema.fieldMapping` (`data/mapping.zod.ts:224`)= `z.array(ImportFieldMappingSchema)`,其 `transform: TransformType.default('none')`(:140)+ `params`(:147); `TransformType`(:84)含 `javascript`,而 REST import path 对它回 400 —— 故沿用 墓碑那份六成员列表 + "rejects `javascript` with a 400" 的补语,列表才是诚实的。 - `os migrate meta --from 16` 存在(`packages/cli/src/commands/migrate/meta.ts:146`), 且转换 `field-mapping-transform-removed` 的 `toMajor: 17` (`conversions/registry.ts:4197`)—— `--from 16` 是对的入口。 纯散文改动,未新增/删除任何 ```typescript 块:`grep -c '^```typescript'` 实测仍 为 6,`etl-author-shape.test.ts` 与 `connector-author-shape.test.ts` 两个门禁 30 tests 实跑通过(非假定);packages/spec 全量 338 files / 8644 tests 亦通过。 `packages/spec/docs/` 不在该包 `package.json` 的 `files` 白名单 (`dist`/`json-schema`/`liveness`/`prompts`/`llms.txt`/`README.md`/ `src/**/*.zod.ts`/`CHANGELOG.md`/`api-surface`/`spec-changes.json`)内,不随包 发布,故不写 changeset,改用 `skip-changeset` 标签。 Fixes #6384 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014wsZeReNTqiceBfLb5Pyf5
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/s
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
added
the
skip-changeset
Claude
os-zhuang
marked this pull request as ready for review
August 7, 2026 17:08
Contributor
Author
|
PM 验收：ACCEPT — 已 ready + auto-merge。 CI:28 个 check,全部 success/skipped,零 failure。ESLint
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #6384
FieldMapping.transform—— 作者面上写作connector.fieldMappings[].transform与externalLookup.fieldMappings[].transform—— 连同整个五成员FieldMappingTransform联合(constant/cast/lookup/javascript/map)已在@objectstack/spec17.0.0 按 #5552 / ADR-0049 退役:五个成员没有任何一个有执行器,javascript成员还在推荐 #3278 已退役的jsdialect。文档 L303 示例块的墓碑注释早已写对,散文却没跟着改 —— 与 #5554 / PR #6388 完全同型,只是换了一次退役。
实测站点数:正文点名 1 处,实测 4 处
- ✅ **Field Mapping**: With transformations and data type conversion- ✅ **Field Mapping**:dataTypetarget type andsyncModeper-field direction — **no value transformation**; see below+ 引用块// Field Mappings with Transformations.// Field Mappings —dataTypetarget type andsyncModedirection. There is no value transformation here; see the tombstone on the second entry.Do you need complex transformations (joins, aggregations)?→**Yes** → L2 (ETL)Do you need to transform values at all — joins and aggregations, or just a per-field convert?→ L2 或 import mapping 的fieldMapping[].transform;并写明 Not L3When a connector's declarative sync needs complex transformations:…needs to transform values — joins and aggregations, or a per-field convert thatfieldMappingscannot do (#5552):未改的三处近似命中,逐条给了理由而非漏掉:
|map| Field mapping/renaming |—— 这是 L2 ETL 的ETLTransformation.type表,不是连接器字段映射。bidirectional本身是真的(syncConfig.direction/syncMode)。沿用 #5554 的两个动作
data type conversion那半是真的),而是行内写出 no value transformation 并另加引用块。删掉只是不再重复该断言,消不掉读者已形成的信念 —— 而这个信念比编译不过更贵:作者会把值转换逻辑规划到一个不执行它的面上。同理 L387 未删行(joins/aggregations → L2 那半是对的)。shared/mapping.zod.ts:89墓碑现成措辞,不另造第二种说法 —— 同一次退役出现两种描述,正是它们日后互相矛盾的成因。L387 值得单说:原行只问
complex transformations,想做逐字段值转换的作者不会把自己读进 "complex",于是落到 L3 —— 正是本 issue 描述的失败路径。保留的每一条都对着 schema 核过,不是假定
ConnectorFieldMappingSchema(connector.zod.ts:121)=BaseFieldMappingSchema.extend({ dataType, required, syncMode })—— 新增的确实只有这三个键;基类FieldMappingSchema(shared/mapping.zod.ts:72)的transform是retiredKey(...)墓碑。dataType,不宣称运行时执行 ——packages/spec/liveness/下没有 connector 记录,执行侧断言无据可依。这是我在措辞上刻意收窄的一处。MappingSchema.fieldMapping(data/mapping.zod.ts:224)=z.array(ImportFieldMappingSchema),其transform: TransformType.default('none')(:140)+params(:147)。TransformType(:84)实为七成员,含javascript;墓碑列的是六个。差额不是笔误:REST import path 对javascript回 400。故沿用六成员列表时必须带上 "rejects its ownjavascriptvalue with a 400" 的补语,列表才是诚实的 —— 已带上。os migrate meta --from 16存在(packages/cli/src/commands/migrate/meta.ts:146),且转换field-mapping-transform-removed的toMajor: 17(conversions/registry.ts:4197)——--from 16是对的入口。门禁:实跑,非推理
packages/spec 全量:
Test Files 338 passed (338)/Tests 8644 passed (8644)。typecheck:tsc --noEmit+check:test-typecheck: OK。node scripts/check-nul-bytes.mjs:OK (scanned 6046 tracked text file(s); no raw ASCII control bytes)。纯散文改动,未新增/删除任何 ```typescript 块,两个门禁钉的数字均未移动。
Changeset
packages/spec/docs/不在该包package.json的files白名单(dist/json-schema/liveness/prompts/llms.txt/README.md/src/**/*.zod.ts/CHANGELOG.md/api-surface/spec-changes.json)内,不随包发布,故不写 changeset,改用skip-changeset标签。注意:
src/**/*.zod.ts在白名单内 —— 同一问题的模块 JSDoc 那半(#6383,已转domain:spec)是随包发布的,那一半需要 changeset。本 PR 未触碰任何*.zod.ts。Generated by Claude Code