feat: package.json 优化方案

主要改动: 配置本地开发环境 PostHog 上报到 Cloud\

     1. 修改 npm start 默认行为
       - start → 使用 .env.mock (默认 mock 数据)
       - 添加 start:real → 使用 .env.local (真实后端)
     2. 添加 PostHog 测试脚本
       - 新增 test:tracking → 启用 PostHog debug 模式 + mock 数据
     3. 清理冗余脚本
       - 移除 start:local (冗余,只是调用 npm start)
       - 重命名 install:clean → reinstall (移除自动启动)
       - 添加 dev 快捷命令 (等同于 npm start)
       - 添加 clean 命令 (只清理,不安装)
     4. 优化 NODE_OPTIONS
       - 不在每个命令中重复,通过注释说明可以提取为环境变量
       - 保持 exit 0 在 lint 命令中

.claude/settings.local.json

@@ -11,7 +11,8 @@
       "Bash(npm install)",
       "Bash(npm run start:mock)",
       "Bash(npm install fsevents@latest --save-optional --force)",
-      "Bash(python -m py_compile:*)"
+      "Bash(python -m py_compile:*)",
+      "Bash(ps -p 20502,53360 -o pid,command)"
     ],
     "deny": [],
     "ask": []

.env.development

@@ -1,5 +1,5 @@
 # 开发环境配置（连接真实后端）
-# 使用方式: npm start
+# 使用方式: npm run start:dev
 
 # React 构建优化配置
 GENERATE_SOURCEMAP=false
@@ -18,3 +18,10 @@ REACT_APP_ENABLE_MOCK=false
 
 # 开发环境标识
 REACT_APP_ENV=development
+
+# PostHog 配置（开发环境）
+# 留空 = 仅控制台 debug
+# 填入 Key = 控制台 + PostHog Cloud 双模式
+REACT_APP_POSTHOG_KEY=
+REACT_APP_POSTHOG_HOST=https://app.posthog.com
+REACT_APP_ENABLE_SESSION_RECORDING=false

.env.mock

@@ -35,3 +35,10 @@ REACT_APP_ENABLE_MOCK=true
 
 # Mock 环境标识
 REACT_APP_ENV=mock
+
+# PostHog 配置（Mock 环境）
+# 留空 = 仅控制台 debug
+# 填入 Key = 控制台 + PostHog Cloud 双模式
+REACT_APP_POSTHOG_KEY=
+REACT_APP_POSTHOG_HOST=https://app.posthog.com
+REACT_APP_ENABLE_SESSION_RECORDING=false

.env.test

@@ -0,0 +1,42 @@
+# ========================================
+# 本地测试环境（前后端都在本地）
+# ========================================
+# 使用方式: npm run start:test
+#
+# 工作原理：
+# 1. concurrently 同时启动前端和后端
+# 2. 前端: localhost:3000
+# 3. 后端: localhost:5001 (python app_2.py)
+# 4. 数据: 本地数据库
+#
+# 适用场景：
+# - 调试后端代码
+# - 性能测试
+# - 离线开发
+# - 数据库调试
+# ========================================
+
+# 环境标识
+REACT_APP_ENV=test
+NODE_ENV=development
+
+# Mock 配置（关闭 MSW）
+REACT_APP_ENABLE_MOCK=false
+
+# 后端 API 地址（本地后端）
+REACT_APP_API_URL=http://localhost:5001
+
+# PostHog 配置（测试环境）
+# 留空 = 仅控制台 debug
+# 填入 Key = 控制台 + PostHog Cloud 双模式
+REACT_APP_POSTHOG_KEY=
+REACT_APP_POSTHOG_HOST=https://app.posthog.com
+REACT_APP_ENABLE_SESSION_RECORDING=false
+
+# React 构建优化配置
+GENERATE_SOURCEMAP=true  # 测试环境保留 sourcemap 便于调试
+SKIP_PREFLIGHT_CHECK=true
+DISABLE_ESLINT_PLUGIN=false  # 测试环境开启 ESLint
+TSC_COMPILE_ON_ERROR=true
+IMAGE_INLINE_SIZE_LIMIT=10000
+NODE_OPTIONS=--max_old_space_size=4096

package.json

@@ -93,24 +93,34 @@
     "uuid": "^9.0.1"
   },
   "scripts": {
-    "start": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' craco start",
+    "prestart": "kill-port 3000",
+    "start": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' env-cmd -f .env.mock craco start",
+    "start:real": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' env-cmd -f .env.local craco start",
     "start:mock": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' env-cmd -f .env.mock craco start",
     "start:dev": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' env-cmd -f .env.development craco start",
+    "start:test": "concurrently \"python app_2.py\" \"npm run frontend:test\" --names \"backend,frontend\" --prefix-colors \"blue,green\"",
+    "frontend:test": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' env-cmd -f .env.test craco start",
+    "dev": "npm start",
+    "backend": "python app_2.py",
+    "kill-port": "kill-port 3000",
     "build": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' craco build && gulp licenses",
     "build:analyze": "NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' ANALYZE=true craco build",
     "test": "craco test --env=jsdom",
+    "test:tracking": "REACT_APP_POSTHOG_DEBUG=true npm run start:mock",
     "eject": "react-scripts eject",
     "deploy": "bash scripts/deploy-from-local.sh",
     "deploy:setup": "bash scripts/setup-deployment.sh",
     "rollback": "bash scripts/rollback-from-local.sh",
     "lint:check": "eslint . --ext=js,jsx;  exit 0",
     "lint:fix": "eslint . --ext=js,jsx --fix;  exit 0",
-    "install:clean": "rm -rf node_modules/ && rm -rf package-lock.json && npm install && npm start"
+    "clean": "rm -rf node_modules/ package-lock.json",
+    "reinstall": "npm run clean && npm install"
   },
   "devDependencies": {
     "@craco/craco": "^7.1.0",
     "ajv": "^8.17.1",
     "autoprefixer": "^10.4.21",
+    "concurrently": "^8.2.2",
     "env-cmd": "^11.0.0",
     "eslint-config-prettier": "8.3.0",
     "eslint-plugin-prettier": "3.4.0",
@@ -119,6 +129,7 @@
     "imagemin": "^9.0.1",
     "imagemin-mozjpeg": "^10.0.0",
     "imagemin-pngquant": "^10.0.0",
+    "kill-port": "^2.0.1",
     "msw": "^2.11.5",
     "postcss": "^8.5.6",
     "prettier": "2.2.1",

src/mocks/browser.js

@@ -19,7 +19,10 @@ export async function startMockServiceWorker() {
 
     try {
         await worker.start({
-            // 不显示未拦截的请求警告（可选）
+            // 🎯 智能穿透模式（关键配置）
+            // 'bypass': 未定义 Mock 的请求自动转发到真实后端
+            // 'warn': 未定义的请求会显示警告（调试用）
+            // 'error': 未定义的请求会抛出错误（严格模式）
             onUnhandledRequest: 'bypass',
 
             // 自定义 Service Worker URL（如果需要）
@@ -27,7 +30,7 @@ export async function startMockServiceWorker() {
                 url: '/mockServiceWorker.js',
             },
 
-            // 静默模式（不在控制台打印启动消息）
+            // 是否在控制台显示启动日志和拦截日志 静默模式（不在控制台打印启动消息）
             quiet: false,
         });
 
@@ -36,11 +39,11 @@ export async function startMockServiceWorker() {
             'color: #4CAF50; font-weight: bold; font-size: 14px;'
         );
         console.log(
-            '%c提示: 所有 API 请求将使用本地 Mock 数据',
+            '%c智能穿透模式：已定义 Mock → 返回假数据 | 未定义 Mock → 转发到 ' + (process.env.REACT_APP_API_URL || '真实后端'),
             'color: #FF9800; font-size: 12px;'
         );
         console.log(
-            '%c要禁用 Mock，请设置 REACT_APP_ENABLE_MOCK=false',
+            '%c查看 src/mocks/handlers/ 目录管理 Mock 接口',
             'color: #2196F3; font-size: 12px;'
         );
     } catch (error) {