openyida 2026.9.1 → 2026.9.2-2

package/README.md

@@ -167,11 +167,13 @@ For a user-facing list of supported features and matching CLI commands, see [Ope
 
 ```bash
 openyida create-app "CRM"
-openyida create-app --name "CRM" --desc "Customer management" --theme deepBlue
+openyida create-app --name "CRM" --desc "Customer management" --theme-file ./app-theme.css --nav-theme light --logo-source appIcon --layout l_shape
 openyida app-list --size 20
 openyida corp-efficiency
 openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
 openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
+openyida sample openyida-scaffold form-fields --output .cache/openyida/forms/customer-fields.json
+openyida sample openyida-scaffold canvas-form-drawer --output project/pages/src/customer-entry.canvas.jsx --var APP_TYPE=APP_XXX --var FORM_UUID=FORM_XXX
 openyida get-schema APP_XXX FORM_XXX
 openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,Status"
 openyida get-schema APP_XXX --all --output-dir .cache/schemas
@@ -200,7 +202,7 @@ openyida configure-process APP_XXX FORM_XXX .cache/openyida/process/process.json
 openyida process preview APP_XXX PROC_INST_XXX --output .cache/openyida/process/process.html
 openyida data query form APP_XXX FORM_XXX --page 1 --size 20
 openyida data query form APP_XXX FORM_XXX --dynamic-order '{"dateField_xxx":"-"}'
-openyida data create form APP_XXX FORM_XXX --data-file .cache/openyida/data-import/record.json
+openyida data create form APP_XXX FORM_XXX --expect-form-name 客户 --expect-form-type receipt --data-file .cache/openyida/data-import/record.json
 openyida get-permission APP_XXX FORM_XXX
 ```
 
@@ -388,7 +390,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida app-list [--size N]` | List my Yida apps |
 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency overview and detail reports |
 | `openyida create-app "<name>"\|--name <name> [options] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a Yida app |
-| `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue] [--hide-app-nav\|--show-app-nav]` | Update app info |
+| `openyida update-app <appType> [--name "..."] [--theme-file <css>] [--nav-theme light\|dark\|white\|gray] [--logo-source appIcon\|customImage] [--layout side\|top\|l_shape] [--hide-app-nav\|--show-app-nav]` | Update app info |
 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` | Enable a Yida app |
 | `openyida app-offline <appType> [--to-ding-app-center] [--show-app-center]` | Disable a Yida app |
 | `openyida nav-group <list\|create\|rename\|delete\|move\|order\|auto-order\|hide\|show> <appType> ...` | Manage app sidebar navigation groups |
@@ -401,7 +403,8 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form create <appType> "<formTitle>" <fieldsJsonFile> [--icon auto\|<iconName>] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form icons [--json]` | List available form navigation icons |
 | `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
 | `openyida create-form update <appType> ... [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
 | `openyida create-form patch <appType> <formUuid> <patchJsonOrFile> [--open\|--no-open]` | Update a form page |
@@ -422,15 +425,12 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida publish <src> <appType> <formUuid> [--health-check] [--force] [--canvas] [--auto-nav-order] [--open\|--no-open]` | Compile and publish custom page |
 | `openyida update-form-config <appType> ...` | Update form configuration |
 | `openyida get-form-config <appType> <formUuid> [--json]` | Query form configuration |
-| `openyida form-detail-style apply <appType> <formUuid> [--css file\|--preset clean-card] [--json]` | Manage form detail page style |
-| `openyida form-detail-style remove <appType> <formUuid> [--json]` | Manage form detail page style |
-| `openyida form-detail-style check <appType> <formUuid> [--json]` | Manage form detail page style |
 
 ### Data & Permissions
 
 | Command | Description |
 |---------|-------------|
-| `openyida data <query\|get\|create\|update> <resource> ... \| delete form <appType> <formUuid> --inst-id <id> --confirm [--json]` | Unified data management (form/process/task/subform) |
+| `openyida data <query\|get\|create\|update> <resource> ... \| delete form <appType> <formUuid> --inst-id <id> --expect-form-name <name> --expect-form-type receipt --confirm [--json]` | Unified data management (form/process/task/subform) |
 | `openyida task-center <type> [options]` | Global task center (todo/processed/cc etc.) |
 | `openyida basic-info <overview\|commodity\|grant\|capacity\|quota\|abs-path\|dataflow\|i18n\|domain>` | Query organization basic info, capacity, quotas, and domain settings |
 | `openyida read-dingtalk-doc <docUrl> [--output <file>] [--json]` | Fetch Markdown content from a DingTalk document |

package/bin/yida.js

@@ -882,14 +882,8 @@ async function main() {
       break;
     }
 
-    case 'form-detail-style': {
-      const { run: runFormDetailStyle } = require('../lib/app/form-detail-style');
-      await runFormDetailStyle(args);
-      break;
-    }
-
     case 'update-app': {
-      if (args.length < 2) {
+      if (args.length < 2 && !hasHelpFlag(args)) {
         throwCliUsage(t('cli.update_app_usage'), t('cli.update_app_example'));
       }
       const { run: runUpdateApp } = require('../lib/app/update-app');

package/lib/app/canvas-compile.js

@@ -139,6 +139,13 @@ const BARE_DEPENDENCY_GLOBALS = Object.freeze({
 const CANVAS_RUNTIME_GLOBAL_IDENTIFIERS = new Set([
   ...Object.keys(globals.builtin),
   ...Object.keys(globals.browser),
+  // globals follows its package release cadence; keep modern standards that
+  // are already available in supported browsers explicit until that list catches up.
+  'URLPattern',
+  'navigation',
+  'cookieStore',
+  'scheduler',
+  'Temporal',
   'iframeWindow',
   'parentWindow',
 ]);

package/lib/app/create-app.js

@@ -2,6 +2,7 @@
  * create-app.js - 宜搭应用创建命令
  *
  * 用法：openyida create-app "<appName>" [description] [icon] [iconColor] [colour] [navTheme] [layoutDirection]
+ *       openyida create-app --name "<appName>" --theme-file ./app-theme.css [--nav-theme light] [--logo-source appIcon] [--layout l_shape]
  */
 
 'use strict';
@@ -20,13 +21,65 @@ const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff
 const { throwCommandError } = require('../core/command-errors');
 const { assertPresetThemeKey } = require('./theme-presets');
 const { resolveBuilderAiSource } = require('./builder-ai-source');
+const { normalizeCssColorToHex, readThemeCssFile } = require('./custom-theme');
+const {
+  applyCustomThemeUpdate,
+  assertLogoSource,
+  assertNavTheme,
+  normalizeLayoutDirection,
+} = require('./update-app');
 
 const DEFAULT_APP_OPTIONS = {
-  icon: 'xian-yingyong',
   iconColor: '#0089FF',
   colour: 'podBlue',
 };
 
+// 与 yida-next/src/components/IconSelect/Icon.js 保持一致。
+const APP_ICON_NAMES = Object.freeze([
+  'xian-xinwen',
+  'xian-diqiu',
+  'xian-zhengfu',
+  'xian-qiche',
+  'xian-yingyong',
+  'xian-feiji',
+  'xian-xueshimao',
+  'xian-diannao',
+  'xian-qiye',
+  'xian-gongzuozheng',
+  'xian-danju',
+  'xian-gouwuche',
+  'xian-shichang',
+  'xian-xinyongka',
+  'xian-jingli',
+  'xian-huodong',
+  'xian-falv',
+  'xian-jiangbei',
+  'xian-baogao',
+  'xian-liucheng',
+  'huoche',
+  'chaxun',
+  'shenbao',
+  'daka',
+]);
+const DEFAULT_CREATE_LAYOUT_DIRECTION = 'l_shape';
+
+function selectRandomAppIcon(random = Math.random) {
+  const index = Math.min(APP_ICON_NAMES.length - 1, Math.floor(random() * APP_ICON_NAMES.length));
+  return APP_ICON_NAMES[Math.max(0, index)];
+}
+
+function applyThemeFileCreateDefaults(params, themeFileInfo) {
+  if (!params || !params.themeFile || !themeFileInfo) {return params;}
+  const iconColor = normalizeCssColorToHex(themeFileInfo.themeColor);
+  if (!iconColor) {
+    throw new Error(`--color-brand1-6 无法转换为应用图标色: ${themeFileInfo.themeColor}`);
+  }
+  return {
+    ...params,
+    iconColor,
+  };
+}
+
 const INDUSTRY_APP_DEFAULTS = [
   {
     name: 'legal',
@@ -147,7 +200,7 @@ function readOptionValue(args, index, optionName) {
   return value;
 }
 
-function parseCreateAppArgs(args) {
+function parseCreateAppArgs(args, random = Math.random) {
   const params = {
     appName: null,
     description: null,
@@ -155,7 +208,9 @@ function parseCreateAppArgs(args) {
     iconColor: null,
     colour: null,
     navTheme: null,
+    logoSource: null,
     layoutDirection: null,
+    themeFile: null,
     locale: null,
   };
   const positional = [];
@@ -194,6 +249,16 @@ function parseCreateAppArgs(args) {
         params.navTheme = readOptionValue(args, index, arg);
         index++;
         break;
+      case '--logo-source':
+      case '--logoSource':
+        params.logoSource = readOptionValue(args, index, arg);
+        index++;
+        break;
+      case '--theme-file':
+      case '--custom-theme-file':
+        params.themeFile = readOptionValue(args, index, arg);
+        index++;
+        break;
       case '--layout':
       case '--layout-direction':
       case '--layoutDirection':
@@ -224,13 +289,33 @@ function parseCreateAppArgs(args) {
   params.appName = params.appName || positional[0] || null;
   params.description = params.description || positional[1] || params.appName;
 
+  const explicitIcon = params.icon || positional[2] || null;
+  params.iconWasExplicit = !!explicitIcon;
   const inferredDefaults = inferAppDefaults(params.appName, params.description);
-  params.icon = params.icon || positional[2] || inferredDefaults.icon;
+  params.icon = explicitIcon || (
+    inferredDefaults.industry === 'default'
+      ? selectRandomAppIcon(random)
+      : inferredDefaults.icon
+  );
   params.iconColor = params.iconColor || positional[3] || inferredDefaults.iconColor;
   params.colour = params.colour || positional[4] || inferredDefaults.colour;
   assertPresetThemeKey(params.colour);
   params.navTheme = params.navTheme || positional[5] || null;
-  params.layoutDirection = params.layoutDirection || positional[6] || null;
+  params.layoutDirection = normalizeLayoutDirection(
+    params.layoutDirection || positional[6] || DEFAULT_CREATE_LAYOUT_DIRECTION
+  );
+  assertNavTheme(params.navTheme);
+  assertLogoSource(params.logoSource);
+  if (params.logoSource && !params.themeFile) {
+    throw new Error('--logo-source must be used with --theme-file so the navigation theme is saved atomically');
+  }
+  if (params.themeFile) {
+    params.navTheme = params.navTheme || 'light';
+    params.logoSource = params.logoSource || 'appIcon';
+    if (params.logoSource !== 'appIcon') {
+      throw new Error('create-app only supports --logo-source appIcon because a new app has no homepageLogo image yet');
+    }
+  }
   params.industry = inferredDefaults.industry;
 
   return params;
@@ -269,10 +354,10 @@ function buildCreateAppPayload(params, auth, contentLocale, openExclusive, openP
     openPhysicColumn,
     openIsolationDatabase: 'n',
     openExclusiveUnit: 'n',
-    createWithModernTheme: 'y',
     group: 'ALL',
     fromBuilderAi: 'y',
     builderAiSource: resolveBuilderAiSource(),
+    createWithModernTheme: 'y',
   };
   if (navTheme) {
     payload.navTheme = navTheme;
@@ -305,7 +390,13 @@ async function run(args) {
     chalkError(t('create_app.usage'), { hint: t('create_app.example') });
   }
 
-  const { appName, description, icon, iconColor, colour, navTheme, layoutDirection } = params;
+  // 在远端创建应用前先完成本地主题校验，避免 CSS 缺失或 token 非法时留下半成品应用。
+  if (params.themeFile) {
+    const themeFileInfo = readThemeCssFile(params.themeFile);
+    Object.assign(params, applyThemeFileCreateDefaults(params, themeFileInfo));
+  }
+
+  const { appName, description, icon, iconColor, colour, navTheme, logoSource, layoutDirection, themeFile } = params;
 
   const { c, banner, step, label, success: chalkSuccess, result: chalkResult } = require('../core/chalk');
 
@@ -313,7 +404,7 @@ async function run(args) {
   label('Name', appName);
   label('Desc', description);
   label('Icon', `${icon} ${c.dim}(${iconColor})${c.reset}`);
-  label('Theme', `${colour} / ${navTheme || 'default'} / ${layoutDirection || 'default'}`);
+  label('Theme', `${themeFile || colour} / ${navTheme || 'default'} / ${logoSource || 'default'} / ${layoutDirection || 'default'}`);
 
   // Step 1: 读取登录态
   step(1, t('common.step_login', 1));
@@ -356,6 +447,29 @@ async function run(args) {
     const appUrl = `${authRef.baseUrl}/${appType}/workbench`;
     const corpId = authRef.corpId || (authRef.authData && authRef.authData.corp_id) || '';
 
+    if (themeFile) {
+      step(3, t('update_app.step_update'));
+      const themeResponse = await applyCustomThemeUpdate(appType, {
+        themeFile,
+        navTheme,
+        logoSource,
+        layoutDirection,
+      }, authRef);
+      if (!themeResponse || !themeResponse.success) {
+        const errorMsg = themeResponse
+          ? themeResponse.errorMsg || t('common.unknown_error')
+          : t('common.request_failed');
+        console.log(JSON.stringify({
+          success: false,
+          appCreated: true,
+          appType,
+          themeApplied: false,
+          error: errorMsg,
+        }));
+        throwCommandError(t('create_app.failed', errorMsg));
+      }
+    }
+
     chalkResult(true, t('create_app.success'), [
       ['appType', appType],
       ['Corp ID', corpId || t('common.unknown_error')],
@@ -366,7 +480,17 @@ async function run(args) {
     if (prdFile) {updatePrdCorpId(prdFile, corpId, appType, authRef.baseUrl);}
 
     console.log(JSON.stringify(withBrowserHandoff(
-      { success: true, appType, appName, corpId, url: appUrl },
+      {
+        success: true,
+        appType,
+        appName,
+        corpId,
+        url: appUrl,
+        themeFile: themeFile || undefined,
+        navTheme: themeFile ? navTheme : undefined,
+        logoSource: themeFile ? logoSource : undefined,
+        layoutDirection,
+      },
       appUrl,
       { stage: 'create_app_success', title: appName },
       openOption.mode
@@ -379,4 +503,13 @@ async function run(args) {
   }
 }
 
-module.exports = { run, parseCreateAppArgs, inferAppDefaults, buildCreateAppPayload };
+module.exports = {
+  APP_ICON_NAMES,
+  DEFAULT_CREATE_LAYOUT_DIRECTION,
+  run,
+  parseCreateAppArgs,
+  inferAppDefaults,
+  selectRandomAppIcon,
+  applyThemeFileCreateDefaults,
+  buildCreateAppPayload,
+};

package/lib/app/create-form/api-path.js

@@ -11,6 +11,8 @@
  * @param {string} [options.prefix]        额外的路径前缀（会以 / 拼接）
  * @param {string} [options.namespace]     命名空间，默认 dingtalk
  * @param {'formdesign'|'formnav'} [options.queryModule] 查询模块，默认 formdesign
+ * @param {string} [options.api]            页面请求标识，例如 Nav.update
+ * @param {boolean} [options.mock]          是否使用 mock 接口
  * @param {boolean} [options.addTimestamp] 是否追加 _stamp 时间戳查询参数
  * @returns {string} 拼接完成的 API 请求路径
  */
@@ -19,14 +21,26 @@ function buildApiPath(appType, apiName, options = {}) {
     prefix = '',
     namespace = 'dingtalk',
     queryModule = 'formdesign',
+    api,
+    mock,
     addTimestamp = false,
   } = options;
   if (queryModule !== 'formdesign' && queryModule !== 'formnav') {
     throw new Error(`Unsupported query module: ${queryModule}`);
   }
   const prefixPath = prefix ? `/${prefix}` : '';
-  const timestamp = addTimestamp ? `?_stamp=${Date.now()}` : '';
-  return `/${namespace}/web/${appType}${prefixPath}/query/${queryModule}/${apiName}.json${timestamp}`;
+  const queryParams = [];
+  if (api) {
+    queryParams.push(`_api=${encodeURIComponent(api)}`);
+  }
+  if (mock !== undefined) {
+    queryParams.push(`_mock=${String(Boolean(mock))}`);
+  }
+  if (addTimestamp) {
+    queryParams.push(`_stamp=${Date.now()}`);
+  }
+  const query = queryParams.length > 0 ? `?${queryParams.join('&')}` : '';
+  return `/${namespace}/web/${appType}${prefixPath}/query/${queryModule}/${apiName}.json${query}`;
 }
 
 module.exports = {

package/lib/app/create-form/args.js

@@ -85,6 +85,7 @@ function createParseArgs(dependencies) {
       layout: 'single',
       theme: 'default',
       labelAlign: 'top',
+      icon: 'auto',
       contentLocale: null,
       browserOpenMode: openOption.mode,
     };
@@ -104,6 +105,12 @@ function createParseArgs(dependencies) {
         options.labelAlign = args[i + 1];
         args.splice(i, 2);
         i--;
+      } else if (args[i] === '--icon' && i + 1 < args.length) {
+        options.icon = args[i + 1];
+        args.splice(i, 2);
+        i--;
+      } else if (args[i] === '--icon') {
+        throwCreateFormError('--icon requires a value', 'CREATE_FORM_INVALID_ARGUMENTS');
       } else if ((args[i] === '--locale' || args[i] === '--content-locale' || args[i] === '--lang') && i + 1 < args.length) {
         options.contentLocale = args[i + 1];
         if (!normalizeYidaLocale(options.contentLocale)) {
@@ -138,6 +145,13 @@ function createParseArgs(dependencies) {
 
     const mode = args[0];
 
+    if (mode === 'icons' || mode === 'list-icons') {
+      return {
+        mode: 'icons',
+        ...options
+      };
+    }
+
     if (mode === 'validate-fields') {
       if (args.length === 2) {
         return {

package/lib/app/create-form/nav-icon-service.js

@@ -0,0 +1,202 @@
+'use strict';
+
+const FORM_NAVIGATION_UPDATE_KEYS = [
+  'gmtModified',
+  'parentNavUuid',
+  'hidden',
+  'mobileHidden',
+  'i18nTitle',
+  'isNewReport',
+  'id',
+  'isNewForm',
+  'slug',
+  'formType',
+  'formUuid',
+  'navUuid',
+  'navType',
+  'isNew',
+  'gmtCreate',
+  'parentId',
+  'url',
+  'topicId',
+  'displayType',
+  'relateFormUuid',
+  'processCode',
+  'listOrder',
+  'formStatus',
+  'relateFormType',
+];
+
+function buildFormNavigationIconUpdatePayload(navigationNode, icon) {
+  const updatePayload = {
+    _locale_time_zone_offset: 28800000,
+  };
+  FORM_NAVIGATION_UPDATE_KEYS.forEach(function (key) {
+    if (navigationNode[key] !== undefined) {
+      updatePayload[key] = key === 'i18nTitle' && navigationNode[key] !== null && typeof navigationNode[key] === 'object'
+        ? String(navigationNode[key])
+        : navigationNode[key];
+    }
+  });
+
+  const navigationTitle = navigationNode.title || navigationNode.i18nTitle || {};
+  updatePayload.title = typeof navigationTitle === 'string'
+    ? navigationTitle
+    : JSON.stringify(navigationTitle);
+  updatePayload.formUuid = navigationNode.formUuid || 'NAV-SYSTEM-FROM-ME-UUID';
+  updatePayload.icon = icon;
+  return updatePayload;
+}
+
+function createFormNavIconService(dependencies) {
+  const {
+    buildApiPath,
+    requestWithAutoLogin,
+    sendGetRequest,
+    sendPostRequest,
+    throwCreateFormError,
+    sanitizeFailureResult,
+    candidateLimit = 8,
+  } = dependencies;
+
+  function flattenNavigationNodes(nodes, output) {
+    const resultNodes = output || [];
+    (nodes || []).forEach(function (node) {
+      resultNodes.push(node);
+      if (Array.isArray(node.children)) {
+        flattenNavigationNodes(node.children, resultNodes);
+      }
+    });
+    return resultNodes;
+  }
+
+  async function fetchFormNavigationList(authRef, appType) {
+    const navigationResult = await requestWithAutoLogin(function (auth) {
+      return sendGetRequest(
+        auth.baseUrl,
+        buildApiPath(appType, 'getFormNavigationListByOrder', {
+          queryModule: 'formnav',
+          addTimestamp: true,
+        }),
+        {
+          _api: 'Nav.queryList',
+          _mock: false,
+          _locale_time_zone_offset: 28800000,
+        }
+      );
+    }, authRef);
+
+    if (!navigationResult || navigationResult.success === false || !Array.isArray(navigationResult.content)) {
+      const message = navigationResult
+        ? navigationResult.errorMsg || navigationResult.message || 'Failed to fetch form navigation list'
+        : 'Failed to fetch form navigation list';
+      throwCreateFormError(message, 'CREATE_FORM_NAV_ICON_LIST_FAILED', {
+        appType,
+        result: sanitizeFailureResult(navigationResult),
+      });
+    }
+
+    return flattenNavigationNodes(navigationResult.content);
+  }
+
+  function resolveFormNavigationNode(nodes, formUuid) {
+    const exactMatches = (nodes || []).filter(function (node) {
+      return node && (node.formUuid === formUuid || node.navUuid === formUuid);
+    });
+    const relatedMatches = (nodes || []).filter(function (node) {
+      return node && node.relateFormUuid === formUuid;
+    });
+    const matches = exactMatches.length > 0 ? exactMatches : relatedMatches;
+    if (matches.length !== 1) {
+      return null;
+    }
+    return matches[0];
+  }
+
+  async function updateCreatedFormNavigationIcon(authRef, appType, formUuid, icon) {
+    const navigationNodes = await fetchFormNavigationList(authRef, appType);
+    const navigationNode = resolveFormNavigationNode(navigationNodes, formUuid);
+    if (!navigationNode) {
+      throwCreateFormError('Created form navigation node could not be resolved uniquely.', 'CREATE_FORM_NAV_ICON_NODE_NOT_FOUND', {
+        appType,
+        formUuid,
+        candidates: navigationNodes.filter(function (node) {
+          return node && node.navType !== 'SYSTEM';
+        }).slice(0, candidateLimit).map(function (node) {
+          return {
+            id: node.id,
+            navUuid: node.navUuid,
+            formUuid: node.formUuid,
+            relateFormUuid: node.relateFormUuid,
+            formType: node.formType,
+          };
+        }),
+      });
+    }
+
+    const updatePayload = buildFormNavigationIconUpdatePayload(navigationNode, icon);
+
+    const updateResult = await requestWithAutoLogin(function (auth) {
+      return sendPostRequest(
+        auth.baseUrl,
+        buildApiPath(appType, 'updateFormNavigation', {
+          queryModule: 'formnav',
+          api: 'Nav.update',
+          mock: false,
+          addTimestamp: true,
+        }),
+        updatePayload,
+        formUuid,
+        auth,
+        {
+          appType,
+          referer: `${auth.baseUrl}/${appType}/admin/${formUuid}`,
+        }
+      );
+    }, authRef);
+
+    if (!updateResult || updateResult.success === false) {
+      const message = updateResult
+        ? updateResult.errorMsg || updateResult.message || 'Failed to update form navigation icon'
+        : 'Failed to update form navigation icon';
+      throwCreateFormError(message, 'CREATE_FORM_NAV_ICON_UPDATE_FAILED', {
+        appType,
+        formUuid,
+        navUuid: navigationNode.navUuid,
+        icon,
+        result: sanitizeFailureResult(updateResult),
+      });
+    }
+
+    const updatedNavigationNodes = await fetchFormNavigationList(authRef, appType);
+    const updatedNavigationNode = resolveFormNavigationNode(updatedNavigationNodes, formUuid);
+    if (!updatedNavigationNode || updatedNavigationNode.icon !== icon) {
+      throwCreateFormError('Form navigation icon readback did not match the requested icon.', 'CREATE_FORM_NAV_ICON_READBACK_MISMATCH', {
+        appType,
+        formUuid,
+        navUuid: navigationNode.navUuid,
+        expectedIcon: icon,
+        actualIcon: updatedNavigationNode && updatedNavigationNode.icon,
+      });
+    }
+
+    return {
+      id: updatedNavigationNode.id,
+      navUuid: updatedNavigationNode.navUuid,
+      icon: updatedNavigationNode.icon,
+    };
+  }
+
+  return {
+    fetchFormNavigationList,
+    flattenNavigationNodes,
+    resolveFormNavigationNode,
+    updateCreatedFormNavigationIcon,
+  };
+}
+
+module.exports = {
+  FORM_NAVIGATION_UPDATE_KEYS,
+  buildFormNavigationIconUpdatePayload,
+  createFormNavIconService,
+};