@openprd/cli 0.1.0

package/src/diagram-core.js

@@ -0,0 +1,1047 @@
+import { timestamp } from './time.js';
+
+function escapeHtml(value) {
+  return `${value ?? ''}`
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function trimText(value, max = 96) {
+  const text = `${value ?? ''}`.trim();
+  if (!text) return '待补充';
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function mermaidId(value, fallback = 'node') {
+  const text = `${value ?? ''}`.trim();
+  const normalized = text
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_');
+  const id = normalized || fallback;
+  return /^[a-zA-Z_]/.test(id) ? id : `${fallback}_${id}`;
+}
+
+function mermaidText(value, max = 64) {
+  return trimText(value, max)
+    .replace(/["`]/g, "'")
+    .replace(/[|<>]/g, ' ')
+    .replace(/\r?\n/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function mermaidNodeLabel(primary, secondary) {
+  const title = mermaidText(primary, 34);
+  const subtitle = mermaidText(secondary, 64);
+  return subtitle && subtitle !== '待补充' ? `${title}<br/>${subtitle}` : title;
+}
+
+function mermaidNodeDeclaration(id, label, type) {
+  if (type === 'decision') {
+    return `  ${id}{"${label}"}`;
+  }
+  if (type === 'success') {
+    return `  ${id}(["${label}"])`;
+  }
+  if (type === 'error_path') {
+    return `  ${id}[["${label}"]]`;
+  }
+  return `  ${id}["${label}"]`;
+}
+
+function mermaidEdge(source, target, label, type = 'standard') {
+  const cleanLabel = mermaidText(label, 42);
+  const arrow = type === 'security' || type === 'error_path' ? '-.->' : '-->';
+  return cleanLabel && cleanLabel !== '待补充'
+    ? `  ${source} ${arrow}|"${cleanLabel}"| ${target}`
+    : `  ${source} ${arrow} ${target}`;
+}
+
+function normalizeList(value, fallback = []) {
+  if (Array.isArray(value)) {
+    const items = value.map((item) => `${item ?? ''}`.trim()).filter(Boolean);
+    return items.length > 0 ? items : fallback;
+  }
+  const text = `${value ?? ''}`.trim();
+  return text ? [text] : fallback;
+}
+
+function takeList(value, count, fallback = []) {
+  return normalizeList(value, fallback).slice(0, count);
+}
+
+function joinList(value, fallback = '待补充', separator = ' · ') {
+  const items = normalizeList(value);
+  return items.length > 0 ? items.join(separator) : fallback;
+}
+
+function pickValue(primary, fallback) {
+  if (primary === null || primary === undefined) return fallback;
+  if (typeof primary === 'string' && primary.trim() === '') return fallback;
+  if (Array.isArray(primary) && primary.length === 0) return fallback;
+  return primary;
+}
+
+function theme(type) {
+  const themes = {
+    frontend: { fill: '#0f172a', stroke: '#22d3ee', title: '#67e8f9' },
+    backend: { fill: '#0f172a', stroke: '#34d399', title: '#6ee7b7' },
+    database: { fill: '#0f172a', stroke: '#c084fc', title: '#d8b4fe' },
+    cloud: { fill: '#0f172a', stroke: '#f59e0b', title: '#fcd34d' },
+    security: { fill: '#0f172a', stroke: '#fb7185', title: '#fda4af' },
+    external: { fill: '#0f172a', stroke: '#94a3b8', title: '#e2e8f0' },
+    user_action: { fill: '#0f172a', stroke: '#22d3ee', title: '#67e8f9' },
+    system_process: { fill: '#0f172a', stroke: '#34d399', title: '#6ee7b7' },
+    decision: { fill: '#0f172a', stroke: '#f59e0b', title: '#fcd34d' },
+    error_path: { fill: '#0f172a', stroke: '#fb7185', title: '#fda4af' },
+    success: { fill: '#0f172a', stroke: '#c084fc', title: '#d8b4fe' },
+  };
+  return themes[type] ?? themes.external;
+}
+
+function normalizeCard(card, fallbackTitle = '摘要', fallbackColor = 'external') {
+  return {
+    title: pickValue(card?.title, fallbackTitle),
+    color: pickValue(card?.color, fallbackColor),
+    items: normalizeList(card?.items, ['待补充']),
+  };
+}
+
+function normalizePanel(panel, fallbackTitle = '评审备注', fallbackColor = 'external') {
+  return {
+    title: pickValue(panel?.title, fallbackTitle),
+    color: pickValue(panel?.color, fallbackColor),
+    items: normalizeList(panel?.items, ['待补充']),
+  };
+}
+
+function normalizeLocale(contract) {
+  return pickValue(contract?.locale, contract?.lang ?? 'zh-CN');
+}
+
+function normalizeReviewStatus(value) {
+  return pickValue(value, 'pending-confirmation');
+}
+
+function hasCjk(text) {
+  return /[\u3400-\u9fff]/.test(text);
+}
+
+function englishWords(text) {
+  return `${text ?? ''}`.match(/[A-Za-z][A-Za-z0-9+_.-]*/g) ?? [];
+}
+
+function isEnglishHeavyText(text) {
+  const value = `${text ?? ''}`.trim();
+  if (!value || hasCjk(value)) return false;
+  const words = englishWords(value);
+  return words.length >= 4;
+}
+
+function collectDiagramTexts(model) {
+  const entries = [];
+  const push = (path, value) => {
+    if (typeof value === 'string' && value.trim()) {
+      entries.push({ path, value: value.trim() });
+    }
+  };
+  push('title', model.title);
+  push('subtitle', model.subtitle);
+  push('metadata.projectName', model.metadata?.projectName);
+  for (const [index, component] of (model.components ?? []).entries()) {
+    push(`components.${index}.name`, component.name);
+    push(`components.${index}.subtitle`, component.subtitle);
+    for (const [detailIndex, detail] of (component.details ?? []).entries()) {
+      push(`components.${index}.details.${detailIndex}`, detail);
+    }
+  }
+  for (const [index, flow] of (model.flows ?? []).entries()) {
+    push(`flows.${index}.label`, flow.label);
+  }
+  for (const [index, card] of (model.summaryCards ?? []).entries()) {
+    push(`summaryCards.${index}.title`, card.title);
+    for (const [itemIndex, item] of (card.items ?? []).entries()) {
+      push(`summaryCards.${index}.items.${itemIndex}`, item);
+    }
+  }
+  for (const [index, panel] of (model.sidePanels ?? []).entries()) {
+    push(`sidePanels.${index}.title`, panel.title);
+    for (const [itemIndex, item] of (panel.items ?? []).entries()) {
+      push(`sidePanels.${index}.items.${itemIndex}`, item);
+    }
+  }
+  for (const [index, instruction] of (model.reviewInstructions ?? []).entries()) {
+    push(`reviewInstructions.${index}`, instruction);
+  }
+  return entries;
+}
+
+export function validateDiagramLanguage(model) {
+  const locale = `${model?.locale ?? 'zh-CN'}`.toLowerCase();
+  if (!locale.startsWith('zh')) {
+    return { valid: true, errors: [] };
+  }
+  const offenders = collectDiagramTexts(model)
+    .filter((entry) => isEnglishHeavyText(entry.value))
+    .slice(0, 12);
+  return {
+    valid: offenders.length === 0,
+    errors: offenders.map((entry) => (
+      `${entry.path} 应使用简体中文表达，当前内容偏英文: ${trimText(entry.value, 96)}`
+    )),
+  };
+}
+
+function getAtPath(root, path) {
+  return path.split('.').reduce((acc, key) => (acc === null || acc === undefined ? undefined : acc[key]), root);
+}
+
+function hasValue(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.trim() !== '';
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function renderShell({ lang = 'zh-CN', title, subtitle, projectName, svgMarkup, summaryCards, sidePanels, footer }) {
+  const cards = summaryCards.map((card) => {
+    const cardTheme = theme(card.color);
+    const items = (card.items ?? []).map((item) => `<li>${escapeHtml(trimText(item, 132))}</li>`).join('');
+    return `
+      <div class="card">
+        <div class="card-header">
+          <span class="dot" style="background:${cardTheme.stroke}"></span>
+          <span>${escapeHtml(card.title)}</span>
+        </div>
+        <ul>${items}</ul>
+      </div>
+    `;
+  }).join('\n');
+
+  const panels = sidePanels.map((panel) => {
+    const panelTheme = theme(panel.color);
+    const items = (panel.items ?? []).map((item) => `<li>${escapeHtml(trimText(item, 120))}</li>`).join('');
+    return `
+      <div class="card">
+        <div class="card-header">
+          <span class="dot" style="background:${panelTheme.stroke}"></span>
+          <span>${escapeHtml(panel.title)}</span>
+        </div>
+        <ul>${items}</ul>
+      </div>
+    `;
+  }).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(lang)}">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(title)}</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #020617;
+        --panel: rgba(15, 23, 42, 0.92);
+        --text: #e2e8f0;
+        --muted: #94a3b8;
+        --grid: rgba(148, 163, 184, 0.12);
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: "JetBrains Mono", "SFMono-Regular", Menlo, monospace;
+        color: var(--text);
+        background:
+          linear-gradient(var(--grid) 1px, transparent 1px),
+          linear-gradient(90deg, var(--grid) 1px, transparent 1px),
+          radial-gradient(circle at top, rgba(34, 211, 238, 0.12), transparent 30%),
+          var(--bg);
+        background-size: 40px 40px, 40px 40px, 100% 100%, auto;
+      }
+      .page { max-width: 1240px; margin: 0 auto; padding: 32px 24px 48px; }
+      .header { display: flex; align-items: center; gap: 12px; margin-bottom: 20px; }
+      .header-copy { display: flex; flex-direction: column; gap: 4px; }
+      .pulse {
+        width: 12px; height: 12px; border-radius: 999px; background: #22d3ee;
+        box-shadow: 0 0 0 0 rgba(34, 211, 238, 0.7); animation: pulse 2s infinite;
+      }
+      @keyframes pulse {
+        0% { box-shadow: 0 0 0 0 rgba(34, 211, 238, 0.7); }
+        70% { box-shadow: 0 0 0 10px rgba(34, 211, 238, 0); }
+        100% { box-shadow: 0 0 0 0 rgba(34, 211, 238, 0); }
+      }
+      .project-chip {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        width: fit-content;
+        padding: 4px 10px;
+        border-radius: 999px;
+        border: 1px solid rgba(148, 163, 184, 0.24);
+        background: rgba(15, 23, 42, 0.72);
+        color: #cbd5e1;
+        font-size: 11px;
+      }
+      h1 { margin: 0; font-size: 28px; }
+      .subtitle-block { margin: 6px 0 0 24px; color: var(--muted); font-size: 13px; }
+      .diagram-shell {
+        margin-top: 24px; border: 1px solid rgba(148, 163, 184, 0.18); border-radius: 20px;
+        padding: 20px; background: rgba(2, 6, 23, 0.72); backdrop-filter: blur(6px);
+      }
+      svg { width: 100%; height: auto; display: block; }
+      .node-title { font-size: 13px; font-weight: 700; }
+      .node-subtitle, .detail, .flow-label, .legend-label, .footer { font-size: 10px; fill: #cbd5e1; }
+      .detail { fill: #94a3b8; }
+      .summary-grid, .side-grid { display: grid; gap: 16px; margin-top: 24px; }
+      .summary-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+      .side-grid { grid-template-columns: 1fr 1fr; }
+      .card {
+        border: 1px solid rgba(148, 163, 184, 0.18); border-radius: 16px;
+        background: var(--panel); padding: 14px 16px;
+      }
+      .card-header { display: flex; align-items: center; gap: 10px; font-size: 12px; margin-bottom: 8px; }
+      .dot { width: 10px; height: 10px; border-radius: 999px; }
+      ul { padding-left: 18px; margin: 0; color: #cbd5e1; font-size: 12px; line-height: 1.65; }
+      .footer { margin-top: 18px; color: var(--muted); }
+    </style>
+  </head>
+  <body>
+    <div class="page">
+      <div class="header">
+        <div class="pulse"></div>
+        <div class="header-copy">
+          <div class="project-chip">${escapeHtml(projectName ?? title)}</div>
+          <h1>${escapeHtml(title)}</h1>
+          <p class="subtitle-block">${escapeHtml(subtitle)}</p>
+        </div>
+      </div>
+      <div class="diagram-shell">${svgMarkup}</div>
+      <div class="summary-grid">${cards}</div>
+      <div class="side-grid">${panels}</div>
+      <div class="footer">${escapeHtml(footer)}</div>
+    </div>
+  </body>
+</html>`;
+}
+
+function renderBox(node, layout) {
+  const nodeTheme = theme(node.type);
+  const detailLines = (node.details ?? []).slice(0, 4);
+  const detailMarkup = detailLines.map((line, index) => (
+    `<text x="${layout.x + 16}" y="${layout.y + 54 + (index * 16)}" class="detail">${escapeHtml(trimText(line, 42))}</text>`
+  )).join('');
+
+  return `
+    <g>
+      <rect x="${layout.x}" y="${layout.y}" width="${layout.width}" height="${layout.height}" rx="14" fill="${nodeTheme.fill}" fill-opacity="0.92" stroke="${nodeTheme.stroke}" stroke-width="1.5"></rect>
+      <text x="${layout.x + 16}" y="${layout.y + 28}" class="node-title" fill="${nodeTheme.title}">${escapeHtml(node.name)}</text>
+      <text x="${layout.x + 16}" y="${layout.y + 44}" class="node-subtitle">${escapeHtml(trimText(node.subtitle, 48))}</text>
+      ${detailMarkup}
+    </g>
+  `;
+}
+
+function renderArrow(def) {
+  const dashed = def.type === 'security' || def.type === 'error_path' ? 'stroke-dasharray="6,4"' : '';
+  const stroke = def.type === 'security' || def.type === 'error_path' ? '#fb7185' : '#7dd3fc';
+  return `<path d="${def.path}" fill="none" stroke="${stroke}" stroke-width="2" ${dashed} marker-end="url(#arrowhead)"></path>
+  <text x="${def.labelX}" y="${def.labelY}" class="flow-label">${escapeHtml(def.label)}</text>`;
+}
+
+function resolveProductLayerTitle(productType) {
+  if (productType === 'consumer') return '消费端体验层';
+  if (productType === 'b2b') return 'B2B 工作流层';
+  if (productType === 'agent') return 'Agent 运行层';
+  return '产品体验层';
+}
+
+function buildArchitectureComponents(snapshot) {
+  const { sections } = snapshot;
+  const reviewTarget = sections.handoff.targetSystem ?? 'OpenSpec';
+  return [
+    {
+      id: 'users',
+      name: '主要用户',
+      type: 'external',
+      subtitle: joinList(sections.users.primaryUsers, '用户'),
+      details: takeList(sections.users.stakeholders, 3, ['相关方需要确认']),
+    },
+    {
+      id: 'experience',
+      name: resolveProductLayerTitle(snapshot.productType),
+      type: 'frontend',
+      subtitle: trimText(joinList(sections.scenarios.primaryFlows, sections.meta.title)),
+      details: takeList(sections.scope.inScope, 3, ['范围仍需细化']),
+    },
+    {
+      id: 'core',
+      name: '核心产品逻辑',
+      type: 'backend',
+      subtitle: trimText(sections.problem.problemStatement ?? '核心逻辑待澄清'),
+      details: takeList(sections.requirements.functional, 3, ['功能需求待补充']),
+    },
+    {
+      id: 'integrations',
+      name: '依赖与集成',
+      type: 'cloud',
+      subtitle: trimText(joinList(sections.constraints.dependencies, '暂无外部依赖记录')),
+      details: takeList(sections.constraints.dependencies, 4, ['依赖尚未确认']),
+    },
+    {
+      id: 'governance',
+      name: '约束与可靠性',
+      type: 'security',
+      subtitle: trimText(joinList(sections.constraints.compliance, joinList(sections.requirements.nonFunctional, '暂无明确约束'))),
+      details: [
+        ...takeList(sections.constraints.compliance, 2),
+        ...takeList(sections.requirements.nonFunctional, 2),
+      ].slice(0, 4),
+    },
+    {
+      id: 'delivery',
+      name: '验证与交接',
+      type: 'database',
+      subtitle: trimText(joinList(sections.goals.successMetrics, '成功指标待确认')),
+      details: [
+        `目标: ${reviewTarget}`,
+        `下一步: ${trimText(sections.handoff.nextStep ?? '确认下一步', 48)}`,
+        ...takeList(sections.goals.acceptanceGoals, 2),
+      ].slice(0, 4),
+    },
+  ];
+}
+
+export function buildArchitectureDiagramModel(snapshot) {
+  const scopeIn = takeList(snapshot.sections.scope.inScope, 3, ['范围待澄清']);
+  const scopeOut = takeList(snapshot.sections.scope.outOfScope, 2, ['范围外内容尚未明确']);
+  const assumptions = takeList(snapshot.sections.risks.assumptions, 4, ['假设仍需评审']);
+  const openQuestions = takeList(snapshot.sections.risks.openQuestions, 4, ['暂无开放问题记录']);
+  const primaryFlows = takeList(snapshot.sections.scenarios.primaryFlows, 3, ['主流程仍需确认']);
+
+  return {
+    type: 'architecture',
+    version: 1,
+    generatedAt: timestamp(),
+    locale: 'zh-CN',
+    title: '架构评审',
+    subtitle: '在需求定稿前评审系统边界、依赖和交接形态。',
+    components: buildArchitectureComponents(snapshot),
+    flows: [
+      { source: 'users', target: 'experience', label: trimText(primaryFlows[0] ?? '用户进入产品流程', 40), type: 'standard' },
+      { source: 'experience', target: 'core', label: '产品动作与编排', type: 'standard' },
+      { source: 'core', target: 'integrations', label: '依赖与外部服务', type: 'standard' },
+      { source: 'core', target: 'governance', label: '策略、可靠性与合规', type: 'security' },
+      { source: 'core', target: 'delivery', label: '成功标准与交接', type: 'standard' },
+      { source: 'integrations', target: 'delivery', label: '运营就绪', type: 'standard' },
+      { source: 'governance', target: 'delivery', label: '评审与确认', type: 'security' },
+    ],
+    summaryCards: [
+      {
+        title: '范围',
+        color: 'frontend',
+        items: [
+          `范围内: ${scopeIn.join(' / ')}`,
+          `范围外: ${scopeOut.join(' / ')}`,
+          `主流程: ${primaryFlows.join(' / ')}`,
+        ],
+      },
+      {
+        title: '架构检查',
+        color: 'backend',
+        items: [
+          `核心逻辑: ${takeList(snapshot.sections.requirements.functional, 2, ['功能需求待补充']).join(' / ')}`,
+          `依赖: ${takeList(snapshot.sections.constraints.dependencies, 2, ['依赖待补充']).join(' / ')}`,
+          `约束: ${takeList(snapshot.sections.constraints.compliance, 2, takeList(snapshot.sections.requirements.nonFunctional, 2, ['约束待补充'])).join(' / ')}`,
+        ],
+      },
+      {
+        title: '评审重点',
+        color: 'cloud',
+        items: [
+          `确认缺失假设: ${assumptions.join(' / ')}`,
+          `开放问题: ${openQuestions.join(' / ')}`,
+          '在需求定稿前请用户确认模块、边界和缺失系统。',
+        ],
+      },
+    ],
+    sidePanels: [
+      { title: '假设', color: 'database', items: assumptions },
+      {
+        title: '评审说明',
+        color: 'cloud',
+        items: [
+          '确认这些模块是否反映澄清后的目标架构。',
+          '标记缺失系统、边界或外部依赖。',
+          '在需求定稿前验证可靠性、合规和交接预期。',
+        ],
+      },
+    ],
+    metadata: {
+      projectName: snapshot.title,
+      productType: snapshot.productType ?? '未分类',
+      owner: snapshot.owner,
+      versionId: snapshot.versionId,
+      targetSystem: snapshot.sections.handoff.targetSystem ?? 'OpenSpec',
+      reviewStatus: normalizeReviewStatus(snapshot?.reviewStatus),
+    },
+  };
+}
+
+export function renderArchitectureDiagramHtml(model) {
+  const layouts = {
+    users: { x: 390, y: 48, width: 300, height: 96 },
+    experience: { x: 70, y: 228, width: 290, height: 120 },
+    core: { x: 395, y: 228, width: 290, height: 120 },
+    delivery: { x: 720, y: 228, width: 290, height: 120 },
+    integrations: { x: 180, y: 448, width: 290, height: 120 },
+    governance: { x: 610, y: 448, width: 290, height: 120 },
+  };
+  const fallbackLayouts = [
+    { x: 390, y: 48, width: 300, height: 96 },
+    { x: 70, y: 228, width: 290, height: 120 },
+    { x: 395, y: 228, width: 290, height: 120 },
+    { x: 720, y: 228, width: 290, height: 120 },
+    { x: 180, y: 448, width: 290, height: 120 },
+    { x: 610, y: 448, width: 290, height: 120 },
+  ];
+
+  const arrows = [
+    { path: 'M 540 144 C 540 182, 215 176, 215 228', label: model.flows[0]?.label ?? '用户流程', labelX: 312, labelY: 176, type: model.flows[0]?.type ?? 'standard' },
+    { path: 'M 360 288 L 395 288', label: model.flows[1]?.label ?? '产品动作', labelX: 366, labelY: 276, type: model.flows[1]?.type ?? 'standard' },
+    { path: 'M 685 288 L 720 288', label: model.flows[4]?.label ?? '成功标准', labelX: 694, labelY: 276, type: model.flows[4]?.type ?? 'standard' },
+    { path: 'M 540 348 C 540 392, 325 396, 325 448', label: model.flows[2]?.label ?? '依赖', labelX: 300, labelY: 392, type: model.flows[2]?.type ?? 'standard' },
+    { path: 'M 540 348 C 540 392, 755 396, 755 448', label: model.flows[3]?.label ?? '约束', labelX: 692, labelY: 392, type: model.flows[3]?.type ?? 'security' },
+    { path: 'M 470 568 C 470 610, 820 610, 820 348', label: model.flows[5]?.label ?? '运营就绪', labelX: 596, labelY: 614, type: model.flows[5]?.type ?? 'standard' },
+    { path: 'M 820 568 C 920 612, 920 416, 865 348', label: model.flows[6]?.label ?? '评审确认', labelX: 850, labelY: 612, type: model.flows[6]?.type ?? 'security' },
+  ];
+
+  const componentMarkup = model.components
+    .map((component, index) => renderBox(component, layouts[component.id] ?? fallbackLayouts[index] ?? fallbackLayouts.at(-1)))
+    .join('\n');
+  const arrowMarkup = arrows.map(renderArrow).join('\n');
+  const svgMarkup = `
+    <svg viewBox="0 0 1080 720" role="img" aria-label="${escapeHtml(model.title)}">
+      <defs>
+        <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
+          <polygon points="0 0, 10 5, 0 10" fill="#7dd3fc"></polygon>
+        </marker>
+      </defs>
+      <rect x="40" y="172" width="1000" height="430" rx="18" fill="none" stroke="#f59e0b" stroke-opacity="0.55" stroke-width="1.5" stroke-dasharray="8,5"></rect>
+      <text x="58" y="194" class="legend-label">方案边界</text>
+      ${arrowMarkup}
+      ${componentMarkup}
+      <g>
+        <text x="54" y="652" class="legend-label">图例</text>
+        <rect x="54" y="666" width="12" height="12" rx="3" fill="#22d3ee"></rect><text x="74" y="676" class="legend-label">体验</text>
+        <rect x="182" y="666" width="12" height="12" rx="3" fill="#34d399"></rect><text x="202" y="676" class="legend-label">核心逻辑</text>
+        <rect x="330" y="666" width="12" height="12" rx="3" fill="#c084fc"></rect><text x="350" y="676" class="legend-label">验证</text>
+        <rect x="476" y="666" width="12" height="12" rx="3" fill="#f59e0b"></rect><text x="496" y="676" class="legend-label">依赖</text>
+        <rect x="640" y="666" width="12" height="12" rx="3" fill="#fb7185"></rect><text x="660" y="676" class="legend-label">约束</text>
+        <rect x="798" y="666" width="12" height="12" rx="3" fill="#94a3b8"></rect><text x="818" y="676" class="legend-label">外部/用户</text>
+      </g>
+    </svg>
+  `;
+
+  return renderShell({
+    lang: model.locale ?? 'zh-CN',
+    title: model.title,
+    subtitle: model.subtitle,
+    projectName: model.metadata?.projectName ?? model.title,
+    svgMarkup,
+    summaryCards: model.summaryCards,
+    sidePanels: model.sidePanels,
+    footer: `负责人: ${model.metadata.owner} · 版本: ${model.metadata.versionId} · 目标: ${model.metadata.targetSystem} · 生成时间: ${model.generatedAt}`,
+  });
+}
+
+export function buildProductFlowDiagramModel(snapshot) {
+  const primaryUsers = takeList(snapshot.sections.users.primaryUsers, 2, ['主要用户']);
+  const primaryFlows = takeList(snapshot.sections.scenarios.primaryFlows, 4, ['主流程仍需确认']);
+  const edgeCases = takeList(snapshot.sections.scenarios.edgeCases, 3, ['边界情况仍需澄清']);
+  const failureModes = takeList(snapshot.sections.scenarios.failureModes, 3, ['失败路径仍需澄清']);
+  const goals = takeList(snapshot.sections.goals.goals, 2, ['目标仍需确认']);
+  const successMetrics = takeList(snapshot.sections.goals.successMetrics, 2, ['成功指标仍需确认']);
+  const openQuestions = takeList(snapshot.sections.risks.openQuestions, 4, ['暂无开放问题记录']);
+  const steps = [
+    {
+      id: 'entry',
+      name: '入口触发',
+      type: 'user_action',
+      lane: primaryUsers[0],
+      subtitle: trimText(primaryFlows[0] ?? '用户进入流程'),
+      details: takeList(snapshot.sections.scope.inScope, 2, ['范围仍需细化']),
+    },
+    {
+      id: 'experience',
+      name: '产品内步骤',
+      type: 'system_process',
+      lane: '产品',
+      subtitle: trimText(primaryFlows[1] ?? snapshot.sections.problem.problemStatement ?? '核心产品步骤'),
+      details: takeList(snapshot.sections.requirements.functional, 2, ['功能需求待补充']),
+    },
+    {
+      id: 'decision',
+      name: '决策点',
+      type: 'decision',
+      lane: '决策',
+      subtitle: trimText(edgeCases[0] ?? '决策标准待澄清'),
+      details: [
+        `目标: ${trimText(goals[0], 40)}`,
+        `指标: ${trimText(successMetrics[0], 40)}`,
+      ],
+    },
+    {
+      id: 'success',
+      name: '成功结果',
+      type: 'success',
+      lane: '结果',
+      subtitle: trimText(successMetrics[0] ?? '成功结果仍需确认'),
+      details: takeList(snapshot.sections.goals.acceptanceGoals, 2, ['验收目标待补充']),
+    },
+    {
+      id: 'failure',
+      name: '失败与恢复',
+      type: 'error_path',
+      lane: '结果',
+      subtitle: trimText(failureModes[0] ?? '失败路径待澄清'),
+      details: [
+        ...failureModes.slice(0, 2),
+        ...openQuestions.slice(0, 2),
+      ].slice(0, 4),
+    },
+  ];
+
+  return {
+    type: 'product-flow',
+    version: 1,
+    generatedAt: timestamp(),
+    locale: 'zh-CN',
+    title: '产品流程评审',
+    subtitle: '在需求定稿前评审主要旅程、决策点和恢复路径。',
+    actors: primaryUsers,
+    steps,
+    transitions: [
+      { from: 'entry', to: 'experience', label: primaryFlows[0] ?? '开始旅程', type: 'standard' },
+      { from: 'experience', to: 'decision', label: primaryFlows[1] ?? '系统处理请求', type: 'standard' },
+      { from: 'decision', to: 'success', label: goals[0] ?? '成功路径', type: 'standard' },
+      { from: 'decision', to: 'failure', label: failureModes[0] ?? '失败路径', type: 'error_path' },
+    ],
+    summaryCards: [
+      {
+        title: '参与者与范围',
+        color: 'user_action',
+        items: [
+          `参与者: ${primaryUsers.join(' / ')}`,
+          `范围内: ${takeList(snapshot.sections.scope.inScope, 2, ['范围待补充']).join(' / ')}`,
+          `范围外: ${takeList(snapshot.sections.scope.outOfScope, 2, ['范围外内容待补充']).join(' / ')}`,
+        ],
+      },
+      {
+        title: '流程检查',
+        color: 'system_process',
+        items: [
+          `主流程: ${primaryFlows.join(' / ')}`,
+          `边界情况: ${edgeCases.join(' / ')}`,
+          `失败模式: ${failureModes.join(' / ')}`,
+        ],
+      },
+      {
+        title: '评审重点',
+        color: 'decision',
+        items: [
+          `目标: ${goals.join(' / ')}`,
+          `成功指标: ${successMetrics.join(' / ')}`,
+          '在需求定稿前确认步骤、决策点和缺失的恢复路径。',
+        ],
+      },
+    ],
+    sidePanels: [
+      { title: '开放问题', color: 'error_path', items: openQuestions },
+      {
+        title: '评审说明',
+        color: 'decision',
+        items: [
+          '确认用户旅程和系统响应顺序是否正确。',
+          '标记缺失的决策点、失败路径和恢复步骤。',
+          '确认该流程是否足以支持进入实现前确认。',
+        ],
+      },
+    ],
+    metadata: {
+      projectName: snapshot.title,
+      productType: snapshot.productType ?? '未分类',
+      owner: snapshot.owner,
+      versionId: snapshot.versionId,
+      targetSystem: snapshot.sections.handoff.targetSystem ?? 'OpenSpec',
+      reviewStatus: normalizeReviewStatus(snapshot?.reviewStatus),
+    },
+  };
+}
+
+export function renderProductFlowDiagramHtml(model) {
+  const layouts = {
+    entry: { x: 90, y: 250, width: 190, height: 112 },
+    experience: { x: 330, y: 250, width: 210, height: 112 },
+    decision: { x: 590, y: 245, width: 180, height: 122 },
+    success: { x: 820, y: 140, width: 180, height: 112 },
+    failure: { x: 820, y: 360, width: 180, height: 122 },
+  };
+  const fallbackLayouts = [
+    { x: 90, y: 250, width: 190, height: 112 },
+    { x: 330, y: 250, width: 210, height: 112 },
+    { x: 590, y: 245, width: 180, height: 122 },
+    { x: 820, y: 140, width: 180, height: 112 },
+    { x: 820, y: 360, width: 180, height: 122 },
+  ];
+
+  const laneMarkup = [
+    { y: 118, label: '用户/触发' },
+    { y: 220, label: '核心流程' },
+    { y: 438, label: '结果/恢复' },
+  ].map((lane) => `
+    <g>
+      <line x1="70" y1="${lane.y}" x2="1020" y2="${lane.y}" stroke="#334155" stroke-width="1" stroke-dasharray="6,4"></line>
+      <text x="74" y="${lane.y - 8}" class="legend-label">${escapeHtml(lane.label)}</text>
+    </g>
+  `).join('\n');
+
+  const stepMarkup = model.steps
+    .map((step, index) => renderBox(step, layouts[step.id] ?? fallbackLayouts[index] ?? fallbackLayouts.at(-1)))
+    .join('\n');
+  const transitions = [
+    { path: 'M 280 306 L 330 306', label: model.transitions[0]?.label ?? '开始', labelX: 288, labelY: 294, type: model.transitions[0]?.type ?? 'standard' },
+    { path: 'M 540 306 L 590 306', label: model.transitions[1]?.label ?? '核心步骤', labelX: 546, labelY: 294, type: model.transitions[1]?.type ?? 'standard' },
+    { path: 'M 770 282 C 800 240, 820 220, 820 196', label: model.transitions[2]?.label ?? '成功路径', labelX: 786, labelY: 226, type: model.transitions[2]?.type ?? 'standard' },
+    { path: 'M 770 330 C 800 370, 820 400, 820 420', label: model.transitions[3]?.label ?? '失败路径', labelX: 786, labelY: 388, type: model.transitions[3]?.type ?? 'error_path' },
+  ].map(renderArrow).join('\n');
+
+  const svgMarkup = `
+    <svg viewBox="0 0 1080 720" role="img" aria-label="${escapeHtml(model.title)}">
+      <defs>
+        <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
+          <polygon points="0 0, 10 5, 0 10" fill="#7dd3fc"></polygon>
+        </marker>
+      </defs>
+      <rect x="56" y="92" width="968" height="520" rx="18" fill="none" stroke="#f59e0b" stroke-opacity="0.45" stroke-width="1.5" stroke-dasharray="8,5"></rect>
+      <text x="74" y="118" class="legend-label">产品流程边界</text>
+      ${laneMarkup}
+      ${transitions}
+      ${stepMarkup}
+      <g>
+        <text x="54" y="652" class="legend-label">图例</text>
+        <rect x="54" y="666" width="12" height="12" rx="3" fill="#22d3ee"></rect><text x="74" y="676" class="legend-label">用户动作</text>
+        <rect x="196" y="666" width="12" height="12" rx="3" fill="#34d399"></rect><text x="216" y="676" class="legend-label">系统处理</text>
+        <rect x="372" y="666" width="12" height="12" rx="3" fill="#f59e0b"></rect><text x="392" y="676" class="legend-label">决策</text>
+        <rect x="516" y="666" width="12" height="12" rx="3" fill="#c084fc"></rect><text x="536" y="676" class="legend-label">成功</text>
+        <rect x="648" y="666" width="12" height="12" rx="3" fill="#fb7185"></rect><text x="668" y="676" class="legend-label">错误/恢复</text>
+      </g>
+    </svg>
+  `;
+
+  return renderShell({
+    lang: model.locale ?? 'zh-CN',
+    title: model.title,
+    subtitle: model.subtitle,
+    projectName: model.metadata?.projectName ?? model.title,
+    svgMarkup,
+    summaryCards: model.summaryCards,
+    sidePanels: model.sidePanels,
+    footer: `负责人: ${model.metadata.owner} · 版本: ${model.metadata.versionId} · 目标: ${model.metadata.targetSystem} · 生成时间: ${model.generatedAt}`,
+  });
+}
+
+export function renderProductFlowMermaid(model) {
+  const steps = Array.isArray(model.steps) ? model.steps : [];
+  const idMap = new Map();
+  const declarations = steps.map((step, index) => {
+    const id = mermaidId(step.id, `step_${index + 1}`);
+    idMap.set(step.id, id);
+    const label = mermaidNodeLabel(step.name, step.subtitle ?? step.description);
+    return mermaidNodeDeclaration(id, label, step.type);
+  });
+  const edges = (Array.isArray(model.transitions) ? model.transitions : [])
+    .map((transition) => {
+      const from = idMap.get(transition.from) ?? mermaidId(transition.from, 'from');
+      const to = idMap.get(transition.to) ?? mermaidId(transition.to, 'to');
+      return mermaidEdge(from, to, transition.label, transition.type);
+    });
+
+  return [
+    'flowchart LR',
+    ...declarations,
+    ...edges,
+  ].join('\n');
+}
+
+export function renderArchitectureMermaid(model) {
+  const components = Array.isArray(model.components) ? model.components : [];
+  const idMap = new Map();
+  const external = [];
+  const internal = [];
+
+  for (const [index, component] of components.entries()) {
+    const id = mermaidId(component.id, `component_${index + 1}`);
+    idMap.set(component.id, id);
+    const label = mermaidNodeLabel(component.name, component.subtitle ?? component.description);
+    const declaration = mermaidNodeDeclaration(id, label, component.type === 'security' ? 'error_path' : 'system_process');
+    if (component.type === 'external') {
+      external.push(declaration);
+    } else {
+      internal.push(declaration);
+    }
+  }
+
+  const edges = (Array.isArray(model.flows) ? model.flows : [])
+    .map((flow) => {
+      const source = idMap.get(flow.source) ?? mermaidId(flow.source, 'source');
+      const target = idMap.get(flow.target) ?? mermaidId(flow.target, 'target');
+      return mermaidEdge(source, target, flow.label, flow.type);
+    });
+
+  return [
+    'flowchart LR',
+    ...external,
+    '  subgraph solution["方案边界"]',
+    ...internal.map((line) => `  ${line}`),
+    '  end',
+    ...edges,
+  ].join('\n');
+}
+
+export function renderDiagramMermaidFromModel(type, model) {
+  if (type === 'product-flow') {
+    return renderProductFlowMermaid(model);
+  }
+  return renderArchitectureMermaid(model);
+}
+
+export function buildDiagramArtifact(snapshot, options = {}) {
+  const type = options.type ?? 'architecture';
+  const contract = options.contract ?? null;
+
+  if (type === 'product-flow' && contract) {
+    const base = buildProductFlowDiagramModel(snapshot);
+    const model = {
+      ...base,
+      ...contract,
+      type: 'product-flow',
+      locale: normalizeLocale(contract),
+      title: pickValue(contract.title, base.title),
+      subtitle: pickValue(contract.subtitle, base.subtitle),
+      actors: normalizeList(contract.actors, base.actors),
+      steps: Array.isArray(contract.steps) && contract.steps.length > 0
+        ? contract.steps.map((step, index) => ({
+          id: pickValue(step?.id, `step-${index + 1}`),
+          name: pickValue(step?.name, `步骤 ${index + 1}`),
+          type: pickValue(step?.type, 'system_process'),
+          lane: pickValue(step?.lane, '流程'),
+          subtitle: pickValue(step?.subtitle, step?.description ?? '待补充'),
+          details: normalizeList(step?.details ?? step?.notes ?? step?.data_involved, ['待补充']),
+        }))
+        : base.steps,
+      transitions: Array.isArray(contract.transitions) && contract.transitions.length > 0
+        ? contract.transitions.map((transition) => ({
+          from: pickValue(transition?.from, transition?.from_step_id),
+          to: pickValue(transition?.to, transition?.to_step_id),
+          label: pickValue(transition?.label, transition?.condition ?? '流转'),
+          type: pickValue(transition?.type, 'standard'),
+        }))
+        : base.transitions,
+      summaryCards: Array.isArray(contract.summaryCards) && contract.summaryCards.length > 0
+        ? contract.summaryCards.map((card, index) => normalizeCard(card, `摘要 ${index + 1}`, 'system_process'))
+        : base.summaryCards,
+      sidePanels: Array.isArray(contract.sidePanels) && contract.sidePanels.length > 0
+        ? contract.sidePanels.map((panel, index) => normalizePanel(panel, `面板 ${index + 1}`, 'decision'))
+        : [
+          normalizePanel({
+            title: contract.openQuestionsTitle ?? '开放问题',
+            color: 'error_path',
+            items: contract.openQuestions,
+          }),
+          normalizePanel({
+            title: contract.reviewInstructionsTitle ?? '评审说明',
+            color: 'decision',
+            items: contract.reviewInstructions,
+          }),
+        ],
+      metadata: {
+        ...base.metadata,
+        ...(contract.metadata ?? {}),
+        projectName: pickValue(contract?.metadata?.projectName, pickValue(contract.title, base.metadata.projectName)),
+        versionId: pickValue(contract?.metadata?.versionId, base.metadata.versionId),
+        owner: pickValue(contract?.metadata?.owner, base.metadata.owner),
+        targetSystem: pickValue(contract?.metadata?.targetSystem, base.metadata.targetSystem),
+      },
+    };
+
+    return { type, model, html: renderProductFlowDiagramHtml(model) };
+  }
+
+  if (type === 'architecture' && contract) {
+    const base = buildArchitectureDiagramModel(snapshot);
+    const model = {
+      ...base,
+      ...contract,
+      type: 'architecture',
+      locale: normalizeLocale(contract),
+      title: pickValue(contract.title, base.title),
+      subtitle: pickValue(contract.subtitle, base.subtitle),
+      components: Array.isArray(contract.components) && contract.components.length > 0
+        ? contract.components.map((component, index) => ({
+          id: pickValue(component?.id, `component-${index + 1}`),
+          name: pickValue(component?.name, `组件 ${index + 1}`),
+          type: pickValue(component?.type, 'external'),
+          subtitle: pickValue(component?.subtitle, component?.description ?? '待补充'),
+          details: normalizeList(component?.details, ['待补充']),
+        }))
+        : base.components,
+      flows: Array.isArray(contract.flows) && contract.flows.length > 0
+        ? contract.flows.map((flow) => ({
+          source: pickValue(flow?.source, 'source'),
+          target: pickValue(flow?.target, 'target'),
+          label: pickValue(flow?.label, '流程'),
+          type: pickValue(flow?.type, 'standard'),
+        }))
+        : base.flows,
+      summaryCards: Array.isArray(contract.summaryCards) && contract.summaryCards.length > 0
+        ? contract.summaryCards.map((card, index) => normalizeCard(card, `摘要 ${index + 1}`, 'frontend'))
+        : base.summaryCards,
+      sidePanels: Array.isArray(contract.sidePanels) && contract.sidePanels.length > 0
+        ? contract.sidePanels.map((panel, index) => normalizePanel(panel, `面板 ${index + 1}`, 'database'))
+        : [
+          normalizePanel({
+            title: contract.assumptionsTitle ?? '假设',
+            color: 'database',
+            items: contract.assumptions,
+          }),
+          normalizePanel({
+            title: contract.reviewInstructionsTitle ?? '评审说明',
+            color: 'cloud',
+            items: contract.reviewInstructions,
+          }),
+        ],
+      metadata: {
+        ...base.metadata,
+        ...(contract.metadata ?? {}),
+        projectName: pickValue(contract?.metadata?.projectName, pickValue(contract.title, base.metadata.projectName)),
+        versionId: pickValue(contract?.metadata?.versionId, base.metadata.versionId),
+        owner: pickValue(contract?.metadata?.owner, base.metadata.owner),
+        targetSystem: pickValue(contract?.metadata?.targetSystem, base.metadata.targetSystem),
+      },
+    };
+
+    return { type, model, html: renderArchitectureDiagramHtml(model) };
+  }
+
+  if (type === 'product-flow') {
+    const model = buildProductFlowDiagramModel(snapshot);
+    return {
+      type,
+      model,
+      html: renderProductFlowDiagramHtml(model),
+    };
+  }
+
+  const model = buildArchitectureDiagramModel(snapshot);
+  return {
+    type: 'architecture',
+    model,
+    html: renderArchitectureDiagramHtml(model),
+  };
+}
+
+export function renderDiagramArtifactFromModel(type, model) {
+  if (type === 'product-flow') {
+    return renderProductFlowDiagramHtml(model);
+  }
+  return renderArchitectureDiagramHtml(model);
+}
+
+export function validateDiagramContract(contract, schema) {
+  const errors = [];
+  if (!schema || typeof schema !== 'object') {
+    return { valid: false, errors: ['Missing diagram schema'] };
+  }
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) {
+    return { valid: false, errors: ['Diagram contract must be a JSON object'] };
+  }
+
+  const requiredFields = Array.isArray(schema.requiredFields) ? schema.requiredFields : [];
+  for (const field of requiredFields) {
+    if (!hasValue(getAtPath(contract, field))) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  const requiredArrays = schema.requiredArrays ?? {};
+  for (const [field, minItems] of Object.entries(requiredArrays)) {
+    const value = getAtPath(contract, field);
+    if (!Array.isArray(value)) {
+      errors.push(`Field must be an array: ${field}`);
+      continue;
+    }
+    if (value.length < Number(minItems)) {
+      errors.push(`Field requires at least ${minItems} item(s): ${field}`);
+    }
+  }
+
+  const itemRequiredFields = schema.itemRequiredFields ?? {};
+  for (const [field, nestedFields] of Object.entries(itemRequiredFields)) {
+    const list = getAtPath(contract, field);
+    if (!Array.isArray(list)) continue;
+    for (let index = 0; index < list.length; index += 1) {
+      const item = list[index];
+      for (const nestedField of nestedFields) {
+        const aliases = nestedField.split('|');
+        const ok = aliases.some((alias) => hasValue(item?.[alias]));
+        if (!ok) {
+          errors.push(`Missing required field in ${field}[${index}]: ${nestedField}`);
+        }
+      }
+    }
+  }
+
+  const allowedValues = schema.allowedValues ?? {};
+  for (const [field, allowed] of Object.entries(allowedValues)) {
+    const value = getAtPath(contract, field);
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (!allowed.includes(item)) {
+          errors.push(`Unsupported value in ${field}: ${item}`);
+        }
+      }
+      continue;
+    }
+    if (!allowed.includes(value)) {
+      errors.push(`Unsupported value for ${field}: ${value}`);
+    }
+  }
+
+  const itemAllowedValues = schema.itemAllowedValues ?? {};
+  for (const [field, mapping] of Object.entries(itemAllowedValues)) {
+    const list = getAtPath(contract, field);
+    if (!Array.isArray(list)) continue;
+    for (let index = 0; index < list.length; index += 1) {
+      const item = list[index];
+      for (const [nestedField, allowed] of Object.entries(mapping)) {
+        const value = item?.[nestedField];
+        if (value === undefined || value === null || value === '') continue;
+        if (!allowed.includes(value)) {
+          errors.push(`Unsupported value for ${field}[${index}].${nestedField}: ${value}`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}