SYNC_ARCHITECTURE.md 的 L3 Key Features 仍打勾 "Field Mapping: With transformations",而 FieldMapping.transform 已在 #5552 退役

[os-zhuang]

发现于 #5554(修同文件同一节的 Rate Limiting 措辞)。属另一次退役(#5552,非 #4911),故不搭 #5554 的车。

事实

packages/spec/docs/SYNC_ARCHITECTURE.md 的 L3 ### Key Features 仍有:

- ✅ **Field Mapping**: With transformations and data type conversion

而 FieldMapping.transform —— 作者面上写作 connector.fieldMappings[].transform —— 与整个 FieldMappingTransform 五成员联合已在 #5552 / PR #6078 按 ADR-0049 退役。墓碑在 packages/spec/src/shared/mapping.zod.ts:89:

'`FieldMapping.transform` — authored as `connector.fieldMappings[].transform` and
 `externalLookup.fieldMappings[].transform` — was removed in @objectstack/spec 17.0.0 …'

实测 ConnectorFieldMappingSchema(connector.zod.ts:121)扩展 BaseFieldMappingSchema 后新增的只有 dataType / required / syncMode —— data type conversion 那半句是真的(dataType),With transformations 那半句不是。与 #5554 的 Decision Matrix 行同构:一半对,一半把作者引向已退役的键。

同文件内的自相矛盾(与 #5554 完全同型)

同一文档 L303–L310 的示例块里,墓碑注释已经写对了:

// (`transform` sat here until #5552 retired it — the five-member union never had
//  an executor …)

—— 例子改了,散文没跟着改。这正是 #5554 的成因,只是换了一次退役。

影响

作者读打勾那行去写 fieldMappings[].transform,拿到 strictObject 的退役提示;比编译不过更值得修的是他会以为连接器字段映射能做值转换,从而把本该放到 L2 import mapping 的 transform(墓碑指定的真实去处)或 ETL transformation step 的逻辑,规划到一个不执行它的面上。

建议

• 把该行改成如实说法:字段映射提供 dataType 类型转换与 syncMode 方向控制;值转换请用 L2 import mapping 的 transform(字符串枚举 + params,墓碑指定)或 ETL transformation step。措辞直接复用 shared/mapping.zod.ts:89 墓碑现成句,避免同一次退役出现两种说法。
• 顺带核一下 connector.zod.ts 模块 JSDoc 的 - Bidirectional sync with field mapping and transformations(同一处过期,已在 connector.zod.ts 的模块 JSDoc 仍在三处宣传出站 Rate Limiting(#4911 已退役),并被逐字生成进 content/docs/references/integration/connector.mdx #6383 记录)。

门禁提示

该文档被两个门禁钉住:packages/spec/src/automation/etl-author-shape.test.ts 钉总 ```typescript 块数 = 6,packages/spec/src/integration/connector-author-shape.test.ts 钉 `Connector` 例子 = 3。纯散文改动不动这两个数,但请跑一遍确认而非假定。

分诊提示

按 PM 指示打 finding,但请复核等级:按 #5554 自己的标准这是作者今天就会撞上的具体缺陷,不像观察类。

[os-zhuang]

🤖 Claiming this issue.

• Session: session_014wsZeReNTqiceBfLb5Pyf5 (os-dev agent, lane domain:spec-tooling)
• Branch: claude/issue-6384-field-mapping-transformations
• Worktree: ../objectstack-issue-6384 off current origin/main

计划:纯散文修正 packages/spec/docs/SYNC_ARCHITECTURE.md,复用 shared/mapping.zod.ts:89 墓碑既有措辞,显式否定而非静默删除;先自行 grep 统计真实站点数,再跑两个文档门禁(etl-author-shape.test.ts / connector-author-shape.test.ts)确认块数未变。不动任何 *.zod.ts(模块 JSDoc 那半属 #6383)。

---

Generated by Claude Code