three-base 2.0.142 → 2.0.166

package/MktMesh/MktMesh.ts

@@ -991,8 +991,22 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
 
     // ───────────────────────── 导入 / 导出 ─────────────────────────
 
-    /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵） */
-    exportData(): MktMeshData {
+    /**
+     * ⭐ 项目名（皇上旨10-08 19:53「导出时图片地址改成 `{项目名称}/xxx.jpg`」）。
+     * 落盘时用它顶替 OSS 上传目录前缀（`three-base_upload/panorama/`），导入时据此还原。
+     * 消费方（编辑器）用 `setProjectName()` 注入；没注入时退化为「只剥域名」的纯相对形态。
+     */
+    projectName: string = "";
+
+    /** 注入项目名（导出 json 前调一次即可；导入时无须调——还原靠落盘地址自身的首段） */
+    setProjectName(name: string): void {
+        this.projectName = typeof name === "string" ? name : "";
+    }
+
+    /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
+     *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
+    exportData(projName?: string): MktMeshData {
+        const pn = typeof projName === "string" && projName ? projName : this.projectName;
         return {
             wallPoints: this.wallPoints.map((p) => ({ x: p.x, y: p.y, z: p.z })),
             wallHeight: this.wallHeight,
@@ -1001,19 +1015,22 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
             // 全景序号映射：每个三角面归属的全景全局序号（与 wallPoints 同几何拓扑绑定，随存档走）
             panoFaceMapping: this.panoFaceMapping.slice(),
             textures: this.textures.map((t) => ({
-                // ⭐ 10-08 旨：存档里只落**根相对路径**（域名在读 JavaScript 之外也用不上，还锁死环境）。
+// ⭐ 10-08 旨：存档里只落**相对路径**（域名在读 JavaScript 之外也用不上，还锁死环境）；
+            //   同日 18:46 旨「前面不要有 /」⇒ ⛔ 无前导 /；19:53 旨「改成 {项目名称}/xxx.jpg」
+                //   ⇒ OSS 上传目录前缀（`three-base_upload/panorama/`）整段顶掉，落成 `{项目名}/x_0.jpg`。
                 //   `stripAssetHost` 幂等 ⇒ 内存里已经是相对的不会出问题，旧存档的绝对地址也不会反复剥。
-                url: stripAssetHost(t.url),
+                url: stripAssetHost(t.url, pn),
                 name: t.name ?? "",
                 // 2026-09-20：导出 4 瓦片（顺序 [左上, 右上, 左下, 右下]）；旧数据无 tiles 时导空数组
-                tiles: (t.tiles && t.tiles.length ? t.tiles.map(stripAssetHost) : []) as string[],
+                tiles: (t.tiles && t.tiles.length ? t.tiles.map((u) => stripAssetHost(u, pn)) : []) as string[],
                 matrix: t.matrix.toArray(),
             })),
         };
     }
 
-    /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理 */
-    importData(data: MktMeshData): void {
+    /** 导入数据：重建墙体几何与纹理列表，并激活第一个纹理
+     *  @param projName 项目名（可选）——用于把落盘的 `{项目名}/x_0.jpg` 还原回真身OSS 地址 */
+    importData(data: MktMeshData, projName?: string): void {
         this.setWallPoints(data.wallPoints ?? [], {
             closed: data.wallClosed,
             height: data.wallHeight,
@@ -1023,16 +1040,20 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
         this.setWallSide(data.wallSide ?? "double");
         this.setTextures(
             (data.textures ?? []).map((t) => {
-                // ⭐ 10-08 旨的成对另一半：存档落的是根相对路径 ⇒ 进内存前在这里**唯一一处**补回域名，
+                // ⭐ 10-08 旨的成对另一半：存档落的是相对路径 ⇒ 进内存前在这里**唯一一处**补回域名，
                 //   下游（拼合器 / 预览 / UI `<img>`）拿到的仍是绝对地址 ⇒ 它们一行都不用改。
-                //   `absAssetUrl` 幂等 ⇒ 旧存档里已是绝对地址的（= 升级前存的）不会被拼成 `https://host/https://host/...`
-                const urlAbs = absAssetUrl(t.url as string);
+                //   · `absAssetUrl` 幂等 + **同时认旧存档的根相对形态** ⇒ 上午发布前存的那批
+                //     （`/three-base_upload/…`）不必重存也能正常加载，不会被拼成 `https://host/https://host/…`
+                //   · 19:53 旨后还要把 `{项目名}/x_0.jpg` **还原**成真身 OSS 地址（顶掉的上传目录要补回来），
+                //     否则 json 里的地址指不回原图（图片裂）。`pn` 取入参、回落 `setProjectName` 注入的那个。
+                const pn = typeof projName === "string" && projName ? projName : this.projectName;
+                const urlAbs = absAssetUrl(t.url as string, pn);
                 return {
                     url: urlAbs,
                     name: t.name ?? "",
                     // 2026-09-20：导入瓦片；缺省回退 [url]（旧存档整图占 1 格）——10-06 晚旨「只支持 32 张（横 8 × 竖 4）」后
                     // 该点走拼合器：整图缩在 1/32 格 + 其余 31 格涂灰，数据不全一眼可见（重传 32 片切片即修复）
-                    tiles: t.tiles && t.tiles.length ? t.tiles.map(absAssetUrl) : [urlAbs],
+                    tiles: t.tiles && t.tiles.length ? t.tiles.map((u) => absAssetUrl(u, pn)) : [urlAbs],
                     matrix: new Matrix4().fromArray(t.matrix),
                 };
             })

package/MktMesh/assetUrl.d.ts

@@ -1,35 +1,59 @@
-/**
- * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
- *
- * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
- *   存档 JSON 里只落**根相对路径**（`/three-base_upload/panorama/xxx_0.jpg`），换来两件事：
- *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
- *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
- *
- * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
- *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
- *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
- *
- * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
- *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
- *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
- *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
- *
- * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
- *    保持零依赖才能被测试单独转译真跑。
- */
-/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
-export declare const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
-/**
- * 剥掉本站域名 ⇒ 根相对路径。
- * - 已是根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
- * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `/a/b.jpg`
- * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `/`
- */
-export declare function stripAssetHost(url: string): string;
-/**
- * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
- * - 已是绝对 / blob / data ⇒ **原样返回**（幂等 ⇒ 旧存档进 `importData` 不会被二次拼接）
- * - `/a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
- */
-export declare function absAssetUrl(url: string): string;
+/**
+ * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
+ *
+ * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」；
+ *    同日 18:46 补充「图片路径要相对路径，**前面不要有 `/`**」⇒ 落盘形态最终定为
+ *   **纯相对路径**（`three-base_upload/panorama/xxx_0.jpg`，⛔ 无前导 `/`），换来两件事：
+ *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
+ *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
+ *   为什么连前导 `/` 都不留：站点部署在子路径 `/three-base/` 下，相对路径随 `<base href>`
+ *   一起解析，换部署位置仍指到同一张图；根相对 `/xxx` 会被钉死在域名根，放到子目录就 404。
+ *
+ * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
+ *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
+ *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
+ *
+ * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
+ *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
+ *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
+ *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
+ * ⚠️ **向后兼容**：`absAssetUrl` 同时认「纯相对」与「旧存档的根相对」两种形态
+ *   （`/a/b.jpg` 也补成绝对）⇒ 上午发布前存下的那些存档**不必重存**也能正常加载。
+ *
+ * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
+ *    保持零依赖才能被测试单独转译真跑。
+ */
+/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
+export declare const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
+/**
+ * 剥掉本站域名 ⇒ **纯相对路径**（⭐ 皇上旨10-08 18:46「图片路径要相对路径，前面不要有 "/"」）。
+ * @param projName 项目名。给了 ⇒ 落盘成 `{项目名}/文件名.jpg`（19:53 旨）；没给 ⇒ 落成 `文件名.jpg`。
+ * - 已是相对 / 根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
+ * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `a/b.jpg`（⛔ 不带前导 `/`）
+ * - `https://www.3dkeshihua.com/three-base_upload/panorama/x_0.jpg` ⇒ `x_0.jpg` 或 `{proj}/x_0.jpg`
+ * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `""`（空串：无路径可留）
+ *
+ * ⚠️ 为何要「不带 `/`」：站点部署在子路径 `/three-base/` 下，相对路径能随
+ *   `<base href>` 一起解析，换部署位置仍指到同一张图；而根相对 `/xxx` 会被钉死在域名根，
+ *   放到子目录就404。
+ * ⚠️ 为何要顶掉上传目录前缀：落盘地址是给「换环境部署 / 交给别人」用的，
+ *   `three-base_upload/panorama` 是本项目的 OSS 内部目录，跟内容无关；顶成项目名后
+ *   「一个项目一套目录」的语义直接体现在地址里。
+ */
+export declare function stripAssetHost(url: string, projName?: string): string;
+/**
+ * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
+ * - 已是绝对 / blob / data ⇒ **原样返回**（幂等⇒ 旧存档进 `importData` 不会被二次拼接）
+ * - `a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
+ * - `/a/b.jpg`（旧存档的根相对形态）⇒ 同样认，补成绝对（**旧存档不必重存也能用**）
+ * - `{项目名}/x_0.jpg`（19:53 旨落盘形态）⇒ 还原成真身
+ *   `https://host/three-base_upload/panorama/x_0.jpg`
+ *   ⚠️ 落盘时顶掉了上传目录前缀，这里必须还原，否则 json 里的地址永远指不回原图。
+ *
+ * ⛔ 认错的后果（所以判据要严）：把「项目名段」误当成真目录，地址会指向**不存在的图**（图片裂开）；
+ *   漏认则地址多一段目录名，同样指不到图。两种都只影响显示、不会崩，所以宁可漏认不可误认 ——
+ *   判据 =「首段命中已知站点目录 ⇒ 一律不还原」+「首段等于传入项目名 ⇒ 才还原」。
+ *
+ * @param projName 项目名。**传了就以它为准**（最可靠）；没传则只认「首段是已知站点目录之外的名字」这一条。
+ */
+export declare function absAssetUrl(url: string, projName?: string): string;

package/MktMesh/assetUrl.js

@@ -1,69 +1,165 @@
-/**
- * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
- *
- * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」：
- *   存档 JSON 里只落**根相对路径**（`/three-base_upload/panorama/xxx_0.jpg`），换来两件事：
- *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
- *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
- *
- * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
- *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
- *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
- *
- * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
- *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
- *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
- *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
- *
- * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
- *    保持零依赖才能被测试单独转译真跑。
- */
-/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
-export const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
-/** http 明文版 host：历史数据里可能存过这个形态，一并认，避免出现「剥不掉」的漏网地址 */
-const MKT_ASSET_HOST_HTTP = "http://www.3dkeshihua.com";
-/**
- * 这些前缀的地址**不参与**剥/补 —— 它们压根不是远端资源：
- * `blob:` 是本地内存里的 File/ObjectURL，`data:` 是内联字节，补域名只会把它们弄坏。
- */
-function isLocalUrl(url) {
-    return url.startsWith("blob:") || url.startsWith("data:");
-}
-/** 是不是「根相对路径」（`//host/x` 是协议相对 = 绝对，不算） */
-function isRootRelative(url) {
-    return url.startsWith("/") && !url.startsWith("//");
-}
-/**
- * 剥掉本站域名 ⇒ 根相对路径。
- * - 已是根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
- * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `/a/b.jpg`
- * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `/`
- */
-export function stripAssetHost(url) {
-    if (typeof url !== "string" || url === "")
-        return url;
-    if (isLocalUrl(url) || isRootRelative(url))
-        return url;
-    for (const host of [MKT_ASSET_HOST, MKT_ASSET_HOST_HTTP]) {
-        if (!url.startsWith(host))
-            continue;
-        const rest = url.slice(host.length);
-        // host 是前缀但后面不是 path/query/fragment 的边界 ⇒ 不是本站资源（例如 `...3dkeshihua.com.evil.com`）
-        if (rest !== "" && !/^[/?#]/.test(rest))
-            return url;
-        return rest === "" ? "/" : rest;
-    }
-    return url;
-}
-/**
- * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
- * - 已是绝对 / blob / data ⇒ **原样返回**（幂等 ⇒ 旧存档进 `importData` 不会被二次拼接）
- * - `/a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
- */
-export function absAssetUrl(url) {
-    if (typeof url !== "string" || url === "")
-        return url;
-    if (isLocalUrl(url) || !isRootRelative(url))
-        return url;
-    return `${MKT_ASSET_HOST}${url}`;
-}
+/**
+ * 全景图片地址的「相对 ⇄ 绝对」互转 —— **零 import 纯函数**（护栏可用 esbuild 直接转译真跑）。
+ *
+ * ⭐ 皇上旨 2026-10-08「json 里面的图片的地址，把域名去掉，只保留相对的根路径」；
+ *    同日 18:46 补充「图片路径要相对路径，**前面不要有 `/`**」⇒ 落盘形态最终定为
+ *   **纯相对路径**（`three-base_upload/panorama/xxx_0.jpg`，⛔ 无前导 `/`），换来两件事：
+ *     ① 换域名 / 换环境部署时，已有存档与下载的 zip 不用改一字就能用；
+ *     ② 导出的 json 里不再写死机器名，人眼可读、可 diff。
+ *   为什么连前导 `/` 都不留：站点部署在子路径 `/three-base/` 下，相对路径随 `<base href>`
+ *   一起解析，换部署位置仍指到同一张图；根相对 `/xxx` 会被钉死在域名根，放到子目录就 404。
+ *
+ * ⛔ 代价必须在同一处偿还：落盘时剥了域名，**加载前就必须补回来**。
+ *   补的动作由 `MktMesh.importData()` 一处统一做（⛔ 不许在拼合器 / 预览 / UI 各补一份 ——
+ *   那就是老坑「旁路即失控」的重演）。同理，剥的动作只在 `MktMesh.exportData()` 一处。
+ *
+ * 🔒 两个函数必须满足两条硬性质（护栏 BR 组逐条真跑）：
+ *   - **幂等**：`strip(strip(x)) === strip(x)`、`abs(abs(x)) === abs(x)`
+ *     ⇒ 旧存档本来存的绝对地址绝不会被反复剥/补成一串 `https://host/https://host/...`
+ *   - **互逆**：`strip(abs(rel)) === rel`（相对 → 绝对 → 相对，回到原样）
+ * ⚠️ **向后兼容**：`absAssetUrl` 同时认「纯相对」与「旧存档的根相对」两种形态
+ *   （`/a/b.jpg` 也补成绝对）⇒ 上午发布前存下的那些存档**不必重存**也能正常加载。
+ *
+ * ⚠️ 本模块刻意**不 import 任何东西**（连 three 都不）：它是地址字符串规则，不是渲染代码，
+ *    保持零依赖才能被测试单独转译真跑。
+ */
+/** 资源公网域名（⛔ 与 `panoramaUpload.OSS_PUBLIC_HOST` 必须同值，护栏 BR ② 钉着两边一致） */
+export const MKT_ASSET_HOST = "https://www.3dkeshihua.com";
+/** http 明文版 host：历史数据里可能存过这个形态，一并认，避免出现「剥不掉」的漏网地址 */
+const MKT_ASSET_HOST_HTTP = "http://www.3dkeshihua.com";
+/**
+ * 这些前缀的地址**不参与**剥/补 —— 它们压根不是远端资源：
+ * `blob:` 是本地内存里的 File/ObjectURL，`data:` 是内联字节，补域名只会把它们弄坏。
+ */
+function isLocalUrl(url) {
+    return url.startsWith("blob:") || url.startsWith("data:");
+}
+/** 是不是「路径式地址」（相对 `three-base_upload/xxx` 或根相对 `/three-base_upload/xxx`；`//host/x` 是协议相对 = 绝对，不算） */
+function isPathLike(url) {
+    return !url.startsWith("//") && (url.startsWith("/") || !/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(url));
+}
+/**
+ * OSS 上传目录前缀（`three-base_upload/panorama/…`）⇒ 落盘时整段丢掉，只留**文件名**。
+ * ⭐ 皇上旨10-08 19:53「导出时图片地址改成 `{项目名称}/xxx.jpg`」⇒ 这一段要被**项目名**顶替。
+ * 取不到项目名时（库内直接调 `exportData()` 而没传）**仍按老口径剥成纯相对**（不退回带`/` 的形态）。
+ */
+/** OSS 上传目录（`three-base_upload/panorama/`）——⛔ **不带尾斜杠**（拼接时自己补 `/`，否则会拼出双斜杠） */
+const UPLOAD_DIR_PREFIX = "three-base_upload";
+/** 上传目录的**完整**两级路径（还原时用） */
+const UPLOAD_FULL_PREFIX = `${UPLOAD_DIR_PREFIX}/panorama`;
+/**
+ * 本桶上「不是资源目录」的一级目录名—— 命中它们就说明是**站点自身路径**，不是项目名。
+ *（`three-base/` = 站点根，`three-base_upload/` = 资源上传根；两者都是固定目录，与项目名无关。）
+ */
+const KNOWN_TOP_DIRS = [UPLOAD_DIR_PREFIX, "three-base"];
+/** 首段看起来像「项目名」（= 不是已知站点目录）—— `strip` 与 `abs` 两侧**必须用同一把尺**，否则闭环对不上 */
+function segs0IsProjectDir(seg0) {
+    return seg0.length > 0 && !KNOWN_TOP_DIRS.includes(seg0);
+}
+/**
+ * 文件名安全化（与 `projectZipLayout.safeFileSegment` **逐字同口径**，两处必须同步 ——
+ * 一个存 json 里的地址、一个存zip 里的目录名，规则不一致会让「按 json 里的地址去 zip 找图」扑空）。
+ * Windows 与URL 都待见的字符 → 下划线；空名回落。
+ */
+function safeSeg(name) {
+    const s = (name || "").replace(/[\\/:*?"<>|]+/g, "_").trim();
+    return s.length > 0 ? s : "";
+}
+/**
+ * 剥掉本站域名 ⇒ **纯相对路径**（⭐ 皇上旨10-08 18:46「图片路径要相对路径，前面不要有 "/"」）。
+ * @param projName 项目名。给了 ⇒ 落盘成 `{项目名}/文件名.jpg`（19:53 旨）；没给 ⇒ 落成 `文件名.jpg`。
+ * - 已是相对 / 根相对 / blob / data / 别的域名 ⇒ **原样返回**（幂等，也保证旧存档安全）
+ * - `https://www.3dkeshihua.com/a/b.jpg` ⇒ `a/b.jpg`（⛔ 不带前导 `/`）
+ * - `https://www.3dkeshihua.com/three-base_upload/panorama/x_0.jpg` ⇒ `x_0.jpg` 或 `{proj}/x_0.jpg`
+ * - host 后面直接跟 `?` `#` 也认（OSS 地址可能带参），或直接到尾 ⇒ `""`（空串：无路径可留）
+ *
+ * ⚠️ 为何要「不带 `/`」：站点部署在子路径 `/three-base/` 下，相对路径能随
+ *   `<base href>` 一起解析，换部署位置仍指到同一张图；而根相对 `/xxx` 会被钉死在域名根，
+ *   放到子目录就404。
+ * ⚠️ 为何要顶掉上传目录前缀：落盘地址是给「换环境部署 / 交给别人」用的，
+ *   `three-base_upload/panorama` 是本项目的 OSS 内部目录，跟内容无关；顶成项目名后
+ *   「一个项目一套目录」的语义直接体现在地址里。
+ */
+export function stripAssetHost(url, projName) {
+    if (typeof url !== "string" || url === "")
+        return url;
+    if (isLocalUrl(url) || isPathLike(url))
+        return url;
+    for (const host of [MKT_ASSET_HOST, MKT_ASSET_HOST_HTTP]) {
+        if (!url.startsWith(host))
+            continue;
+        const rest = url.slice(host.length);
+        // host 是前缀但后面不是 path/query/fragment 的边界 ⇒ 不是本站资源（例如`...3dkeshihua.com.evil.com`）
+        if (rest !== "" && !/^[/?#]/.test(rest))
+            return url;
+        // 去掉前导 `/`：得到真正的相对路径（`/a/b.jpg` → `a/b.jpg`；`/` → `""`）
+        let path = rest.replace(/^\/+/, "");
+        // 上传目录前缀整段丢掉，换成**项目名**（皇上 19:53 旨）；项目名缺失时退回「无项目名」的裸文件名。
+        // ⭐ 无论哪种形态，产出的地址都必须能被 `absAssetUrl` **原样还原**回真身 OSS 地址
+        //   （这是「运行期地址不动、只在导出 json 里临时改」的前提 —— 顶替必须是可逆的）。
+        if (path === UPLOAD_DIR_PREFIX || path.startsWith(`${UPLOAD_DIR_PREFIX}/`)) {
+            const tail = path.slice(UPLOAD_DIR_PREFIX.length + 1); // 越过 `three-base_upload/` ⇒ `panorama/x_0.jpg`
+            const cut = tail.search(/[/?#]/); // 截到第一个分隔符（`/` `?` `#`）
+            // ⚠️ slice(cut) 会把那个分隔符一起带上（`panorama/x.jpg` → `/x.jpg`）⇒ 要 slice(cut+1)
+            const file = cut < 0 ? tail : tail.slice(cut + 1); // 文件名（含后面的 ?/#）
+            const dir = safeSeg(projName ?? "");
+            return dir ? `${dir}/${file}` : file;
+        }
+        // ⭐ 幂等对称：`{项目名}/x.jpg` 这种**已顶替过**的形态（还原回绝对后再剥）要认出来，
+        //   否则项目名段会被原样留着、形态跟首轮落盘的不一致 ⇒ 导出→导入→导出闭环对不上。
+        //   判据 = 首段既不是已知站点目录、也不是上传目录（与 `absAssetUrl` 的还原判据镜像）。
+        const seg0 = path.split("/")[0];
+        if (segs0IsProjectDir(seg0)) {
+            const tail = path.slice(seg0.length + 1); // 越过 `{项目名}/`
+            const dir = safeSeg(projName ?? "");
+            // 传了项目名且首段与它一致 ⇒ 剥掉首段还原成裸文件名（无项目名时的落盘形态）
+            if (dir && seg0 === dir)
+                return tail;
+            // 没传项目名 ⇒ 首段无从确认是不是项目名，⛔ 原样留着（宁可多一段也不猜错）
+            return path;
+        }
+        return path;
+    }
+    return url;
+}
+/**
+ * 补回域名 ⇒ 绝对地址（加载前的唯一落点）。
+ * - 已是绝对 / blob / data ⇒ **原样返回**（幂等⇒ 旧存档进 `importData` 不会被二次拼接）
+ * - `a/b.jpg` ⇒ `https://www.3dkeshihua.com/a/b.jpg`
+ * - `/a/b.jpg`（旧存档的根相对形态）⇒ 同样认，补成绝对（**旧存档不必重存也能用**）
+ * - `{项目名}/x_0.jpg`（19:53 旨落盘形态）⇒ 还原成真身
+ *   `https://host/three-base_upload/panorama/x_0.jpg`
+ *   ⚠️ 落盘时顶掉了上传目录前缀，这里必须还原，否则 json 里的地址永远指不回原图。
+ *
+ * ⛔ 认错的后果（所以判据要严）：把「项目名段」误当成真目录，地址会指向**不存在的图**（图片裂开）；
+ *   漏认则地址多一段目录名，同样指不到图。两种都只影响显示、不会崩，所以宁可漏认不可误认 ——
+ *   判据 =「首段命中已知站点目录 ⇒ 一律不还原」+「首段等于传入项目名 ⇒ 才还原」。
+ *
+ * @param projName 项目名。**传了就以它为准**（最可靠）；没传则只认「首段是已知站点目录之外的名字」这一条。
+ */
+export function absAssetUrl(url, projName) {
+    if (typeof url !== "string" || url === "")
+        return url;
+    if (isLocalUrl(url) || !isPathLike(url))
+        return url;
+    const path = url.replace(/^\/+/, "");
+    // ⛔ 空路径（`/` 或 `/` 去掉斜杠后）不是文件名，别当裸文件名补上传目录（实测会补出 `host/three-base_upload/panorama/`）
+    if (path === "")
+        return `${MKT_ASSET_HOST}/`;
+    const segs = path.split("/");
+    // ⭐ 情形①：**裸文件名**（`x_26.jpg`，无目录）—— 这是 `stripAssetHost` 无项目名时的落盘形态，
+    //   它必然来自上传目录 ⇒ 直接还原回 `three-base_upload/panorama/`。
+    //   ⛔ 漏了这一条就会补成 `https://host/x_26.jpg`（丢了上传目录）⇒ 线上取图 404（皇上 10-09 实测撞到）。
+    if (segs.length === 1)
+        return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[0]}`;
+    // 情形②：`{项目名}/文件名`（两段、首段不是已知站点目录）⇒ 同样还原回上传目录。
+    //   判据与 `strip` 侧镜像，两边用同一把尺（`segs0IsProjectDir`）才能保证「顶替可逆」。
+    if (segs.length === 2 && segs0IsProjectDir(segs[0])) {
+        const dir = safeSeg(projName ?? "");
+        // 传了项目名就严格比它（最可靠）；没传才放宽到「非已知目录即可认」
+        if (!dir || segs[0] === dir)
+            return `${MKT_ASSET_HOST}/${UPLOAD_FULL_PREFIX}/${segs[1]}`;
+    }
+    // 情形③：其余形态（`three-base/model/a.glb`、已是 `three-base_upload/…` 的）⇒ 原样补域名，不还原。
+    return `${MKT_ASSET_HOST}/${path}`;
+}