# Project: n8n 演示展览项目
_Last updated: 2025-09-29_

## Pinned（仅高置信"必须遵守"写入；受保护不可修订）
- 必须确保所有 React Hook 依赖正确声明，避免闭包陷阱
- 绝对不允许在生产代码中留下console.log调试语句
- 必须在每次修改后检查浏览器控制台，确认无任何错误
- 项目运行在端口4173，不是5173

### 🔴 前端开发质量保证（绝对禁止规则）
- **必须**：每次修改前端代码后，使用 playwright/puppeteer 检查浏览器控制台
- **绝不允许**：代码中出现以下问题
  - 重复导入语句
  - 函数定义不完整或混乱
  - useCallback/useEffect 依赖项错误
  - console.log 调试语句遗留
  - 语法错误导致的构建失败

### 质量检查流程（强制执行）
1. 修改代码
2. 检查语法（构建测试）
3. 打开浏览器控制台检查
4. 确认无任何错误才算完成

### 错误后果警示
- 重复导入 → React hooks 冲突
- 函数结构混乱 → 语法解析失败
- 依赖项错误 → 闭包陷阱，状态更新失败
- console语句 → 生产环境信息泄露

## Decisions（按时间顺序追加，历史不可改）
- 2025-09-29: 决定使用 useCallback 解决 React Hook 依赖问题（理由：确保函数能够正确获取最新状态值）
- 2025-09-29: 决定从useEffect依赖项中移除terminalData，避免重复执行（理由：防止数据更新时的无限循环）
- 2025-09-29: 决定在useCallback内部使用局部变量避免闭包问题（理由：确保获取最新状态值）

## TODO（权威待办清单）

## In Progress

## Done（最近完成的放前面）
- 2025-09-29: [#4] 实现Agent状态栏条件显示逻辑优化（evidence：WorkflowPageV4.tsx）
- 2025-09-29: [#3] 完成文旅订单班无响应问题调试日志添加（evidence：WorkflowPageV4.tsx, index.ts, test-terminal-data.html, test-workflow.html）
- 2025-09-29: [#2] 修复文旅订单班useEffect和useCallback依赖项问题（evidence：/web_frontend/exhibition-demo/src/pages/WorkflowPageV4.tsx）
- 2025-09-29: [#1] 修复文旅JSON加载失败问题（evidence：/web_frontend/exhibition-demo/src/pages/WorkflowPageV4.tsx）

## Risks & Assumptions
- Risk：React Hook 依赖管理复杂性增加（Mitigation：添加完整的依赖声明和调试日志）
- Risk：过多的调试日志可能影响性能（Mitigation：仅在开发环境启用，生产环境需移除）
- Assumption：useCallback 能够有效解决闭包陷阱问题（Confidence：High）
- Assumption：浏览器控制台调试日志能够准确反映文旅订单班的数据流转问题（Confidence：High）

## Notes（简要要点）
- 2025-09-29: Agent状态栏现在只在选择订单班且数据加载成功后显示，条件为：selectedOrderClass && terminalData
- 2025-09-29: 添加了未选择订单班时的友好提示，说明每个订单班有专属的AI专家团队
- 2025-09-29: terminalData.agents 数据结构包含：id（标识）、name（名称）、icon（emoji图标）、avatar（头像图片）、outputs（输出内容）
- 2025-09-29: 专家团队信息现在根据选中的订单班动态显示，头像、名称、图标都从terminalData获取
- 2025-09-29: 完成文旅订单班无响应问题调试环境搭建，添加了全链路调试日志跟踪数据流转
- 2025-09-29: 调试日志覆盖范围：handleRequirementSubmit → loadTerminalData → getSimulationData → executeStartupSequence
- 2025-09-29: 确认文旅订单班ID为"wenlu"，数据结构已从JSON格式改为TSX格式提供类型安全
- 2025-09-29: 创建了两个测试页面：test-terminal-data.html（基础数据加载）和test-workflow.html（完整工作流）
- 2025-09-29: 文旅和食品订单班都使用箭头函数形式的agent引用，数据结构一致性已确认
- 2025-09-29: 调试排查步骤：访问localhost:4173 → 打开F12控制台 → 选择文旅订单班 → 查看日志输出
- 2025-09-29: 文旅订单班加载失败的根本原因是useEffect依赖项包含terminalData导致闭包问题
- 2025-09-29: React Hook 依赖问题是导致功能失效的常见原因，需要特别注意函数依赖的外部状态
- 2025-09-29: 使用 useCallback 可以确保函数在依赖变化时重新创建，避免闭包陷阱
- 2025-09-29: 添加调试日志有助于快速定位状态传递问题
- 2025-09-29: 已建立前端开发质量保证绝对禁止规则，确保代码质量和浏览器兼容性

## Context Index（轻量索引）