WeKnora/internal/datasource/connector/dingtalk
linus-liu-web 7d1d71e50d
fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822)
* fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按契约渲染 + 未建模块类型可见)

渲染器有三处会无声地丢正文:

- 列表块只在 inline 子节点渲染结果为空时才递归子块,于是 children 里既有
  inline 又有块级元素时,块级子节点的文本永远不渲染 —— 而且连 unknown 标记
  都不设,完全无痕;块级列表项还会被 strings.Fields 折叠进同一个 bullet 行;
- 未建模的块类型(code / attachment / slot / sheet / unknown …)payload 解析
  不出来,正文整块丢失,只剩类型名写进文档 metadata,全仓没有一行日志;
- 未建模的 inline 元素类型(slot 等,官方文档里文本放在 children)在默认分支
  只写 text 字段,children 里的正文直接消失。

改动:

- 列表按官方契约渲染:一个列表块 = 一个列表项,缩进用 list.level(0-based),
  同一列表的多项是共享 listId 的兄弟块(扁平模型),不假设结构嵌套;契约外的
  块级子节点仍然逐个渲染,作为防御,不再二选一、不再塌行;
- 未建模的 inline 元素在自身没有文本时渲染 children,避免整段消失;
- 未建模块类型在 Fetch 路径上显式暴露(这一层同时拿得到 ctx 与节点身份):
  collectUnknownBlockTypes 产出可测值,同时喂给 logger.Warnf 与
  common.PipelineWarn;文档 metadata 保持不变。

code / attachment / sheet / slot 的正文渲染不在本次范围:它们的块级 JSON 形状
仍无可靠证据(官方与公开 CLI 参考的键名互相冲突),先靠告警把真实 payload
找出来再按形状补,免得用猜测的字段把"可见的丢失"变回"静默的丢失"。

* fix(datasource/dingtalk): 按实测形状补 code / attachment / unknown 三类块的渲染

只读探针在真实 adoc 文档上取到的形状(不再依赖公开参考里互相冲突的键名):

- code: {"syntax":"bash","text":"...","title":"..."},title 有时缺;语言键是
  syntax 而不是 language;
- attachment: {"name":..,"size":..,"type":..,"viewType":..,"resourceId":..},
  resourceId 有时缺,payload 里没有任何下载 URL;
- unknown: {"rawType":"..."},只有真实类型名,没有正文;
- table.cells 的读取路径与实测一致,未改动。

改动:

- code 渲染成围栏代码块:语言取 syntax(含反引号或换行这类无法作为 info string
  的值时省略),围栏长度取 max(3, 正文最长反引号串+1),避免正文自带的围栏把代码块
  提前截断;title 非空时在围栏前输出一行加粗标题;text 为空不输出空围栏,仍按未建模
  类型记录并告警;
- attachment 渲染成一行纯文本 Attachment: <name> (<size>):名称做 Markdown 转义,
  size 按 1024 进制保留一位小数(B/KB/MB/GB),size<=0 时省略括号;payload 没有可
  解析的下载地址,因此不拿 resourceId 拼任何链接;名称为空不输出,仍按未建模类型
  记录并告警;
- unknown:default 分支在 rawType 非空时把标记写成 "unknown:"+rawType,使
  unknown_block_types metadata 与 warnUnknownBlockTypes 的日志/pipeline 事件直接
  带真实类型名,而不是无信息量的 "unknown"(字段名、签名与调用位置均未动),
  children 仍逐层递归。

既有普通块(段落/标题/引用/表格/列表)的输出逐字节不变,回归用例
TestRenderDocumentKeepsOrdinaryBlocksStable 未修改即通过。原先拿 code/attachment
当“未建模”夹具的两个用例改用空载荷的同类块与带 rawType 的 unknown 块,覆盖新的
“渲染不出内容仍要告警”语义。

* fix(datasource/dingtalk): 列表按线上真实形状渲染(块自带 text)

线上 Blocks API 返回的是一个列表项一个块,正文在块自带的 text 字段里,
没有 children、没有 list.level、也没有 listId。列表是唯一一类没有回退到
「块自带 text」的正文块 —— paragraph / heading / blockquote 都有
renderInlines(children) 取不到就取自身 text 的回退,列表直接进
renderListBlock,而那个函数只遍历 children,于是列表正文被整条丢弃;
又因为 blockType 是已知类型,switch 命中了它,连 unknown_block_types
都不会记一笔。

同一形状问题还影响 unknown:sdt 块(文档目录)的正文就在 unknown.text 里,
此前只写标记不渲染正文。

夹具取自线上 payload(markdown_live_shape_test.go),不按转述的契约自造。

---------

Co-authored-by: linus-liu-web <11640009+linus-liu-web@users.noreply.github.com>
2026-09-29 00:48:20 +08:00
..
client.go feat(datasource): add DingTalk Docs integration with safe sync and localization (#2313) 2026-09-14 19:53:29 +08:00
client_test.go feat(datasource): add DingTalk Docs integration with safe sync and localization (#2313) 2026-09-14 19:53:29 +08:00
connector.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
connector_test.go fix(datasource/dingtalk): 跳过不再静默,展开叶子不再报错 2026-09-29 00:47:02 +08:00
connector_unknown_blocks_test.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
markdown.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
markdown_blocks_test.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
markdown_lists_test.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
markdown_live_shape_test.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
markdown_test.go fix(datasource/dingtalk): 块级渲染不再静默丢内容(列表按线上真实形状渲染 + 未建模块类型可见) (#3822) 2026-09-29 00:48:20 +08:00
resource.go feat(datasource): add DingTalk Docs integration with safe sync and localization (#2313) 2026-09-14 19:53:29 +08:00
resource_test.go feat(datasource): add DingTalk Docs integration with safe sync and localization (#2313) 2026-09-14 19:53:29 +08:00
sync_safety_test.go feat(datasource): add DingTalk Docs integration with safe sync and localization (#2313) 2026-09-14 19:53:29 +08:00