@microi.net/cli 5.3.8 → 5.4.0

package/skills/microi.v8.js

@@ -151,42 +151,59 @@ function deserializeUser(value) {
   return parseMaybeJson(value, null);
 }
 
-// 吾码文件字段可能来自上传控件、HDFS 接口、字符串或 JSON 字符串，这里统一抽取可用路径。
-function extractUploadPath(value) {
-  if (!value) return '';
-  if (typeof value === 'object') {
-    const raw = Array.isArray(value) ? (value[0] || {}) : value;
-    if (typeof raw === 'string') return extractUploadPath(raw);
-    return raw.Url || raw.FileUrl || raw.FileURL || raw.PreviewUrl || raw.PreviewURL ||
-      raw.FullUrl || raw.Path || raw.FilePathName || raw.FilePath || raw.FullPath || '';
-  }
-
-  const text = String(value || '').trim();
-  if (!text) return '';
-  if ((text.startsWith('{') && text.endsWith('}')) || (text.startsWith('[') && text.endsWith(']'))) {
-    return extractUploadPath(parseMaybeJson(text, text));
-  }
-  return text;
-}
-
-function normalizeUploadValue(value) {
-  if (!value) return [];
-  if (Array.isArray(value)) return value.map(extractUploadPath).filter(Boolean);
-  if (typeof value === 'object') {
-    const path = extractUploadPath(value);
-    return path ? [path] : [];
-  }
+const uploadPathKeys = [
+  'Url', 'FileUrl', 'FileURL', 'PreviewUrl', 'PreviewURL', 'FullUrl',
+  'Path', 'FilePathName', 'FilePath', 'FullPath', 'Src', 'Href',
+  'url', 'fileUrl', 'previewUrl', 'fullUrl',
+  'path', 'filePathName', 'filePath', 'fullPath', 'src', 'href'
+];
+
+// 吾码文件字段可能是旧版绝对/相对字符串、新版单图对象、多图数组，
+// 也可能是上述结构序列化后的 JSON 字符串；这里统一抽取第一个有效路径。
+function extractUploadPath(value, depth = 0) {
+  if (depth > 6 || value === null || value === undefined) return '';
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const path = extractUploadPath(item, depth + 1);
+      if (path) return path;
+    }
+    return '';
+  }
+  if (typeof value === 'object') {
+    for (const key of uploadPathKeys) {
+      const path = extractUploadPath(value[key], depth + 1);
+      if (path) return path;
+    }
+    return '';
+  }
+
+  const text = String(value || '').trim();
+  if (!text) return '';
+  if ((text.startsWith('{') && text.endsWith('}')) || (text.startsWith('[') && text.endsWith(']'))) {
+    return extractUploadPath(parseMaybeJson(text, text), depth + 1);
+  }
+  return text;
+}
 
-  const text = String(value || '').trim();
-  if (!text) return [];
-  if ((text.startsWith('[') && text.endsWith(']')) || (text.startsWith('{') && text.endsWith('}'))) {
-    const parsed = parseMaybeJson(text, null);
-    if (Array.isArray(parsed)) return parsed.map(extractUploadPath).filter(Boolean);
-    const path = extractUploadPath(parsed);
-    return path ? [path] : [];
-  }
-  return [text];
-}
+function normalizeUploadEntries(value) {
+  if (!value) return [];
+  let parsed = value;
+  if (typeof parsed === 'string') {
+    const text = parsed.trim();
+    if (!text) return [];
+    if ((text.startsWith('[') && text.endsWith(']')) || (text.startsWith('{') && text.endsWith('}'))) {
+      parsed = parseMaybeJson(text, text);
+    }
+  }
+  const items = Array.isArray(parsed) ? parsed : [parsed];
+  return items.map((item) => ({ item, path: extractUploadPath(item) })).filter((entry) => entry.path);
+}
+
+// 旧调用方依赖路径数组，继续保持返回类型；需要 Name/Size/Id 等元数据时
+// 使用 normalizeUploadEntries，禁止把上传对象 String(...) 后再解析。
+function normalizeUploadValue(value) {
+  return normalizeUploadEntries(value).map((entry) => entry.path);
+}
 
 function normalizeUploadData(body) {
   const raw = Array.isArray(body && body.Data) ? (body.Data[0] || {}) : ((body && body.Data) || {});
@@ -940,7 +957,9 @@ export function createMicroiV8(options = {}) {
     if (!picked || isBlockedAsset(picked)) return '';
     if (/^(https?:|data:|blob:|file:)/i.test(picked)) return picked;
     if (isLocalPackagedAsset(picked)) return picked;
-    if (/^\/?file\//i.test(picked)) return joinUrl(config.apiBase, picked);
+    if (/^\/?file\//i.test(picked) || /^\/?micro-app\/v3(?:\/|$)/i.test(picked)) {
+      return joinUrl(config.apiBase, picked);
+    }
     if (/^\//.test(picked) || /^[a-z0-9_-]+\//i.test(picked)) return joinUrl(config.fileServer || config.apiBase, picked);
     return picked;
   }
@@ -1509,9 +1528,10 @@ export function createMicroiV8(options = {}) {
     resolveAvatarUrl: resolveFileUrl,
     resolveFileUrl,
     isBlockedAsset,
-    extractUploadPath,
-    normalizeUploadValue,
-    uploadFile,
+    extractUploadPath,
+    normalizeUploadValue,
+    normalizeUploadEntries,
+    uploadFile,
     getSafeArea,
     formatDate,
     toNumber,

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

@@ -11,13 +11,25 @@ description: Microi UniApp、H5、商城与 PC 页面中的上传图片、附件
 
 ## 先识别资源类型
 
-Microi 上传字段通常保存对象存储 Key 或相对路径，例如 `/demo/product/20260101/p1.jpg`。页面不能把相对路径直接交给 `<image>` / `<img>`，也不能一律拼接 API Base。
+Microi 上传字段存在四种必须长期兼容的存储形态，不能假设字段一定是字符串：
+
+| 存储形态 | 示例 | 兼容要求 |
+|---|---|---|
+| 旧版绝对地址字符串 | `https://cdn.example.com/a.png` | 校验协议和允许域名后原样使用，禁止再次拼接 `FileServer` |
+| 旧版相对路径字符串 | `/tenant/a.png` | 仅此类纯相对对象 Key 拼接当前租户 `FileServer` |
+| 新版单图对象 | `{ FilePathName:'/tenant/a.png', Name:'a.png' }` | 提取路径字段；保留对象的名称、大小、Id 等元数据，不得把整个对象转成字符串 |
+| 新版多图数组 | `[{ FilePathName:'/tenant/a.png' }, ...]` | 逐项解析并保持原顺序；单图展示取第一个有效路径，多图展示返回全部有效项 |
+
+数据库或接口还可能返回上述对象/数组的 JSON 字符串，解析器也必须兼容。标准路径键按以下顺序识别：`Url`、`FileUrl`、`FileURL`、`PreviewUrl`、`PreviewURL`、`FullUrl`、`Path`、`FilePathName`、`FilePath`、`FullPath`、`Src`、`Href`，并兼容相应 camelCase 键。
+
+页面不能把相对路径直接交给 `<image>` / `<img>`，也不能一律拼接 API Base。项目已使用 `microi.v8.js` 时，优先直接复用 `V8.extractUploadPath`、返回路径数组的 `V8.normalizeUploadValue`、保留 `{ item, path }` 元数据的 `V8.normalizeUploadEntries`、`V8.assetUrl` / `V8.resolveAssetUrl` 和 `V8.resolveFileUrl`，不得在业务页面另造一套不完整的解析规则。
 
 | 类型 | 处理方式 |
 |---|---|
 | 已允许的 `https://` 绝对地址 | 校验协议和允许域名后使用 |
 | 公有对象存储相对路径 | 拼接当前租户 `FileServer` |
 | `/file/...` 平台本地文件路由 | 拼接当前 API Base |
+| `/micro-app/v3/...` 应用稳定解析路由 | 拼接当前 API Base；这是动态指针路由，不是 HDFS 对象 Key，禁止拼接 `FileServer` |
 | 私有对象 | 后端鉴权后签发短期 URL，前端只使用临时 URL |
 | `blob:` | 仅用于本页创建且能及时 `revokeObjectURL` 的预览 |
 | `data:` | 仅允许经过大小和 MIME 校验的图片预览；禁止用于富文本任意 HTML |
@@ -26,15 +38,54 @@ Microi 上传字段通常保存对象存储 Key 或相对路径，例如 `/demo/
 
 ## 统一资源解析函数
 
-项目应在共享请求/资源模块中实现一个 `resolveAssetUrl`，所有页面复用同一逻辑：
+未使用 `microi.v8.js` 的项目，应在共享请求/资源模块中实现等价的“提取上传路径 + 解析资源 URL”两层函数，所有页面复用同一逻辑：
 
 ```js
+const uploadPathKeys = [
+  'Url', 'FileUrl', 'FileURL', 'PreviewUrl', 'PreviewURL', 'FullUrl',
+  'Path', 'FilePathName', 'FilePath', 'FullPath', 'Src', 'Href',
+  'url', 'fileUrl', 'previewUrl', 'fullUrl', 'path', 'filePathName', 'filePath', 'fullPath', 'src', 'href'
+];
+
+export function extractUploadPath(raw, depth = 0) {
+  if (depth > 4 || raw === null || raw === undefined) return '';
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      const path = extractUploadPath(item, depth + 1);
+      if (path) return path;
+    }
+    return '';
+  }
+  if (typeof raw === 'object') {
+    for (const key of uploadPathKeys) {
+      const path = extractUploadPath(raw[key], depth + 1);
+      if (path) return path;
+    }
+    return '';
+  }
+  const value = String(raw).trim();
+  if (!value) return '';
+  if (/^[{[]/.test(value)) {
+    try { return extractUploadPath(JSON.parse(value), depth + 1); } catch (_) {}
+  }
+  return value;
+}
+
+export function normalizeUploadValue(raw) {
+  let value = raw;
+  if (typeof value === 'string' && /^[{[]/.test(value.trim())) {
+    try { value = JSON.parse(value); } catch (_) {}
+  }
+  const items = Array.isArray(value) ? value : [value];
+  return items.map(item => ({ item, path: extractUploadPath(item) })).filter(entry => entry.path);
+}
+
 export function resolveAssetUrl(raw, {
   apiBase,
   fileServer,
   allowedHosts = []
 }) {
-  const value = String(raw || '').trim();
+  const value = extractUploadPath(raw);
   if (!value) return '';
 
   if (/^https:\/\//i.test(value)) {
@@ -44,6 +95,9 @@ export function resolveAssetUrl(raw, {
   if (/^blob:/i.test(value)) return value;
   if (/^data:image\/(png|jpeg|gif|webp);base64,/i.test(value)) return value;
   if (value.startsWith('/file/')) return `${apiBase.replace(/\/$/, '')}${value}`;
+  if (/^\/?micro-app\/v3(?:\/|$)/i.test(value)) {
+    return `${apiBase.replace(/\/$/, '')}/${value.replace(/^\/+/, '')}`;
+  }
 
   const relative = value.replace(/^\/+/, '');
   return `${fileServer.replace(/\/$/, '')}/${relative}`;
@@ -103,7 +157,9 @@ function imageUrl(path) {
 
 ## 验收清单
 
-- [ ] 公有对象、本地文件、私有对象、绝对 URL 的路径分支均有测试
+- [ ] 公有对象、本地文件、`/micro-app/v3` 动态路由、私有对象、绝对 URL 的路径分支均有测试
+- [ ] 绝对地址字符串、相对路径字符串、单图对象、多图数组及其 JSON 字符串均有测试
+- [ ] 单图从数组取第一个有效路径，多图保持原顺序；解析 URL 时不丢失或改写上传对象元数据
 - [ ] 切换两个 `OsClient` 后使用各自 `FileServer`，无跨租户路径或缓存复用
 - [ ] 私有 URL 越权、过期、篡改签名和复制到其它账号均失败
 - [ ] 网络面板中没有硬编码客户域名、真实租户或永久签名 URL