与 Kiro 一同构建：打造工厂自动化门户背后的自动化分析引擎

仅供工程教学工作坊使用。此为软件架构演练，而非正式发布之工艺建议。

摘要： 本独立工作坊旨在教导开发者如何使用 Kiro、TypeScript、纯工艺窗口函数、SVG 图表产生器、测试以及受控的实时模拟，重新构建最新工厂自动化门户（Factory Automation Portal）的 JavaScript 分析与互动逻辑。开发者将实施工艺变动量（deltas）、漂移（drift）、信号波动度（signal volatility）、效率比（efficiency ratio）、P05 变动量、最佳变动量、最差变动量、窗口率（window rate）、排序、搜索过滤、走势图路径（sparkline paths）、工艺窗口指标曲线、漂移水位线（drift waterlines）、直方图、状态图砖图表、页签互动状态保留，以及具备完整原型覆盖率与审查任务的更新循环安全性。

---

工作坊目的

这场 2 小时的工作坊将焦点放在工厂自动化门户展示背后的分析与互动引擎。本工作坊不侧重于 UI 样式，而是将原型的 JavaScript 行为萃取至可测试的 TypeScript 模块中。开发者将学习如何使用 Kiro 来设计确定性的工艺窗口函数、测试边缘情况、解释指标含意、保留状态图砖与排行榜的行为，并将实时更新模拟明确限制在展示行为内。

学习目标与原始的分析引擎工作坊架构一致：捕捉每个 JavaScript 辅助函数、为简短的原型函数定义专业的领域名称、编写确定性测试，并保护图表几何形状免于发生退化（regressions）。所有内容皆已全面更新至最新的门户展示。

---

展示涵盖范围地图

本工作坊涵盖以下门户实施细节：

● runtimeCards 数组：包含六个运行时工作台项目：同步运行时（Synchronous Runtime）、串流运行时（Streaming Runtime）、大型负载运行时（Large Payload Runtime）、承载数据验证（Payload Validation）、冒烟测试（Smoke Tests）、会话清理（Session Cleanup）。

● tools 数组：包含四个工具：throughput_throughput、metrology_drift_widening、process_window_drift 和 tool_to_tool_mismatch。

● specialists 数组：包含四个受治理的代理：throughput、metrology、overlay 和 etch-process。

● runbook 数组：包含从 0-10 到 115-120 的八个时间轴步骤。

● 工艺窗口数据列数组 P：包含 8 个自动化工作站（cells）、工艺模式、指标 %、变动量 %、稳定度、PF、WR、偏态（Skew）、最大漂移以及索引序列。

● 状态图砖数组 M：包含 Runtime、Tools、Policy 和 Eval 等通道（lanes）、变动值、整备状态以及微型序列。

● 格式化辅助函数：sg（正负号数值）、cl（语义类别）和 id（详细数据面板 ID）。

● 计算辅助函数：ret、dd、avg、sd 和 perc，对应至专业的 TypeScript 函数。

● SVG 辅助函数：path、spark、gridlines、eqChart、ddChart 和 hist。

● 详细数据面板构建器 panel：包含衍生的高阶指标与 architecture 自动化笔记。

● data 中的搜索与排序行为。

● render 中的数据列转译与开启面板状态保留。

● tog 中的分析切换行为。

● markets 中的状态图砖转译。

● clock 中的实时 HKT 时钟。

● 5 秒受控的工艺窗口模拟更新循环。

---

目标开发者

● 欲将仪表板数学公式转换为经测试模块的 TypeScript 开发者。

● 学习如何为自动化门户设计确定性计算模式的开发者。

● 需要产生可重现图表路径的前端工程师。

● 学习如何利用 Kiro 审查数学公式、边缘情况、模拟行为及互动式仪表板一致性的平台工程师。

---

两小时议程

---

系统架构

src/domain/
├─ types.ts              # AutomationCell, StatusTile, RuntimeCard, ToolCard, SpecialistCard, RunbookStep, Metrics, SortKey
├─ fixtures.ts           # 從入口網站展示複製的 P, M, runtimeCards, tools, specialists, runbook
├─ formatting.ts         # 帶正負號的百分比、語意類別、慢速命名 ID (slug ID)
├─ calculations.ts       # 變動量、漂移、波動度、百分位數、自動化指標
├─ portalAnalytics.ts    # 搜尋、排序、統計、資料列模型、面板模型
├─ charts.ts             # SVG 路徑與圖表模型函式
├─ simulator.ts          # 確定性更新迴圈輔助函式
├─ chartAudit.ts         # 供審查的圖表元資料
└─ __tests__/
   ├─ calculations.test.ts
   ├─ portalAnalytics.test.ts
   ├─ charts.test.ts
   ├─ simulator.test.ts
   ├─ fixtures.test.ts
   └─ chartAudit.test.ts

---

自动化指标定义与审查用途

---

步骤 1 — 为工艺窗口计算加入 Kiro 引导规范

建立 .kiro/steering/process-math.md：

# 製程數學引導規範
- 將所有顯示的變動量（deltas）和指標變動視為百分點，而非小數。
- 漂移值必須為零或負數。
- 在此展示中，P05 變動量為每日變動量的第五百分位數。
- 訊號波動度使用 sqrt(252) 年化計算，以呼應原型設計的計算風格。
- 保持所有計算函式為純函式且無副作用。
- 請勿杜撰實際設備資料或製程發佈聲明。
- 展示模擬必須明確標記為模擬行為。
- 除非工作坊明確要求建立合成固定裝置（fixtures），否則請保留原始入口網站的值與序列。

建立 .kiro/steering/testing.md：

# 測試引導規範
每個製程視窗公式都需要確定性的單元測試。
使用屬性導向測試（property-style tests）來驗證不變量，例如漂移量 <= 0。
測試空陣列、單點陣列、平坦指標、全漲指標、全跌指標、無效指標以及極端漂移。
在模擬測試中使用注入的隨機值。
驗證來自入口網站展示的所有八個自動化單元序列和四個狀態圖磚序列。

给 Kiro 的提示词示例

Create a spec for extracting the latest factory automation portal JavaScript into TypeScript analytics modules. Include process-window formula definitions, sort and search behavior, SVG path generation, live simulation behavior, fixture parity, status-tile analytics, tests, edge cases, and production-hardening tasks.

商业逻辑： 引导规范在代码产生之前先定义了指标的含意。开发者需要一致的单位和正负号惯例，以避免产生误导性的排名。

程序逻辑： Kiro 使用引导规则来产生纯函数与测试，而不是将计算逻辑嵌入 UI 转译过程中。

预期结果： Kiro 为自动化分析引擎产出需求／设计／任务流程。

系统设计原理解析：

● 工艺数学引导规范是强制性的，因为原型包含诸如 ret、dd 和 perc 等简短的辅助名称；生产环境开发者需要明确的定义。

● 测试引导规范与数学规范分离，因为测试覆盖率是一项工程政策，而非数学公式。

● 禁止杜撰实际数据的规则，能确保工作坊的真实性。模拟数据仅能在明确标记为展示行为时使用。

---

步骤 2 — 定义类型

建立 src/domain/types.ts：

export type SortKey = 'indexPct' | 'deltaPct' | 'stability' | 'processFactor' | 'windowRatePct' | 'maxDriftPct';

export type RuntimeCard = {
  title: string;
  body: string;
  tags: string[];
};

export type ToolCard = {
  name: string;
  desc: string;
  signals: string[];
};

export type SpecialistCard = {
  name: string;
  focus: string;
  tools: string;
};

export type RunbookStep = [string, string, string];

export type AutomationCell = {
  name: string;
  strategy: string;
  indexPct: number;
  deltaPct: number;
  stability: number;
  processFactor: number;
  windowRatePct: number;
  skew: number;
  maxDriftPct: number;
  series: number[];
};

export type AutomationMetrics = {
  windowIndexPct: number;
  signalVolPct: number;
  efficiencyRatio: number;
  p05DeltaPct: number;
  bestDeltaPct: number;
  worstDeltaPct: number;
  windowRatePct: number;
  maxDriftPct: number;
};

export type StatusTile = {
  key: 'RUNTIME' | 'GATEWAY' | 'POLICY' | 'EVAL';
  move: string;
  state: 'READY' | 'WATCH';
  up: boolean;
  series: number[];
};

商业逻辑： 类型文件化了哪些数值是原始输入，哪些是衍生的分析结果。它们也保留了 Runtime、Tools、Governed 和 Runbook 面板所需的非数据列门户数据。

程序逻辑： SortKey 模拟了展示中的排序按钮。AutomationCell 对应工艺窗口的数据列对象，而 AutomationMetrics 则对应详细数据面板中的区块。

预期结果： TypeScript 在开发期间能捕捉到无效的排序键值、缺失的固定装置字段或不完整的门户面板数据。

系统设计原理解析：

● 明确的类型取代了隐式的 JavaScript 对象形状。

● 排序键值使用领域名称，而非 UI 标签（如 INDEX、PF 或 DRIFT），这使代码更容易理解，同时在展示层保留原有的标签。

● 衍生指标与自动化工作站输入分离，因为诸如 P05 变动量和效率比等数值是由序列计算而得，而非手动维护。

---

步骤 3 — 完整复制门户固定装置

建立 src/domain/fixtures.ts：

import type { AutomationCell, RuntimeCard, RunbookStep, SpecialistCard, StatusTile, ToolCard } from './types';

export const runtimeCards: RuntimeCard[] = [
  { title: 'Synchronous Runtime', body: 'runtime entrypoint in app.py validates prompt, injects request and session context, runs an AI assistant backed by Amazon Bedrock, and returns structured engineering analysis.', tags: ['app.py', 'FactoryAutomationApp', 'boto3 invoke'] },
  { title: 'Streaming Runtime', body: 'Async entrypoint yields incremental chunks from agent.stream_async so portals and chat interfaces can render analysis progressively.', tags: ['app_streaming.py', 'async', 'partial output'] },
  { title: 'Large Payload Runtime', body: 'Base64 Excel and image fields are decoded into typed document and image content payloads for combined factory engineering analysis.', tags: ['xlsx', 'png', 'base64'] },
  { title: 'Payload Validation', body: 'Local validators check required prompt field, optional metadata, and unknown top-level fields before runtime invocation.', tags: ['JSON Schema', 'fail fast', 'client contract'] },
  { title: 'Smoke Tests', body: 'Deterministic tests validate payload contract and Python calculation tools without model calls, credentials, or latency.', tags: ['pytest', 'deterministic', 'local'] },
  { title: 'Session Cleanup', body: 'Runtime sessions are treated as managed resources and stopped explicitly after workflow completion.', tags: ['session ID', 'cleanup', 'operations'] },
];

export const tools: ToolCard[] = [
  { name: 'throughput_throughput', desc: 'Assess WIP queue stress, tool availability pressure, wafer throughput, and hot-lot preference.', signals: ['queue depth', 'tool availability', 'wafer throughput', 'hot-lot preference'] },
  { name: 'metrology_drift_widening', desc: 'Assess inline and lot-level drift widening, CD-SEM pressure, yield-loss watch, and measurement capacity.', signals: ['inline drift', 'lot drift', 'CD-SEM index', 'yield-loss watch'] },
  { name: 'process_window_drift', desc: 'Assess process capability, overlay error, recipe divergence, lot flow, and process-window drift.', signals: ['overlay error', 'process capability', 'recipe divergence', 'lot flow'] },
  { name: 'tool_to_tool_mismatch', desc: 'Assess overlay mismatch, backlog pressure, baseline offsets, and control context.', signals: ['overlay mismatch', 'baseline offsets', 'control context', 'tool matching'] },
];

export const specialists: SpecialistCard[] = [
  { name: 'throughput', focus: 'throughput stability, WIP queue stress, hot-lot preference, and tool capacity depth', tools: 'bpu_change, throughput_buffer' },
  { name: 'metrology', focus: 'CD-SEM drift widening, yield-loss pressure, defect-risk drift, and measurement capacity', tools: 'bpu_change' },
  { name: 'overlay', focus: 'tool-to-tool mismatch, lot flow, overlay drift, baseline offsets, and control context', tools: 'control_amount' },
  { name: 'etch-process', focus: 'overlay error, process capability, recipe divergence, controller reaction, and process-window drift', tools: 'bpu_change' },
];

export const runbook: RunbookStep[] = [
  ['0-10', 'Environment and architecture check', 'Confirm AWS identity, region, Python environment, project resources, and role boundaries.'],
  ['10-25', 'Prompt and schema contracts', 'Create runtime system prompt, orchestrator prompt, canonical tool schema, and payload contract.'],
  ['25-45', 'Local agent and tooling build', 'Implement AI assistance tools, local runtime logic, local FastAPI tool server server, and discovery client.'],
  ['45-65', 'Validation, policy, and smoke tests', 'Run payload validators, deterministic tool smoke tests, policy tests, and tool schema linting.'],
  ['65-85', 'Managed deployment', 'Launch runtime, package Lambda target, create AWS tool gateway, and register tooling target.'],
  ['85-105', 'Invocation and debugging', 'Invoke runtime with boto3, run Tools semantic search, direct tools/call, and tools/list debugging.'],
  ['105-115', 'Governed orchestration', 'Run specialists, bounded memory, response policy checks, and structured observability events.'],
  ['115-120', 'Evaluation and handoff', 'Run safe and blocked evaluation fixtures, capture session ID, cleanup, and backlog follow-up tasks.'],
];

export const automationCells: AutomationCell[] = [
  { name: 'Sofia Garcia', strategy: 'Etch Endpoint Depth Multi-Step Recipe Control', indexPct: 18.4, deltaPct: 0.42, stability: 0.73, processFactor: 1.8, windowRatePct: 58, skew: 0.44, maxDriftPct: 18, series: [100,101,100.7,102.2,104,103.2,105.7,106.1,108,109.8,111,112.4,114.9,116.2,118.4] },
  { name: 'Lucia Fernandez', strategy: 'Photolithography Overlay Drift Detection', indexPct: 16.9, deltaPct: 0.88, stability: 0.91, processFactor: 1.7, windowRatePct: 61, skew: 0.31, maxDriftPct: 22, series: [100,102.1,101.5,103.8,102.9,106.4,108.2,107.5,110.8,112.2,111.6,114.1,115.2,116,116.9] },
  { name: 'Carmen Lopez', strategy: 'Chamber Matching RF Power Pressure Stability', indexPct: 14.2, deltaPct: -0.31, stability: 0.68, processFactor: 1.6, windowRatePct: 56, skew: 0.22, maxDriftPct: 25, series: [100,99.4,101.7,103.2,104.8,103.7,106.8,108.9,110.4,109.2,112.6,113.8,115.1,114.8,114.2] },
  { name: 'Elena Martin', strategy: 'Factory Line Yield Trend Automation', indexPct: 11.8, deltaPct: 0.17, stability: 0.62, processFactor: 1.5, windowRatePct: 54, skew: 0.18, maxDriftPct: 17, series: [100,100.8,101.1,102.5,103.2,104,103.8,105.4,106.2,107,108.9,109.3,110.2,111.1,111.8] },
  { name: 'Marta Sanchez', strategy: 'Recipe Parameter Relative Stability', indexPct: 9.6, deltaPct: 0.09, stability: 0.57, processFactor: 1.4, windowRatePct: 53, skew: 0.09, maxDriftPct: 15, series: [100,100.2,99.9,101,101.8,102.5,102.2,103.6,104.1,105.4,106,106.8,108.2,109,109.6] },
  { name: 'Paula Romero', strategy: 'Metrology Feature Ensemble Scoring', indexPct: 7.1, deltaPct: -0.12, stability: 0.49, processFactor: 1.3, windowRatePct: 52, skew: -0.04, maxDriftPct: 14, series: [100,100.5,101.2,100.8,102.1,102.7,103.4,104.2,103.8,105,105.4,106.2,106.8,107.3,107.1] },
  { name: 'Ana Torres', strategy: 'Endpoint Signal Breakout Alarm System', indexPct: 5.4, deltaPct: 0.28, stability: 0.42, processFactor: 1.2, windowRatePct: 51, skew: 0.12, maxDriftPct: 19, series: [100,99.1,100.4,101.6,100.8,102.2,101.5,103.4,102.8,104.2,103.8,104.7,105.1,105.2,105.4] },
  { name: 'Laura Navarro', strategy: 'Multi-Tool Mean Reversion Control', indexPct: 3.8, deltaPct: -0.06, stability: 0.35, processFactor: 1.1, windowRatePct: 49, skew: -0.11, maxDriftPct: 16, series: [100,100.4,99.8,100.9,101.4,100.6,101.8,102.2,101.7,102.8,103.1,102.9,103.6,103.9,103.8] },
];

export const statusTiles: StatusTile[] = [
  { key: 'RUNTIME', move: '+0.38%', state: 'READY', up: true, series: [20,21,20,22,23,23,24,25,24,26] },
  { key: 'GATEWAY', move: '-0.22%', state: 'WATCH', up: false, series: [30,29,31,28,27,26,25,24,23,22] },
  { key: 'POLICY', move: '+0.62%', state: 'READY', up: true, series: [18,18.5,19,18.7,20,21,20.5,22,23,23.5] },
  { key: 'EVAL', move: '+2.18%', state: 'READY', up: true, series: [20,22,21,24,26,25,29,28,32,34] },
];

商业逻辑： 固定装置保留了门户作为单一事实来源。开发者应能证明每个可见的数据列、图砖、卡片和执行手册步骤都得到了呈现。

程序逻辑： 此文件映射了原始的 JavaScript 数组，并为 React、测试、分析模块和文件提供一个具备类型定义的导入路径。

预期结果： 固定装置测试可以断言数量：6 个运行时卡片、4 个工具、4 个专家、8 个执行手册步骤、8 个自动化单元和 4 个状态图砖。

---

步骤 4 — 实施计算逻辑

建立 src/domain/calculations.ts：

import type { AutomationMetrics } from './types';

export function deltasPct(series: number[]): number[] {
  if (series.length < 2) return [];
  return series.slice(1).map((value, index) => ((value / series[index]) - 1) * 100);
}

export function driftPct(series: number[]): number[] {
  if (!series.length) return [];
  let peak = series[0];
  return series.map(value => {
    peak = Math.max(peak, value);
    return peak === 0 ? 0 : ((value / peak) - 1) * 100;
  });
}

export function average(values: number[]): number {
  return values.length ? values.reduce((a, b) => a + b, 0) / values.length : 0;
}

export function standardDeviation(values: number[]): number {
  const m = average(values);
  return values.length ? Math.sqrt(average(values.map(v => (v - m) ** 2))) : 0;
}

export function percentile(values: number[], p: number): number {
  if (!values.length) return 0;
  const sorted = [...values].sort((a, b) => a - b);
  const index = Math.min(sorted.length - 1, Math.max(0, Math.floor((p / 100) * sorted.length)));
  return sorted[index];
}

export function automationMetrics(series: number[]): AutomationMetrics {
  const deltas = deltasPct(series);
  const drift = driftPct(series);
  const windowIndexPct = series.length >= 2 ? ((series.at(-1)! / series[0]) - 1) * 100 : 0;
  const maxDriftPct = drift.length ? Math.min(...drift) : 0;

  return {
    windowIndexPct,
    signalVolPct: standardDeviation(deltas) * Math.sqrt(252),
    efficiencyRatio: maxDriftPct === 0 ? 0 : windowIndexPct / Math.abs(maxDriftPct),
    p05DeltaPct: percentile(deltas, 5),
    bestDeltaPct: deltas.length ? Math.max(...deltas) : 0,
    worstDeltaPct: deltas.length ? Math.min(...deltas) : 0,
    windowRatePct: deltas.length ? deltas.filter(x => x > 0).length / deltas.length * 100 : 0,
    maxDriftPct,
  };
}

商业逻辑： 这些函数使用专业名称和安全的空数组处理行为，重新实现分析面板的逻辑。

程序逻辑： 此段代码将原型的辅助工具转换为可组合的函数。automationMetrics 聚合了详细数据面板中显示的特定区块数值。

预期结果： 传入 Sofia 的指标序列会返回约 18.4% 的窗口指标、负值最大漂移以及面板所需的进阶分析数值。

系统设计原理解析：

● 纯函数使分析引擎可供 UI、API、测试或批次作业使用。

● automationMetrics 集中管理面板计算，使 React 详细数据面板不需重复编写公式。

● 百分位数方法故意呼应了简化的展示逻辑。生产环境系统在将下尾部摘要用于运营决策前，需要更健全的数据治理。

---

步骤 5 — 实施排序、过滤、摘要统计与面板模型

建立 src/domain/portalAnalytics.ts：

import type { AutomationCell, SortKey, StatusTile } from './types';
import { automationMetrics } from './calculations';

export function signed(value: number, digits = 1, suffix = ''): string {
  return `${value >= 0 ? '+' : ''}${value.toFixed(digits)}${suffix}`;
}

export function semanticClass(value: number): 'pos' | 'neg' {
  return value >= 0 ? 'pos' : 'neg';
}

export function slugId(value: string): string {
  return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
}

export function searchAndSort(cells: AutomationCell[], query: string, sortKey: SortKey): AutomationCell[] {
  const q = query.trim().toLowerCase();
  return cells
    .filter(cell => !q || cell.name.toLowerCase().includes(q) || cell.strategy.toLowerCase().includes(q))
    .sort((a, b) => sortKey === 'maxDriftPct' ? a.maxDriftPct - b.maxDriftPct : b[sortKey] - a[sortKey]);
}

export function portalLeaderboardStats(cells: AutomationCell[]) {
  return {
    cellCount: cells.length,
    bestStability: Math.max(...cells.map(cell => cell.stability)),
    avgWindowRatePct: cells.reduce((sum, cell) => sum + cell.windowRatePct, 0) / cells.length,
    bestIndexPct: Math.max(...cells.map(cell => cell.indexPct)),
  };
}

export function statusTileSummary(tiles: StatusTile[]) {
  return {
    tileCount: tiles.length,
    readyCount: tiles.filter(tile => tile.state === 'READY').length,
    watchCount: tiles.filter(tile => tile.state === 'WATCH').length,
  };
}

export function analysisPanelModel(cell: AutomationCell) {
  return {
    id: slugId(cell.name),
    owner: cell.name,
    strategy: cell.strategy,
    metrics: automationMetrics(cell.series),
    automationNote: `Automation path: runtime validates payload and session context; Tools discovers or calls domain tools; Lambda returns structured evidence; specialists synthesize throughput, metrology, overlay, and etch-process findings; policy checks confirm boundary terms; telemetry is emitted with request ID and trace ID. Domain context: ${cell.strategy}.`,
  };
}

商业逻辑： 用户可以依据指标、变动量、稳定度、工艺因子、窗口率或漂移进行排名，并依据拥有者或工艺模式进行搜索。

程序逻辑： 此函数重现了展示的 data、panel、architecture 和状态摘要行为。最大漂移采用升序排序，因为在原始逻辑中，较低的漂移压力代表较佳的状态。

预期结果： 依指标排序时 Sofia 会排在第一位。搜索 overlay 会返回 Lucia Fernandez。搜索 metrology 会返回 Paula Romero。搜索 tool 会返回 Laura Navarro。

系统设计原理解析：

● 排序逻辑自转译流程中分离，如此一来，测试便能在不依赖 UI 的情况下验证排名行为。

● 搜索同时匹配拥有者与策略，因为门户允许用户通过工艺模式来探索数据列。

● 最大漂移排序属于特例处理，因为压力指标的方向性通常与正向指标相反。

---

步骤 6 — 实施 SVG 路径辅助函数

建立 src/domain/charts.ts：

import { deltasPct, driftPct } from './calculations';

export function svgPath(values: number[], width: number, height: number, padding = 18): string {
  if (!values.length) return '';
  const min = Math.min(...values);
  const max = Math.max(...values);
  const range = max - min || 1;
  const innerWidth = width - padding * 2;
  const innerHeight = height - padding * 2;

  return values.map((value, index) => {
    const x = padding + index * innerWidth / Math.max(1, values.length - 1);
    const y = padding + innerHeight - ((value - min) / range) * innerHeight;
    return `${index ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`;
  }).join(' ');
}

export function histogramBars(deltas: number[], width: number, height: number, padding = 18) {
  const maxAbs = Math.max(...deltas.map(Math.abs), 1);
  const barWidth = (width - padding * 2) / Math.max(1, deltas.length);
  const mid = height / 2;

  return deltas.map((value, index) => {
    const barHeight = Math.abs(value) / maxAbs * (height / 2 - padding);
    return {
      x: padding + index * barWidth + 1,
      y: value >= 0 ? mid - barHeight : mid,
      width: Math.max(2, barWidth - 2),
      height: barHeight,
      positive: value >= 0,
    };
  });
}

export function sparklineModel(values: number[]) {
  return { viewBox: '0 0 120 32', path: svgPath(values, 120, 32, 2) };
}

export function indexChartModel(series: number[]) {
  return {
    viewBox: '0 0 680 190',
    path: svgPath(series, 680, 190, 20),
    label: `Index ${series[0]?.toFixed(1) ?? '0.0'} to ${series.at(-1)?.toFixed(1) ?? '0.0'}`,
  };
}

export function driftChartModel(series: number[]) {
  const drift = driftPct(series);
  return {
    viewBox: '0 0 680 120',
    drift,
    maxDriftPct: drift.length ? Math.min(...drift) : 0,
  };
}

export function deltaHistogramModel(series: number[]) {
  const deltas = deltasPct(series);
  return {
    viewBox: '0 0 680 120',
    deltas,
    bars: histogramBars(deltas, 680, 120, 18),
  };
}

商业逻辑： 比起单纯的数字，图表能帮助开发者更快理解趋势、漂移压力以及每日工艺变动量的分布。

程序逻辑： svgPath 呼应了原型路径产生器。histogramBars 将变动量转换为正向／负向长条条的矩形几何图形。图表模型函数将数据准备流程与 React/SVG 转译流程解耦。

预期结果： 同一个指标序列可以生成走势图、工艺窗口指标图、漂移模型和每日变动量直方图模型。

系统设计原理解析：

● 图表几何形状在纯函数中计算，因此可以在不依赖浏览器渲染的情况下进行测试。

● 路径函数将数值正规化到查看区（view box）。这使得同一个辅助函数既能支持微型走势图，也能支持大型图表。

● 直方图条条带有正向旗标（positive flag），因此 UI 可以直接套用绿色或红色样式，不需重新计算正负号逻辑。

---

步骤 7 — 实施受控的实时模拟

建立 src/domain/simulator.ts：

import type { AutomationCell } from './types';

export function nextTick(cells: AutomationCell[], random = Math.random): AutomationCell[] {
  return cells.map(cell => {
    const bump = (random() - 0.48) * 0.18;
    const nextDeltaPct = Number((cell.deltaPct + bump).toFixed(2));
    const nextIndexPct = Number((cell.indexPct + bump * 0.25).toFixed(2));

    return {
      ...cell,
      deltaPct: nextDeltaPct,
      indexPct: nextIndexPct,
      series: [...cell.series.slice(1), 100 + nextIndexPct],
    };
  });
}

商业逻辑： 展示看板每五秒更新一次，以模拟实时的自动化看板。开发者必须将其明确标记为模拟数据，而非实际设备数据。

程序逻辑： 此函数呼应了更新循环，但使随机性可被注入，以利进行确定性测试。

预期结果： 每个周期（tick）会调整变动量、微幅调整指标、移动系列窗口，并附加一个新的合成指标点。

系统设计原理解析：

● 注入随机性是因为测试需要确定性的行为。

● 该序列通过舍弃最旧的数据点来使用滚动窗口。这保留了图表长度并避免了无限制的内存增长。

● 该函数返回新对象而非变更原始数组，符合 React 状态管理预期。

---

步骤 8 — 加入测试

建立 src/domain/__tests__/calculations.test.ts：

import { describe, expect, it } from 'vitest';
import { automationMetrics, driftPct, deltasPct } from '../calculations';

describe('process-window calculations', () => {
  it('calculates deltas from indexed series', () => {
    expect(deltasPct([100, 110, 99]).map(x => Number(x.toFixed(2)))).toEqual([10, -10]);
  });

  it('drift is never positive', () => {
    expect(driftPct([100, 120, 90, 130]).every(x => x <= 0)).toBe(true);
  });

  it('creates automation panel metrics', () => {
    const metrics = automationMetrics([100, 105, 99.75]);
    expect(Number(metrics.windowIndexPct.toFixed(2))).toBe(-0.25);
    expect(Number(metrics.maxDriftPct.toFixed(2))).toBe(-5.00);
  });
});

建立 src/domain/__tests__/fixtures.test.ts：

import { describe, expect, it } from 'vitest';
import { automationCells, runtimeCards, runbook, specialists, statusTiles, tools } from '../fixtures';

describe('portal fixtures', () => {
  it('preserves portal fixture counts', () => {
    expect(runtimeCards).toHaveLength(6);
    expect(tools).toHaveLength(4);
    expect(specialists).toHaveLength(4);
    expect(runbook).toHaveLength(8);
    expect(automationCells).toHaveLength(8);
    expect(statusTiles).toHaveLength(4);
  });

  it('preserves required tool names', () => {
    expect(tools.map(tool => tool.name)).toEqual([
      'throughput_throughput',
      'metrology_drift_widening',
      'process_window_drift',
      'tool_to_tool_mismatch',
    ]);
  });
});

建立 src/domain/__tests__/portalAnalytics.test.ts :

import { describe, expect, it } from 'vitest';
import { automationCells } from '../fixtures';
import { searchAndSort, signed, slugId } from '../portalAnalytics';

describe('portal analytics', () => {
  it('formats signed values', () => {
    expect(signed(0.42, 2, '%')).toBe('+0.42%');
    expect(signed(-0.31, 2, '%')).toBe('-0.31%');
  });

  it('creates stable detail ids', () => {
    expect(slugId('Sofia Garcia')).toBe('sofia-garcia');
  });

  it('sorts by index descending', () => {
    expect(searchAndSort(automationCells, '', 'indexPct')[0].name).toBe('Sofia Garcia');
  });

  it('searches by process pattern', () => {
    expect(searchAndSort(automationCells, 'photolithography', 'indexPct').map(cell => cell.name)).toEqual(['Lucia Fernandez']);
    expect(searchAndSort(automationCells, 'metrology', 'indexPct').map(cell => cell.name)).toEqual(['Paula Romero']);
  });
});

给 Kiro 的提示词示例

Review the automation analytics modules and tests. Add test cases for every automation-cell series, every status tile series, sort behavior for Index and Max Drift, search by each process-pattern keyword, SVG path boundaries, histogram positive/negative bars, and deterministic simulation with injected random values.

商业逻辑： 测试可保护驱动工程解读的计算公式，并证明 TypeScript 移植版仍与门户展示相符。

程序逻辑： 单元测试验证了已知的数值示例，并可扩展至涵盖所有的自动化工作站与状态图砖。

预期结果： 执行 npx vitest run 通过，且 Kiro 提出了额外的覆盖范围建议。

系统设计原理解析：

● 已知值测试能快速捕获公式退化。

● 要求 Kiro 加入自动化工作站专属的回归测试，使数据或公式的变更不会非预期地改变显示的分析结果。

● 图表测试着重于几何图形边界，因为视觉化图表测试成本高昂，且对于此工作坊而言并非必要。

---

最终实验室挑战

询问 Kiro：

Generate a complete analytics gap report comparing the TypeScript modules against the latest portal JavaScript functions and data structures: runtimeCards, tools, specialists, runbook, P, M, renderStatic, tab click handling, sg, cl, id, ret, dd, avg, sd, perc, path, spark, gridlines, eqChart, ddChart, hist, architecture, panel, data, render, tog, markets, clock, and the five-second update loop. Identify what is implemented, what is intentionally moved to React, and what still needs tests.

---

完成检查清单

● [ ] 已为 Runtime 卡片、工具、专家、执行手册步骤、自动化工作站和状态图砖定义类型。

● [ ] 已实施变动量、漂移、信号波动度、百分位数、效率比、P05 变动量、最佳／最差变动量以及窗口率。

● [ ] 搜索与排序重现展示行为。

● [ ] SVG 路径与直方图几何图形为纯函数。

● [ ] 图表模型辅助工具涵盖走势图、指标图、漂移图和变动量直方图。

● [ ] 实时模拟在测试中被明确标记且具备确定性。

● [ ] Kiro 已审查数学边缘情况。

● [ ] 测试涵盖固定装置、计算、排序、图表和模拟。

---

附录 — 用于分析测试的完整自动化工作站与状态图砖涵盖范围

使用此检查清单以确保分析引擎涵盖完整的门户展示，而非仅仅是示例数据列：

● Sofia Garcia — 蚀刻终点深度多步骤配方控制（Etch Endpoint Depth Multi-Step Recipe Control）：指标 +18.4%、变动量 +0.42%、稳定度 0.73、工艺因子 1.8、窗口率 58%、偏态 +0.44、最大漂移 18。

● Lucia Fernandez — 黄光微影叠对漂移检测（Photolithography Overlay Drift Detection）：指标 +16.9%、变动量 +0.88%、稳定度 0.91、工艺因子 1.7、窗口率 61%、偏态 +0.31、最大漂移 22。

● Carmen Lopez — 反应腔匹配射频功率压力稳定度（Chamber Matching RF Power Pressure Stability）：指标 +14.2%、变动量 -0.31%、稳定度 0.68、工艺因子 1.6、窗口率 56%、偏态 +0.22、最大漂移 25。

● Elena Martin — 工厂产线良率趋势自动化（Factory Line Yield Trend Automation）：指标 +11.8%、变动量 +0.17%、稳定度 0.62、工艺因子 1.5、窗口率 54%、偏态 +0.18、最大漂移 17。

● Marta Sanchez — 配方参数相对稳定度（Recipe Parameter Relative Stability）：指标 +9.6%、变动量 +0.09%、稳定度 0.57、工艺因子 1.4、窗口率 53%、偏态 +0.09、最大漂移 15。

● Paula Romero — 量测特徵集成评分（Metrology Feature Ensemble Scoring）：指标 +7.1%、变动量 -0.12%、稳定度 0.49、工艺因子 1.3、窗口率 52%、偏态 -0.04、最大漂移 14。

● Ana Torres — 终点信号异常告警系统（Endpoint Signal Breakout Alarm System）：指标 +5.4%、变动量 +0.28%、稳定度 0.42、工艺因子 1.2、窗口率 51%、偏态 +0.12、最大漂移 19。

● Laura Navarro — 多工具均值回归控制（Multi-Tool Mean Reversion Control）：指标 +3.8%、变动量 -0.06%、稳定度 0.35、工艺因子 1.1、窗口率 49%、偏态 -0.11、最大漂移 16。

状态图砖回归测试个案：

● RUNTIME：+0.38%, READY, 序列 [20,21,20,22,23,23,24,25,24,26]。

● GATEWAY：-0.22%, WATCH, 序列 [30,29,31,28,27,26,25,24,23,22]。

● POLICY：+0.62%, READY, 序列 [18,18.5,19,18.7,20,21,20.5,22,23,23.5]。

● EVAL：+2.18%, READY, 序列 [20,22,21,24,26,25,29,28,32,34]。

用于完整涵盖范围的 Kiro 提示词：

Generate a regression test suite that loads all six runtime cards, four tools, four specialists, eight runbook steps, eight automation-cell rows, and four status tiles. Validate summary stats, sort order for every sort key, search by each process-pattern keyword, SVG paths for each series, and automation panel metrics for every row.

---

针对进阶开发者的额外动手操练实验室 — HTML 图形分析

这些实验室藉由分析展示网站的 SVG 图表图形，扩展了自动化分析工作坊。它们遵循与原始量化分析工作坊相同的架构，但每个概念都针对工厂自动化门户进行了更新。

进阶图形分析目标

在本节结束时，进阶开发者将能够：

● 解释 HTML 如何将工艺窗口序列转换为 SVG 路径、区域、线条、标签和长条条。

● 通过确定性测试验证图表几何形状。

● 将视觉编码逻辑与工艺窗口计算分离。

● 建立图表审查元数据，帮助审查人员理解图形含意。

● 检测因缩放比例、内边距、样本过短或边缘情况数据所导致的误导性图表输出。

来自门户 HTML 文件的图表图形清单

门户 HTML 使用多个 JavaScript 函数来产生 SVG 图形：

● path(a,w,h,p) 将序列正规化为 SVG 的 M 和 L 指令。

● spark(a) 转译紧凑的数据列与状态图砖走势图。

● gridlines(w,h,p) 建立水平网格线和底部轴线。

● eqChart(a) 转译带有填满区域和起迄标签的工艺窗口指标路径。

● ddChart(a) 将漂迁移译为零轴下方的红色水位线形状。

● hist(a) 围绕中线转译每日工艺变动量长条条，并使用独立的正向和负向类别。

进阶实验室 1 — 图表几何形状契约测试

目标： 建立测试以证明 SVG 几何图形保持在图表边界内，并安全地处理平坦、过短和高波动的序列。

建立 src/domain/__tests__/chartGeometry.test.ts：

import { describe, expect, it } from 'vitest';
import { histogramBars, svgPath } from '../charts';

function extractNumbers(path: string): number[] {
  return path.match(/-?\d+(\.\d+)?/g)?.map(Number) ?? [];
}

describe('SVG chart geometry contracts', () => {
  it('keeps path coordinates inside the viewbox padding boundaries', () => {
    const d = svgPath([100, 102, 101, 104], 120, 32, 2);
    const numbers = extractNumbers(d);
    const xs = numbers.filter((_, index) => index % 2 === 0);
    const ys = numbers.filter((_, index) => index % 2 === 1);
    expect(Math.min(...xs)).toBeGreaterThanOrEqual(2);
    expect(Math.max(...xs)).toBeLessThanOrEqual(118);
    expect(Math.min(...ys)).toBeGreaterThanOrEqual(2);
    expect(Math.max(...ys)).toBeLessThanOrEqual(30);
  });

  it('renders flat series without division-by-zero geometry failures', () => {
    const d = svgPath([100, 100, 100], 120, 32, 2);
    expect(d).toContain('M');
    expect(d).toContain('L');
    expect(d).not.toContain('NaN');
    expect(d).not.toContain('Infinity');
  });

  it('creates positive and negative histogram bars around a midline', () => {
    const bars = histogramBars([1, -2, 0.5], 680, 120, 18);
    expect(bars.some(bar => bar.positive)).toBe(true);
    expect(bars.some(bar => !bar.positive)).toBe(true);
  });
});

Kiro 提示词：

Generate chart geometry tests for the portal HTML path, sparkline, Process Window Index Path, Drift Waterline, and Daily Process Delta Distribution behavior. Verify coordinate bounds, no NaN or Infinity, flat series behavior, short series behavior, positive/negative histogram flags, and drawing consistency across all automation-cell and status-tile series.

预期结果： 开发者可以重构图表代码，而不会意外产生损坏的 SVG。

进阶实验室 2 — SVG 视觉编码文件化

目标： 文件化工艺窗口概念与图形标记之间的关系，使图表行为可被审查。

建立 docs/svg-visual-encoding.md：

# 工廠自動化入口網站 SVG 視覺編碼說明

## 走勢圖 (Sparkline)
- 資料輸入：自動化單元指標序列或狀態圖磚微型序列。
- 標記類型：單一綠色線條。
- 目的：精簡的趨勢預覽。
- 風險：未顯示 Y 軸刻度，因此不應視為精確量測。

## 製程視窗指標路徑 (Process Window Index Path)
- 資料輸入：索引化的製程視窗序列。
- 標記類型：綠色線條加上半透明填滿區域。
- 目的：視覺化累積指標路徑。
- 標籤：第一個指標值與最後一個指標值。

## 漂移水位線 (Drift Waterline)
- 資料輸入：衍生自指標序列的漂移百分比序列。
- 標記類型：紅色線條與零軸下方的紅色填滿區域。
- 目的：顯示峰值到谷底的漂移壓力與復原情況。

## 每日製程變動量分佈 (Daily Process Delta Distribution)
- 資料輸入：每日製程變動量序列。
- 標記類型：圍繞水平中線的垂直長條條。
- 正向編碼：中線之上的綠色長條。
- 負向編碼：中線之下的紅色長條。

Kiro 提示词：

Create visual encoding documentation for the portal charts. Explain sparkline, Process Window Index Path, Drift Waterline, and Daily Process Delta Distribution using data input, SVG mark type, color encoding, scale limitations, automation-boundary notes, and reviewer cautions.

预期结果： 图表图形对开发者、设计师和审查人员而言变得清晰易懂。

进阶实验室 3 — 图表审查元数据产生器

目标： 为每个图表产生元数据，以便审查人员可以检查缩放比例、极值、范围、正负长条计数和标签文字。

建立 src/domain/chartAudit.ts：

import { deltasPct, driftPct } from './calculations';

export type SeriesAudit = {
  pointCount: number;
  min: number;
  max: number;
  range: number;
  first: number;
  last: number;
};

export type ChartAudit = {
  index: SeriesAudit;
  drift: SeriesAudit;
  deltas: SeriesAudit & {
    positiveCount: number;
    negativeCount: number;
    zeroCount: number;
  };
};

function auditSeries(values: number[]): SeriesAudit {
  if (!values.length) {
    return { pointCount: 0, min: 0, max: 0, range: 0, first: 0, last: 0 };
  }
  const min = Math.min(...values);
  const max = Math.max(...values);
  return {
    pointCount: values.length,
    min,
    max,
    range: max - min,
    first: values[0],
    last: values.at(-1)!,
  };
}

export function auditChartSeries(indexSeries: number[]): ChartAudit {
  const drift = driftPct(indexSeries);
  const deltas = deltasPct(indexSeries);
  const deltasAudit = auditSeries(deltas);
  return {
    index: auditSeries(indexSeries),
    drift: auditSeries(drift),
    deltas: {
      ...deltasAudit,
      positiveCount: deltas.filter(value => value > 0).length,
      negativeCount: deltas.filter(value => value < 0).length,
      zeroCount: deltas.filter(value => value === 0).length,
    },
  };
}

Kiro 提示词：

Add chart-audit metadata for every process-window index series and every status-tile mini-series. Include point count, min, max, range, first/last values, drift range, delta range, and positive/negative/zero delta counts. Add tests for all eight automation-cell series and four status-tile series.

预期结果： 分析审查人员无需开启浏览器即可检查图表输入与缩放风险。

进阶实验室 4 — 具误导性的图表边缘情况实验室

目标： 教导开发者识别图表虽然在技术上正确，但视觉上可能产生误导的边缘情况。

建立 docs/misleading-chart-edge-cases.md：

# 工廠自動化入口網站 具誤導性的圖表邊緣情況

## 平坦序列
平坦的指標序列會產生一條直線，但如果忽略標籤，視覺範圍的回退機制可能會使微小的變動看起來比實際更大。

## 單點序列
單個數據點無法呈現趨勢。圖表應轉譯安全的預留位置，或顯示資料不足的訊息。

## 極端離群值
單一巨大跳躍可能會壓縮所有其他變化，使正常的訊號變動看起來像是隱形了。

## 過短的變動量視窗
14 點的變動量直方圖具有教學意義，但不足以得出穩健的分佈結論。

## 缺失刻度標籤
走勢圖對於快速形狀識別非常實用，但不應被用作精確的製程證據。

## 自動化邊界
任何圖表皆不應被解讀為設備指令、製程發佈決策或旁路訊號。

Kiro 提示词：

Create a misleading-graphic edge-case guide for the portal chart functions. Cover flat series, one-point series, extreme outliers, short delta windows, missing y-axis scale, histogram interpretation limits, and automation-boundary cautions.

进阶实验室 5 — 图表渲染验收标准

目标： 在进行生产环境重构验收之前，定义图表图形的验收标准。

建立 docs/chart-rendering-acceptance-criteria.md：

# 工廠自動化入口網站 圖表渲染驗收標準

## 製程視窗指標路徑 (Process Window Index Path)
- 使用與 HTML 原型相同的正規化座標邏輯。
- 包含可見的線條與填滿區域。
- 標註第一個和最後一個指標值。
- 不得轉譯出 NaN 或 Infinity。

## 漂移水位線 (Drift Waterline)
- 漂移值在轉譯前必須為零或負數。
- 零軸必須清晰可見。
- 紅色區域隨著漂移加深而向下擴展。
- 最大漂移標籤與計算出的最小漂移相符。

## 每日製程變動量分佈 (Daily Process Delta Distribution)
- 正向長條出現在中線上方。
- 負向長條出現在中線下方。
- 零值長條不會導致視覺錯誤。
- 長條寬度在所有支援的圖表尺寸下皆保持可見。

## 走勢圖 (Sparkline)
- 緊湊的圖表不包含未受支援的刻度宣告。
- 為所有自動化工作站與狀態圖磚微型序列保留趨勢形狀。

Kiro 提示词：

Generate chart rendering acceptance criteria for React/SVG refactoring. Include Process Window Index Path, Drift Waterline, Daily Process Delta Distribution, and Sparkline checks. Tie every visual assertion to a deterministic test where possible.

进阶最终挑战 — SVG 图表精确度审查

询问 Kiro：

Perform an SVG chart fidelity review against the latest portal HTML file. Compare path normalization, padding, index-area closure, grid lines, drift zero axis, histogram midline, positive/negative bar placement, labels, status-tile sparklines, and edge-case behavior. Produce a prioritized remediation backlog.

进阶图形分析完成检查清单

● [ ] 图表几何形状测试已验证边界与无效数值保护。

● [ ] 视觉编码文件已解释每个门户 SVG 图表类型。

● [ ] 图表审查元数据已摘要指标、漂移与变动量序列。

● [ ] 已文件化具误导性的图表边缘情况。

● [ ] 转译验收标准为图表重构提供了保护。

● [ ] 自动化边界告警在图表文件中保持可见。