@microi.net/cli 5.8.5 → 5.8.7

package/skills/v8-export-import/references/progressive-02-powerpoint-/345/257/274/345/207/272.md

@@ -1,202 +1,202 @@
-# v8-export-import 详细参考 2
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=v8-export-import-007 sha256=d2958751b32d5143693cbdb6fb72aeca97f450c80c360aa7d826d4f6595c0ab1 -->
-## PowerPoint 导出
-
-PowerPoint 的幻灯片尺寸、图片/表格位置与宽高单位均为英寸，默认画布为 16:9（13.333 × 7.5）。
-
-```javascript
-var pptResult = V8.Office.ExportPowerPoint({
-  Title: '季度经营汇报',
-  Author: V8.CurrentUser.Name,
-  Subject: '季度复盘',
-  Company: '吾码',
-  SlideWidth: 13.333,
-  SlideHeight: 7.5,
-  FontFamily: 'Microsoft YaHei',
-  BackgroundColor: 'FFFFFF',
-  TitleColor: '17365D',
-  TextColor: '222222',
-  TitleFontSize: 28,
-  BodyFontSize: 18,
-  ShowSlideNumber: true,
-  Slides: [
-    {
-      Layout: 'TitleSlide',
-      Title: '季度经营汇报',
-      Subtitle: DateNow('yyyy-MM-dd')
-    },
-    {
-      Layout: 'TitleAndContent',
-      Title: '核心结论',
-      Bullets: ['收入保持增长', '重点客户续约稳定'],
-      TextItems: [
-        { Text: '风险：回款周期延长', Bullet: true, Level: 0, Bold: true, FontColor: 'C00000' }
-      ],
-      Tables: [{
-        Headers: ['指标', '本期', '目标'],
-        Rows: [['销售额', '128万', '120万']],
-        X: 0.7, Y: 4.0, Width: 11.9, Height: 2.2,
-        HeaderBackgroundColor: '17365D'
-      }]
-    },
-    {
-      Title: '趋势图',
-      Images: [{
-        FileByteBase64: chartBase64,
-        FileName: 'trend.png',
-        ContentType: 'image/png',
-        X: 1.2, Y: 1.5, Width: 10.9, Height: 5.2
-      }]
-    }
-  ]
-});
-if (pptResult.Code !== 1) return pptResult;
-return {
-  Code: 1,
-  Data: {
-    FileName: '季度经营汇报.pptx',
-    ContentType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-    FileByteBase64: System.Convert.ToBase64String(pptResult.Data)
-  }
-};
-```
-
-`Layout` 支持 `TitleSlide`、`TitleAndContent`。单页支持独立覆盖 `BackgroundColor/TitleColor/TextColor/TitleFontSize/BodyFontSize`。`TextItems` 支持 `Text/Level/Bullet/Bold/Italic/FontSize/FontColor/Alignment`；表格支持位置、尺寸、列宽、表头/单元格颜色；图片支持 Base64/data URI、位置和尺寸。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-export-import-008 sha256=af467dae5c05433fe3be2759f48a6ed09f67be04f620791652033804535ea39c -->
-## 完整导入模式（含进度跟踪）
-
-模块引擎【导入接口替换】+【导入进度接口替换】可实现实时进度提示。
-
-### 导入接口（替换默认导入）
-
-```javascript
-if (!V8.Param.TableId) {
-  return { Code: 0, Msg: '必须指定 TableId 标记当前导入哪张表' };
-}
-
-var importingKey = 'Microi:' + V8.OsClient + ':ImportTableDataStart:' + V8.Param.TableId;
-var stepKey      = 'Microi:' + V8.OsClient + ':ImportTableDataStep:'  + V8.Param.TableId;
-
-// 防止重复导入
-if (V8.Cache.Get(importingKey) === '1') {
-  return { Code: 0, Msg: '有数据正在导入中，请稍后再试' };
-}
-V8.Cache.Set(importingKey, '1');
-
-var stepList = [];
-function pushStep(msg) {
-  stepList.push(DateNow('yyyy-MM-dd HH:mm:ss') + '：' + msg);
-  V8.Cache.Set(stepKey, JSON.stringify(stepList));
-}
-
-pushStep('正在读取文件数据...');
-
-// 解析 Excel
-var base64 = Object.values(V8.FilesByteBase64)[0];
-var parsed = V8.Office.ExcelToList({ FileByteBase64: base64, SheetIndex: 0 });
-if (parsed.Code !== 1) {
-  V8.Cache.Set(importingKey, '0');
-  pushStep('文件解析失败：' + parsed.Msg);
-  return parsed;
-}
-
-pushStep('已读取【' + parsed.Data.length + '】条数据');
-pushStep('已导入【0】条数据...');
-
-// 循环导入
-for (var i = 0; i < parsed.Data.length; i++) {
-  var row = parsed.Data[i];
-  // 字段映射 / 校验
-  row.AAA = 111;
-
-  var addResult = V8.FormEngine.AddFormData(V8.Param.TableName, row, V8.DbTrans);
-  if (addResult.Code !== 1) {
-    V8.Cache.Set(importingKey, '0');
-    pushStep('导入第 ' + (i + 1) + ' 条出错：' + addResult.Msg + '（已回滚）');
-    return { Code: 0, Msg: addResult.Msg };  // 平台自动回滚事务
-  }
-  // 覆盖最后一条进度
-  stepList[stepList.length - 1] = DateNow('yyyy-MM-dd HH:mm:ss') + '：已导入【' + (i + 1) + '】条';
-  V8.Cache.Set(stepKey, JSON.stringify(stepList));
-}
-
-pushStep('导入成功，已结束');
-V8.Cache.Set(importingKey, '0');
-return { Code: 1, Data: { Imported: parsed.Data.length } };
-```
-
-### 导入进度查询接口
-
-```javascript
-if (!V8.Param.TableId) return { Code: 0, Msg: '需要 TableId' };
-var stepStr = V8.Cache.Get('Microi:' + V8.OsClient + ':ImportTableDataStep:' + V8.Param.TableId);
-return { Code: 1, Data: stepStr ? JSON.parse(stepStr) : [] };
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-export-import-009 sha256=f1583c2154c79acea7445119be851654d0cec81620fe0c1f0fadeee90f330bbf -->
-## 接收并下载文件（HTTP 链接转 Excel）
-
-```javascript
-// 从 URL 下载图片插入 Excel 等场景
-var resp = V8.Http.GetResponse({
-  Url: 'https://static.itdos.com/path/file.png'
-});
-var bytes = resp.RawBytes;            // .NET byte[]
-var base64 = System.Convert.ToBase64String(bytes);
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-export-import-010 sha256=0df463f76ba60100c087364b48dab1886d1315b093577ea9485471b34a7a3f6c -->
-## 子表导入自动关联主表
-
-当单独导入 `TableChild` 子表时，Excel 经常没有主表 Id，只带项目编号、客户名称等业务字段。默认导入引擎支持通过子表控件配置批量反查主表，并自动补齐子表外键。
-
-本节只适用于“主表 1:N 子表”；单条独立记录关联应使用 `JoinForm`，不能把明细导入模型
-设计成 `JoinForm`。在主表 `TableChild` 字段的 `Config` 中配置，其中子表、菜单和外键
-位于 Config 根节点，导入选项位于 `Config.TableChild`：
-
-```json
-{
-  "TableChildTableId": "子表 diy_table.Id",
-  "TableChildSysMenuId": "子表 sys_menu.Id",
-  "TableChildSysMenuName": "项目成品清单",
-  "TableChildFkFieldName": "XiangmuId",
-  "TableChild": {
-    "PrimaryTableFieldName": "Id",
-    "ImportAutoFillFk": true,
-    "FieldRelations": [
-      ["Code", "XiangmuBM", true],
-      ["Name", "XiangmuMC"]
-    ]
-  }
-}
-```
-
-配置含义：
-
-- 根节点 `TableChildTableId` / `TableChildSysMenuId` / `TableChildFkFieldName` 必须是
-  回读后的真实子表、隐藏子菜单和子表物理外键，不能猜 Id，也不能放进内层
-  `Config.TableChild`。
-- `ImportAutoFillFk`：是否在导入子表时自动补齐 Config 根节点指定的
-  `TableChildFkFieldName`；默认建议开启。
-- `FieldRelations`：每项为 `[主表字段, 子表/Excel字段, 是否参与导入匹配]`。全部关系用于新增回写和导入回填；第三位为 `true` 的关系用于反查主表，多项为 `true` 时作为组合条件匹配。
-- 不要把所有回填关系都标为 `true`。例如 Excel 只保证有项目编号时，`["Code","XiangmuBM",true]` 负责匹配，`["Name","XiangmuMC"]` 只在找到主表后补名称。
-- 后端继续读取旧版 `ImportParentMatchFieldName` / `ImportChildMatchFieldName`、`ImportRelations`、`ImportBackfillFields` 和根节点 `TableChildCallbackField`；新版前端会合并去重为 `FieldRelations`，并在字段下次保存时清除旧键。
-
-运行规则：
-
-- 只有子表外键为空时才补齐；Excel 已传外键时不覆盖。
-- `FieldRelations` 回填只有在子表对应字段为空时才写入；Excel 已传该字段值时不覆盖。
-- 导入前按业务字段批量查询主表，避免逐行查询。
-- 从主表表单内、左右树形页面或 `V8.OpenAnyTable` 带主表条件打开子表后导入时，即使 Excel 没有匹配字段，也可以通过固定主表 Id 查询主表并回填子表外键和全部 `FieldRelations`。
-- 如果业务字段为空、主表找不到或匹配到多条主表，当前行不自动补齐，并写入导入进度/后台日志，避免错误关联。
-- 示例：项目主表 `xiangmuguanli.Code` 匹配用料清单 `yongliaoqqingdan.XiangmuBM`，自动写入 `yongliaoqqingdan.XiangmuID`。
-- 示例：项目主表 `xiangmuguanli.Name` 回填成品清单 `xiangmugoujianqd.XiangmuMC`，保证导入模板缺少项目名称列时列表仍显示正常。
-
-<!-- /microi-progressive:chunk -->
+# v8-export-import 详细参考 2
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-export-import-007 sha256=d2958751b32d5143693cbdb6fb72aeca97f450c80c360aa7d826d4f6595c0ab1 -->
+## PowerPoint 导出
+
+PowerPoint 的幻灯片尺寸、图片/表格位置与宽高单位均为英寸，默认画布为 16:9（13.333 × 7.5）。
+
+```javascript
+var pptResult = V8.Office.ExportPowerPoint({
+  Title: '季度经营汇报',
+  Author: V8.CurrentUser.Name,
+  Subject: '季度复盘',
+  Company: '吾码',
+  SlideWidth: 13.333,
+  SlideHeight: 7.5,
+  FontFamily: 'Microsoft YaHei',
+  BackgroundColor: 'FFFFFF',
+  TitleColor: '17365D',
+  TextColor: '222222',
+  TitleFontSize: 28,
+  BodyFontSize: 18,
+  ShowSlideNumber: true,
+  Slides: [
+    {
+      Layout: 'TitleSlide',
+      Title: '季度经营汇报',
+      Subtitle: DateNow('yyyy-MM-dd')
+    },
+    {
+      Layout: 'TitleAndContent',
+      Title: '核心结论',
+      Bullets: ['收入保持增长', '重点客户续约稳定'],
+      TextItems: [
+        { Text: '风险：回款周期延长', Bullet: true, Level: 0, Bold: true, FontColor: 'C00000' }
+      ],
+      Tables: [{
+        Headers: ['指标', '本期', '目标'],
+        Rows: [['销售额', '128万', '120万']],
+        X: 0.7, Y: 4.0, Width: 11.9, Height: 2.2,
+        HeaderBackgroundColor: '17365D'
+      }]
+    },
+    {
+      Title: '趋势图',
+      Images: [{
+        FileByteBase64: chartBase64,
+        FileName: 'trend.png',
+        ContentType: 'image/png',
+        X: 1.2, Y: 1.5, Width: 10.9, Height: 5.2
+      }]
+    }
+  ]
+});
+if (pptResult.Code !== 1) return pptResult;
+return {
+  Code: 1,
+  Data: {
+    FileName: '季度经营汇报.pptx',
+    ContentType: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    FileByteBase64: System.Convert.ToBase64String(pptResult.Data)
+  }
+};
+```
+
+`Layout` 支持 `TitleSlide`、`TitleAndContent`。单页支持独立覆盖 `BackgroundColor/TitleColor/TextColor/TitleFontSize/BodyFontSize`。`TextItems` 支持 `Text/Level/Bullet/Bold/Italic/FontSize/FontColor/Alignment`；表格支持位置、尺寸、列宽、表头/单元格颜色；图片支持 Base64/data URI、位置和尺寸。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-export-import-008 sha256=af467dae5c05433fe3be2759f48a6ed09f67be04f620791652033804535ea39c -->
+## 完整导入模式（含进度跟踪）
+
+模块引擎【导入接口替换】+【导入进度接口替换】可实现实时进度提示。
+
+### 导入接口（替换默认导入）
+
+```javascript
+if (!V8.Param.TableId) {
+  return { Code: 0, Msg: '必须指定 TableId 标记当前导入哪张表' };
+}
+
+var importingKey = 'Microi:' + V8.OsClient + ':ImportTableDataStart:' + V8.Param.TableId;
+var stepKey      = 'Microi:' + V8.OsClient + ':ImportTableDataStep:'  + V8.Param.TableId;
+
+// 防止重复导入
+if (V8.Cache.Get(importingKey) === '1') {
+  return { Code: 0, Msg: '有数据正在导入中，请稍后再试' };
+}
+V8.Cache.Set(importingKey, '1');
+
+var stepList = [];
+function pushStep(msg) {
+  stepList.push(DateNow('yyyy-MM-dd HH:mm:ss') + '：' + msg);
+  V8.Cache.Set(stepKey, JSON.stringify(stepList));
+}
+
+pushStep('正在读取文件数据...');
+
+// 解析 Excel
+var base64 = Object.values(V8.FilesByteBase64)[0];
+var parsed = V8.Office.ExcelToList({ FileByteBase64: base64, SheetIndex: 0 });
+if (parsed.Code !== 1) {
+  V8.Cache.Set(importingKey, '0');
+  pushStep('文件解析失败：' + parsed.Msg);
+  return parsed;
+}
+
+pushStep('已读取【' + parsed.Data.length + '】条数据');
+pushStep('已导入【0】条数据...');
+
+// 循环导入
+for (var i = 0; i < parsed.Data.length; i++) {
+  var row = parsed.Data[i];
+  // 字段映射 / 校验
+  row.AAA = 111;
+
+  var addResult = V8.FormEngine.AddFormData(V8.Param.TableName, row, V8.DbTrans);
+  if (addResult.Code !== 1) {
+    V8.Cache.Set(importingKey, '0');
+    pushStep('导入第 ' + (i + 1) + ' 条出错：' + addResult.Msg + '（已回滚）');
+    return { Code: 0, Msg: addResult.Msg };  // 平台自动回滚事务
+  }
+  // 覆盖最后一条进度
+  stepList[stepList.length - 1] = DateNow('yyyy-MM-dd HH:mm:ss') + '：已导入【' + (i + 1) + '】条';
+  V8.Cache.Set(stepKey, JSON.stringify(stepList));
+}
+
+pushStep('导入成功，已结束');
+V8.Cache.Set(importingKey, '0');
+return { Code: 1, Data: { Imported: parsed.Data.length } };
+```
+
+### 导入进度查询接口
+
+```javascript
+if (!V8.Param.TableId) return { Code: 0, Msg: '需要 TableId' };
+var stepStr = V8.Cache.Get('Microi:' + V8.OsClient + ':ImportTableDataStep:' + V8.Param.TableId);
+return { Code: 1, Data: stepStr ? JSON.parse(stepStr) : [] };
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-export-import-009 sha256=f1583c2154c79acea7445119be851654d0cec81620fe0c1f0fadeee90f330bbf -->
+## 接收并下载文件（HTTP 链接转 Excel）
+
+```javascript
+// 从 URL 下载图片插入 Excel 等场景
+var resp = V8.Http.GetResponse({
+  Url: 'https://static.itdos.com/path/file.png'
+});
+var bytes = resp.RawBytes;            // .NET byte[]
+var base64 = System.Convert.ToBase64String(bytes);
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-export-import-010 sha256=0df463f76ba60100c087364b48dab1886d1315b093577ea9485471b34a7a3f6c -->
+## 子表导入自动关联主表
+
+当单独导入 `TableChild` 子表时，Excel 经常没有主表 Id，只带项目编号、客户名称等业务字段。默认导入引擎支持通过子表控件配置批量反查主表，并自动补齐子表外键。
+
+本节只适用于“主表 1:N 子表”；单条独立记录关联应使用 `JoinForm`，不能把明细导入模型
+设计成 `JoinForm`。在主表 `TableChild` 字段的 `Config` 中配置，其中子表、菜单和外键
+位于 Config 根节点，导入选项位于 `Config.TableChild`：
+
+```json
+{
+  "TableChildTableId": "子表 diy_table.Id",
+  "TableChildSysMenuId": "子表 sys_menu.Id",
+  "TableChildSysMenuName": "项目成品清单",
+  "TableChildFkFieldName": "XiangmuId",
+  "TableChild": {
+    "PrimaryTableFieldName": "Id",
+    "ImportAutoFillFk": true,
+    "FieldRelations": [
+      ["Code", "XiangmuBM", true],
+      ["Name", "XiangmuMC"]
+    ]
+  }
+}
+```
+
+配置含义：
+
+- 根节点 `TableChildTableId` / `TableChildSysMenuId` / `TableChildFkFieldName` 必须是
+  回读后的真实子表、隐藏子菜单和子表物理外键，不能猜 Id，也不能放进内层
+  `Config.TableChild`。
+- `ImportAutoFillFk`：是否在导入子表时自动补齐 Config 根节点指定的
+  `TableChildFkFieldName`；默认建议开启。
+- `FieldRelations`：每项为 `[主表字段, 子表/Excel字段, 是否参与导入匹配]`。全部关系用于新增回写和导入回填；第三位为 `true` 的关系用于反查主表，多项为 `true` 时作为组合条件匹配。
+- 不要把所有回填关系都标为 `true`。例如 Excel 只保证有项目编号时，`["Code","XiangmuBM",true]` 负责匹配，`["Name","XiangmuMC"]` 只在找到主表后补名称。
+- 后端继续读取旧版 `ImportParentMatchFieldName` / `ImportChildMatchFieldName`、`ImportRelations`、`ImportBackfillFields` 和根节点 `TableChildCallbackField`；新版前端会合并去重为 `FieldRelations`，并在字段下次保存时清除旧键。
+
+运行规则：
+
+- 只有子表外键为空时才补齐；Excel 已传外键时不覆盖。
+- `FieldRelations` 回填只有在子表对应字段为空时才写入；Excel 已传该字段值时不覆盖。
+- 导入前按业务字段批量查询主表，避免逐行查询。
+- 从主表表单内、左右树形页面或 `V8.OpenAnyTable` 带主表条件打开子表后导入时，即使 Excel 没有匹配字段，也可以通过固定主表 Id 查询主表并回填子表外键和全部 `FieldRelations`。
+- 如果业务字段为空、主表找不到或匹配到多条主表，当前行不自动补齐，并写入导入进度/后台日志，避免错误关联。
+- 示例：项目主表 `xiangmuguanli.Code` 匹配用料清单 `yongliaoqqingdan.XiangmuBM`，自动写入 `yongliaoqqingdan.XiangmuID`。
+- 示例：项目主表 `xiangmuguanli.Name` 回填成品清单 `xiangmugoujianqd.XiangmuMC`，保证导入模板缺少项目名称列时列表仍显示正常。
+
+<!-- /microi-progressive:chunk -->

package/skills/v8-export-import/references/progressive-03-/345/256/211/345/205/250-/346/200/247/350/203/275/346/263/250/346/204/217.md

@@ -1,42 +1,42 @@
-# v8-export-import 详细参考 3
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=v8-export-import-011 sha256=13a671d4b3628e57bdac68f283af740c405faf3a004ded4dcfa13c638b341505 -->
-## 安全 / 性能注意
-
-- ❌ 不要在循环中逐条 `AddFormData` 而不传 `V8.DbTrans`：每条独立事务，性能差且部分失败会留脏数据
-- ✅ 传 `V8.DbTrans` 让所有插入在同一事务，失败自动回滚
-- ✅ 大文件（>1万行）建议拆批 `AddTableData` 批量插入
-- ✅ 校验字段长度、类型、必填，防脏数据
-- ✅ 接口引擎要返回文件，必须在配置中开启【响应文件】
-- ✅ 进度 Key 用 `Microi:${V8.OsClient}:Category:Key` 命名，区分租户
-
-### 复盘：应用包同步物理字段时直接 ALTER 导致安装异常
-
-- 触发场景：目标租户安装或升级应用包时，已有长文本配置超过来源包的 `varchar(N)` 长度，或历史数值字段仍以空字符串保存，`MODIFY COLUMN` 分别报 `Data too long`、`Incorrect integer value: ''`。
-- 根因：导入器把来源库物理字段定义直接覆盖到目标库，没有判断是否属于缩窄变更，也没有在文本转数值前兼容平台历史空值。
-- 通用规则：物理字段同步必须只扩宽、不缩窄；目标库已有更宽文本类型或更大整数类型时保留目标类型。文本转数值前仅可把空字符串规范为 `NULL`，发现非空非数字值必须中止该字段迁移并报告数量，禁止静默转为 `0` 或截断数据。只要导入日志存在异常，就不得写入“安装成功”的应用版本记录。
-- 自动化检查：准备“超长 JSON + 空字符串数值 + 非数字脏值”三类旧库样本，重复安装同一应用包；前两类应无异常且数据不丢失，第三类应明确失败且原数据保持不变。
-
-### 复盘：重复字段与业务 Key 改名破坏应用包幂等安装
-
-- 触发场景：应用包中同一张表出现两个同名字段时，第一次 `ADD COLUMN` 成功、第二次报 `Duplicate column name`；在线应用保留原 Id 但修改 `AppKey/MsKey` 后，目标库按新 Key 查不到记录，又用原 Id 执行 INSERT，报主键重复。
-- 根因：安装器只在阶段开始时读取一次物理字段快照，新增后没有更新；同时只按业务 Key 判断在线应用是否存在，没有优先按稳定 Id 对齐，也没有迁移旧 Key 关联的微服务和页面。
-- 通用规则：包内字段必须按 `TableId + lower(Name)` 去重，新增物理列后立刻更新内存快照；并发或历史残留造成的重复列错误需回查后按幂等跳过。在线应用、微服务及版本数据必须先按 Id、再按业务 Key 查找；Id 命中而 Key 变化时更新原记录并沿用原 Id，把关联页面统一迁移到新 Key，禁止再次 INSERT。
-- 自动化检查：构造“同表重复字段”和“固定 AppId、AppKey 从 old-key 改为 new-key”两个包，连续安装至少两次；每次都应 `Code=1`，物理列、应用、微服务均只有一条，所有页面引用新 Key 且保留原关联 Id。
-
-### 复盘：租户历史残留绕过 FormEngine 查询后触发主键和重命名冲突
-
-- 触发场景：同一应用包在平台主租户、平台子租户和客户独立部署中表现不同；字段导入报 `diy_field.PRIMARY` 重复，字段改名报目标物理列已存在，旧版微服务包还可能调用不存在的 ZIP 哈希函数。
-- 根因：导入器只用 FormEngine 判断记录是否存在，软删除、空 OsClient 或历史异常记录会被过滤，但物理主键仍在；字段重命名只判断元数据变化，没有在 DDL 前分别检查源列和目标列；修复只写入某个租户接口引擎，没有让全局升级器按导入器能力重新刷新。
-- 通用规则：元数据 UPSERT 必须在 FormEngine 未命中时直查物理主键；同一逻辑字段应恢复后更新，真正的 Id 冲突应生成目标 Id 并建立包内引用映射。执行 `CHANGE COLUMN` 前必须检查源列存在且目标列不存在，目标列已存在时按幂等跳过。导入器修复必须同时更新官方资源、目标租户和自动升级能力检测，禁止只依赖全局版本号。
-- 自动化检查：准备软删除主键、空租户主键、同表目标列已存在、旧导入器函数缺失四类租户快照；连续安装系统设置、首页数据包和含源码 ZIP 的微服务包两次，均应 `Code=1` 且版本记录只反映无异常安装。再把全局版本号设为高于修复版本、导入器降级，验证启动升级仍会按能力标记自动恢复导入器且不降低全局版本号。
-
-### 复盘：数据库空库导出日期区域化且导入器吞错导致延迟误报
-
-- 触发场景：空库 SQL 把 MySQL `datetime` 导出成 `05/12/2026 12:50:33` 等区域格式；导入器逐句执行时跳过或吞掉失败语句，后续初始化才误报“缺少默认 admin 用户”。
-- 根因：导出器只按 CLR 返回类型格式化，没有以 `information_schema.COLUMNS.DATA_TYPE` 为事实源；导入器把局部失败计数后仍返回成功，也没有在导入结束立即校验核心表和模板账号。
-- 通用规则：数据库转储必须按真实物理列类型格式化 `date/datetime/timestamp`，统一输出 ISO 日期；完整 SQL 导入任一语句失败必须整体失败并保留原始数据库错误，禁止吞错继续。导入完成后立即校验核心表和模板账号，后端读取最新发布包时优先直读对象存储，避免 CDN 长缓存返回旧包。
-- 自动化检查：制作并发布空库后校验 ZIP 哈希、SQL 中区域日期匹配数为 0、核心表和默认 `admin` 存在；再从真实注册页创建新租户，并使用新租户 `admin` 的初始密码登录一次，不能只验证发布任务或租户记录返回成功。
-<!-- /microi-progressive:chunk -->
+# v8-export-import 详细参考 3
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=v8-export-import-011 sha256=13a671d4b3628e57bdac68f283af740c405faf3a004ded4dcfa13c638b341505 -->
+## 安全 / 性能注意
+
+- ❌ 不要在循环中逐条 `AddFormData` 而不传 `V8.DbTrans`：每条独立事务，性能差且部分失败会留脏数据
+- ✅ 传 `V8.DbTrans` 让所有插入在同一事务，失败自动回滚
+- ✅ 大文件（>1万行）建议拆批 `AddTableData` 批量插入
+- ✅ 校验字段长度、类型、必填，防脏数据
+- ✅ 接口引擎要返回文件，必须在配置中开启【响应文件】
+- ✅ 进度 Key 用 `Microi:${V8.OsClient}:Category:Key` 命名，区分租户
+
+### 复盘：应用包同步物理字段时直接 ALTER 导致安装异常
+
+- 触发场景：目标租户安装或升级应用包时，已有长文本配置超过来源包的 `varchar(N)` 长度，或历史数值字段仍以空字符串保存，`MODIFY COLUMN` 分别报 `Data too long`、`Incorrect integer value: ''`。
+- 根因：导入器把来源库物理字段定义直接覆盖到目标库，没有判断是否属于缩窄变更，也没有在文本转数值前兼容平台历史空值。
+- 通用规则：物理字段同步必须只扩宽、不缩窄；目标库已有更宽文本类型或更大整数类型时保留目标类型。文本转数值前仅可把空字符串规范为 `NULL`，发现非空非数字值必须中止该字段迁移并报告数量，禁止静默转为 `0` 或截断数据。只要导入日志存在异常，就不得写入“安装成功”的应用版本记录。
+- 自动化检查：准备“超长 JSON + 空字符串数值 + 非数字脏值”三类旧库样本，重复安装同一应用包；前两类应无异常且数据不丢失，第三类应明确失败且原数据保持不变。
+
+### 复盘：重复字段与业务 Key 改名破坏应用包幂等安装
+
+- 触发场景：应用包中同一张表出现两个同名字段时，第一次 `ADD COLUMN` 成功、第二次报 `Duplicate column name`；在线应用保留原 Id 但修改 `AppKey/MsKey` 后，目标库按新 Key 查不到记录，又用原 Id 执行 INSERT，报主键重复。
+- 根因：安装器只在阶段开始时读取一次物理字段快照，新增后没有更新；同时只按业务 Key 判断在线应用是否存在，没有优先按稳定 Id 对齐，也没有迁移旧 Key 关联的微服务和页面。
+- 通用规则：包内字段必须按 `TableId + lower(Name)` 去重，新增物理列后立刻更新内存快照；并发或历史残留造成的重复列错误需回查后按幂等跳过。在线应用、微服务及版本数据必须先按 Id、再按业务 Key 查找；Id 命中而 Key 变化时更新原记录并沿用原 Id，把关联页面统一迁移到新 Key，禁止再次 INSERT。
+- 自动化检查：构造“同表重复字段”和“固定 AppId、AppKey 从 old-key 改为 new-key”两个包，连续安装至少两次；每次都应 `Code=1`，物理列、应用、微服务均只有一条，所有页面引用新 Key 且保留原关联 Id。
+
+### 复盘：租户历史残留绕过 FormEngine 查询后触发主键和重命名冲突
+
+- 触发场景：同一应用包在平台主租户、平台子租户和客户独立部署中表现不同；字段导入报 `diy_field.PRIMARY` 重复，字段改名报目标物理列已存在，旧版微服务包还可能调用不存在的 ZIP 哈希函数。
+- 根因：导入器只用 FormEngine 判断记录是否存在，软删除、空 OsClient 或历史异常记录会被过滤，但物理主键仍在；字段重命名只判断元数据变化，没有在 DDL 前分别检查源列和目标列；修复只写入某个租户接口引擎，没有让全局升级器按导入器能力重新刷新。
+- 通用规则：元数据 UPSERT 必须在 FormEngine 未命中时直查物理主键；同一逻辑字段应恢复后更新，真正的 Id 冲突应生成目标 Id 并建立包内引用映射。执行 `CHANGE COLUMN` 前必须检查源列存在且目标列不存在，目标列已存在时按幂等跳过。导入器修复必须同时更新官方资源、目标租户和自动升级能力检测，禁止只依赖全局版本号。
+- 自动化检查：准备软删除主键、空租户主键、同表目标列已存在、旧导入器函数缺失四类租户快照；连续安装系统设置、首页数据包和含源码 ZIP 的微服务包两次，均应 `Code=1` 且版本记录只反映无异常安装。再把全局版本号设为高于修复版本、导入器降级，验证启动升级仍会按能力标记自动恢复导入器且不降低全局版本号。
+
+### 复盘：数据库空库导出日期区域化且导入器吞错导致延迟误报
+
+- 触发场景：空库 SQL 把 MySQL `datetime` 导出成 `05/12/2026 12:50:33` 等区域格式；导入器逐句执行时跳过或吞掉失败语句，后续初始化才误报“缺少默认 admin 用户”。
+- 根因：导出器只按 CLR 返回类型格式化，没有以 `information_schema.COLUMNS.DATA_TYPE` 为事实源；导入器把局部失败计数后仍返回成功，也没有在导入结束立即校验核心表和模板账号。
+- 通用规则：数据库转储必须按真实物理列类型格式化 `date/datetime/timestamp`，统一输出 ISO 日期；完整 SQL 导入任一语句失败必须整体失败并保留原始数据库错误，禁止吞错继续。导入完成后立即校验核心表和模板账号，后端读取最新发布包时优先直读对象存储，避免 CDN 长缓存返回旧包。
+- 自动化检查：制作并发布空库后校验 ZIP 哈希、SQL 中区域日期匹配数为 0、核心表和默认 `admin` 存在；再从真实注册页创建新租户，并使用新租户 `admin` 的初始密码登录一次，不能只验证发布任务或租户记录返回成功。
+<!-- /microi-progressive:chunk -->