@lark-apaas/fullstack-nestjs-core 1.1.32 → 1.1.33-alpha.0

package/dist/index.cjs

@@ -1371,8 +1371,8 @@ var require_node = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -18069,8 +18069,8 @@ var require_node2 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -18839,8 +18839,8 @@ var require_node3 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -20634,11 +20634,11 @@ var require_view = __commonJS({
     "use strict";
     var debug = require_src3()("express:view");
     var path2 = require("path");
-    var fs2 = require("fs");
-    var dirname = path2.dirname;
+    var fs3 = require("fs");
+    var dirname2 = path2.dirname;
     var basename = path2.basename;
     var extname2 = path2.extname;
-    var join2 = path2.join;
+    var join3 = path2.join;
     var resolve2 = path2.resolve;
     module2.exports = View;
     function View(name, options) {
@@ -20675,7 +20675,7 @@ var require_view = __commonJS({
       for (var i = 0; i < roots.length && !path3; i++) {
         var root = roots[i];
         var loc = resolve2(root, name);
-        var dir = dirname(loc);
+        var dir = dirname2(loc);
         var file = basename(loc);
         path3 = this.resolve(dir, file);
       }
@@ -20687,12 +20687,12 @@ var require_view = __commonJS({
     }, "render");
     View.prototype.resolve = /* @__PURE__ */ __name(function resolve3(dir, file) {
       var ext = this.ext;
-      var path3 = join2(dir, file);
+      var path3 = join3(dir, file);
       var stat = tryStat(path3);
       if (stat && stat.isFile()) {
         return path3;
       }
-      path3 = join2(dir, basename(file, ext), "index" + ext);
+      path3 = join3(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path3);
       if (stat && stat.isFile()) {
         return path3;
@@ -20701,7 +20701,7 @@ var require_view = __commonJS({
     function tryStat(path3) {
       debug('stat "%s"', path3);
       try {
-        return fs2.statSync(path3);
+        return fs3.statSync(path3);
       } catch (e) {
         return void 0;
       }
@@ -21350,8 +21350,8 @@ var require_node4 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -21537,7 +21537,7 @@ var require_mime = __commonJS({
   "../../../node_modules/mime/mime.js"(exports2, module2) {
     "use strict";
     var path2 = require("path");
-    var fs2 = require("fs");
+    var fs3 = require("fs");
     function Mime() {
       this.types = /* @__PURE__ */ Object.create(null);
       this.extensions = /* @__PURE__ */ Object.create(null);
@@ -21559,7 +21559,7 @@ var require_mime = __commonJS({
     };
     Mime.prototype.load = function(file) {
       this._loading = file;
-      var map = {}, content = fs2.readFileSync(file, "ascii"), lines = content.split(/[\r\n]+/);
+      var map = {}, content = fs3.readFileSync(file, "ascii"), lines = content.split(/[\r\n]+/);
       lines.forEach(function(line) {
         var fields = line.replace(/\s*#.*|^\s*|\s*$/g, "").split(/\s+/);
         map[fields.shift()] = fields;
@@ -21804,7 +21804,7 @@ var require_send = __commonJS({
     var escapeHtml = require_escape_html();
     var etag = require_etag();
     var fresh = require_fresh();
-    var fs2 = require("fs");
+    var fs3 = require("fs");
     var mime = require_mime();
     var ms = require_ms5();
     var onFinished = require_on_finished();
@@ -21814,7 +21814,7 @@ var require_send = __commonJS({
     var Stream = require("stream");
     var util = require("util");
     var extname2 = path2.extname;
-    var join2 = path2.join;
+    var join3 = path2.join;
     var normalize2 = path2.normalize;
     var resolve2 = path2.resolve;
     var sep = path2.sep;
@@ -22031,7 +22031,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path3.split(sep);
-        path3 = normalize2(join2(root, path3));
+        path3 = normalize2(join3(root, path3));
       } else {
         if (UP_PATH_REGEXP.test(path3)) {
           debug('malicious path "%s"', path3);
@@ -22137,7 +22137,7 @@ var require_send = __commonJS({
       var i = 0;
       var self = this;
       debug('stat "%s"', path3);
-      fs2.stat(path3, /* @__PURE__ */ __name(function onstat(err, stat) {
+      fs3.stat(path3, /* @__PURE__ */ __name(function onstat(err, stat) {
         if (err && err.code === "ENOENT" && !extname2(path3) && path3[path3.length - 1] !== sep) {
           return next(err);
         }
@@ -22152,7 +22152,7 @@ var require_send = __commonJS({
         }
         var p = path3 + "." + self._extensions[i++];
         debug('stat "%s"', p);
-        fs2.stat(p, function(err2, stat) {
+        fs3.stat(p, function(err2, stat) {
           if (err2) return next(err2);
           if (stat.isDirectory()) return next();
           self.emit("file", p, stat);
@@ -22169,9 +22169,9 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join2(path3, self._index[i]);
+        var p = join3(path3, self._index[i]);
         debug('stat "%s"', p);
-        fs2.stat(p, function(err2, stat) {
+        fs3.stat(p, function(err2, stat) {
           if (err2) return next(err2);
           if (stat.isDirectory()) return next();
           self.emit("file", p, stat);
@@ -22184,7 +22184,7 @@ var require_send = __commonJS({
     SendStream.prototype.stream = /* @__PURE__ */ __name(function stream(path3, options) {
       var self = this;
       var res = this.res;
-      var stream2 = fs2.createReadStream(path3, options);
+      var stream2 = fs3.createReadStream(path3, options);
       this.emit("stream", stream2);
       stream2.pipe(res);
       function cleanup() {
@@ -34404,13 +34404,15 @@ var require_express2 = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AutoTrace: () => import_nestjs_common7.AutoTrace,
+  AutoTrace: () => import_nestjs_common8.AutoTrace,
   CanRole: () => import_nestjs_authzpaas2.CanRole,
   CsrfMiddleware: () => CsrfMiddleware,
   CsrfTokenMiddleware: () => CsrfTokenMiddleware,
   DevToolsModule: () => import_nestjs_openapi_devtools2.DevToolsModule,
   DevToolsV2Module: () => import_nestjs_openapi_devtools2.DevToolsV2Module,
   FileService: () => FileService,
+  HtmlHotUpdateModule: () => HtmlHotUpdateModule,
+  HtmlHotUpdateService: () => HtmlHotUpdateService,
   PlatformHttpClientService: () => PlatformHttpClientService,
   PlatformModule: () => PlatformModule,
   StaticModule: () => StaticModule,
@@ -34422,9 +34424,9 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/modules/platform/module.ts
-var import_common12 = require("@nestjs/common");
+var import_common15 = require("@nestjs/common");
 var import_core2 = require("@nestjs/core");
-var import_nestjs_common5 = require("@lark-apaas/nestjs-common");
+var import_nestjs_common6 = require("@lark-apaas/nestjs-common");
 var import_config2 = require("@nestjs/config");
 var import_nestjs_observable = require("@lark-apaas/nestjs-observable");
 var import_axios2 = require("@nestjs/axios");
@@ -34432,7 +34434,7 @@ var import_nestjs_logger2 = require("@lark-apaas/nestjs-logger");
 var import_nestjs_datapaas = require("@lark-apaas/nestjs-datapaas");
 var import_nestjs_authnpaas = require("@lark-apaas/nestjs-authnpaas");
 var import_nestjs_trigger = require("@lark-apaas/nestjs-trigger");
-var import_nestjs_common6 = require("@lark-apaas/nestjs-common");
+var import_nestjs_common7 = require("@lark-apaas/nestjs-common");
 var import_nestjs_capability = require("@lark-apaas/nestjs-capability");
 
 // src/middlewares/user-context/index.ts
@@ -35819,7 +35821,18 @@ StaticModule = _ts_decorate11([
   })
 ], StaticModule);
 
-// src/modules/platform/module.ts
+// src/modules/html-hot-update/html-hot-update.module.ts
+var import_common14 = require("@nestjs/common");
+
+// src/modules/html-hot-update/html-hot-update.controller.ts
+var import_common13 = require("@nestjs/common");
+var import_swagger2 = require("@nestjs/swagger");
+
+// src/modules/html-hot-update/html-hot-update.service.ts
+var import_common12 = require("@nestjs/common");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_nestjs_common5 = require("@lark-apaas/nestjs-common");
 function _ts_decorate12(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -35827,6 +35840,291 @@ function _ts_decorate12(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate12, "_ts_decorate");
+function _ts_metadata8(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata8, "_ts_metadata");
+function _ts_param4(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param4, "_ts_param");
+var Mutex = class Mutex2 {
+  static {
+    __name(this, "Mutex");
+  }
+  locked = false;
+  waiting = [];
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise((resolve2) => {
+      this.waiting.push(() => {
+        this.locked = true;
+        resolve2();
+      });
+    });
+  }
+  release() {
+    if (this.waiting.length > 0) {
+      const next = this.waiting.shift();
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+};
+var HtmlHotUpdateService = class _HtmlHotUpdateService {
+  static {
+    __name(this, "HtmlHotUpdateService");
+  }
+  httpClient;
+  logger = new import_common12.Logger(_HtmlHotUpdateService.name);
+  /** 文件锁：冷启动更新和 innerapi 主动更新共用 */
+  fileLock = new Mutex();
+  /** 本地 HTML 文件目录（dist/dist/client，与 build.sh [4/5] 对齐） */
+  localHtmlDir = (0, import_node_path.join)(process.cwd(), "dist", "client");
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+  * 任务一：冷启动时尝试更新 HTML 文件列表
+  *
+  * - 生产环境默认启用（模块仅在生产环境加载）
+  * - 失败则降级，使用部署时打包的 HTML 正常启动
+  * - 超时 3s，避免拉长冷启动耗时
+  */
+  async onModuleInit() {
+    const appID = this.getAppID();
+    if (!appID) {
+      this.logger.warn("Skip HTML hot update on startup: appID not found");
+      return;
+    }
+    try {
+      this.logger.log(`Startup HTML update: appID=${appID}`);
+      const result = await this.updateFromRemote(appID);
+      this.logger.log(`Startup HTML update complete: ${result.updatedFiles.length} updated, ${result.failedFiles.length} failed`);
+    } catch (error) {
+      this.logger.warn(`Startup HTML update failed (degraded to bundled HTML): ${error instanceof Error ? error.message : String(error)}, appID=${appID}`);
+    }
+  }
+  /**
+  * 从远端获取最新 HTML 文件并更新本地
+  *
+  * 调用方：
+  * 1) 冷启动更新（onModuleInit）
+  * 2) innerapi 主动更新（controller 调用）
+  */
+  async updateFromRemote(appID, commitID) {
+    const fileMap = await this.fetchLatestHtmlFiles(appID, commitID);
+    return this.writeHtmlFiles(fileMap);
+  }
+  /**
+  * 将文件内容写入本地 HTML 目录（带文件锁）
+  */
+  async writeHtmlFiles(fileMap) {
+    const result = {
+      updatedFiles: [],
+      failedFiles: []
+    };
+    const entries = Object.entries(fileMap);
+    if (entries.length === 0) {
+      return result;
+    }
+    await this.fileLock.acquire();
+    try {
+      for (const [filePath, content] of entries) {
+        try {
+          const localPath = (0, import_node_path.join)(this.localHtmlDir, filePath);
+          await import_node_fs.promises.mkdir((0, import_node_path.dirname)(localPath), {
+            recursive: true
+          });
+          await import_node_fs.promises.writeFile(localPath, content, "utf-8");
+          result.updatedFiles.push(filePath);
+        } catch (error) {
+          const reason = error instanceof Error ? error.message : String(error);
+          result.failedFiles.push({
+            filePath,
+            reason
+          });
+          this.logger.warn(`Failed to write HTML file ${filePath}: ${reason}`);
+        }
+      }
+    } finally {
+      this.fileLock.release();
+    }
+    return result;
+  }
+  /**
+  * 调用后端 GetLatestArtifactHtmlFiles 接口
+  */
+  async fetchLatestHtmlFiles(appID, commitID) {
+    const url = `/v1/app/${appID}/pipeline/frontend/latest_artifact/html_files`;
+    const body = {};
+    if (commitID) {
+      body.commitID = commitID;
+    }
+    const response = await this.httpClient.post(url, body, {
+      timeout: 3e3
+    });
+    if (!response.ok) {
+      throw new Error(`GetLatestArtifactHtmlFiles failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (data.BaseResp?.StatusCode && data.BaseResp.StatusCode !== 0) {
+      throw new Error(`GetLatestArtifactHtmlFiles error: ${data.BaseResp.StatusMessage}`);
+    }
+    if (!data.fileMap || Object.keys(data.fileMap).length === 0) {
+      throw new Error("GetLatestArtifactHtmlFiles returned empty fileMap");
+    }
+    return data.fileMap;
+  }
+  /**
+  * 从 CLIENT_BASE_PATH 提取 appID
+  * CLIENT_BASE_PATH 格式: /app/{appId}
+  */
+  getAppID() {
+    const basePath = process.env.CLIENT_BASE_PATH || "";
+    const match = basePath.match(/\/app\/([^/]+)/);
+    return match?.[1] ?? "";
+  }
+};
+HtmlHotUpdateService = _ts_decorate12([
+  (0, import_common12.Injectable)(),
+  _ts_param4(0, (0, import_common12.Inject)(import_nestjs_common5.PLATFORM_HTTP_CLIENT)),
+  _ts_metadata8("design:type", Function),
+  _ts_metadata8("design:paramtypes", [
+    typeof PlatformHttpClient === "undefined" ? Object : PlatformHttpClient
+  ])
+], HtmlHotUpdateService);
+
+// src/modules/html-hot-update/html-hot-update.controller.ts
+function _ts_decorate13(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate13, "_ts_decorate");
+function _ts_metadata9(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata9, "_ts_metadata");
+function _ts_param5(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param5, "_ts_param");
+var UpdateHtmlFilesDto = class UpdateHtmlFilesDto2 {
+  static {
+    __name(this, "UpdateHtmlFilesDto");
+  }
+  commitID;
+  appID;
+};
+var HtmlHotUpdateController = class {
+  static {
+    __name(this, "HtmlHotUpdateController");
+  }
+  htmlHotUpdateService;
+  constructor(htmlHotUpdateService) {
+    this.htmlHotUpdateService = htmlHotUpdateService;
+  }
+  /**
+  * POST /__innerapi__/update_html_files
+  *
+  * 请求体: { commitID: string, appID: string }
+  * 响应:
+  *   成功: { code: 0, msg: "success" }
+  *   失败: { code: -1, msg: "update html failed: <error>" }
+  */
+  async updateHtmlFiles(body) {
+    const { commitID, appID } = body;
+    if (!commitID || !appID) {
+      return {
+        code: -1,
+        msg: "commitID and appID are required"
+      };
+    }
+    try {
+      const result = await this.htmlHotUpdateService.updateFromRemote(appID, commitID);
+      if (result.updatedFiles.length === 0 && result.failedFiles.length > 0) {
+        return {
+          code: -1,
+          msg: `update html failed: all ${result.failedFiles.length} files failed to write`
+        };
+      }
+      return {
+        code: 0,
+        msg: "success"
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return {
+        code: -1,
+        msg: `update html failed: ${errorMsg}`
+      };
+    }
+  }
+};
+_ts_decorate13([
+  (0, import_common13.Post)("update_html_files"),
+  (0, import_common13.HttpCode)(import_common13.HttpStatus.OK),
+  _ts_param5(0, (0, import_common13.Body)()),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
+    typeof UpdateHtmlFilesDto === "undefined" ? Object : UpdateHtmlFilesDto
+  ]),
+  _ts_metadata9("design:returntype", Promise)
+], HtmlHotUpdateController.prototype, "updateHtmlFiles", null);
+HtmlHotUpdateController = _ts_decorate13([
+  (0, import_swagger2.ApiExcludeController)(),
+  (0, import_common13.Controller)("__innerapi__"),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
+    typeof HtmlHotUpdateService === "undefined" ? Object : HtmlHotUpdateService
+  ])
+], HtmlHotUpdateController);
+
+// src/modules/html-hot-update/html-hot-update.module.ts
+function _ts_decorate14(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate14, "_ts_decorate");
+var HtmlHotUpdateModule = class {
+  static {
+    __name(this, "HtmlHotUpdateModule");
+  }
+};
+HtmlHotUpdateModule = _ts_decorate14([
+  (0, import_common14.Module)({
+    controllers: [
+      HtmlHotUpdateController
+    ],
+    providers: [
+      HtmlHotUpdateService
+    ],
+    exports: [
+      HtmlHotUpdateService
+    ]
+  })
+], HtmlHotUpdateModule);
+
+// src/modules/platform/module.ts
+function _ts_decorate15(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate15, "_ts_decorate");
 var PLATFORM_MODULE_OPTIONS = /* @__PURE__ */ Symbol("PLATFORM_MODULE_OPTIONS");
 var PlatformModule = class _PlatformModule {
   static {
@@ -35848,7 +36146,7 @@ var PlatformModule = class _PlatformModule {
             app_config_default
           ]
         }),
-        import_nestjs_common5.CommonModule,
+        import_nestjs_common6.CommonModule,
         import_nestjs_observable.NestjsObservableModule,
         import_nestjs_logger2.LoggerModule,
         import_axios2.HttpModule.register({
@@ -35897,6 +36195,11 @@ var PlatformModule = class _PlatformModule {
         // 开发环境由 Vite/Rspack dev server 的中间件处理 /static/* 请求
         ...process.env.NODE_ENV === "development" ? [] : [
           StaticModule
+        ],
+        // HTML 热更新模块（仅生产环境启用）
+        // 提供 innerapi 供 tce 服务触发 HTML 热更新，冷启动时也会尝试拉取最新 HTML
+        ...process.env.NODE_ENV === "development" ? [] : [
+          HtmlHotUpdateModule
         ]
       ],
       providers: [
@@ -35906,7 +36209,7 @@ var PlatformModule = class _PlatformModule {
         },
         {
           provide: import_core2.APP_PIPE,
-          useValue: new import_common12.ValidationPipe({
+          useValue: new import_common15.ValidationPipe({
             transform: true,
             transformOptions: {
               enableImplicitConversion: true
@@ -35914,19 +36217,19 @@ var PlatformModule = class _PlatformModule {
           })
         },
         {
-          provide: import_nestjs_common5.OBSERVABLE_SERVICE,
+          provide: import_nestjs_common6.OBSERVABLE_SERVICE,
           useClass: import_nestjs_observable.Observable
         },
         PlatformHttpClientService,
         {
-          provide: import_nestjs_common6.PLATFORM_HTTP_CLIENT,
+          provide: import_nestjs_common7.PLATFORM_HTTP_CLIENT,
           useFactory: /* @__PURE__ */ __name((svc) => svc.instance, "useFactory"),
           inject: [
             PlatformHttpClientService
           ]
         },
         {
-          provide: import_nestjs_common5.HTTP_CLIENT_FACTORY,
+          provide: import_nestjs_common6.HTTP_CLIENT_FACTORY,
           useFactory: /* @__PURE__ */ __name((svc) => ({
             create: /* @__PURE__ */ __name((options2) => svc.createWithGlobalInterceptors(options2), "create")
           }), "useFactory"),
@@ -35944,10 +36247,10 @@ var PlatformModule = class _PlatformModule {
       exports: [
         import_config2.ConfigModule,
         import_nestjs_logger2.LoggerModule,
-        import_nestjs_common5.CommonModule,
-        import_nestjs_common5.OBSERVABLE_SERVICE,
-        import_nestjs_common6.PLATFORM_HTTP_CLIENT,
-        import_nestjs_common5.HTTP_CLIENT_FACTORY,
+        import_nestjs_common6.CommonModule,
+        import_nestjs_common6.OBSERVABLE_SERVICE,
+        import_nestjs_common7.PLATFORM_HTTP_CLIENT,
+        import_nestjs_common6.HTTP_CLIENT_FACTORY,
         PlatformHttpClientService,
         import_nestjs_capability.CapabilityModule,
         FileService
@@ -35979,9 +36282,9 @@ var PlatformModule = class _PlatformModule {
     }
   }
 };
-PlatformModule = _ts_decorate12([
-  (0, import_common12.Global)(),
-  (0, import_common12.Module)({})
+PlatformModule = _ts_decorate15([
+  (0, import_common15.Global)(),
+  (0, import_common15.Module)({})
 ], PlatformModule);
 
 // src/setup.ts
@@ -36069,7 +36372,7 @@ __reExport(index_exports, require("@lark-apaas/nestjs-datapaas"), module.exports
 __reExport(index_exports, require("@lark-apaas/nestjs-observable"), module.exports);
 __reExport(index_exports, require("@lark-apaas/nestjs-trigger"), module.exports);
 __reExport(index_exports, require("@lark-apaas/file-service"), module.exports);
-var import_nestjs_common7 = require("@lark-apaas/nestjs-common");
+var import_nestjs_common8 = require("@lark-apaas/nestjs-common");
 var import_nestjs_authzpaas2 = require("@lark-apaas/nestjs-authzpaas");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -36080,6 +36383,8 @@ var import_nestjs_authzpaas2 = require("@lark-apaas/nestjs-authzpaas");
   DevToolsModule,
   DevToolsV2Module,
   FileService,
+  HtmlHotUpdateModule,
+  HtmlHotUpdateService,
   PlatformHttpClientService,
   PlatformModule,
   StaticModule,

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { NestModule, DynamicModule, MiddlewareConsumer, NestMiddleware } from '@nestjs/common';
+import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, NestMiddleware } from '@nestjs/common';
 import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { NestExpressApplication } from '@nestjs/platform-express';
-export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
-import { Request, Response, NextFunction } from 'express';
 import { PlatformHttpClient, RequestContextService, ObservableService } from '@lark-apaas/nestjs-common';
 export { AutoTrace } from '@lark-apaas/nestjs-common';
+export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+import { Request, Response, NextFunction } from 'express';
 import * as _lark_apaas_file_service from '@lark-apaas/file-service';
 import { FileBody, UploadOptions, FileDownloadBuilder, SearchOptions } from '@lark-apaas/file-service';
 export * from '@lark-apaas/file-service';
@@ -123,6 +123,67 @@ declare function configureApp(app: NestExpressApplication, perms?: {
 declare class StaticModule {
 }
 
+/**
+ * HTML 热更新模块
+ *
+ * 提供两个能力：
+ * 1. 冷启动时主动拉取最新 HTML 文件列表并替换本地文件（任务一）
+ * 2. 对外暴露 innerapi 接口，供 tce 服务主动触发热更新（任务二）
+ *
+ * 仅在生产环境加载（PlatformModule 中控制），两个能力默认都启用。
+ */
+declare class HtmlHotUpdateModule {
+}
+
+/**
+ * HTML 热更新结果
+ */
+interface HtmlHotUpdateResult {
+    updatedFiles: string[];
+    failedFiles: {
+        filePath: string;
+        reason: string;
+    }[];
+}
+declare class HtmlHotUpdateService implements OnModuleInit {
+    private readonly httpClient;
+    private readonly logger;
+    /** 文件锁：冷启动更新和 innerapi 主动更新共用 */
+    private readonly fileLock;
+    /** 本地 HTML 文件目录（dist/dist/client，与 build.sh [4/5] 对齐） */
+    private readonly localHtmlDir;
+    constructor(httpClient: PlatformHttpClient);
+    /**
+     * 任务一：冷启动时尝试更新 HTML 文件列表
+     *
+     * - 生产环境默认启用（模块仅在生产环境加载）
+     * - 失败则降级，使用部署时打包的 HTML 正常启动
+     * - 超时 3s，避免拉长冷启动耗时
+     */
+    onModuleInit(): Promise<void>;
+    /**
+     * 从远端获取最新 HTML 文件并更新本地
+     *
+     * 调用方：
+     * 1) 冷启动更新（onModuleInit）
+     * 2) innerapi 主动更新（controller 调用）
+     */
+    updateFromRemote(appID: string, commitID?: string): Promise<HtmlHotUpdateResult>;
+    /**
+     * 将文件内容写入本地 HTML 目录（带文件锁）
+     */
+    writeHtmlFiles(fileMap: Record<string, string>): Promise<HtmlHotUpdateResult>;
+    /**
+     * 调用后端 GetLatestArtifactHtmlFiles 接口
+     */
+    private fetchLatestHtmlFiles;
+    /**
+     * 从 CLIENT_BASE_PATH 提取 appID
+     * CLIENT_BASE_PATH 格式: /app/{appId}
+     */
+    private getAppID;
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -354,4 +415,4 @@ declare class PlatformHttpClientService {
     private registerInterceptorsForClient;
 }
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware };
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { NestModule, DynamicModule, MiddlewareConsumer, NestMiddleware } from '@nestjs/common';
+import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, NestMiddleware } from '@nestjs/common';
 import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { NestExpressApplication } from '@nestjs/platform-express';
-export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
-import { Request, Response, NextFunction } from 'express';
 import { PlatformHttpClient, RequestContextService, ObservableService } from '@lark-apaas/nestjs-common';
 export { AutoTrace } from '@lark-apaas/nestjs-common';
+export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+import { Request, Response, NextFunction } from 'express';
 import * as _lark_apaas_file_service from '@lark-apaas/file-service';
 import { FileBody, UploadOptions, FileDownloadBuilder, SearchOptions } from '@lark-apaas/file-service';
 export * from '@lark-apaas/file-service';
@@ -123,6 +123,67 @@ declare function configureApp(app: NestExpressApplication, perms?: {
 declare class StaticModule {
 }
 
+/**
+ * HTML 热更新模块
+ *
+ * 提供两个能力：
+ * 1. 冷启动时主动拉取最新 HTML 文件列表并替换本地文件（任务一）
+ * 2. 对外暴露 innerapi 接口，供 tce 服务主动触发热更新（任务二）
+ *
+ * 仅在生产环境加载（PlatformModule 中控制），两个能力默认都启用。
+ */
+declare class HtmlHotUpdateModule {
+}
+
+/**
+ * HTML 热更新结果
+ */
+interface HtmlHotUpdateResult {
+    updatedFiles: string[];
+    failedFiles: {
+        filePath: string;
+        reason: string;
+    }[];
+}
+declare class HtmlHotUpdateService implements OnModuleInit {
+    private readonly httpClient;
+    private readonly logger;
+    /** 文件锁：冷启动更新和 innerapi 主动更新共用 */
+    private readonly fileLock;
+    /** 本地 HTML 文件目录（dist/dist/client，与 build.sh [4/5] 对齐） */
+    private readonly localHtmlDir;
+    constructor(httpClient: PlatformHttpClient);
+    /**
+     * 任务一：冷启动时尝试更新 HTML 文件列表
+     *
+     * - 生产环境默认启用（模块仅在生产环境加载）
+     * - 失败则降级，使用部署时打包的 HTML 正常启动
+     * - 超时 3s，避免拉长冷启动耗时
+     */
+    onModuleInit(): Promise<void>;
+    /**
+     * 从远端获取最新 HTML 文件并更新本地
+     *
+     * 调用方：
+     * 1) 冷启动更新（onModuleInit）
+     * 2) innerapi 主动更新（controller 调用）
+     */
+    updateFromRemote(appID: string, commitID?: string): Promise<HtmlHotUpdateResult>;
+    /**
+     * 将文件内容写入本地 HTML 目录（带文件锁）
+     */
+    writeHtmlFiles(fileMap: Record<string, string>): Promise<HtmlHotUpdateResult>;
+    /**
+     * 调用后端 GetLatestArtifactHtmlFiles 接口
+     */
+    private fetchLatestHtmlFiles;
+    /**
+     * 从 CLIENT_BASE_PATH 提取 appID
+     * CLIENT_BASE_PATH 格式: /app/{appId}
+     */
+    private getAppID;
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -354,4 +415,4 @@ declare class PlatformHttpClientService {
     private registerInterceptorsForClient;
 }
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware };
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware };

package/dist/index.js

@@ -1370,8 +1370,8 @@ var require_node = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = __require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = __require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -18068,8 +18068,8 @@ var require_node2 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = __require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = __require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -18838,8 +18838,8 @@ var require_node3 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = __require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = __require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -20633,11 +20633,11 @@ var require_view = __commonJS({
     "use strict";
     var debug = require_src3()("express:view");
     var path2 = __require("path");
-    var fs2 = __require("fs");
-    var dirname = path2.dirname;
+    var fs3 = __require("fs");
+    var dirname2 = path2.dirname;
     var basename = path2.basename;
     var extname2 = path2.extname;
-    var join2 = path2.join;
+    var join3 = path2.join;
     var resolve2 = path2.resolve;
     module.exports = View;
     function View(name, options) {
@@ -20674,7 +20674,7 @@ var require_view = __commonJS({
       for (var i = 0; i < roots.length && !path3; i++) {
         var root = roots[i];
         var loc = resolve2(root, name);
-        var dir = dirname(loc);
+        var dir = dirname2(loc);
         var file = basename(loc);
         path3 = this.resolve(dir, file);
       }
@@ -20686,12 +20686,12 @@ var require_view = __commonJS({
     }, "render");
     View.prototype.resolve = /* @__PURE__ */ __name(function resolve3(dir, file) {
       var ext = this.ext;
-      var path3 = join2(dir, file);
+      var path3 = join3(dir, file);
       var stat = tryStat(path3);
       if (stat && stat.isFile()) {
         return path3;
       }
-      path3 = join2(dir, basename(file, ext), "index" + ext);
+      path3 = join3(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path3);
       if (stat && stat.isFile()) {
         return path3;
@@ -20700,7 +20700,7 @@ var require_view = __commonJS({
     function tryStat(path3) {
       debug('stat "%s"', path3);
       try {
-        return fs2.statSync(path3);
+        return fs3.statSync(path3);
       } catch (e) {
         return void 0;
       }
@@ -21349,8 +21349,8 @@ var require_node4 = __commonJS({
           }
           break;
         case "FILE":
-          var fs2 = __require("fs");
-          stream2 = new fs2.SyncWriteStream(fd2, {
+          var fs3 = __require("fs");
+          stream2 = new fs3.SyncWriteStream(fd2, {
             autoClose: false
           });
           stream2._type = "fs";
@@ -21536,7 +21536,7 @@ var require_mime = __commonJS({
   "../../../node_modules/mime/mime.js"(exports, module) {
     "use strict";
     var path2 = __require("path");
-    var fs2 = __require("fs");
+    var fs3 = __require("fs");
     function Mime() {
       this.types = /* @__PURE__ */ Object.create(null);
       this.extensions = /* @__PURE__ */ Object.create(null);
@@ -21558,7 +21558,7 @@ var require_mime = __commonJS({
     };
     Mime.prototype.load = function(file) {
       this._loading = file;
-      var map = {}, content = fs2.readFileSync(file, "ascii"), lines = content.split(/[\r\n]+/);
+      var map = {}, content = fs3.readFileSync(file, "ascii"), lines = content.split(/[\r\n]+/);
       lines.forEach(function(line) {
         var fields = line.replace(/\s*#.*|^\s*|\s*$/g, "").split(/\s+/);
         map[fields.shift()] = fields;
@@ -21803,7 +21803,7 @@ var require_send = __commonJS({
     var escapeHtml = require_escape_html();
     var etag = require_etag();
     var fresh = require_fresh();
-    var fs2 = __require("fs");
+    var fs3 = __require("fs");
     var mime = require_mime();
     var ms = require_ms5();
     var onFinished = require_on_finished();
@@ -21813,7 +21813,7 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util = __require("util");
     var extname2 = path2.extname;
-    var join2 = path2.join;
+    var join3 = path2.join;
     var normalize2 = path2.normalize;
     var resolve2 = path2.resolve;
     var sep = path2.sep;
@@ -22030,7 +22030,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path3.split(sep);
-        path3 = normalize2(join2(root, path3));
+        path3 = normalize2(join3(root, path3));
       } else {
         if (UP_PATH_REGEXP.test(path3)) {
           debug('malicious path "%s"', path3);
@@ -22136,7 +22136,7 @@ var require_send = __commonJS({
       var i = 0;
       var self = this;
       debug('stat "%s"', path3);
-      fs2.stat(path3, /* @__PURE__ */ __name(function onstat(err, stat) {
+      fs3.stat(path3, /* @__PURE__ */ __name(function onstat(err, stat) {
         if (err && err.code === "ENOENT" && !extname2(path3) && path3[path3.length - 1] !== sep) {
           return next(err);
         }
@@ -22151,7 +22151,7 @@ var require_send = __commonJS({
         }
         var p = path3 + "." + self._extensions[i++];
         debug('stat "%s"', p);
-        fs2.stat(p, function(err2, stat) {
+        fs3.stat(p, function(err2, stat) {
           if (err2) return next(err2);
           if (stat.isDirectory()) return next();
           self.emit("file", p, stat);
@@ -22168,9 +22168,9 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join2(path3, self._index[i]);
+        var p = join3(path3, self._index[i]);
         debug('stat "%s"', p);
-        fs2.stat(p, function(err2, stat) {
+        fs3.stat(p, function(err2, stat) {
           if (err2) return next(err2);
           if (stat.isDirectory()) return next();
           self.emit("file", p, stat);
@@ -22183,7 +22183,7 @@ var require_send = __commonJS({
     SendStream.prototype.stream = /* @__PURE__ */ __name(function stream(path3, options) {
       var self = this;
       var res = this.res;
-      var stream2 = fs2.createReadStream(path3, options);
+      var stream2 = fs3.createReadStream(path3, options);
       this.emit("stream", stream2);
       stream2.pipe(res);
       function cleanup() {
@@ -34401,7 +34401,7 @@ var require_express2 = __commonJS({
 });
 
 // src/modules/platform/module.ts
-import { Global, Module as Module2, ValidationPipe } from "@nestjs/common";
+import { Global, Module as Module3, ValidationPipe } from "@nestjs/common";
 import { APP_INTERCEPTOR, APP_PIPE } from "@nestjs/core";
 import { CommonModule, OBSERVABLE_SERVICE as OBSERVABLE_SERVICE2, HTTP_CLIENT_FACTORY } from "@lark-apaas/nestjs-common";
 import { ConfigModule, ConfigService } from "@nestjs/config";
@@ -34411,7 +34411,7 @@ import { LoggerModule, AppLogger as AppLogger2, LoggerContextMiddleware } from "
 import { DataPaasModule, SqlExecutionContextMiddleware } from "@lark-apaas/nestjs-datapaas";
 import { AuthNPaasModule } from "@lark-apaas/nestjs-authnpaas";
 import { AutomationModule } from "@lark-apaas/nestjs-trigger";
-import { PLATFORM_HTTP_CLIENT as PLATFORM_HTTP_CLIENT3 } from "@lark-apaas/nestjs-common";
+import { PLATFORM_HTTP_CLIENT as PLATFORM_HTTP_CLIENT4 } from "@lark-apaas/nestjs-common";
 import { CapabilityModule } from "@lark-apaas/nestjs-capability";
 
 // src/middlewares/user-context/index.ts
@@ -35798,7 +35798,18 @@ StaticModule = _ts_decorate11([
   })
 ], StaticModule);
 
-// src/modules/platform/module.ts
+// src/modules/html-hot-update/html-hot-update.module.ts
+import { Module as Module2 } from "@nestjs/common";
+
+// src/modules/html-hot-update/html-hot-update.controller.ts
+import { Controller as Controller2, Post, Body, HttpCode, HttpStatus as HttpStatus2 } from "@nestjs/common";
+import { ApiExcludeController as ApiExcludeController2 } from "@nestjs/swagger";
+
+// src/modules/html-hot-update/html-hot-update.service.ts
+import { Injectable as Injectable10, Logger as Logger5, Inject as Inject3 } from "@nestjs/common";
+import { promises as fs2 } from "fs";
+import { join as join2, dirname } from "path";
+import { PLATFORM_HTTP_CLIENT as PLATFORM_HTTP_CLIENT3 } from "@lark-apaas/nestjs-common";
 function _ts_decorate12(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -35806,6 +35817,291 @@ function _ts_decorate12(decorators, target, key, desc) {
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 __name(_ts_decorate12, "_ts_decorate");
+function _ts_metadata8(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata8, "_ts_metadata");
+function _ts_param4(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param4, "_ts_param");
+var Mutex = class Mutex2 {
+  static {
+    __name(this, "Mutex");
+  }
+  locked = false;
+  waiting = [];
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise((resolve2) => {
+      this.waiting.push(() => {
+        this.locked = true;
+        resolve2();
+      });
+    });
+  }
+  release() {
+    if (this.waiting.length > 0) {
+      const next = this.waiting.shift();
+      next();
+    } else {
+      this.locked = false;
+    }
+  }
+};
+var HtmlHotUpdateService = class _HtmlHotUpdateService {
+  static {
+    __name(this, "HtmlHotUpdateService");
+  }
+  httpClient;
+  logger = new Logger5(_HtmlHotUpdateService.name);
+  /** 文件锁：冷启动更新和 innerapi 主动更新共用 */
+  fileLock = new Mutex();
+  /** 本地 HTML 文件目录（dist/dist/client，与 build.sh [4/5] 对齐） */
+  localHtmlDir = join2(process.cwd(), "dist", "client");
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+  * 任务一：冷启动时尝试更新 HTML 文件列表
+  *
+  * - 生产环境默认启用（模块仅在生产环境加载）
+  * - 失败则降级，使用部署时打包的 HTML 正常启动
+  * - 超时 3s，避免拉长冷启动耗时
+  */
+  async onModuleInit() {
+    const appID = this.getAppID();
+    if (!appID) {
+      this.logger.warn("Skip HTML hot update on startup: appID not found");
+      return;
+    }
+    try {
+      this.logger.log(`Startup HTML update: appID=${appID}`);
+      const result = await this.updateFromRemote(appID);
+      this.logger.log(`Startup HTML update complete: ${result.updatedFiles.length} updated, ${result.failedFiles.length} failed`);
+    } catch (error) {
+      this.logger.warn(`Startup HTML update failed (degraded to bundled HTML): ${error instanceof Error ? error.message : String(error)}, appID=${appID}`);
+    }
+  }
+  /**
+  * 从远端获取最新 HTML 文件并更新本地
+  *
+  * 调用方：
+  * 1) 冷启动更新（onModuleInit）
+  * 2) innerapi 主动更新（controller 调用）
+  */
+  async updateFromRemote(appID, commitID) {
+    const fileMap = await this.fetchLatestHtmlFiles(appID, commitID);
+    return this.writeHtmlFiles(fileMap);
+  }
+  /**
+  * 将文件内容写入本地 HTML 目录（带文件锁）
+  */
+  async writeHtmlFiles(fileMap) {
+    const result = {
+      updatedFiles: [],
+      failedFiles: []
+    };
+    const entries = Object.entries(fileMap);
+    if (entries.length === 0) {
+      return result;
+    }
+    await this.fileLock.acquire();
+    try {
+      for (const [filePath, content] of entries) {
+        try {
+          const localPath = join2(this.localHtmlDir, filePath);
+          await fs2.mkdir(dirname(localPath), {
+            recursive: true
+          });
+          await fs2.writeFile(localPath, content, "utf-8");
+          result.updatedFiles.push(filePath);
+        } catch (error) {
+          const reason = error instanceof Error ? error.message : String(error);
+          result.failedFiles.push({
+            filePath,
+            reason
+          });
+          this.logger.warn(`Failed to write HTML file ${filePath}: ${reason}`);
+        }
+      }
+    } finally {
+      this.fileLock.release();
+    }
+    return result;
+  }
+  /**
+  * 调用后端 GetLatestArtifactHtmlFiles 接口
+  */
+  async fetchLatestHtmlFiles(appID, commitID) {
+    const url = `/v1/app/${appID}/pipeline/frontend/latest_artifact/html_files`;
+    const body = {};
+    if (commitID) {
+      body.commitID = commitID;
+    }
+    const response = await this.httpClient.post(url, body, {
+      timeout: 3e3
+    });
+    if (!response.ok) {
+      throw new Error(`GetLatestArtifactHtmlFiles failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (data.BaseResp?.StatusCode && data.BaseResp.StatusCode !== 0) {
+      throw new Error(`GetLatestArtifactHtmlFiles error: ${data.BaseResp.StatusMessage}`);
+    }
+    if (!data.fileMap || Object.keys(data.fileMap).length === 0) {
+      throw new Error("GetLatestArtifactHtmlFiles returned empty fileMap");
+    }
+    return data.fileMap;
+  }
+  /**
+  * 从 CLIENT_BASE_PATH 提取 appID
+  * CLIENT_BASE_PATH 格式: /app/{appId}
+  */
+  getAppID() {
+    const basePath = process.env.CLIENT_BASE_PATH || "";
+    const match = basePath.match(/\/app\/([^/]+)/);
+    return match?.[1] ?? "";
+  }
+};
+HtmlHotUpdateService = _ts_decorate12([
+  Injectable10(),
+  _ts_param4(0, Inject3(PLATFORM_HTTP_CLIENT3)),
+  _ts_metadata8("design:type", Function),
+  _ts_metadata8("design:paramtypes", [
+    typeof PlatformHttpClient === "undefined" ? Object : PlatformHttpClient
+  ])
+], HtmlHotUpdateService);
+
+// src/modules/html-hot-update/html-hot-update.controller.ts
+function _ts_decorate13(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate13, "_ts_decorate");
+function _ts_metadata9(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata9, "_ts_metadata");
+function _ts_param5(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param5, "_ts_param");
+var UpdateHtmlFilesDto = class UpdateHtmlFilesDto2 {
+  static {
+    __name(this, "UpdateHtmlFilesDto");
+  }
+  commitID;
+  appID;
+};
+var HtmlHotUpdateController = class {
+  static {
+    __name(this, "HtmlHotUpdateController");
+  }
+  htmlHotUpdateService;
+  constructor(htmlHotUpdateService) {
+    this.htmlHotUpdateService = htmlHotUpdateService;
+  }
+  /**
+  * POST /__innerapi__/update_html_files
+  *
+  * 请求体: { commitID: string, appID: string }
+  * 响应:
+  *   成功: { code: 0, msg: "success" }
+  *   失败: { code: -1, msg: "update html failed: <error>" }
+  */
+  async updateHtmlFiles(body) {
+    const { commitID, appID } = body;
+    if (!commitID || !appID) {
+      return {
+        code: -1,
+        msg: "commitID and appID are required"
+      };
+    }
+    try {
+      const result = await this.htmlHotUpdateService.updateFromRemote(appID, commitID);
+      if (result.updatedFiles.length === 0 && result.failedFiles.length > 0) {
+        return {
+          code: -1,
+          msg: `update html failed: all ${result.failedFiles.length} files failed to write`
+        };
+      }
+      return {
+        code: 0,
+        msg: "success"
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return {
+        code: -1,
+        msg: `update html failed: ${errorMsg}`
+      };
+    }
+  }
+};
+_ts_decorate13([
+  Post("update_html_files"),
+  HttpCode(HttpStatus2.OK),
+  _ts_param5(0, Body()),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
+    typeof UpdateHtmlFilesDto === "undefined" ? Object : UpdateHtmlFilesDto
+  ]),
+  _ts_metadata9("design:returntype", Promise)
+], HtmlHotUpdateController.prototype, "updateHtmlFiles", null);
+HtmlHotUpdateController = _ts_decorate13([
+  ApiExcludeController2(),
+  Controller2("__innerapi__"),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
+    typeof HtmlHotUpdateService === "undefined" ? Object : HtmlHotUpdateService
+  ])
+], HtmlHotUpdateController);
+
+// src/modules/html-hot-update/html-hot-update.module.ts
+function _ts_decorate14(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate14, "_ts_decorate");
+var HtmlHotUpdateModule = class {
+  static {
+    __name(this, "HtmlHotUpdateModule");
+  }
+};
+HtmlHotUpdateModule = _ts_decorate14([
+  Module2({
+    controllers: [
+      HtmlHotUpdateController
+    ],
+    providers: [
+      HtmlHotUpdateService
+    ],
+    exports: [
+      HtmlHotUpdateService
+    ]
+  })
+], HtmlHotUpdateModule);
+
+// src/modules/platform/module.ts
+function _ts_decorate15(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate15, "_ts_decorate");
 var PLATFORM_MODULE_OPTIONS = /* @__PURE__ */ Symbol("PLATFORM_MODULE_OPTIONS");
 var PlatformModule = class _PlatformModule {
   static {
@@ -35876,6 +36172,11 @@ var PlatformModule = class _PlatformModule {
         // 开发环境由 Vite/Rspack dev server 的中间件处理 /static/* 请求
         ...process.env.NODE_ENV === "development" ? [] : [
           StaticModule
+        ],
+        // HTML 热更新模块（仅生产环境启用）
+        // 提供 innerapi 供 tce 服务触发 HTML 热更新，冷启动时也会尝试拉取最新 HTML
+        ...process.env.NODE_ENV === "development" ? [] : [
+          HtmlHotUpdateModule
         ]
       ],
       providers: [
@@ -35898,7 +36199,7 @@ var PlatformModule = class _PlatformModule {
         },
         PlatformHttpClientService,
         {
-          provide: PLATFORM_HTTP_CLIENT3,
+          provide: PLATFORM_HTTP_CLIENT4,
           useFactory: /* @__PURE__ */ __name((svc) => svc.instance, "useFactory"),
           inject: [
             PlatformHttpClientService
@@ -35925,7 +36226,7 @@ var PlatformModule = class _PlatformModule {
         LoggerModule,
         CommonModule,
         OBSERVABLE_SERVICE2,
-        PLATFORM_HTTP_CLIENT3,
+        PLATFORM_HTTP_CLIENT4,
         HTTP_CLIENT_FACTORY,
         PlatformHttpClientService,
         CapabilityModule,
@@ -35958,9 +36259,9 @@ var PlatformModule = class _PlatformModule {
     }
   }
 };
-PlatformModule = _ts_decorate12([
+PlatformModule = _ts_decorate15([
   Global(),
-  Module2({})
+  Module3({})
 ], PlatformModule);
 
 // src/setup.ts
@@ -36058,6 +36359,8 @@ export {
   DevToolsModule,
   DevToolsV2Module2 as DevToolsV2Module,
   FileService,
+  HtmlHotUpdateModule,
+  HtmlHotUpdateService,
   PlatformHttpClientService,
   PlatformModule,
   StaticModule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-nestjs-core",
-  "version": "1.1.32",
+  "version": "1.1.33-alpha.0",
   "description": "FullStack Nestjs Core",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,7 +43,7 @@
     "@lark-apaas/http-client": "^0.1.2",
     "@lark-apaas/nestjs-authnpaas": "^1.0.2",
     "@lark-apaas/nestjs-authzpaas": "^0.1.2",
-    "@lark-apaas/nestjs-capability": "^0.1.10",
+    "@lark-apaas/nestjs-capability": "^0.1.6",
     "@lark-apaas/nestjs-common": "^0.1.4",
     "@lark-apaas/nestjs-datapaas": "^1.0.11",
     "@lark-apaas/nestjs-logger": "^1.0.10",