@jira-deploy/core 1.0.14 → 1.0.16

package/tools/cd.js

@@ -1,27 +1,47 @@
 /**
- * CI Golden Image 相關 tools
+ * CD 相關 tools
  *   - create_cd_ticket
  */
-import {error, getModuleName, getServerList, ok, today} from './helpers.js';
+import {Poller} from '../poller.js';
+import {ensureCIReadyForCD} from './ci.js';
+import {handleSendJabberMessage} from './jabber.js';
+import {handleGetReleaseManager, handleWaitForComment} from './release.js';
+import {error, getModuleName, getPollIntervalMs, getPollTimeoutMs, getServerList, ok, today} from './helpers.js';
 import {
   CD_FIELD_IDS,
   CI_FIELD_IDS,
-  SERVERS,
   DEPT_CODES,
   ENV_CODES,
   FIELD_OPTIONS,
+  getDeployConfig,
   ISSUE_TYPE_IDS,
   JIRA_PROJECT_ID,
   LIBRARY_MODULE_IDS,
+  MODULE_MAP,
+  REPO_LABEL_MAP,
+  REPO_MAPS,
+  resolveAccountId,
   SYSTEM_CODES,
   SYSTEM_MODULES,
   SYSTEM_TO_DEPT_MAP,
-  MODULE_MAP,
-  REPO_MAPS,
-  REPO_LABEL_MAP,
 } from '../constants/index.js';
-import {SERVER_MODULE_MAP} from '../constants/server.js';
 
+// ── Flow Definition ──────────────────────────────────────────────
+
+/**
+ * CD 狀態流程定義
+ *
+ * 完整流程：
+ *   TO DO → (Accept) → PREPARE FOR DEPLOY → (Prepare to create deployment ticket) 自動開立 Deployment 單
+ *   → PREPARE FOR DEPLOY → (Apply for approval) → WAIT APPROVAL → (Approved，依環境處理簽核) → WAIT FOR SEND NOTICE EMAIL
+ *   → (To Wait Deploy) → Wait Deploy → (Apply for close) → Wait APPROVAL TO CLOSED → (To Done) → Done
+ *
+ * 簽核規則：
+ *   - DEV：直接 Approve
+ *   - STG：指派給當日 Release Manager，等待簽核
+ *   - UAT：依 env/config 指派第一階段與最終簽核人
+ *   - PRD：依 env/config 指派第一~三階段與最終簽核人
+ */
 // ── Schema definitions ───────────────────────────────────────────
 export function getCDToolDefinitions() {
   return [
@@ -48,11 +68,6 @@ export function getCDToolDefinitions() {
             type: 'boolean',
             description: '(選填) 是否要集群部署，預設為 true',
           },
-          summary: {
-            type: 'string',
-            description:
-              '（選填）自訂標題，不填則自動生成：[IBK][STG] 程式上版作業申請單_YYYYMMDD (CD deployment with {release_version})',
-          },
           ciTicket: {
             type: 'string',
             description:
@@ -68,15 +83,11 @@ export function getCDToolDefinitions() {
           },
           moduleChild: {
             type: 'string',
-            description: '(選填) 模組 child 名稱；不填時預設同 systemCode 小寫',
+            description: '(選填) 模組 child 名稱',
           },
           restartOnly: {
             type: 'boolean',
-            description: '(選填) 是否只重啟不部署',
-          },
-          extraVars: {
-            type: 'string',
-            description: '(選填) 自訂部署 extra vars JSON 字串；不填時依 system/module/env 自動生成',
+            description: '(選填) 是否只重啟不部署，只跑 before after script，預設為 false',
           },
           metaTest: {
             type: 'boolean',
@@ -97,18 +108,13 @@ export function getCDToolDefinitions() {
 /**
  * 建立 CD 上版單
  */
-export async function handleCreateCDTicket(args, {jira, notifier}) {
+export async function handleCreateCDTicket(args, {jira, notifier, progress: reportProgress}) {
   try {
-    const envCode = (args.environment ?? '').toLowerCase();
+    const envCode = (args.environment ?? 'STG').toLowerCase();
     const ciTicket = args.ciTicket ?? args.linkedCiKey;
-    const clusterDeploy = typeof args.clusterDeploy === 'string'
-      ? args.clusterDeploy.split(',').map((cluster) => cluster.trim()).filter(Boolean)
-      : null;
-    const isClusterDeploy = args.isClusterDeploy ?? (envCode !== 'dev');
     const normalizedArgs = {
       ...args,
       ciTicket,
-      isClusterDeploy,
       environment: envCode,
     };
 
@@ -121,30 +127,34 @@ export async function handleCreateCDTicket(args, {jira, notifier}) {
       });
     }
 
-    // extra_vars 參數邏輯：只對 ibk/cwa 的 prd 環境生效
-    const serverList = clusterDeploy ?? getServerList(
-      normalizedArgs.systemCode,
-      normalizedArgs.environment,
-      normalizedArgs.metaTest,
-    );
+    const moduleResolution = await resolveCDModules(normalizedArgs, {jira});
+    if (moduleResolution.needsModuleSelection) return ok(moduleResolution);
+
+    if (!normalizedArgs.dryRun && normalizedArgs.ciTicket) {
+      await ensureCIReadyForCD(
+        {issueKey: normalizedArgs.ciTicket, environment: envCode},
+        {jira, notifier, progress: reportProgress},
+      );
+    }
+
+    const serverList = getModuleServerList(normalizedArgs, moduleResolution.modules);
 
     let goldenImageVersion = '';
 
-    // 先取 CI 單的 deploy_version JSON（customfield_13438，如 {"cwa_ap_version":"0.0.12"}）
+    // 先取 CI 單的 releaseVersion JSON（customfield_13438，如 {"cwa_ap_version":"0.0.12"}）
     let ciReleaseVersion = '';
     if (normalizedArgs.ciTicket) {
       try {
         const ciFields = await jira.getIssueFields(normalizedArgs.ciTicket, [CI_FIELD_IDS.releaseVersion]);
         ciReleaseVersion = ciFields?.[CI_FIELD_IDS.releaseVersion] ?? '';
-        if (!ciReleaseVersion) {
-          const legacyFields = await jira.getIssueFields(normalizedArgs.ciTicket, ['customfield_14705']);
-          ciReleaseVersion = legacyFields?.customfield_14705 ?? '';
-        }
+
+        // 如果找不到 CI 單的 releaseVersion，用 CI 單的 summary 抓 golden image version
         if (!ciReleaseVersion) {
           const summaryFields = await jira.getIssueFields(normalizedArgs.ciTicket, ['summary']);
           const summaryMatch = summaryFields?.summary?.match(/\bfor\s+([0-9]+(?:\.[0-9]+){2,})\b/i);
           ciReleaseVersion = summaryMatch?.[1] ?? '';
         }
+
         if (ciReleaseVersion) {
           try {
             const parsed = JSON.parse(ciReleaseVersion);
@@ -163,14 +173,14 @@ export async function handleCreateCDTicket(args, {jira, notifier}) {
     const dateStr = today().replace(/-/g, '');
     const displayEnv =
       normalizedArgs.metaTest ? 'prd' : (envCode === 'prd' || envCode === 'prd/dr') ? 'prd/dr' : envCode;
-    const summaryVersion = goldenImageVersion || normalizedArgs.ciTicket || '';
+    const summaryVersion = goldenImageVersion || '';
     const autoSummary = `[${normalizedArgs.systemCode}][${displayEnv.toUpperCase()}] 程式上版作業申請單_${dateStr} (CD deployment with ${summaryVersion})`;
 
     const fields = {
       project: {key: JIRA_PROJECT_ID},
       issuetype: {id: ISSUE_TYPE_IDS.CD},
       duedate: today(),
-      summary: normalizedArgs.summary ?? autoSummary,
+      summary: autoSummary,
     };
 
     // CID_deploy_version：deploy JSON 優先，否則 release_version
@@ -202,19 +212,19 @@ export async function handleCreateCDTicket(args, {jira, notifier}) {
     fields[CD_FIELD_IDS.serverList] = serverList.map((c) => c.trim()).join('\n');
 
     // CID_restart_only（option id 格式）
-    if (normalizedArgs.restartOnly !== undefined) {
-      fields[CD_FIELD_IDS.restartOnly] = {
-        id: normalizedArgs.restartOnly
-          ? FIELD_OPTIONS.restartOnly.true
-          : FIELD_OPTIONS.restartOnly.false,
-      };
-    }
+    fields[CD_FIELD_IDS.restartOnly] = {
+      id: normalizedArgs.restartOnly
+        ? FIELD_OPTIONS.restartOnly.true
+        : FIELD_OPTIONS.restartOnly.false,
+    };
 
-    fields[CD_FIELD_IDS.extraVars] = normalizedArgs.extraVars
-      ?? await getExtraVarsJson({serverList, ...normalizedArgs}, {jira});
+    fields[CD_FIELD_IDS.extraVars] = await getExtraVarsJson({
+      modules: moduleResolution.modules,
+      ...normalizedArgs,
+    }, {jira});
 
     // 預先生成 description（dryRun 預覽用，正式開單後也會再呼叫 updateIssue 寫入）
-    let previewDescription = generateCDDescription(ciReleaseVersion || '');
+    let previewDescription = generateCDDescription(goldenImageVersion || ciReleaseVersion);
     if (normalizedArgs.ciTicket) {
       const releaseNotesStr = await generateReleaseNotes(
         jira,
@@ -251,7 +261,7 @@ export async function handleCreateCDTicket(args, {jira, notifier}) {
     // 更新 description 表格，因為 cid jira worker 會將 init 的表格回朔
     if (issue.key) {
       // version = ciReleaseVersion（CI golden image version，例如 0.0.11）
-      let cdDescription = generateCDDescription(ciReleaseVersion || '');
+      let cdDescription = generateCDDescription(goldenImageVersion || ciReleaseVersion);
 
       // 生成 release notes Bitbucket compare URL
       if (normalizedArgs.ciTicket) {
@@ -293,82 +303,440 @@ export async function handleCreateCDTicket(args, {jira, notifier}) {
   }
 }
 
+export async function handleCDApproval(issueKey, environment, systemCode, ctx) {
+  const env = String(environment ?? '').toLowerCase().replace('&', '/');
+
+  if (env === 'dev') {
+    return {skipped: true, reason: 'DEV 環境使用自助 Approved 流程'};
+  }
+
+  if (env === 'stg') {
+    return handleCDStgApproval(issueKey, systemCode, ctx);
+  }
+
+  if (env === 'uat') {
+    return handleCDUatApproval(issueKey, systemCode, ctx);
+  }
+
+  if (isPrdLikeEnv(env)) {
+    return handleCDPrdApproval(issueKey, env, systemCode, ctx);
+  }
+
+  throw new Error(`不支援的 CD 簽核環境: ${environment}`);
+}
+
+async function handleCDStgApproval(issueKey, systemCode, ctx) {
+  const {jira, notifier} = ctx;
+  const managerResult = await handleGetReleaseManager();
+  const managerData = parseToolResult(managerResult);
+
+  if (!managerData?.found) {
+    throw new Error('無法查詢 STG 值班組長，請手動處理');
+  }
+
+  const managerName = managerData.name;
+  const accountId = resolveRequiredAccountId(managerName, 'STG 值班組長');
+
+  progress(ctx, {
+    phase: 'action',
+    title: '指派 CD 簽核人',
+    detail: managerName,
+    issueKey,
+  });
+  await jira.updateAssignee(issueKey, accountId);
+  await notifier.notify(issueKey, `已指派給 STG 值班組長 ${managerName}`);
+
+  const substituteMessage = managerData.substituted
+    ? `\n原值班組長 ${managerData.originalName} 今日請假（${managerData.leaveReason ?? '無請假說明'}），請 ${managerName} 協助簽單。`
+    : '';
+  await sendCDApprovalJabber(ctx, {
+    issueKey,
+    alias: managerName,
+    accountId,
+    message: `[CD 簽核通知] ${issueKey} 需要您的簽核。環境: STG，系統: ${systemCode}${substituteMessage}\n${getIssueUrl(issueKey)}`,
+  });
+
+  await waitForPostApprovalStatus(issueKey, ctx);
+
+  return {approved: true, by: managerName, substituted: Boolean(managerData.substituted)};
+}
+
+async function handleCDUatApproval(issueKey, systemCode, ctx) {
+  const {jira, notifier} = ctx;
+  const approvers = getDeployConfig().release.grayReleaseUatApprovers ?? {};
+  const commentReviewerAlias = approvers.commentReviewerAlias;
+  const finalApproverAlias = approvers.finalApproverAlias;
+  const commentReviewerAccountId = resolveRequiredAccountId(
+    commentReviewerAlias,
+    'UAT 第一階段簽核人 release.grayReleaseUatApprovers.commentReviewerAlias',
+  );
+
+  await assignAndNotify(ctx, {
+    issueKey,
+    alias: commentReviewerAlias,
+    accountId: commentReviewerAccountId,
+    assigneeMessage: `已指派給 ${commentReviewerAlias}，等待 approved 留言確認`,
+    jabberMessage: `[CD 簽核通知] ${issueKey} 需要您的簽核並留言 approved。環境: UAT，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+  });
+
+  const commentData = await waitForCommentWithKeyword(ctx, {
+    issueKey,
+    alias: commentReviewerAlias,
+    accountId: commentReviewerAccountId,
+    keyword: 'approved',
+  });
+  await notifier.notify(issueKey, `${commentReviewerAlias} 已留言確認: ${commentData.comment}`);
+
+  const finalApproverAccountId = resolveRequiredAccountId(
+    finalApproverAlias,
+    'UAT 最終簽核人 release.grayReleaseUatApprovers.finalApproverAlias',
+  );
+  await assignAndNotify(ctx, {
+    issueKey,
+    alias: finalApproverAlias,
+    accountId: finalApproverAccountId,
+    assigneeMessage: `已轉單給 ${finalApproverAlias}，等待最終簽核`,
+    jabberMessage: `[CD 簽核通知] ${issueKey} 已由 ${commentReviewerAlias} 留言確認，需要您的最終簽核。環境: UAT，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+  });
+
+  await waitForPostApprovalStatus(issueKey, ctx);
+
+  return {approved: true, by: `${commentReviewerAlias} → ${finalApproverAlias}`};
+}
+
+async function handleCDPrdApproval(issueKey, env, systemCode, ctx) {
+  const {notifier} = ctx;
+  const approvers = getDeployConfig().release.cdApprovers?.prd ?? {};
+  const leadReviewerAliases = approvers.leadReviewerAliases ?? [];
+  if (leadReviewerAliases.length < 2) {
+    throw new Error('缺少 release.cdApprovers.prd.leadReviewerAliases，PRD CD 需要兩位組長');
+  }
+
+  const leadReviewers = leadReviewerAliases.map((alias) => ({
+    alias,
+    accountId: resolveRequiredAccountId(alias, 'PRD 組長簽核人 release.cdApprovers.prd.leadReviewerAliases'),
+  }));
+
+  for (const reviewer of leadReviewers) {
+    await sendCDApprovalJabber(ctx, {
+      issueKey,
+      alias: reviewer.alias,
+      accountId: reviewer.accountId,
+      message: `[CD PRD 簽核通知] ${issueKey} 需要您的留言確認。環境: ${env.toUpperCase()}，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+    });
+  }
+
+  for (const reviewer of leadReviewers) {
+    const commentData = await waitForAnyCommentByAuthor(ctx, {
+      issueKey,
+      alias: reviewer.alias,
+      accountId: reviewer.accountId,
+    });
+    await notifier.notify(issueKey, `${reviewer.alias} 已留言確認: ${commentData.comment}`);
+  }
+
+  const secondReviewerAlias = approvers.secondReviewerAlias;
+  const thirdReviewerAlias = approvers.thirdReviewerAlias;
+  const finalApproverAlias = approvers.finalApproverAlias;
+
+  const secondReviewerAccountId = resolveRequiredAccountId(
+    secondReviewerAlias,
+    'PRD 第二階段簽核人 release.cdApprovers.prd.secondReviewerAlias',
+  );
+  await assignAndNotify(ctx, {
+    issueKey,
+    alias: secondReviewerAlias,
+    accountId: secondReviewerAccountId,
+    assigneeMessage: `已轉單給 ${secondReviewerAlias}，等待 approved 留言確認`,
+    jabberMessage: `[CD PRD 簽核通知] ${issueKey} 兩位組長已留言確認，需要您的 approved 留言。環境: ${env.toUpperCase()}，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+  });
+  const secondCommentData = await waitForCommentWithKeyword(ctx, {
+    issueKey,
+    alias: secondReviewerAlias,
+    accountId: secondReviewerAccountId,
+    keyword: 'approved',
+  });
+  await notifier.notify(issueKey, `${secondReviewerAlias} 已留言確認: ${secondCommentData.comment}`);
+
+  const thirdReviewerAccountId = resolveRequiredAccountId(
+    thirdReviewerAlias,
+    'PRD 第三階段簽核人 release.cdApprovers.prd.thirdReviewerAlias',
+  );
+  await assignAndNotify(ctx, {
+    issueKey,
+    alias: thirdReviewerAlias,
+    accountId: thirdReviewerAccountId,
+    assigneeMessage: `已轉單給 ${thirdReviewerAlias}，等待 approved 留言確認`,
+    jabberMessage: `[CD PRD 簽核通知] ${issueKey} 已由 ${secondReviewerAlias} 留言確認，需要您的 approved 留言。環境: ${env.toUpperCase()}，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+  });
+  const thirdCommentData = await waitForCommentWithKeyword(ctx, {
+    issueKey,
+    alias: thirdReviewerAlias,
+    accountId: thirdReviewerAccountId,
+    keyword: 'approved',
+  });
+  await notifier.notify(issueKey, `${thirdReviewerAlias} 已留言確認: ${thirdCommentData.comment}`);
+
+  const finalApproverAccountId = resolveRequiredAccountId(
+    finalApproverAlias,
+    'PRD 最終簽核人 release.cdApprovers.prd.finalApproverAlias',
+  );
+  await assignAndNotify(ctx, {
+    issueKey,
+    alias: finalApproverAlias,
+    accountId: finalApproverAccountId,
+    assigneeMessage: `已轉單給 ${finalApproverAlias}，等待最終 Approved`,
+    jabberMessage: `[CD PRD 簽核通知] ${issueKey} 已由 ${thirdReviewerAlias} 留言確認，需要您的最終 Approved。環境: ${env.toUpperCase()}，系統: ${systemCode}\n${getIssueUrl(issueKey)}`,
+  });
+
+  await waitForPostApprovalStatus(issueKey, ctx);
+
+  return {
+    approved: true,
+    by: `${leadReviewerAliases.join(' + ')} → ${secondReviewerAlias} → ${thirdReviewerAlias} → ${finalApproverAlias}`,
+  };
+}
+
+async function assignAndNotify(ctx, {issueKey, alias, accountId, assigneeMessage, jabberMessage}) {
+  const {jira, notifier} = ctx;
+  progress(ctx, {
+    phase: 'action',
+    title: '指派 CD 簽核人',
+    detail: alias,
+    issueKey,
+  });
+  await jira.updateAssignee(issueKey, accountId);
+  await notifier.notify(issueKey, assigneeMessage);
+  await sendCDApprovalJabber(ctx, {issueKey, alias, accountId, message: jabberMessage});
+}
+
+async function sendCDApprovalJabber(ctx, {issueKey, alias, accountId, message}) {
+  const jabberTo = getJabberJid(accountId);
+  progress(ctx, {
+    phase: 'waiting',
+    title: '發送 CD 簽核通知',
+    detail: `to ${alias} (${jabberTo})`,
+    issueKey,
+  });
+  const result = await handleSendJabberMessage({to: jabberTo, message}, {});
+  if (result.isError) {
+    throw new Error(result.content[0].text.replace(/^❌ 錯誤: /, ''));
+  }
+}
+
+async function waitForCommentWithKeyword(ctx, {issueKey, alias, accountId, keyword}) {
+  const result = await handleWaitForComment(
+    {
+      issueKey,
+      keyword,
+      authorAccountId: accountId,
+      intervalMs: getPollIntervalMs(),
+      timeoutMs: getPollTimeoutMs(),
+    },
+    {jira: ctx.jira, progress: ctx.progress},
+  );
+  const data = parseToolResult(result);
+  if (!data?.found) {
+    throw new Error(`等待 ${alias} 留言 ${keyword} 超時`);
+  }
+  return data;
+}
+
+async function waitForAnyCommentByAuthor(ctx, {issueKey, alias, accountId}) {
+  const {jira} = ctx;
+  const intervalMs = getPollIntervalMs();
+  const timeoutMs = getPollTimeoutMs();
+  const startedAt = Date.now();
+  let attempts = 0;
+
+  while (true) {
+    attempts++;
+    const comments = await jira.getComments(issueKey);
+    const elapsedMs = Date.now() - startedAt;
+    const match = comments.find((comment) => commentMatchesAuthor(comment, accountId));
+
+    progress(ctx, {
+      phase: 'polling',
+      title: '等待 Jira comment',
+      detail: `author=${accountId}`,
+      issueKey,
+      attempts,
+      elapsedMs,
+      timeoutMs,
+      nextPollMs: intervalMs,
+    });
+
+    if (match) {
+      return {
+        found: true,
+        issueKey,
+        author: match.author?.displayName ?? match.author?.name ?? '',
+        comment: (match.body ?? '').slice(0, 500),
+        attempts,
+        elapsedMs,
+      };
+    }
+
+    if (elapsedMs >= timeoutMs) {
+      throw new Error(`Timeout：等待 ${alias} 在 ${issueKey} 留言（${attempts} 次輪詢，${Math.round(elapsedMs / 1000)}s）`);
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+async function waitForPostApprovalStatus(issueKey, ctx) {
+  const poller = new Poller(ctx.jira);
+  return poller.waitForStatus(issueKey, 'WAIT FOR SEND NOTICE EMAIL', {
+    intervalMs: getPollIntervalMs(),
+    timeoutMs: getPollTimeoutMs(),
+    onProgress: ctx.progress,
+  });
+}
+
+function parseToolResult(result) {
+  if (result?.isError) {
+    throw new Error(result.content?.[0]?.text?.replace(/^❌ 錯誤: /, '') ?? 'tool execution failed');
+  }
+  const text = result?.content?.[0]?.text;
+  if (!text) return null;
+  return JSON.parse(text);
+}
+
+function resolveRequiredAccountId(alias, label) {
+  if (!alias) {
+    throw new Error(`缺少 ${label}`);
+  }
+  const accountId = resolveAccountId(alias);
+  if (!accountId) {
+    throw new Error(`找不到 ${label}「${alias}」的 accountId，請更新 users.aliases`);
+  }
+  return accountId;
+}
+
+function getJabberJid(accountId) {
+  const domain = process.env.JABBER_DOMAIN ?? getDeployConfig().jabber?.domain;
+  return domain ? `${accountId}@${domain}` : accountId;
+}
+
+function getIssueUrl(issueKey) {
+  return `${process.env.JIRA_BASE_URL}/browse/${issueKey}`;
+}
+
+function isPrdLikeEnv(env) {
+  return ['prd', 'dr', 'prd/dr'].includes(env);
+}
+
+function commentMatchesAuthor(comment, accountId) {
+  const author = comment.author ?? {};
+  return author.name === accountId || author.accountId === accountId;
+}
+
+function progress(ctx, event) {
+  if (typeof ctx.progress === 'function') {
+    ctx.progress(event);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
- * 計算下一個 Golden Image Release 版號
+ * 取得 extra var JSON 給 ansible playbook，格式為 {"ibk_cust_installation": {"server1": true, "server2": true}, ...}
  */
 export async function getExtraVarsJson(args, {jira}) {
   try {
-    const {serverList, module} = args;
-
-    let extraVarsJson = null;
-    // ① 從 CI 關聯的 Library 票推導模組（只含本次實際部署的模組）
-    let modules = null;
+    const modules = args.modules ?? (await resolveCDModules(args, {jira})).modules;
+    if (!modules?.length) throw new Error('缺少部署模組，無法產生 CID_extra_vars');
+    const sysLower = args.systemCode.toLowerCase();
 
-    if (args.ciTicket) {
-      try {
-        const ciFields = await jira.getIssueFields(args.ciTicket, ['issuelinks']);
-        const issueLinks = ciFields?.issuelinks ?? [];
-        // 建立反查表：child module ID → module name（僅限本系統）
-        const childIdToName = Object.fromEntries(
-          Object.entries(LIBRARY_MODULE_IDS[args.systemCode] ?? {}).map(([name, id]) => [id, name]),
+    const vars = Object.fromEntries(
+      modules.map((module) => {
+        const moduleServerList = getServerList(
+          args.systemCode,
+          args.environment,
+          args.metaTest,
+          module,
         );
+        return [
+          `${sysLower}_${module}_installation`,
+          Object.fromEntries(moduleServerList.map((server) => [server, true])),
+        ];
+      }),
+    );
+    return JSON.stringify(vars);
+  } catch (e) {
+    throw new Error(`無法產生 CID_extra_vars: ${e.message}`);
+  }
+}
 
-        const detectedModules = [];
-        for (const link of issueLinks) {
-          const linked = link.inwardIssue ?? link.outwardIssue;
-          if (linked?.fields?.issuetype?.name !== 'Library') continue;
-          try {
-            const libFields = await jira.getIssueFields(linked.key, ['customfield_13702']);
-            const childId = libFields?.['customfield_13702']?.child?.id;
-            if (childId && childIdToName[childId]) {
-              detectedModules.push(childIdToName[childId]);
-            }
-          } catch (_) {
-            /* skip this library */
-          }
-        }
-        if (detectedModules.length > 0) modules = [...new Set(detectedModules)];
-      } catch (_) {
-        /* fall through */
-      }
-    }
+// ── Private helpers ───────────────────────────────────────────────
 
-    // ② fallback：CI 無關聯 Library 時使用全系統模組
-    if (!modules) modules = SYSTEM_MODULES[args.systemCode] ?? [];
+async function resolveCDModules(args, {jira}) {
+  const modulesFromCi = await getModulesFromCiLibraries(args, {jira});
+  if (modulesFromCi.length > 0) return {modules: modulesFromCi};
 
-    const sysLower = args.systemCode.toLowerCase();
+  const modulesFromArgs = parseModuleChild(args.moduleChild);
+  if (modulesFromArgs.length > 0) return {modules: modulesFromArgs};
 
-    const envServerList = SERVERS[args.systemCode]?.[args.environment];
+  return {
+    needsModuleSelection: true,
+    message: '請問要部署哪些模組？',
+    options: SYSTEM_MODULES[args.systemCode] ?? [],
+    systemCode: args.systemCode,
+    environment: args.environment,
+    ciTicket: args.ciTicket,
+    hint: '請指定 moduleChild 後再建立 CD 單；未明確指定模組時不會自動部署全模組。',
+  };
+}
 
-    // 只對 cluster 是 flat array 的系統自動生成（EIB/EVT 結構較複雜，另外處理）
-    const flatClusters = Array.isArray(envServerList) ? serverList : null;
+async function getModulesFromCiLibraries(args, {jira}) {
+  if (!args.ciTicket) return [];
+  try {
+    const ciFields = await jira.getIssueFields(args.ciTicket, ['issuelinks']);
+    const issueLinks = ciFields?.issuelinks ?? [];
+    const childIdToName = Object.fromEntries(
+      Object.entries(LIBRARY_MODULE_IDS[args.systemCode] ?? {}).map(([name, id]) => [id, name]),
+    );
 
-    if (flatClusters) {
-      const serverMap = Object.fromEntries(flatClusters.map((s) => [s, true]));
-      const vars = Object.fromEntries(
-        modules.map((mod) => [`${sysLower}_${mod}_installation`, serverMap]),
-      );
-      extraVarsJson = JSON.stringify(vars);
-    } else {
-      // EVT & EIB 有分 web was 機器
-      const serverType = modules.map((module) => SERVER_MODULE_MAP[module]);
-      const vars = Object.fromEntries(
-        modules.map((mod, i) => {
-          const servers = envServerList[serverType[i]] ?? [];
-          return [
-            `${sysLower}_${mod}_installation`,
-            Object.fromEntries(servers.map((s) => [s, true])),
-          ];
-        }),
-      );
-      extraVarsJson = JSON.stringify(vars);
+    const detectedModules = [];
+    for (const link of issueLinks) {
+      const linked = link.inwardIssue ?? link.outwardIssue;
+      if (linked?.fields?.issuetype?.name !== 'Library') continue;
+      try {
+        const libFields = await jira.getIssueFields(linked.key, ['customfield_13702']);
+        const childId = libFields?.['customfield_13702']?.child?.id;
+        if (childId && childIdToName[childId]) detectedModules.push(childIdToName[childId]);
+      } catch (_) {
+        /* skip this library */
+      }
     }
-    return extraVarsJson;
-  } catch (e) {
+    return [...new Set(detectedModules)];
+  } catch (_) {
+    return [];
   }
-} // end getExtraVarsJson
+}
 
-// ── Private helpers ───────────────────────────────────────────────
+function parseModuleChild(moduleChild) {
+  return String(moduleChild ?? '')
+    .split(',')
+    .map((module) => module.trim())
+    .filter(Boolean);
+}
+
+function getModuleServerList(args, modules) {
+  return [
+    ...new Set(
+      modules.flatMap((module) => getServerList(
+        args.systemCode,
+        args.environment,
+        args.metaTest,
+        module,
+      )),
+    ),
+  ];
+}
 
 function generateCDDescription(version) {
   return `||一般資訊作業申請單||參考符號 ◼️◻️||
@@ -600,12 +968,8 @@ async function generateReleaseNotes(jira, ciKey, env, systemCode) {
         if (prevVersion) {
           targetBranch = `ci/${branchWithDashes}-${prevVersion}`;
         } else {
-          // 找最新的 release/ 開頭 branch（非 tag）
-          const branches = await jira.getBitbucketBranches(repoMeta.project, repoName, {
-            filterValue: 'release/',
-          });
-          if (!branches?.length) continue;
-          targetBranch = branches[0].displayId;
+          targetBranch = await findLatestReleaseBranchWithTag(jira, repoMeta, repoName);
+          if (!targetBranch) continue;
         }
         const baseUrl = process.env.BITBUCKET_URL || 'https://bitbucket.example.com';
         const compareUrl = `${baseUrl}/projects/${repoMeta.project}/repos/${repoName}/compare/diff?sourceBranch=${sourceBranch.replace(/\//g, '%2F')}&targetBranch=${targetBranch.replace(/\//g, '%2F')}&targetRepoId=${repoMeta.repoId}`;
@@ -620,6 +984,28 @@ async function generateReleaseNotes(jira, ciKey, env, systemCode) {
   }
 }
 
+async function findLatestReleaseBranchWithTag(jira, repoMeta, repoName) {
+  const tags = await jira.getBitbucketTags(repoMeta.project, repoName, {
+    filterValue: 'release/',
+    orderBy: 'MODIFICATION',
+    limit: 1,
+  });
+  const tagName = getBitbucketRefName(tags?.[0]);
+  if (!tagName.startsWith('release/')) return '';
+
+  const branches = await jira.getBitbucketBranches(repoMeta.project, repoName, {
+    filterValue: tagName,
+    orderBy: 'MODIFICATION',
+    limit: 1,
+  });
+  const matchedBranch = branches?.find((branch) => getBitbucketRefName(branch) === tagName);
+  return matchedBranch ? tagName : '';
+}
+
+function getBitbucketRefName(ref) {
+  return String(ref?.displayId ?? ref?.id ?? '').replace(/^refs\/(heads|tags)\//, '');
+}
+
 /**
  * 自動從 CI 單的 relates Library 單取 CID_branch，比對 LBPRJ 版本頁，每個 Library 單加一筆 Web Link
  */