PBIR ↔ Legacy 格式转换（面向 PBIRS）
你在处理 Power BI pbix 的报表定义格式转换。核心场景：把 PBIR 格式（Report/definition/** 目录结构）反向翻译为 PBIRS 可用的 Legacy 格式（单一 Report/Layout），或在此过程中改写、重打包、修复签名。
何时启用
满足任一条即进入本技能流程，不要凭经验直接动手：
- 把 PBIR 定义的 pbix 转成 Report Server 能打开的格式
- 目标环境是 Power BI Report Server (PBIRS)，需要产出可用 pbix
- 要改写 / 生成 / 校验
Report/Layout - 在 pbix 里新增或修改页面、视觉对象、主题、切片器同步组
- Desktop 报「此文件已损坏」或「报表包含增强型报表格式(PBIR)」
- 重新打包 pbix（替换 Layout、追加主题资源、处理签名）
先读参考文档（动手前必读，不要跳过）
| 文档 | 内容 |
|---|---|
@references/field-mapping.md |
权威字段映射：Layout 顶层 / config / 资源包枚举 / section / visualContainer / singleVisual 官方字段顺序 / PBIR↔Legacy 对照 / actionButton 动作 |
@references/constraints.md |
格式硬约束 + 目标环境约束：编码、zip 条目、签名、两道关卡模型、PBIRS 视觉选型限制 |
@references/toolchain.md |
工具链：现成脚本、Desktop 自动化要点、交付前校验清单 |
三条必须先建立的心智模型
1. 打开 pbix 有两道独立关卡，可绕过性不同
| 关卡 | 报错文案 | 触发条件 | 能否绕过 |
|---|---|---|---|
| A 文件完整性 | 「此文件已损坏…」 | Report/* 被外部改过、SecurityBindings 失配 |
能 → 移除 SecurityBindings |
| B 报表格式 | 「报表包含增强型报表格式(PBIR)…」 | 使用 Report/definition/** 目录结构 |
不能 → 必须转成 Legacy |
2. SecurityBindings 是 Report/* 的内容签名 —— 改过就必须丢弃它
任何外部工具对 Report/* 的改动都会使签名失配。打包时跳过 SecurityBindings，让 Desktop 打开后 Ctrl+S 重建。
> 有效文件判据：Report/Layout 尾随空格 = 0 且 SecurityBindings = 358 B。
3. RS 版与标准版 Desktop 的保存行为相反
| 标准版 Desktop | RS 版 Desktop | |
|---|---|---|
| 保存后格式 | 升级为 PBIR | 保持 Legacy |
Report/Layout |
消失 | 保留 |
Metadata.CreatedFrom |
变 | 仍 OnPrem |
推论（重要）：用标准版 Desktop 打开 PBIRS 服务器上的报表并保存，会把 PBIR 回写服务器 → PBIRS 端打不开。编辑服务器报表只用 RS 版 Desktop。
标准作业链路
1. 判断源格式
· 有 Report/Layout → Legacy
· 有 Report/definition/** → PBIR，需转换
· 判断口径见 @references/constraints.md
2. 生成 Legacy Layout
· 以一份原版 Legacy 骨架为基础，继承 prototypeQuery / isDrillDisabled /
hasDefaultSort / queryOptions 等 PBIR 里没有的字段
· 用 PBIR 的 visual.json 覆写：位置 / objects / vcObjects /
projections / columnProperties / syncGroup
· 新增视觉从零构造（照 singleVisual 官方字段顺序）
· 字段规则全部见 @references/field-mapping.md
3. 打包 pbix
· 替换 Report/Layout（UTF-16LE 无 BOM、紧凑单行、中文不转义）
· 追加主题资源 Report/StaticResources/RegisteredResources/<主题>.json
· 丢弃 SecurityBindings
· 逐条保留 compress_type / external_attr / flag_bits / date_time
· DataModel 以 stored 压缩原样流式复制
4. RS 版 Desktop 打开 → Ctrl+S → 签名自动重建
5. 交付前静态校验 + 原文件基线复核（清单见 @references/toolchain.md）
必做的两项校验
- 字段映射零缺失 —— 源里出现的每个
queryRef，都必须能在 Legacy 骨架的prototypeQuery.Select[].Name中找到。写脚本比对，不要靠眼睛看。 - 原文件未动 —— 动手前记录所有相关文件的 大小 + 时间戳 + MD5，交付时逐项复核。
四条最容易踩的规则
syncGroup必须在vc.config.singleVisual.syncGroup—— 放 visualContainer 顶层会被静默丢弃- Legacy
projections每项仅 2 键（queryRef+active），PBIR 的field/nativeQueryRef/displayName不能搬 relationships.type是数值枚举（Default=0 / DataFilter=1 / HighlightFilter=2 / NoFilter=3），不是字符串Layout.config与section.config都是 JSON 字符串（不是嵌套对象），需要序列化两次
输出
- 转换后的 pbix 文件（新文件名，不动原文件）
- 校验报告：条目清单 + Layout 编码/长度/尾随空格 + 页数与视觉数 + 关键字段存在性 + 原文件基线对照
- 若目标为 PBIRS，额外确认：产出的视觉类型全在 PBIRS 支持范围内（见
@references/constraints.md的环境约束节）
