ai-git-tools 2.1.5 → 2.1.7

package/README.md

@@ -350,9 +350,9 @@ ai-git-tools redmine-update --apply --from redmine-update.json
 
 `--pr <number>` 是可選的補充 evidence，會加入 PR title、body、URL、merge state、commits 與 changed files；沒有 PR 仍可完整分析本機 Git diff。沒有 PR 時，工具不會自動推論已 merge、已部署或必須關閉 Issue。
 
-Preview 會以色彩分開顯示每個 Issue 的開發內容、程式修改重點、API 變更、重要技術細節、修改檔案與實際 note。狀態由 Redmine API 提供選單，只有使用者選擇的 status 才會寫入。
+Preview 會以色彩分開顯示每個 Issue 的開發內容、程式修改重點、API 變更、重要技術細節、修改檔案與實際 note。工具會從 Redmine API 找到 `已解決` 狀態並直接套用，不顯示互動式狀態選單。
 
-原始 Issue description 會保留原始內容；若 AI 產生可靠流程，工具只替換 description 中由 `ai-git-tools` 管理的 Mermaid 區塊，不會重複追加。更新摘要會寫入 notes，並使用 Markdown 標題、項目符號與雙反引號標示程式路徑、API path、function 與 class。只有找到明確測試或驗證證據時才會加入驗證段落；流程圖會使用 Redmine Mermaid macro 並放在 description（公司 Redmine 的 notes 不支援 Mermaid）：
+原始 Issue description 會保留原始內容，供未來其它內容使用。AI 可產生多張流程圖，每張流程圖都有穩定的用途 ID，流程圖會放在 notes（公司 Redmine 已支援 notes Mermaid）。更新摘要會使用 Markdown 標題、項目符號與雙反引號標示程式路徑、API path、function 與 class。只有找到明確測試或驗證證據時才會加入驗證段落：
 
 ```text
 {{mermaid
@@ -362,9 +362,9 @@ flowchart TD
 }}
 ```
 
-Issue note 的基本責任分工如下：`description` 保存原始需求，`status` 保存目前狀態，`notes` 保存 Git 開發與同步紀錄。
+Issue 的基本責任分工如下：`description` 保存原始需求與未來其它內容，`status` 保存目前狀態，`notes` 保存 Git 開發紀錄與 Mermaid 流程圖。
 
-當 preview 選擇「已解決」後套用，工具會同步將完成百分比設為 `100%`，並依欄位名稱找到 `程式碼更版進度` custom field，勾選測試機選項 `測`。custom field ID 會從 Issue API 動態取得，不會寫死公司 Redmine 的 ID。
+當 preview 套用時，工具會直接將狀態設為 `已解決`，並同步將完成百分比設為 `100%`、完成日期設為執行當天，依欄位名稱找到 `程式碼更版進度` custom field，勾選測試機選項 `測`。custom field ID 會從 Issue API 動態取得，不會寫死公司 Redmine 的 ID。
 
 同一個 Issue 若已經有先前的 notes，後續再次執行更新仍會新增一筆新的 Redmine journal，不會因為已有 notes 而略過；只有 Issue 的需求內容或狀態在產生草稿後被其他人修改時，才會停下來要求重新確認。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-git-tools",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "AI-powered Git automation tools for commit messages and PR generation",
   "main": "src/index.js",
   "type": "module",

package/src/redmine/issue-analyzer.js

@@ -12,6 +12,38 @@ const ANALYSIS_FIELDS = [
   'evidence',
 ];
 
+function normalizeFlowcharts(value) {
+  const flowcharts = Array.isArray(value)
+    ? value
+    : value
+      ? [{ source: value }]
+      : [];
+
+  const usedIds = new Set();
+  return flowcharts
+    .filter(flowchart => flowchart && typeof flowchart === 'object')
+    .map((flowchart, index) => {
+      const title = typeof flowchart.title === 'string' ? flowchart.title.trim() : '';
+      const requestedId = typeof flowchart.id === 'string' ? flowchart.id.trim() : '';
+      const stableId = (requestedId || title || `flowchart-${index + 1}`)
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '') || `flowchart-${index + 1}`;
+
+      let uniqueId = stableId;
+      if (usedIds.has(uniqueId)) uniqueId = `${stableId}-${index + 1}`;
+      usedIds.add(uniqueId);
+
+      return {
+        id: uniqueId,
+        title,
+        source: typeof flowchart.source === 'string' ? flowchart.source.trim() : '',
+        evidence: asStringArray(flowchart.evidence),
+      };
+    })
+    .filter(flowchart => flowchart.source);
+}
+
 function asStringArray(value) {
   return Array.isArray(value) ? value.filter(item => typeof item === 'string') : [];
 }
@@ -52,7 +84,8 @@ export function buildIssueAnalysisPrompt({ issue, evidence }) {
 - 不得捏造 API endpoint、參數、檔案、function、class、測試或部署結果。
 - 沒有明確測試或驗證證據時，verification 必須是空陣列。
 - 沒有可靠 API 變更證據時，apiChanges 必須是空陣列。
-- 若能從實際流程推導出可靠的複製流程，才產生 flowchart；否則為 null。flowchart 必須以 graph TD 開始，不要加入 Mermaid wrapper 或 code fence。
+- requirementDescription 應整理指定 Issue 的需求重點；behaviorRules 使用 scenario/behavior 物件陣列。
+- 若能從實際流程推導出可靠的複製流程，才產生 flowcharts；否則為空陣列。每張流程圖必須有穩定、描述用途的 id，source 必須以 graph TD 開始，不要加入 Mermaid wrapper 或 code fence。
 - developmentSummary、codeChanges、apiChanges、technicalDetails 中的程式路徑、API path、function 與 class 使用雙反引號標示；需要多行程式片段時使用 code block。
 - 不要產生 suggestedStatus、coverage 或 confidence，也不要決定 Redmine status。
 
@@ -73,12 +106,12 @@ ${JSON.stringify(evidence, null, 2)}
   "technicalDetails": [],
   "modifiedFiles": [],
   "verification": [],
-  "flowchart": null,
+  "flowcharts": [],
   "unresolvedItems": [],
   "evidence": []
 }
 
-developmentSummary、codeChanges、apiChanges、technicalDetails、modifiedFiles、verification、unresolvedItems 與 evidence 必須是字串陣列；requirementDescription 必須是字串；behaviorRules 必須是包含 scenario 與 behavior 字串的物件陣列；flowchart 必須是合法 Mermaid source 字串或 null。`;
+developmentSummary、codeChanges、apiChanges、technicalDetails、modifiedFiles、verification、unresolvedItems 與 evidence 必須是字串陣列；requirementDescription 必須是字串；behaviorRules 必須是包含 scenario 與 behavior 字串的物件陣列；flowcharts 必須是包含 id、title、source 與 evidence 的物件陣列。`;
 }
 
 /**
@@ -97,10 +130,9 @@ export function parseIssueAnalysis(content, issueId) {
       : asStringArray(parsed[field]);
   }
   result.behaviorRules = asBehaviorRules(parsed.behaviorRules);
+  result.flowcharts = normalizeFlowcharts(parsed.flowcharts || parsed.flowchart);
 
-  result.flowchart = typeof parsed.flowchart === 'string' && parsed.flowchart.trim()
-    ? parsed.flowchart.trim()
-    : null;
+  result.flowchart = result.flowcharts[0]?.source || null;
 
   return result;
 }

package/src/redmine/issue-sync.js

@@ -2,15 +2,21 @@ import { analyzeIssue as defaultAnalyzeIssue } from './issue-analyzer.js';
 import { createHash } from 'crypto';
 import {
   formatRedmineNote,
-  formatRedmineDescription,
   formatRedminePreview,
-  selectIssueStatus,
+  resolveIssueStatus,
 } from './redmine-formatters.js';
 
 function uniqueIssueIds(issueIds = []) {
   return [...new Set(issueIds.map(id => Number(id)).filter(Number.isInteger))];
 }
 
+function getCurrentDate() {
+  const now = new Date();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+
 /**
  * 判斷 Redmine 狀態是否代表已解決
  * @param {string} statusName
@@ -35,6 +41,7 @@ export function buildCompletionUpdate(issue, selectedStatus) {
   if (!progressField) {
     return {
       doneRatio: 100,
+      dueDate: getCurrentDate(),
       customFields: [],
       warning: '找不到 custom field「程式碼更版進度」，已略過 checkbox 更新',
     };
@@ -42,6 +49,7 @@ export function buildCompletionUpdate(issue, selectedStatus) {
 
   return {
     doneRatio: 100,
+    dueDate: getCurrentDate(),
     customFields: [{ id: progressField.id, value: ['測'] }],
   };
 }
@@ -72,7 +80,7 @@ export async function generateRedmineDraft({
   evidence,
   pullRequest = null,
   analyzeIssueFn = defaultAnalyzeIssue,
-  selectStatusFn = selectIssueStatus,
+  selectStatusFn = resolveIssueStatus,
   model,
   maxRetries,
 }) {
@@ -82,9 +90,11 @@ export async function generateRedmineDraft({
     try {
       const issue = await client.getIssue(issueId);
       const analysis = await analyzeIssueFn({ issue, evidence: { ...evidence, pullRequest }, model, maxRetries });
-      const selectedStatus = await selectStatusFn(issue, { client });
+      const fallbackStatuses = issue.allowedStatuses?.length ? [] : await client.getIssueStatuses();
+      const selectedStatus = selectStatusFn === resolveIssueStatus
+        ? resolveIssueStatus(issue, fallbackStatuses)
+        : await selectStatusFn(issue, { client });
       const completion = buildCompletionUpdate(issue, selectedStatus);
-      const description = formatRedmineDescription(issue.description, analysis.flowchart);
       const syncId = createSyncId({ issueId, evidence, pullRequest });
       const note = formatRedmineNote({
         issueId,
@@ -104,9 +114,9 @@ export async function generateRedmineDraft({
         statusId: selectedStatus.statusId,
         statusName: selectedStatus.statusName,
         doneRatio: completion.doneRatio,
+        dueDate: completion.dueDate,
         customFields: completion.customFields,
         customFieldWarning: completion.warning || null,
-        description: description !== issue.description ? description : undefined,
         analysis,
         note,
         syncId,
@@ -150,6 +160,7 @@ export async function applyRedmineDraft({ draft, client, force = false }) {
 
       const update = { statusId: item.statusId, notes: item.note };
       if (item.doneRatio !== undefined) update.doneRatio = item.doneRatio;
+      if (item.dueDate !== undefined) update.dueDate = item.dueDate;
       if (item.description !== undefined) update.description = item.description;
       if (item.customFields?.length) update.customFields = item.customFields;
 

package/src/redmine/redmine-client.js

@@ -131,13 +131,14 @@ export class RedmineClient {
 
   /**
   * @param {number|string} issueId
-  * @param {{statusId?: number, doneRatio?: number, description?: string, notes?: string, customFields?: Array<object>}} update
+  * @param {{statusId?: number, doneRatio?: number, dueDate?: string, description?: string, notes?: string, customFields?: Array<object>}} update
    * @returns {Promise<object>}
    */
-  async updateIssue(issueId, { statusId, doneRatio, description, notes, customFields }) {
+  async updateIssue(issueId, { statusId, doneRatio, dueDate, description, notes, customFields }) {
     const issue = {};
     if (statusId !== undefined && statusId !== null) issue.status_id = statusId;
     if (doneRatio !== undefined && doneRatio !== null) issue.done_ratio = doneRatio;
+    if (dueDate !== undefined && dueDate !== null) issue.due_date = dueDate;
     if (description !== undefined) issue.description = description;
     if (notes) issue.notes = notes;
     if (Array.isArray(customFields) && customFields.length > 0) {

package/src/redmine/redmine-formatters.js

@@ -20,8 +20,67 @@ function formatBehaviorRules(rules = []) {
   return `### 行為規則\n\n| 情境 | 行為 |\n|---|---|\n${rows.join('\n')}\n`;
 }
 
-const MERMAID_START = '<!-- ai-git-tools:mermaid:start -->';
-const MERMAID_END = '<!-- ai-git-tools:mermaid:end -->';
+function formatFlowcharts(flowcharts = []) {
+  if (!Array.isArray(flowcharts) || flowcharts.length === 0) return '';
+
+  return flowcharts
+    .map((flowchart, index) => {
+      const mermaid = formatMermaid(flowchart?.source);
+      if (!mermaid) return '';
+      const id = normalizeFlowchartId(flowchart?.id, index);
+      const title = flowchart?.title?.trim() || '開發流程';
+      return `### 流程圖：${title}\n\n<!-- flowchart-id: ${id} -->\n${mermaid}\n`;
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+const MERMAID_START = '<!-- ai-git-tools:mermaid:start';
+const MERMAID_END = '<!-- ai-git-tools:mermaid:end';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function normalizeFlowchartId(id, index) {
+  const source = typeof id === 'string' && id.trim() ? id : `flowchart-${index + 1}`;
+  return source
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || `flowchart-${index + 1}`;
+}
+
+function normalizeFlowchartInput(flowcharts) {
+  if (Array.isArray(flowcharts)) return flowcharts;
+  if (typeof flowcharts === 'string' && flowcharts.trim()) {
+    return [{ id: 'flowchart-1', title: '開發流程', source: flowcharts }];
+  }
+  return [];
+}
+
+function hasSameMermaid(description, mermaid) {
+  const existing = description.match(/\{\{\s*mermaid\b[\s\S]*?\}\}/gi) || [];
+  return existing.some(block => formatMermaid(block) === mermaid);
+}
+
+function managedFlowchartPattern(id) {
+  const escapedId = escapeRegExp(id);
+  return new RegExp(
+    `${escapeRegExp(MERMAID_START)} id="${escapedId}" -->[\\s\\S]*?${escapeRegExp(MERMAID_END)} id="${escapedId}" -->`
+  );
+}
+
+function formatManagedFlowchart(flowchart, index) {
+  const mermaid = formatMermaid(flowchart.source);
+  if (!mermaid) return '';
+
+  const id = normalizeFlowchartId(flowchart.id, index);
+  const title = typeof flowchart.title === 'string' && flowchart.title.trim()
+    ? flowchart.title.trim()
+    : '開發流程';
+  return `${MERMAID_START} id="${id}" -->\n\n### 流程圖：${title}\n\n${mermaid}\n\n${MERMAID_END} id="${id}" -->`;
+}
 
 /**
  * 將 Mermaid source 包成 Redmine macro
@@ -37,9 +96,9 @@ export function formatMermaid(source) {
     .replace(/\s*```$/, '')
     .trim();
 
-  if (cleanSource.startsWith('{{mermaid')) {
+  if (/^\{\{\s*mermaid\b/i.test(cleanSource)) {
     cleanSource = cleanSource
-      .replace(/^\{\{mermaid\s*/, '')
+      .replace(/^\{\{\s*mermaid\s*/i, '')
       .replace(/\s*\}\}$/, '')
       .trim();
   }
@@ -64,19 +123,27 @@ export function formatMermaid(source) {
  * @returns {string}
  */
 export function formatRedmineDescription(description = '', source = null) {
-  const mermaid = formatMermaid(source);
-  if (!mermaid) return description;
+  let result = description;
+  const flowcharts = normalizeFlowchartInput(source);
 
-  const block = `${MERMAID_START}\n\n### 開發流程\n\n${mermaid}\n\n${MERMAID_END}`;
-  const markerPattern = new RegExp(
-    `${MERMAID_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${MERMAID_END.replace(/[.*+?^${}()|[\]\\\\]/g, '\\$&')}`
-  );
+  flowcharts.forEach((flowchart, index) => {
+    const mermaid = formatMermaid(flowchart?.source);
+    if (!mermaid) return;
 
-  if (markerPattern.test(description)) {
-    return description.replace(markerPattern, block);
-  }
+    const block = formatManagedFlowchart(flowchart, index);
+    const id = normalizeFlowchartId(flowchart?.id, index);
+    const markerPattern = managedFlowchartPattern(id);
+    if (markerPattern.test(result)) {
+      result = result.replace(markerPattern, block);
+      return;
+    }
 
-  return `${description.trim()}\n\n${block}`.trim();
+    if (!hasSameMermaid(result, mermaid)) {
+      result = `${result.trim()}\n\n${block}`.trim();
+    }
+  });
+
+  return result;
 }
 
 /**
@@ -104,6 +171,7 @@ export function formatRedmineNote({ issueId, issue = {}, analysis = {}, evidence
   const unresolved = analysis.unresolvedItems?.length
     ? `### 待確認\n${analysis.unresolvedItems.map(item => `- [ ] ${item}`).join('\n')}\n`
     : '';
+  const flowcharts = formatFlowcharts(analysis.flowcharts);
 
   sections.push(
     development,
@@ -113,22 +181,30 @@ export function formatRedmineNote({ issueId, issue = {}, analysis = {}, evidence
     codeChanges,
     apiChanges,
     technicalDetails,
+    flowcharts,
     verification
   );
   sections.push(unresolved);
 
-  if (evidence.currentBranch || evidence.baseBranch) {
-    sections.push(
-      `### Git\n\n- Branch：\`\`${evidence.currentBranch || '—'}\`\``,
-      `- Base：\`\`${evidence.baseBranch || '—'}\`\``,
-      ''
-    );
-  }
-
-  if (pullRequest) {
+  if (evidence.currentBranch || evidence.baseBranch || pullRequest) {
+    const branch = evidence.currentBranch || '—';
+    const branchUrl = evidence.repository
+      ? `https://github.com/${evidence.repository}/tree/${encodeURI(branch)}`
+      : '';
+    const gitLines = [
+      '### Git',
+      '',
+      `- Branch：${branchUrl ? `[${branch}](${branchUrl})` : `\`\`${branch}\`\``}`,
+      `- Base：${evidence.baseBranch || '—'}`,
+    ];
+    if (pullRequest) {
+      gitLines.push(
+        `- PR：${pullRequest.url ? `[${pullRequest.url}](${pullRequest.url})` : `#${pullRequest.number}`}`,
+        `- PR 狀態：${pullRequest.state || '—'}${pullRequest.mergedAt ? `（合併於 ${pullRequest.mergedAt}）` : ''}`
+      );
+    }
     sections.push(
-      `GitHub PR：${pullRequest.url || `#${pullRequest.number}`}`,
-      `PR 狀態：${pullRequest.state || '—'}${pullRequest.mergedAt ? `（合併於 ${pullRequest.mergedAt}）` : ''}`,
+      gitLines.join('\n'),
       ''
     );
   }
@@ -188,6 +264,19 @@ export async function selectIssueStatus(issue, { client, prompt = inquirer.promp
   return { statusId: answer.statusId, statusName: selected?.name || String(answer.statusId) };
 }
 
+/**
+ * 直接取得已解決狀態，不啟動互動式選單
+ * @param {object} issue
+ * @param {Array<object>} fallbackStatuses
+ * @returns {{statusId: number, statusName: string}}
+ */
+export function resolveIssueStatus(issue, fallbackStatuses = []) {
+  const statuses = getAvailableStatuses(issue, fallbackStatuses);
+  const resolved = statuses.find(status => /已解決|resolved/i.test(status.name || ''));
+  if (!resolved) throw new Error(`Issue #${issue.id} 找不到「已解決」狀態`);
+  return { statusId: resolved.id, statusName: resolved.name };
+}
+
 /**
  * 產生有色 terminal preview
  * @param {Array<object>} drafts
@@ -202,6 +291,7 @@ export function formatRedminePreview(drafts = []) {
       `${chalk.dim('目前狀態：')} ${draft.currentStatusName || draft.originalStatusName || '—'}`,
       `${chalk.green('更新狀態：')} ${draft.statusName || '未選擇'}`,
       draft.doneRatio !== undefined ? `${chalk.green('完成百分比：')} ${draft.doneRatio}%` : '',
+      draft.dueDate ? `${chalk.green('完成日期：')} ${draft.dueDate}` : '',
       draft.customFields?.length
         ? `${chalk.green('程式碼更版進度：')} ${draft.customFields.flatMap(field => field.value || []).join('、')}`
         : '',