diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 3eed4d5..0300943 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -9,7 +9,13 @@ "Bash(npm run build:*)", "Bash(npm run test:*)", "Bash(python -m py_compile:*)", - "Bash(node --check:*)" + "Bash(node --check:*)", + "Bash(ls:*)", + "Bash(findstr:*)", + "mcp__zai-mcp-server__analyze_image" + ], + "additionalDirectories": [ + "c:\\Users\\meowr\\projects\\excel2json\\src\\lib" ] }, "enableAllProjectMcpServers": true, diff --git a/demands/DEMAND-proxy.md b/demands/DEMAND-proxy.md new file mode 100644 index 0000000..dc58a7c --- /dev/null +++ b/demands/DEMAND-proxy.md @@ -0,0 +1,163 @@ +这是一个为您准备的 **v3.0 版本需求文档**。 + +这份文档的核心目标是**“收口”**:将之前零散开发的“前端代理 (Proxy)”功能正式集成到主流程中,确立 **“混合模式 (Hybrid Mode)”** 的架构策略。 + +即:**前端负责实时测试和预览(利用 Proxy),后端/脚本负责全量执行(利用 Job Bundle)。** + +--- + +### 复制下面的内容发送给 Claude: + +--- + +**Role:** 资深全栈架构师 (SvelteKit + TypeScript) + +**Project Context:** +我们正在开发 "Excel2JSON ETL Blueprint Generator"。 +目前我们已经具备了: + +1. **前端:** Excel 解析、映射配置、JSON 预览。 +2. **后端能力:** 一个 `/api/proxy` 端点 (SvelteKit Endpoint),可以绕过 CORS 转发请求。 +3. **输出:** `job_bundle.json` 用于给 Python 脚本跑全量数据。 + +**Current Goal (Phase 3 Integration):** +我们需要正式集成 `/api/proxy`,实现 **“所见即所得”** 的 API 调试体验。 +用户在配置 API 字段时,可以直接点击“测试”,前端调用 Proxy 立即拿回数据并展示,确保配置无误后再导出。 + +### Phase 3: 在线调试与混合执行架构需求文档 + +#### 1. 核心架构策略:混合模式 (Hybrid Execution) + +为了平衡**用户体验**与**系统性能**,我们采用以下策略: + +* **调试/预览阶段 (Online Mode):** +* 使用 SvelteKit 后端代理 (`/api/proxy`)。 +* **作用:** 让用户在配置界面就能实时验证 "URL 填得对不对"、"JSON Path 提取得对不对"。 +* **限制:** 仅用于**单条数据**测试或**小批量 (前10条)** 预览。 + + +* **生产/执行阶段 (Offline Mode):** +* 使用 `job_bundle.json` + Python 脚本。 +* **作用:** 处理成千上万行数据的全量抓取和入库。 +* **优势:** 无超时限制,无浏览器崩溃风险。 + + + +#### 2. UI/UX 交互升级 + +##### 2.1 API 配置面板 (Enrichment Config Modal) + +在 `ApiConfigModal.svelte` 中增加 **"Test Connection" (测试连接)** 功能区。 + +* **输入区:** (已有的 URL, Method, Headers, Body 配置) +* **测试上下文 (Test Context):** +* 显示当前 Excel 的 **第一行数据** 作为测试样本。 +* *示例:* `User ID: 101`, `Name: Alice`。 +* 用户可以手动修改这些样本值来测试不同情况。 + + +* **操作:** 点击 **[Test Request]** 按钮。 +* **逻辑:** +1. 前端将 URL 模板中的 `{{Variables}}` 替换为测试样本值。 +2. 发送 POST 请求给本站的 `/api/proxy`。 +3. 等待响应。 + + +* **反馈区:** +* **Status:** 显示 HTTP 状态码 (e.g., `200 OK`, `404 Not Found`)。 +* **Response Preview:** 显示原始返回的 JSON (带语法高亮)。 +* **Extracted Result:** 根据用户配置的 `Response Path` (e.g., `data.balance`),显示最终提取到的值。 +* *交互:* 如果提取结果为 `undefined`,高亮提示用户检查 Path 配置。 + + + +##### 2.2 主界面实时预览 (Enriched Preview) + +在主界面的右侧 JSON 预览区,增加一个 **"Preview Enrichment" (预览增强数据)** 开关。 + +* **默认状态 (Off):** 仅展示静态映射后的数据(API 字段显示为 `null` 或占位符)。 +* **开启状态 (On):** +* **限制:** 仅对前 **5 行** 数据生效。 +* **加载:** 显示 Loading 骨架屏。 +* **并发:** 并发调用 `/api/proxy` (限制并发数为 3)。 +* **展示:** 成功获取后,JSON 预览中的相关字段会被真实数据填充并高亮显示。 +* **警告:** 在开关旁显示小字提示 *"Live preview limited to first 5 rows to prevent API abuse."* + + + +#### 3. 数据流与接口定义 (Data Flow) + +##### 3.1 前端代理调用函数 + +封装一个通用的 `proxyFetch` 工具函数,用于前端组件调用: + +```typescript +// src/lib/utils/proxy.ts + +interface ProxyOptions { + url: string; + method: string; + headers: Record; + body?: any; +} + +export async function proxyFetch(options: ProxyOptions): Promise { + // 1. 调用我们自己的 SvelteKit 后端 + const response = await fetch('/api/proxy', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(options) + }); + + if (!response.ok) { + throw new Error(`Proxy Error: ${response.statusText}`); + } + + return response.json(); +} + +``` + +##### 3.2 变量替换逻辑 (Template Interpolation) + +确保前端和后端(Python)使用一致的变量替换逻辑。建议实现一个简单的 `renderTemplate` 函数: + +```typescript +/** + * 将 "https://api.com/users/{{id}}" 使用 { id: 123 } 替换为 "https://api.com/users/123" + */ +export function renderTemplate(template: string, context: Record): string { + return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, key) => { + return context[key] !== undefined ? String(context[key]) : ''; + }); +} + +``` + +#### 4. 安全性与限流 (Security & Constraints) + +为了防止 `/api/proxy` 被滥用或导致服务器卡死,请在服务端 (`src/routes/api/proxy/+server.ts`) 增加以下保护: + +1. **超时控制:** 设置 `AbortController`,如果目标接口 10 秒未响应,强制中断并返回 504。 +2. **错误屏蔽:** 如果目标接口返回敏感信息(如 Stack Trace),后端应进行脱敏处理后再返回给前端。 + +#### 5. 开发任务清单 + +1. **工具库:** 实现 `src/lib/utils/proxy.ts` 和 `renderTemplate`。 +2. **组件升级:** +* 改造 `ApiConfigModal`:加入测试按钮和结果展示面板。 +* 改造 `JsonPreview`:集成“实时预览”开关和并发请求逻辑。 + + +3. **流程集成:** 确保在导出 `job_bundle.json` 时,不需要改动任何逻辑(导出依然是纯配置)。 + +--- + +### 给 AI 的提示 (Prompt Tip) + +* **Focus on State:** 提醒 Claude 注意 Svelte 的状态管理。在测试 API 时,不要阻塞主 UI 的渲染。建议使用 `async/await` 配合局部 loading 状态变量。 +* **Error Handling:** 强调错误处理。如果用户填的 API URL 是错的(比如 404),前端不应该报错崩溃,而是应该优雅地在“测试结果”面板里显示红色错误信息。 + +--- + +**请先实现 `src/lib/utils/proxy.ts` 和 `ApiConfigModal` 的测试功能。** \ No newline at end of file diff --git a/DEMAND-queryFiled.md b/demands/DEMAND-queryFiled.md similarity index 100% rename from DEMAND-queryFiled.md rename to demands/DEMAND-queryFiled.md diff --git a/DEMAND-字典映射.md b/demands/DEMAND-字典映射.md similarity index 100% rename from DEMAND-字典映射.md rename to demands/DEMAND-字典映射.md diff --git a/demands/DEMAND-样式.md b/demands/DEMAND-样式.md new file mode 100644 index 0000000..8168071 --- /dev/null +++ b/demands/DEMAND-样式.md @@ -0,0 +1,145 @@ + +**Role:** 资深 UI/UX 工程师 & Svelte 专家 + +**Current Context:** +我们已经完成了 "Excel2JSON ETL Blueprint Generator" 的核心功能(Excel 解析、API 配置、JSON 导出)。 +目前的界面比较原始。现在需要进行 **Phase 3: UI/UX Overhaul & Theming**。 + +**Goal:** +全面优化应用样式,引入 **Dark Mode (夜间模式)** 支持,提升视觉层级和交互体验。目标风格是 **"Modern SaaS"** (类似 Vercel/Linear/Shadcn 的风格)。 + +### Phase 3: UI/UX 优化与多主题需求文档 + +#### 1. 技术方案 (Technical Approach) + +* **Tailwind CSS Dark Mode:** 使用 `class` 策略(通过在 `` 标签添加 `class="dark"` 来切换)。 +* **State Management:** 创建一个 `themeStore.ts` (Svelte Store),用于管理 `light` | `dark` | `system` 状态,并持久化到 `localStorage`。 +* **CSS Variables:** 建议在 `app.css` 中定义语义化的 CSS 变量 (如 `--bg-primary`, `--text-secondary`),或者直接使用 Tailwind 的 `slate` 色系作为主轴。 + +#### 2. 设计规范 (Design System Specs) + +请严格遵循以下配色逻辑,确保深色模式下的对比度和可读性。 + +##### 2.1 基础色盘 (Color Palette) + +* **Primary Brand:** Indigo-600 (Light) / Indigo-500 (Dark) +* **Background (Canvas):** +* Light: `bg-white` (Main), `bg-slate-50` (Sidebar/Header) +* Dark: `bg-slate-950` (Main), `bg-slate-900` (Sidebar/Header) + + +* **Surface (Cards/Modals):** +* Light: `bg-white` + `shadow-sm` + `border-slate-200` +* Dark: `bg-slate-900` + `shadow-none` + `border-slate-800` + + +* **Text (Typography):** +* Primary: `text-slate-900` (Light) / `text-slate-50` (Dark) +* Secondary: `text-slate-500` (Light) / `text-slate-400` (Dark) +* Muted: `text-slate-400` (Light) / `text-slate-500` (Dark) + + +* **Borders:** `border-slate-200` (Light) / `border-slate-800` (Dark) + +##### 2.2 交互反馈 (Interactive States) + +* **Buttons:** +* Primary: Solid Indigo background. Hover: `hover:bg-indigo-700` (Light) / `hover:bg-indigo-400` (Dark). +* Ghost/Secondary: Transparent background. Hover: `hover:bg-slate-100` (Light) / `hover:bg-slate-800` (Dark). + + +* **Inputs:** +* Default: `bg-transparent border border-slate-300 dark:border-slate-700`. +* Focus: `ring-2 ring-indigo-500/20 border-indigo-500`. + + + +#### 3. 组件级优化详情 + +##### 3.1 顶部导航栏 (Header) + +* **布局:** Flexbox,高度 `h-14` or `h-16`。 +* **功能区:** +* 左侧: Logo + Title (Bold, Tracking-tight)。 +* 右侧: [Export Button] [Settings Icon] [Theme Toggle]。 + + +* **Theme Toggle:** 实现一个图标按钮,点击在 🌞 (Sun) / 🌙 (Moon) / 💻 (System) 之间切换。切换时添加平滑的 `transition-colors` 动画。 + +##### 3.2 Excel 表格区域 (Left Panel) + +* **容器:** 卡片式设计,圆角 `rounded-lg`,带边框。 +* **表头 (Thead):** +* Light: `bg-slate-50` +* Dark: `bg-slate-900` +* 文字: `text-xs font-semibold uppercase tracking-wider text-slate-500`. + + +* **单元格 (Td):** +* 必须有边框:`border-r border-b border-slate-200 dark:border-slate-800`。 +* 斑马纹 (Zebra Striping): 偶数行在 Dark mode 下给予微弱的背景色 `dark:even:bg-slate-900/50` 增加可读性。 + + +* **列配置按钮:** 表头上的“设置图标”在 Hover 时才显示,保持界面整洁。 + +##### 3.3 JSON 预览区域 (Right Panel) + +* **容器:** 模拟 IDE/终端外观。 +* **背景:** +* Light: `bg-slate-50` (或者纯白) +* Dark: `bg-[#0d1117]` (GitHub Dark Dimmed 风格) 或 `bg-slate-950`. + + +* **代码高亮:** +* **关键点:** 语法高亮需要根据主题动态切换。 +* 如果没有引入重的 highlighter 库,请手动为 Key/String/Number/Boolean 定义两套颜色。 +* *Example:* Keys (Blue-600/Blue-400), Strings (Green-600/Green-400), Numbers (Orange-600/Orange-400). + + +* **Copy 按钮:** 悬浮在右上角的绝对定位按钮,点击后显示 "Copied!" 提示。 + +##### 3.4 模态框 (Modals - API & Dictionary Config) + +* **背景遮罩 (Backdrop):** `bg-black/50` (Light) / `bg-black/80` (Dark) with `backdrop-blur-sm`. +* **弹窗本体:** `bg-white dark:bg-slate-900`,边框 `dark:border-slate-700`。 +* **表单元素:** 输入框在 Dark Mode 下背景应为 `bg-slate-950` 或深灰色,避免过亮。 + +##### 3.5 滚动条 (Scrollbars) + +* 请自定义 Webkit 滚动条样式,使其不再是默认的丑陋灰色条。 +* Track: Transparent. +* Thumb: `bg-slate-300 dark:bg-slate-700`,圆角 `rounded-full`。 + +#### 4. 开发任务清单 (Action Plan) + +1. **基础建设:** +* 在 `app.css` 中配置 Tailwind 的 `@apply` 基础样式。 +* 实现 `themeStore.ts` 并处理 `onMount` 时的系统偏好检测。 +* 在 `App.svelte` 根节点绑定 `class:dark={$themeStore === 'dark'}`。 + + +2. **组件重构:** +* 重写 `Header.svelte`,加入主题切换器。 +* 重构 `ExcelTable.svelte` 的 class,全面加入 `dark:` 修饰符。 +* 重构 `JsonPreview.svelte`,优化配色和字体 (使用 Monospace 字体)。 +* 优化 `Modal` 和 `Drawer` 组件的阴影和边框。 + + +3. **细节打磨:** +* 为所有可点击元素添加 `transition-all duration-200`。 +* 确保 Loading 状态(骨架屏或 Spinner)在深色模式下不可见度正常。 + + + +--- + +### 给 AI 的提示 (Prompt Tip) + +* **Syntax Highlighting:** 告诉 Claude,如果目前的 JSON 预览只是纯文本 `pre` 标签,请帮我写一个简单的 `syntaxHighlight(json)` 函数,通过正则把 HTML 标签包进去,并用 Tailwind 的颜色类(如 `text-blue-600 dark:text-blue-400`)来控制颜色,从而实现轻量级的双模式高亮。 + +--- + +### 你可以期待的效果 + +有了这份文档,Claude 会帮你把界面做得像 **VS Code** 或 **GitHub** 一样专业。 +左边是清爽的表格,右边是极客风的代码预览,切换开关时,整个页面会平滑过渡(如果不做 transition 就是瞬间切换,做了就是渐变,建议做 transition)。 \ No newline at end of file diff --git a/DEMAND.md b/demands/DEMAND.md similarity index 100% rename from DEMAND.md rename to demands/DEMAND.md diff --git a/src/lib/components/ApiConfigModal.svelte b/src/lib/components/ApiConfigModal.svelte index 23ff598..94947e9 100644 --- a/src/lib/components/ApiConfigModal.svelte +++ b/src/lib/components/ApiConfigModal.svelte @@ -1,18 +1,22 @@ @@ -98,141 +223,59 @@