light-chaser-pro 1.0.0

package/.trae/.ignore

@@ -0,0 +1 @@
+../deploy.bat

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 xiaopujun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# Light Chaser Pro 项目文档
+
+## 1. 项目概述 (Project Overview)
+
+**Light Chaser Pro (LC Pro)** 是一款基于 React 技术的现代化**低代码/无代码数据可视化大屏设计器**。它旨在帮助开发者和业务人员通过图形化界面，快速构建专业级的数据仪表盘、大屏展示和人机交互界面（HMI）。
+
+**核心价值：**
+- **所见即所得**：通过拖拽组件、配置属性即可完成页面搭建。
+- **逻辑编排**：内置“蓝图”系统，通过节点连线实现复杂的交互逻辑，无需编写代码。
+- **多数据源**：支持 HTTP、WebSocket、MQTT 等多种数据接入方式。
+
+## 2. 技术架构 (Technical Architecture)
+
+项目采用现代前端 Monorepo 架构构建：
+
+- **包管理器**：**pnpm** (使用 Workspace 管理多包依赖)
+- **核心框架**：React 18 + TypeScript
+- **构建工具**：Vite
+- **状态管理**：MobX (用于管理设计器复杂的全局状态)
+- **UI 组件库**：
+    - `antd`: 通用 UI 组件
+    - `light-chaser-ui`: 项目自研的专用 UI 组件库
+- **图表渲染**：ECharts, @antv/g2plot
+- **画布交互**：react-moveable, react-selecto
+- **本地存储**：localforage (IndexedDB)
+
+## 3. 目录结构与 Workspace (Directory Structure)
+
+项目采用 **Monorepo** 结构，核心代码分散在 `packages` 中（根目录配置在 `pnpm-workspace.yaml`）：
+
+### 3.1 Workspace Packages
+
+| 包名 (Package) | 目录 | 说明 |
+| :--- | :--- | :--- |
+| **light-chaser-app** | `/light-chaser-app` | **主应用核心**。包含设计器主体、画布、蓝图系统及运行时逻辑。 |
+| **light-chaser-ui** | `/light-chaser-ui` | **UI 组件库**。提供设计器面板中使用的自定义控件（如属性设置器、颜色选择器等）。 |
+| **light-chaser-util** | `/light-chaser-util` | **工具库**。通用的辅助函数和工具类。 |
+| **light-chaser-interface** | `/light-chaser-interface` | **接口定义**。定义项目通用的 TypeScript 接口和规范。 |
+| **light-chaser-types** | `/light-chaser-types` | **类型定义**。全局类型声明。 |
+| **light-chaser-cli** | `/light-chaser-cli` | **命令行工具**。可能用于脚手架或辅助构建任务。 |
+
+### 3.2 核心应用模块 (`light-chaser-app/src`)
+
+主应用 (`light-chaser-app`) 是项目的大脑，其 `src` 目录结构如下：
+
+- **`src/designer` (设计器核心)**:
+    - **Canvas**: 画布区域。
+    - **Header**: 顶部工具栏。
+    - **Left/Right**: 左右侧面板（组件库、图层、属性配置）。
+    - **Blueprint**: 蓝图逻辑编排模块。
+- **`src/comps` (可视化组件库)**:
+    - 包含所有可拖拽到画布上的组件（图表、文本、媒体等）。
+    - 每个组件包含 Definition (元数据), Controller (逻辑), Component (视图), Config (配置面板)。
+- **`src/designer/blueprint` (蓝图系统)**:
+    - 可视化逻辑编辑器，处理组件交互和事件流。
+
+## 4. 数据流与状态管理 (Data Flow)
+
+### 4.1 状态管理 (MobX)
+- `ProjectManager`: 管理项目整体配置。
+- `DesignerManager`: 管理画布交互状态。
+- `LayerListStore`: 管理组件图层树。
+
+### 4.2 数据持久化
+- **自动保存**: 利用 `localforage` 将快照存入 IndexedDB。
+- **项目文件**: 保存为 JSON 格式，包含画布配置、组件树 (Layer) 和蓝图逻辑 (Blueprint)。
+
+## 5. 核心功能特性 (Key Features)
+
+1.  **Monorepo 架构**: 模块解耦，便于维护和复用。
+2.  **可视化拖拽**: 自由布局，支持成组、锁定、快捷键操作。
+3.  **蓝图交互**: 节点式逻辑编排，支持复杂业务场景。
+4.  **多源数据**: 支持静态 JSON、API、WebSocket、MQTT。
+5.  **插件化组件**: 组件结构标准化，易于扩展。
+
+## 6. 开发指南 (Development Guide)
+
+### 环境准备
+- Node.js (推荐 LTS)
+- **pnpm** (必须安装: `npm install -g pnpm`)
+
+### 安装与启动
+
+1. **安装依赖** (在根目录执行):
+   ```bash
+   pnpm install
+   ```
+
+2. **启动开发环境**:
+   由于是 Monorepo，通常需要进入主应用目录或使用 pnpm 过滤器启动。
+   ```bash
+   # 或者在根目录使用 pnpm 过滤 (假设主应用有 dev 脚本)
+   pnpm --F light-chaser-app dev
+   ```
+
+3. **构建项目**:
+   ```bash
+   pnpm --F light-chaser-app build
+   ```

package/UI_DESIGN_SPEC.md

@@ -0,0 +1,130 @@
+# Light Chaser Pro - UI 设计规范文档
+
+本文档基于 "Dark Blue Dashboard" 设计风格制定，旨在统一项目的视觉体验与交互规范。后续所有组件开发与页面设计均需严格遵循本规范。
+
+## 1. 设计理念 (Design Philosophy)
+
+*   **沉浸式深色主题 (Immersive Dark Theme)**: 使用深蓝/蓝紫作为主色调，营造科技感与现代感，降低长时间使用的视觉疲劳。
+*   **高对比度 (High Contrast)**: 关键数据与操作按钮使用高饱和度的霓虹色（粉、蓝、青），在深色背景下形成鲜明对比。
+*   **层级分明 (Clear Hierarchy)**: 通过背景亮度的细微差异（背景色 vs 卡片色）与投影区分内容层级。
+*   **卡片式布局 (Card-based Layout)**: 内容被封装在独立的卡片容器中，边界清晰，圆角柔和。
+
+---
+
+## 2. 颜色系统 (Color System)
+
+### 2.1 背景色 (Backgrounds)
+*   **应用背景 (App Background)**: `#1E1E2F` (深蓝黑色，用于页面底层)
+*   **卡片背景 (Card Background)**: `#27293D` (稍亮的蓝灰色，用于内容容器)
+*   **侧边栏/导航栏 (Navigation)**: `#1E1E2F` 或透明度变体
+
+### 2.2 品牌色 / 强调色 (Brand & Accent Colors)
+*   **主色调 (Primary - Pink/Red)**: `#FD5D93` (用于主要操作按钮如 "Create"、关键高亮)
+    *   *渐变应用*: `linear-gradient(to bottom left, #fd5d93, #ec250d)`
+*   **信息色 (Info - Blue)**: `#1D8CF8` (用于辅助图表、链接、选中状态)
+    *   *渐变应用*: `linear-gradient(to bottom left, #1d8cf8, #3358f4)`
+*   **成功色 (Success - Teal/Green)**: `#00F2C3` (用于增长趋势、完成状态)
+    *   *渐变应用*: `linear-gradient(to bottom left, #00f2c3, #0098f0)`
+*   **警告/其他 (Warning/Purple)**: `#E14ECA` (用于特定图表线条或次要高亮)
+
+### 2.3 文本颜色 (Typography Colors)
+*   **主要文本 (Heading/Body)**: `#FFFFFF` (纯白，用于标题、数值、正文)
+*   **次要文本 (Muted/Label)**: `#9A9A9A` (灰白，用于副标题、图表轴标、辅助说明)
+*   **占位符/禁用 (Disabled)**: `rgba(255, 255, 255, 0.3)`
+
+---
+
+## 3. 排版 (Typography)
+
+*   **字体家族 (Font Family)**: `"Poppins", "Roboto", "Helvetica Neue", Arial, sans-serif`
+*   **字重 (Font Weight)**:
+    *   Light: 300 (大标题)
+    *   Regular: 400 (正文)
+    *   Medium: 500 (导航、小标题)
+    *   Bold: 700 (关键数值)
+
+### 3.1 文字层级规范
+*   **H1 / 页面标题**: 24px - 32px, White
+*   **H2 / 卡片标题**: 16px - 18px, Muted (`#9A9A9A`)，通常位于卡片左上角
+*   **H3 / 关键数值**: 24px - 36px, White, Bold (e.g., "9,000")
+*   **Body / 正文**: 14px, White/Muted
+*   **Small / 辅助文字**: 12px, Muted
+
+---
+
+## 4. 布局与间距 (Layout & Spacing)
+
+### 4.1 栅格系统 (Grid)
+*   采用 12 列栅格系统。
+*   **Gutter (槽宽)**: 20px - 30px。
+
+### 4.2 尺寸与圆角 (Dimensions & Radius)
+*   **卡片圆角 (Card Radius)**: `4px` 或 `6px` (保持微圆角，避免过度圆润)
+*   **按钮圆角 (Button Radius)**: `4px` (实心按钮) / `30px` (胶囊型，视具体场景)
+*   **内边距 (Padding)**:
+    *   卡片内边距: `20px` (标准)
+    *   卡片头部与内容间距: `15px`
+
+---
+
+## 5. 组件样式规范 (Component Styles)
+
+### 5.1 卡片 (Cards)
+*   **背景**: `#27293D`
+*   **阴影**: `0 1px 20px 0px rgba(0, 0, 0, 0.1)` (极其柔和的阴影，主要靠颜色区分层级)
+*   **边框**: 无边框 (None)
+
+### 5.2 按钮 (Buttons)
+*   **主要按钮 (Primary - "Create")**:
+    *   背景: `#FD5D93` (或渐变)
+    *   文字: White
+    *   圆角: `4px`
+    *   阴影: `0 4px 6px rgba(50, 50, 93, 0.11), 0 1px 3px rgba(0, 0, 0, 0.08)`
+    *   交互: Hover 时亮度提升或阴影加深。
+*   **次要/幽灵按钮 (Secondary/Outline - "Add Task")**:
+    *   背景: Transparent
+    *   边框: `1px solid #FD5D93` (或其他强调色)
+    *   文字: White 或 对应强调色
+
+### 5.3 图表 (Charts)
+*   **线条**: 平滑曲线 (Spline)。
+*   **描边宽度**: `3px`。
+*   **特效**: 
+    *   线条发光效果 (Glow/Shadow): `drop-shadow(0px 5px 5px rgba(..., 0.4))`
+    *   节点: 实心圆点，白色描边。
+
+### 5.4 导航栏 (Navbar)
+*   **布局**: 顶部水平布局。
+*   **状态**: 
+    *   激活项: 亮白色文字 + 底部或侧边强调色圆点 (e.g., 蓝色小圆点)。
+    *   未激活项: 灰色文字 (`#9A9A9A`)。
+
+---
+
+## 6. 代码实现参考 (CSS Variables)
+
+```css
+:root {
+  /* Colors */
+  --lc-color-bg-app: #1e1e2f;
+  --lc-color-bg-card: #27293d;
+  
+  --lc-color-primary: #fd5d93;
+  --lc-color-info: #1d8cf8;
+  --lc-color-success: #00f2c3;
+  --lc-color-warning: #ff8d72;
+  --lc-color-danger: #fd5d93;
+
+  /* Text */
+  --lc-color-text-primary: #ffffff;
+  --lc-color-text-secondary: #9a9a9a;
+  --lc-color-text-disabled: rgba(255, 255, 255, 0.3);
+
+  /* Spacing & Radius */
+  --lc-radius-base: 4px;
+  --lc-padding-card: 20px;
+  
+  /* Typography */
+  --lc-font-family: "Poppins", sans-serif;
+}
+```

package/deploy.bat

@@ -0,0 +1,98 @@
+@echo off
+chcp 65001 >nul
+
+setlocal enabledelayedexpansion
+
+REM 设置颜色变量
+for /F "tokens=1,2 delims=#" %%a in ('"prompt #$H#$E# & echo on & for %%b in (1) do rem"') do (
+  set "DEL=%%a"
+)
+
+echo.
+echo ========================================
+echo       开始部署LIGHT CHASER PRO 前端
+echo ========================================
+echo.
+
+REM 检查必要的工具是否安装
+
+echo [1/6] 检查工具链...
+
+where ssh >nul 2>nul
+if errorlevel 1 (
+    echo 错误: 未找到ssh命令，请安装OpenSSH或添加ssh到PATH
+    pause
+    exit /b 1
+)
+
+where scp >nul 2>nul
+if errorlevel 1 (
+    echo 错误: 未找到scp命令，请安装OpenSSH或添加scp到PATH
+    pause
+    exit /b 1
+)
+
+echo [2/6] 初始化部署环境...
+
+set "FRONTEND_DIR=D:\dev_project\light-chaser-pro"
+set "FRONTEND_ZIP=app.zip"
+
+set "SERVER_USER=root"
+set "SERVER_HOST=116.198.230.57"
+set "SERVER_PORT=22"
+set "DEPLOY_DIR=/home/dagu/LCP/lib"
+set "APP_ROOT=/home/dagu/LCP"
+set "SERVICE_NAME=your_service_name"
+
+echo [3/6] 构建前端项目...
+if errorlevel 1 (
+    echo 错误: 前端目录不存在
+    pause
+    exit /b 1
+)
+
+call pnpm install
+if errorlevel 1 (
+    echo 错误: pnpm install 失败
+    pause
+    exit /b 1
+)
+
+call pnpm -F light-chaser-app build
+if errorlevel 1 (
+    echo 错误: 前端构建失败
+    pause
+    exit /b 1
+)
+
+echo [4/6] 压缩前端文件...
+
+cd /d %FRONTEND_DIR%\light-chaser-app\dist
+call tar -a -c -f app.zip *
+
+if errorlevel 1 (
+    echo 错误: 压缩前端文件失败
+    pause
+    exit /b 1
+)
+
+
+echo [5/6] 上传文件到服务器...
+scp -P %SERVER_PORT% "%FRONTEND_DIR%\light-chaser-app\dist\%FRONTEND_ZIP%" "%SERVER_USER%@%SERVER_HOST%:%DEPLOY_DIR%/"
+
+
+echo [6/6] 在服务器上执行部署操作...
+
+ssh -p %SERVER_PORT% %SERVER_USER%@%SERVER_HOST% "cd %DEPLOY_DIR% && rm -rf app && unzip app.zip -d app && rm app.zip && cd %APP_ROOT% && ./stop.sh && ./start.sh"
+
+echo 清理临时文件
+
+del /f /q "%FRONTEND_DIR%\light-chaser-app\dist\%FRONTEND_ZIP%"
+
+echo.
+echo ========================================
+echo   LIGHT CHASER PRO 前端部署完毕~
+echo ========================================
+echo.
+
+pause

package/doc//344/277/256/345/244/215/347/224/273/345/270/203/350/207/252/351/200/202/345/272/224bug/350/203/214/345/220/216/347/232/204/347/220/206/350/256/272/347/237/245/350/257/206.md

@@ -0,0 +1,291 @@
+# ScreenFit 组件核心原理解析
+
+## 一、组件设计目标
+
+实现一个**自适应大屏缩放容器**，支持多种缩放模式，在不同浏览器缩放比例和视口尺寸下，都能正确显示内容且不出现布局空白。
+
+---
+
+## 二、核心概念理解
+
+### 2.1 CSS Transform 的本质特性
+
+CSS `transform` 属性有一个关键特性：**只改变视觉呈现，不改变布局空间**。
+
+#### 示例说明：
+```css
+.element {
+  width: 1000px;
+  height: 2000px;
+  transform: scale(0.5);
+}
+```
+
+这个元素会产生两个不同的"高度"：
+- **视觉高度（Visual Height）**: 2000px × 0.5 = 1000px（用户眼睛看到的）
+- **布局高度（Layout Height）**: 2000px（浏览器计算文档流、滚动条时使用的）
+
+**差值**: 2000 - 1000 = 1000px 的"幽灵空间"
+
+这就是空白问题的根源。
+
+---
+
+### 2.2 浏览器缩放的影响
+
+当用户使用 `Ctrl + 滚轮` 或 `Ctrl + +/-` 调整浏览器缩放时：
+- `document.body.clientWidth/Height` 会相应变化
+- 但我们设定的设计稿尺寸（如 1920×6800）不会变
+- 这导致计算出的缩放比例 `widthScale` 会动态变化
+
+#### 缩放比例计算：
+```javascript
+const widthScale = currentWidth / designWidth
+```
+
+**不同浏览器缩放下的表现：**
+| 浏览器缩放 | 视口宽度 | widthScale | 6800px 缩放后视觉高度 | 布局高度 | 空白 |
+|---------|---------|-----------|---------------------|---------|-----|
+| 100% | 1920px | 1.0 | 6800px | 6800px | 0px ✅ |
+| 60% | 3200px | 1.67 | 11356px | 6800px | -4556px ❌ |
+| 150% | 1280px | 0.67 | 4556px | 6800px | 2244px ❌ |
+
+可以看到，除了 100% 缩放，其他情况都会产生视觉高度与布局高度的不匹配。
+
+---
+
+## 三、解决方案原理
+
+### 3.1 核心思路
+
+**使用负 margin 抵消多余的布局空间**
+
+原理公式：
+```
+实际占用空间 = 布局高度 + marginBottom
+让：实际占用空间 = 视觉高度
+则：marginBottom = 视觉高度 - 布局高度
+```
+
+### 3.2 数学推导
+
+设：
+- `H` = 原始设计高度（如 6800px）
+- `S` = 缩放比例（widthScale）
+- `H_visual` = 视觉高度 = H × S
+- `H_layout` = 布局高度 = H
+- `H_diff` = 高度差 = H_layout - H_visual = H - H×S = H(1-S)
+
+修正方案：
+```text
+marginBottom = -H_diff = -(H - H×S) = H×S - H
+```
+
+简化为：
+```javascript
+const scaledHeight = realHeight * widthScale  // H×S
+const heightDiff = realHeight - scaledHeight  // H - H×S
+marginBottom = -heightDiff                     // -(H - H×S)
+```
+
+### 3.3 代码实现
+
+```javascript
+case 'full-x':
+    // 1. 等比缩放（保持宽高比，不变形）
+    elRef.current!.style.transform = `scale(${widthScale}, ${widthScale})`
+    
+    // 2. 计算视觉高度
+    const scaledHeight = +realHeight * widthScale
+    
+    // 3. 计算多余的布局空间
+    const heightDiff = +realHeight - scaledHeight
+    
+    // 4. 使用负 margin 抵消多余空间
+    if (heightDiff > 0) {
+        // 缩小场景：布局高度 > 视觉高度，有多余空间
+        elRef.current!.style.marginBottom = `-${heightDiff}px`
+    } else {
+        // 放大场景：视觉高度 >= 布局高度，不需要调整
+        elRef.current!.style.marginBottom = `0px`
+    }
+    break;
+```
+
+---
+
+## 四、完整工作流程
+
+### 4.1 初始化阶段
+1. 组件挂载，获取设计稿尺寸（width, height）
+2. 设置容器固定尺寸：`width: 1920px; height: 6800px`
+3. 监听窗口 resize 事件
+
+### 4.2 缩放计算阶段
+1. **获取视口尺寸**：`currentWidth = document.body.clientWidth`
+2. **计算缩放比例**：`widthScale = currentWidth / 1920`
+3. **应用 transform**：`transform: scale(widthScale, widthScale)`
+4. **计算视觉高度**：`scaledHeight = 6800 × widthScale`
+5. **计算高度差**：`heightDiff = 6800 - scaledHeight`
+6. **修正布局**：`marginBottom = -heightDiff`
+
+### 4.3 滚动条行为
+```
+外层容器高度：100vh（固定）
+内层容器占用空间：scaledHeight（动态）
+
+if (scaledHeight <= 100vh) {
+    // 内容未超出视口，留白显示，无滚动条 ✅
+} else {
+    // 内容超出视口，出现滚动条 ✅
+    // 滚动范围 = scaledHeight（正好到内容底部，无多余空白）✅
+}
+```
+
+---
+
+## 五、关键技术点总结
+
+### 5.1 为什么用负 margin 而不是其他方案？
+
+**方案对比：**
+
+| 方案 | 原理 | 缺点 |
+|-----|------|------|
+| 动态改变 height | 直接设置 `height: scaledHeight` | 会影响 transform 的计算基准，导致二次缩放 ❌ |
+| 使用 padding-bottom | 用 padding 撑开空间 | padding 会增加空间，不是减少空间 ❌ |
+| 修改父容器高度 | 调整外层容器 | 破坏了固定视口的设计，滚动条消失 ❌ |
+| **负 margin-bottom** | 减少元素占用空间 | 完美解决，不影响其他布局 ✅ |
+
+### 5.2 transform-origin 的作用
+
+```javascript
+elRef.current!.style.transformOrigin = 'left top'
+```
+
+- **作用**：设置缩放的原点为左上角
+- **效果**：内容从左上角开始缩放，不会产生偏移
+- **如果不设置**：默认是 `center center`，内容会向右下偏移
+
+### 5.3 等比缩放的重要性
+
+```javascript
+// full-x 模式：X 和 Y 都使用 widthScale
+transform: scale(widthScale, widthScale)
+
+// 而不是：
+transform: scale(widthScale, 1)  // ❌ 会导致拉伸变形
+```
+
+**原因**：
+- 只缩放 X 轴会导致内容横向压缩，纵向不变 → 变形
+- X、Y 使用相同比例 → 保持原始宽高比 → 不变形
+
+---
+
+## 六、数学验证
+
+### 场景：浏览器 60% 缩放
+
+**已知条件：**
+- 设计稿：1920 × 6800
+- 视口宽度：3200px（因为缩小到 60%）
+- 视口高度：1800px
+
+**计算过程：**
+```
+widthScale = 3200 / 1920 = 1.67
+
+应用 transform: scale(1.67, 1.67)
+视觉宽度 = 1920 × 1.67 = 3206px ≈ 3200px ✅ (铺满屏幕)
+视觉高度 = 6800 × 1.67 = 11356px
+
+布局高度 = 6800px (transform 不改变)
+高度差 = 6800 - 11356 = -4556px
+
+marginBottom = -(-4556) = 4556px ？❌
+
+等等，这里是放大场景！
+heightDiff = 6800 - 11356 = -4556 < 0
+所以不需要负 margin，保持 marginBottom = 0
+```
+
+**实际效果：**
+- 内容放大到 11356px
+- 超出视口 1800px
+- 出现滚动条，滚动范围正常 ✅
+
+### 场景：浏览器 150% 缩放
+
+**已知条件：**
+- 视口宽度：1280px（因为放大到 150%）
+
+**计算过程：**
+```
+widthScale = 1280 / 1920 = 0.67
+
+应用 transform: scale(0.67, 0.67)
+视觉高度 = 6800 × 0.67 = 4556px
+布局高度 = 6800px
+高度差 = 6800 - 4556 = 2244px
+
+marginBottom = -2244px
+```
+
+**实际效果：**
+- 元素原本占用 6800px
+- 负 margin 减少 2244px
+- 最终占用 = 6800 - 2244 = 4556px
+- 正好等于视觉高度 ✅
+- 滚动到底没有空白 ✅
+
+---
+
+## 七、设计模式总结
+
+这个组件体现了以下设计理念：
+
+### 7.1 关注点分离
+- **视觉呈现**：由 `transform: scale()` 处理
+- **布局空间**：由 `margin-bottom` 修正
+- **滚动行为**：由外层容器的 `overflow` 控制
+
+### 7.2 响应式适配
+- 监听 `resize` 事件
+- 使用防抖（debounce）优化性能
+- 动态计算并应用样式
+
+### 7.3 数学精确性
+- 所有计算基于精确的数学公式
+- 不依赖经验值或魔法数字
+- 适用于任意尺寸和缩放比例
+
+---
+
+## 八、核心公式总结
+
+**full-x 模式（宽度铺满）：**
+```
+widthScale = 视口宽度 / 设计稿宽度
+transform: scale(widthScale, widthScale)
+视觉高度 = 设计稿高度 × widthScale
+高度差 = 设计稿高度 - 视觉高度
+marginBottom = -max(高度差, 0)
+```
+
+**full-y 模式（高度铺满）：**
+```
+heightScale = 视口高度 / 设计稿高度
+transform: scale(heightScale, heightScale)
+视觉宽度 = 设计稿宽度 × heightScale
+宽度差 = 设计稿宽度 - 视觉宽度
+marginRight = -max(宽度差, 0)
+```
+
+**关键不等式：**
+```
+当 scale < 1 时（缩小）：布局空间 > 视觉空间 → 需要负 margin
+当 scale >= 1 时（放大）：视觉空间 >= 布局空间 → 不需要调整
+```
+
+这就是整个组件的核心原理！

package/light-chaser-app/.dockerignore

@@ -0,0 +1,6 @@
+../.idea
+node_modules
+doc
+.vite
+README.md
+README_ZH.md

package/light-chaser-app/.eslintrc.cjs

@@ -0,0 +1,19 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+    "@typescript-eslint/no-explicit-any": "off",
+  },
+}