@microi.net/cli 6.2.1 → 6.2.3

package/skills/ui-design/references/progressive-07-/351/200/237/346/237/245-/344/273/216/345/244/264/346/220/255/345/273/272/344/270/200/344/270/252/347/247/273/345/212/250/347/253/257/351/241/265/351/235/242.md

@@ -1,207 +1,207 @@
-# ui-design 详细参考 7
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=ui-design-020 sha256=2efd631603aff04a45f251f0fc06ac83b39b2aebc1551b311920aac4ac6b9273 -->
-## 速查：从头搭建一个移动端页面
-
-```vue
-<template>
-  <div class="mci-mobile-page">
-    <!-- 顶部导航 -->
-    <header class="mci-navbar">
-      <h1 class="mci-navbar__title">{{ title }}</h1>
-    </header>
-
-    <!-- 主内容 -->
-    <main class="page-content">
-      <section
-        v-for="(item, i) in list"
-        :key="item.id"
-        class="mci-card mci-stagger-item"
-        :style="{ '--mci-index': i }"
-      >
-        <span class="mci-tag mci-tag--hot">HOT</span>
-        <h3>{{ item.name }}</h3>
-        <p class="mci-text-gradient price">{{ item.price }}</p>
-        <button class="mci-btn">立即查看</button>
-      </section>
-    </main>
-
-    <!-- 底部 Tabbar -->
-    <nav class="mci-tabbar">
-      <a class="mci-tabbar__item mci-tabbar__item--active"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-home" /></svg><span>首页</span></a>
-      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-message" /></svg><span>消息</span></a>
-      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-user" /></svg><span>我的</span></a>
-    </nav>
-  </div>
-</template>
-
-<style lang="scss" scoped>
-.page-content {
-  padding: var(--mci-space-4);
-  padding-bottom: calc(var(--mci-touch-target) + var(--mci-safe-bottom) + var(--mci-space-8));
-  display: flex;
-  flex-direction: column;
-  gap: var(--mci-space-4);
-}
-.price {
-  font-size: var(--mci-text-2xl);
-  font-weight: var(--mci-font-bold);
-}
-</style>
-```
-
-
----
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=ui-design-021 sha256=210d5091c308f562b56bce93b257a74ed1894cf0f15393f703149c05c3ac2584 -->
-## 🚨 移动端低代码项目落地踩坑（必读，2026.5）
-
-实战中频繁出现的 7 类问题，统一按以下规则处理。
-
-### 1. 路由前缀不要硬编码租户名
-
-- 错误：在 `manifest.json` 写死 `"router": { "base": "/fixed-tenant/" }`。
-- 正确：默认使用 `"router": { "base": "/" }`；租户由运行配置、`OsClient` 和请求头/参数确定。
-- 不要自行把租户名拼进 API 路径。平台接口使用 `/api/...`、`/apiengine/...` 等标准路由。
-
-### 2. tabBar 使用本地静态 PNG 图标
-
-- uni-app/微信小程序 tabBar 的 `iconPath`、`selectedIconPath` 使用项目内静态 PNG。
-- 不使用 emoji、字体图标、远程 URL；SVG 仅在目标端明确支持并已做真实设备验证时使用。
-- 普通态与选中态保持相同画布和轮廓，推荐 60×60 至 81×81 px，并验证深浅色背景可读性。
-
-### 3. 字号样式不要通配所有 `text`
-
-Scoped SCSS 中的 `.entry text { font-size: 40rpx; }` 会同时放大图标文字和子标签。图标、标题、说明必须使用独立 class：
-
-```scss
-.entry .entry-icon { font-size: 40rpx; }
-.entry .entry-label { font-size: 22rpx; }
-```
-
-### 4. 个人中心/详情入口按信息层级选布局
-
-- 高频资产、订单状态、服务入口适合 4～5 列网格。
-- 设置、安全、协议等低频入口适合纵向列表。
-- 单元格须有稳定触控区域、清晰标签和一致间距；不要为了追求密度牺牲可读性。
-
-### 5. 每个可点击元素都要有反馈
-
-```scss
-.cell, .entry-item, .product-card, .zone-card {
-  position: relative;
-  transition: transform .2s ease, box-shadow .2s ease;
-}
-.cell:active, .entry-item:active {
-  transform: scale(.94);
-}
-@keyframes fadein-up {
-  from { opacity: 0; transform: translateY(16rpx); }
-  to { opacity: 1; transform: translateY(0); }
-}
-.animate-fadein { animation: fadein-up .45s ease both; }
-@media (prefers-reduced-motion: reduce) {
-  .animate-fadein { animation: none; }
-}
-```
-
-动效只表达状态，不承担业务完成事实；提交、支付、安装等动作仍以服务端返回和可恢复状态为准。
-
-### 6. 品牌名和 Logo 的用户可见位置保持一致
-
-同步检查 `manifest.json` 的 `name/h5.title`、`pages.json` 的导航标题、登录/注册/首页品牌区、空状态和分享标题。控制台中的技术标识可保留，但用户可见文案必须统一。
-
-### 7. 接口地址由标准引擎工具维护
-
-- `microi_create_engine`/`microi_upsert_engine` 会维护 `ApiEngineKey`、`ApiAddress` 和路由缓存。
-- 写入超时先用标准 get/list 工具回读，不得立即重复创建。
-- 禁止通过手工 SQL、直接修改 `sys_apiengine` 或自行拼 Redis Key 修补路由；这会绕过租户、审计、缓存失效和控制面权限。
-- 长任务使用后台任务并持久化进度；普通接口写入后以远端回读为最终依据。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=ui-design-022 sha256=8f8a9a69e2816682ac2b6a26d932c23240c477191d4f3029a821dafe23250c7b -->
-## 🔗 关联字段：保存真实 Id，界面展示可读标签
-
-关联字段的数据库事实值通常是 `XxxId`。表单使用 `JoinForm`、`OpenTable` 或带数据源的 `Select` 显示名称，`SelectSaveField` 保存 `Id`，`SelectLabel` 展示名称。不要因为列表默认显示 Id，就强制所有业务表冗余一对可编辑的 `XxxId/XxxName` 字段。
-
-### Select 数据源示例
-
-```json
-{
-  "DataSource": "Sql",
-  "Sql": "select Id, Name from mall_category where Name like '%$Keyword$%' limit 0,20",
-  "SelectLabel": "Name",
-  "SelectSaveField": "Id",
-  "SelectSaveFormat": "Text",
-  "EnableSearch": true,
-  "DataSourceSqlRemote": true
-}
-```
-
-- `$Keyword$` 是平台数据源占位符，不要把浏览器输入直接拼进任意 SQL。
-- 关联表、字段和数据源必须来自当前租户，并受当前表单/菜单的授权与数据范围约束。
-- 大表使用远程搜索和分页，不一次性把全表拉到浏览器。
-- 列表展示名称优先配置 Join/模块关联字段或受控数据源，不把隐藏 Id 暴露给用户。
-
-### 什么时候增加 `XxxName` 快照字段
-
-只有在业务明确要求“保存当时名称”、离线展示、历史审计或高频报表需要时才增加 `XxxName`。它是快照/冗余字段，不是外键事实源，并遵守：
-
-1. 后端 SubmitBefore/接口引擎在同一事务内根据 `XxxId` 校验并写入名称。
-2. 前端 V8 可以即时回显，但不能作为唯一一致性保障。
-3. 关联名称后续变化时，先明确历史快照是否应随之更新。
-4. 批量回填必须参数化、可恢复、可幂等，并经过明确写入确认。
-
-### MCP 建模流程
-
-1. 先用 `microi_get_db_schema` 获取真实表和字段。
-2. 使用 `microi_build_field_config` 生成 JoinForm/OpenTable/Select 配置。
-3. 使用 `microi_add_field` 或 `microi_update_field` 写入字段。
-4. 修改 KeyValue/Config 后回读 `microi_get_field_list`，并执行 `microi_refresh_schema_cache`。
-5. 在真实菜单下验证普通角色能看到标签，但不能借数据源越权读取其它表或行。
----
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=ui-design-023 sha256=9767f1e46e8491d63a9f9a00fadef9125d124841a79141f07dd7e4529da3bc25 -->
-## 表单布局规范（Column）
-
-> 平台默认设计标准：所有 `diy_table` **应使用双列布局** (`Column = 2`)，更紧凑现代，符合主流后台 SaaS 视觉密度。
-
-### 创建表时
-
-```jsonc
-microi_create_table {
-  "name": "Crm_Customer",
-  "description": "客户",
-  "column": 2     // ✅ 默认就是 2，无需显式传，但推荐写明
-}
-```
-
-### 修复存量表（一次性把所有 `Column=null` 改成 2）
-
-```jsonc
-microi_update_table {
-  "name": "Crm_Customer",
-  "column": 2
-}
-```
-
-### 何时使用 Column=1（单列）
-
-- 工作流审批表单（字段少且需要专注）
-- 移动端优先表单（手机宽度不够双列）
-- 含大量富文本/长文本字段的内容编辑表
-
-### 何时使用 Column=3（三列）
-
-- 字段≥18 的"基础档案"类大表（员工、商品 SKU、设备清单）
-- 桌面分辨率≥1920px 的内部管理后台
-
-> 修改 `Column` 后会自动清缓存（`microi_update_table` 后端走 `UptFormData('diy_table')` + 主动 `RefreshSchemaCache`），前端硬刷新（Ctrl+Shift+R）即可看到效果。
-
----
-
-<!-- /microi-progressive:chunk -->
+# ui-design 详细参考 7
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-020 sha256=8af48a2af341cf338cbb3937def060827f39f40795330c2cca7c342897f48ce7 -->
+## 速查：从头搭建一个移动端页面
+
+```vue
+<template>
+  <div class="mci-mobile-page">
+    <!-- 顶部导航 -->
+    <header class="mci-navbar">
+      <h1 class="mci-navbar__title">{{ title }}</h1>
+    </header>
+
+    <!-- 主内容 -->
+    <main class="page-content">
+      <section
+        v-for="(item, i) in list"
+        :key="item.id"
+        class="mci-card"
+        :style="{ '--mci-index': i }"
+      >
+        <span class="mci-tag mci-tag--hot">HOT</span>
+        <h3>{{ item.name }}</h3>
+        <p class="price">{{ item.price }}</p>
+        <button class="mci-btn">立即查看</button>
+      </section>
+    </main>
+
+    <!-- 底部 Tabbar -->
+    <nav class="mci-tabbar">
+      <a class="mci-tabbar__item mci-tabbar__item--active"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-home" /></svg><span>首页</span></a>
+      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-message" /></svg><span>消息</span></a>
+      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-user" /></svg><span>我的</span></a>
+    </nav>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.page-content {
+  padding: var(--mci-space-4);
+  padding-bottom: calc(var(--mci-touch-target) + var(--mci-safe-bottom) + var(--mci-space-3));
+  display: flex;
+  flex-direction: column;
+  gap: var(--mci-space-3);
+}
+.price {
+  font-size: var(--mci-text-2xl);
+  font-weight: var(--mci-font-bold);
+}
+</style>
+```
+
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-021 sha256=8a8884b0b064e7805cd03d904541b12da4539e73172d31f00d32c1ecfaee32f6 -->
+## 🚨 移动端低代码项目落地踩坑（必读，2026.5）
+
+实战中频繁出现的 7 类问题，统一按以下规则处理。
+
+### 1. 路由前缀不要硬编码租户名
+
+- 错误：在 `manifest.json` 写死 `"router": { "base": "/fixed-tenant/" }`。
+- 正确：默认使用 `"router": { "base": "/" }`；租户由运行配置、`OsClient` 和请求头/参数确定。
+- 不要自行把租户名拼进 API 路径。平台接口使用 `/api/...`、`/apiengine/...` 等标准路由。
+
+### 2. tabBar 使用本地静态 PNG 图标
+
+- uni-app/微信小程序 tabBar 的 `iconPath`、`selectedIconPath` 使用项目内静态 PNG。
+- 不使用 emoji、字体图标、远程 URL；SVG 仅在目标端明确支持并已做真实设备验证时使用。
+- 普通态与选中态保持相同画布和轮廓，推荐 60×60 至 81×81 px，并验证深浅色背景可读性。
+
+### 3. 字号样式不要通配所有 `text`
+
+Scoped SCSS 中的 `.entry text { font-size: 40rpx; }` 会同时放大图标文字和子标签。图标、标题、说明必须使用独立 class：
+
+```scss
+.entry .entry-icon { font-size: 40rpx; }
+.entry .entry-label { font-size: 22rpx; }
+```
+
+### 4. 个人中心/详情入口按信息层级选布局
+
+- 高频资产、订单状态、服务入口适合 4～5 列网格。
+- 设置、安全、协议等低频入口适合纵向列表。
+- 单元格须有稳定触控区域、清晰标签和一致间距；不要为了追求密度牺牲可读性。
+
+### 5. 每个可点击元素都要有反馈
+
+```scss
+.cell, .entry-item, .product-card, .zone-card {
+  position: relative;
+  transition: transform .2s ease, box-shadow .2s ease;
+}
+.cell:active, .entry-item:active {
+  transform: scale(.94);
+}
+@keyframes fadein-up {
+  from { opacity: 0; transform: translateY(16rpx); }
+  to { opacity: 1; transform: translateY(0); }
+}
+.animate-fadein { animation: fadein-up .45s ease both; }
+@media (prefers-reduced-motion: reduce) {
+  .animate-fadein { animation: none; }
+}
+```
+
+动效只表达状态，不承担业务完成事实；提交、支付、安装等动作仍以服务端返回和可恢复状态为准。
+
+### 6. 品牌名和 Logo 的用户可见位置保持一致
+
+同步检查 `manifest.json` 的 `name/h5.title`、`pages.json` 的导航标题、登录/注册/首页品牌区、空状态和分享标题。控制台中的技术标识可保留，但用户可见文案必须统一。
+
+### 7. 接口地址由标准引擎工具维护
+
+- `microi_create_engine`/`microi_upsert_engine` 会维护 `ApiEngineKey`、`ApiAddress` 和路由缓存。
+- 写入超时先用标准 get/list 工具回读，不得立即重复创建。
+- 禁止通过手工 SQL、直接修改 `sys_apiengine` 或自行拼 Redis Key 修补路由；这会绕过租户、审计、缓存失效和控制面权限。
+- 长任务使用后台任务并持久化进度；普通接口写入后以远端回读为最终依据。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-022 sha256=4962a1ec7bc49ae1a2706c58fb6f929304ca254e3fd4d8b626fefbc17067bce2 -->
+## 🔗 关联字段：保存真实 Id，界面展示可读标签
+
+关联字段的数据库事实值通常是 `XxxId`。表单使用 `JoinForm`、`OpenTable` 或带数据源的 `Select` 显示名称，`SelectSaveField` 保存 `Id`，`SelectLabel` 展示名称。不要因为列表默认显示 Id，就强制所有业务表冗余一对可编辑的 `XxxId/XxxName` 字段。
+
+### Select 数据源示例
+
+```json
+{
+  "DataSource": "Sql",
+  "Sql": "select Id, Name from mall_category where Name like '%$Keyword$%' limit 0,20",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "SelectSaveFormat": "Text",
+  "EnableSearch": true,
+  "DataSourceSqlRemote": true
+}
+```
+
+- `$Keyword$` 是平台数据源占位符，不要把浏览器输入直接拼进任意 SQL。
+- 关联表、字段和数据源必须来自当前租户，并受当前表单/菜单的授权与数据范围约束。
+- 大表使用远程搜索和分页，不一次性把全表拉到浏览器。
+- 列表展示名称优先配置 Join/模块关联字段或受控数据源，不把隐藏 Id 暴露给用户。
+
+### 什么时候增加 `XxxName` 快照字段
+
+只有在业务明确要求“保存当时名称”、离线展示、历史审计或高频报表需要时才增加 `XxxName`。它是快照/冗余字段，不是外键事实源，并遵守：
+
+1. 后端 SubmitBefore/接口引擎在同一事务内根据 `XxxId` 校验并写入名称。
+2. 前端 V8 可以即时回显，但不能作为唯一一致性保障。
+3. 关联名称后续变化时，先明确历史快照是否应随之更新。
+4. 批量回填必须参数化、可恢复、可幂等，并经过明确写入确认。
+
+### MCP 建模流程
+
+1. 先用 `microi_get_db_schema` 获取真实表和字段。
+2. 使用 `microi_build_field_config` 生成 JoinForm/OpenTable/Select 配置。
+3. 使用 `microi_add_field` 或 `microi_update_field` 写入字段。
+4. 修改 KeyValue/Config 后回读 `microi_get_field_list`，并执行 `microi_refresh_schema_cache`。
+5. 在真实菜单下验证普通角色能看到标签，但不能借数据源越权读取其它表或行。
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-023 sha256=1c731f6915dae4de788e84af3f6a59cf5d116a4de1f9ca5541f13b55110521ca -->
+## 表单布局规范（Column）
+
+> 平台默认设计标准：所有 `diy_table` **应使用双列布局** (`Column = 2`)，更紧凑现代，符合主流后台 SaaS 视觉密度。
+
+### 创建表时
+
+```jsonc
+microi_create_table {
+  "name": "Crm_Customer",
+  "description": "客户",
+  "column": 2     // ✅ 默认就是 2，无需显式传，但推荐写明
+}
+```
+
+### 修复存量表（一次性把所有 `Column=null` 改成 2）
+
+```jsonc
+microi_update_table {
+  "name": "Crm_Customer",
+  "column": 2
+}
+```
+
+### 何时使用 Column=1（单列）
+
+- 工作流审批表单（字段少且需要专注）
+- 移动端优先表单（手机宽度不够双列）
+- 含大量富文本/长文本字段的内容编辑表
+
+### 何时使用 Column=3（三列）
+
+- 字段≥18 的"基础档案"类大表（员工、商品 SKU、设备清单）
+- 桌面分辨率≥1920px 的内部管理后台
+
+> 修改 `Column` 后会自动清缓存（`microi_update_table` 后端走 `UptFormData('diy_table')` + 主动 `RefreshSchemaCache`），前端硬刷新（Ctrl+Shift+R）即可看到效果。
+
+---
+
+<!-- /microi-progressive:chunk -->

package/skills/uniapp-mall-assets/SKILL.md

@@ -29,13 +29,21 @@ Microi 上传字段存在四种必须长期兼容的存储形态，不能假设
 | 已允许的 `https://` 绝对地址 | 校验协议和允许域名后使用 |
 | 公有对象存储相对路径 | 拼接当前租户 `FileServer` |
 | `/file/...` 平台本地文件路由 | 拼接当前 API Base |
-| `/micro-app/v3/...` 应用稳定解析路由 | 拼接当前 API Base；这是动态指针路由，不是 HDFS 对象 Key，禁止拼接 `FileServer` |
+| `/micro-app/{tenantLower}/{AppKey}/index.html` 当前公开体验入口 | 应用体验专用 authority resolver 生成可信 API Base 下的绝对 URL；直接返回已提交 HTML，地址栏不跳到 typed v3、CDN/NAS 或版本目录；不能拼 `FileServer` |
+| `/micro-app/v3/...` 内部应用资产解析路由 | 拼接当前 API Base；这是内部动态指针协议，不是 HDFS 对象 Key，也不作为用户当前体验链接 |
 | 私有对象 | 后端鉴权后签发短期 URL，前端只使用临时 URL |
 | `blob:` | 仅用于本页创建且能及时 `revokeObjectURL` 的预览 |
 | `data:` | 仅允许经过大小和 MIME 校验的图片预览；禁止用于富文本任意 HTML |
 
 `FileServer` 是对象存储/CDN 地址，不等同于 API 服务。租户切换时必须使用当前 `OsClient` 的运行期配置，禁止在源码中写死域名或租户目录。
 
+当前体验 URL 的租户段使用可信连接 OsClient 小写，AppKey 与公开范围取同源权威应用记录。显式历史版本使用已回读的实际 `{可信FileServer}/{tenantLower}/micro-app/{AppKey}/{exactPublishedVersion}/index.html`，保留 FileServer 路径前缀；数字 `CurrentVersion` 不能推算语义版本。旧 `/{version}/...` 短 API 或 `?version=` 不是通用 V3 历史读取协议。签名 URL、历史地址、私有或未知公开性的入口不改写成 current；数据库相对 `PreviewUrl/PublicPublishPath` 与 typed `StableResolverPath` 保持内部协议，不为展示批量改表。
+
+应用导航与上传资源解析分开：官网、工作台和商城的专用体验 resolver 先按权威应用身份生成绝对 API URL；通用 `V8.assetUrl/resolveAssetUrl` 不承担相对短入口识别，不能把相对短入口直接交给它或声称本次已升级 SDK。其既有绝对 HTTP(S) 地址分支继续保留原地址；下方示例用于上传资源，不代替应用体验入口决策。
+
+- 历史配置的原始 `FileServer` 主地址兼容 HTTP/HTTPS。公有相对路径的兼容回退保留协议、端口和路径前缀，不强制升级 HTTPS，也不改拼 API Base；仅此原始主地址允许 HTTP。备用绑定、源地址映射和别名仍限定 HTTPS 并通过原验证，私有路径、带凭据地址及危险协议的限制不变。
+- 公共解析器以 `Microi.Client/src/utils/public-resource-router.mjs` 为单一事实源；修改后运行 `node microi.skills/scripts/sync-public-resource-router.mjs --write` 同步三份 SDK 生成块并执行 `--check`。PlatformService 的 SDK 属于其源码输入，变更后必须按原生 Bundle 入口重建及更新四个所属应用包，不能只更新 PC 或手改嵌入 Base64。
+
 ### 跨端上传字段的形态与桶属性
 
 - 控件读取嵌套 `Config.ImgUpload/FileUpload.Multiple` 与 `MaxCount`；`Multiple=false` 保存单图对象，不能因数量上限或默认九图值而保存数组。已有单元素数组在单图控件中按第一项读取，不在查看时回写业务数据。
@@ -168,7 +176,7 @@ function imageUrl(path) {
 
 ## 验收清单
 
-- [ ] 公有对象、本地文件、`/micro-app/v3` 动态路由、私有对象、绝对 URL 的路径分支均有测试
+- [ ] 公有对象、本地文件、精确 API 固定入口、`/micro-app/v3` 内部动态路由、私有对象、绝对 URL 的路径分支均有测试；历史与签名地址不被规范化为 current
 - [ ] 绝对地址字符串、相对路径字符串、单图对象、多图数组及其 JSON 字符串均有测试
 - [ ] 单图从数组取第一个有效路径，多图保持原顺序；解析 URL 时不丢失或改写上传对象元数据
 - [ ] 切换两个 `OsClient` 后使用各自 `FileServer`，无跨租户路径或缓存复用

package/skills/v8-crud-api/SKILL.md

@@ -38,12 +38,13 @@ Microi.net.Api 普通本地启动不要额外设置 `ASPNETCORE_ENVIRONMENT` / `
 生成接口引擎代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；跨表事务、权限校验、状态机、金额/库存计算、复杂 `_Where` 条件等代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-crud-api-001 sha256=93eb45145fcf6849628c73e51f8ae5e450532b425bf763d63587a44dc84bd7aa -->
+<!-- microi-progressive:chunk id=v8-crud-api-001 sha256=6aab6dc9a9cefda0938f29ca5f13c85c5c86ccfde52b9f31e8510465fc56a730 -->
 ## 核心规则
 
 - 接口引擎文件是纯 JavaScript（Jint 引擎，非 Node.js）
 - 全局对象 `V8` 是所有后端能力的入口
 - 通过 `V8.Param` 获取前端传入的参数（URL参数 / form-data / payload-json）
+- 业务接口禁止接收客户端 SQL 并执行，包含改名/嵌套/编码的整段 SQL、表列及 WHERE/JOIN/ORDER BY 片段。SQL 结构必须是可信服务端固定代码或白名单定义；前端只传有界业务值或有限 queryKey，动态值用 `_Where` / `.AddInParameter`。参数绑定不保护不可信 SQL 正文，不能以只读、仅 SELECT 或管理员登录代替此规则。受权设计期 SQL 配置/数据库管理 MCP 不等于业务接口可透传 SQL。发布前按 `../v8-sql-query/SKILL.md` 检查请求到执行点的数据流和拒绝负例。
 - 严格业务字段白名单先逐项排除本入口支持的宿主传输字段：固定 `ApiEngineKey / ApiAddress`、调用类型、设备和 HTTP 请求元数据；不得把整个下划线前缀视为安全字段，不解析 `_RawBody` 重写动作，也不从传输字段取授权。历史调试器的 `TestParam1` 仅兼容 null/undefined、最多 200 字符的字符串、有限数字或布尔值并立即丢弃；对象、数组、超长值和其它未知字段继续拒绝。真实 HTTP 与内部调用都须验收，普通岗位无初始化配置副作用，权限继续读取权威当前用户与目标租户。
 - `V8.Param` 中嵌套 JSON 的 `JObject/JArray` 可能是 Jint 宿主对象，`Array.isArray` 不一定成立。需要严格数组、布尔或结构校验时，在业务入口对有界业务参数使用 `JSON.parse(JSON.stringify(V8.Param || {}))` 转为纯 JSON，再执行原字段白名单、类型、大小与权限校验；不能把只有 `length` 的对象当数组。只规范化业务参数，不复制或信任客户端身份、`V8.CurrentUser`、`V8.DbTrans` 或 `V8.WF`；大文件继续使用专用文件通道。验收须同时覆盖真实 HTTP 宿主集合和离线 JavaScript 数组。
 - 通过 `V8.CurrentUser` 获取当前登录用户信息

package/skills/v8-explorer-tree/SKILL.md

@@ -28,7 +28,7 @@ MCP 后端实现位于 `Microi.Server/Microi.MCP/`：`V8Engine/V8McpLogic*.cs`
 | 按钮显隐 | `<按钮Name>_显隐判断（<按钮Id>）` | `指派_显隐判断（01K3X...）.js` |
 | 按钮分类目录 | `<按钮类型中文>（<EnglishField>）` | `[行]更多按钮（MoreBtns）/` |
 
-### 0.1 7 类表单 V8 事件中文名（以 `diy_table` 对应 `diy_field.Label` 为准）
+### 0.1 表单 V8 事件中文名（以 `diy_table` 对应 `diy_field.Label` 为准）
 
 | EventType | 中文名 |
 |-----------|--------|
@@ -40,6 +40,27 @@ MCP 后端实现位于 `Microi.Server/Microi.MCP/`：`V8Engine/V8McpLogic*.cs`
 | OutFormV8 | 前端表单提交后V8事件 |
 | DataFilterV8 | 后端数据过滤V8事件 |
 
+日志、评论、版本还包括以下 12 个独立事件。它们同样位于表单 V8 事件目录，只有非空代码才落文件；
+保存使用标准事件接口和版本链，后端源码保持管理员设计期边界，不随普通表单返回。
+
+| EventType | 中文名 |
+|---|---|
+| DataLogBeforeClientV8 | 前端数据日志写入前V8事件 |
+| DataLogBeforeServerV8 | 后端数据日志写入前V8事件 |
+| DataLogAfterServerV8 | 后端数据日志写入后V8事件 |
+| DataLogAfterClientV8 | 前端数据日志写入后V8事件 |
+| DataCommentBeforeClientV8 | 前端数据评论写入前V8事件 |
+| DataCommentBeforeServerV8 | 后端数据评论写入前V8事件 |
+| DataCommentAfterServerV8 | 后端数据评论写入后V8事件 |
+| DataCommentAfterClientV8 | 前端数据评论写入后V8事件 |
+| DataVersionBeforeClientV8 | 前端数据版本写入前V8事件 |
+| DataVersionBeforeServerV8 | 后端数据版本写入前V8事件 |
+| DataVersionAfterServerV8 | 后端数据版本写入后V8事件 |
+| DataVersionAfterClientV8 | 前端数据版本写入后V8事件 |
+
+完整触发顺序、活动上下文、共享父事务和幂等回执规则见 `../v8-table-event/SKILL.md`。
+`DataFilterV8` 是 `ServerDataV8` 历史别名，写入时规范为真实属性，不能创建第二份事件。
+
 > 统一用“后端”，不要再生成“服务端”或“服务器端”可见目录/文件名。
 
 ### 0.2 4 类字段 V8 事件中文名