flnxi-Wu/docs/guides/SMART_FEATURES.md

# 智能功能更新 v2.3

## 📅 更新日期：2025-10-17

---

## ✨ 新功能概览

### 1. 🎯 拖拽上传功能
- **全窗口拖拽**：整个上传窗口都支持拖拽
- **智能识别**：自动识别图片和压缩包
- **视觉反馈**：拖拽时显示蓝色覆盖层提示
- **多文件支持**：可同时拖拽图片和压缩包

### 2. 🌐 智能网络切换
- **后台检测**：自动检测内网是否可达
- **自动切换**：内网可达时自动切换，无需用户操作
- **无感知**：检测过程在后台进行，不影响用户体验
- **状态显示**：仅显示最终使用的网络模式

---

## 🎯 拖拽上传详解

### 使用方法

#### 方式1：拖拽文件到窗口
1. 打开上传模态框
2. 从文件管理器拖拽文件到窗口
3. 系统自动识别文件类型
4. 图片 → 预览图字段
5. 压缩包 → 压缩包字段

#### 方式2：传统点击上传
1. 点击"选择图片"或"选择压缩包"按钮
2. 从文件对话框选择文件

### 支持的文件类型

**预览图**：
- ✅ JPG/JPEG
- ✅ PNG
- ✅ WebP
- ✅ GIF
- ✅ 其他浏览器支持的图片格式

**压缩包**：
- ✅ .zip
- ✅ .rar
- ✅ .7z

### 视觉交互

#### 拖拽状态
```
┌─────────────────────────────────┐
│  ╔═══════════════════════════╗  │
│  ║                           ║  │
│  ║    📤                     ║  │
│  ║    拖放文件到这里           ║  │
│  ║    支持图片和压缩包文件     ║  │
│  ║                           ║  │
│  ╚═══════════════════════════╝  │
└─────────────────────────────────┘
蓝色覆盖层，清晰提示
```

#### 实现细节
```typescript
// 拖拽事件处理
onDragEnter  → 显示蓝色覆盖层
onDragLeave  → 隐藏覆盖层
onDragOver   → 阻止默认行为
onDrop       → 处理文件，隐藏覆盖层

// 智能文件识别
- 图片：file.type.startsWith('image/')
- 压缩包：['.zip', '.rar', '.7z'].includes(extension)
```

---

## 🌐 智能网络切换详解

### 工作原理

#### 1. 网络检测流程
```
页面加载
    ↓
后台检测内网 (192.168.58.20:4320)
    ↓
├─ 可达 → 切换到内网模式 ✅
│  └─ 显示："内网模式 🏠"
│
└─ 不可达 → 使用公网模式 ⚠️
   └─ 显示："公网模式 🌍"
```

#### 2. 检测机制
- **超时时间**：2秒
- **检测端点**：`/api/health`
- **检测方式**：HTTP HEAD请求
- **失败处理**：自动降级到公网模式

#### 3. 用户体验
- ✅ **无感知**：检测在后台进行
- ✅ **不阻塞**：页面正常加载显示
- ✅ **自动优化**：优先使用内网（速度更快）
- ✅ **智能降级**：内网不可达时自动使用公网

### 使用场景

#### 场景1：办公室内网访问公网地址
```
用户访问：http://180.97.221.140:2320
         ↓
系统检测：内网可达 ✅
         ↓
自动切换：内网模式 🏠
结果：使用内网API，速度快
```

#### 场景2：外网访问
```
用户访问：http://180.97.221.140:2320
         ↓
系统检测：内网不可达 ❌
         ↓
使用当前：公网模式 🌍
结果：使用公网API，正常访问
```

#### 场景3：直接访问内网
```
用户访问：http://192.168.58.20:4320
         ↓
直接使用：内网模式 🏠
结果：无需检测，直接使用内网
```

### 状态显示

#### 内网模式
```
┌────────────────────────────────────┐
│ 🏠 内网模式                         │
│    已自动切换到内网，速度更快        │
└────────────────────────────────────┘
绿色背景，表示最优状态
```

#### 公网模式
```
┌────────────────────────────────────┐
│ 🌍 公网模式                         │
│    当前使用公网访问    ⓘ 内网不可达 │
└────────────────────────────────────┘
蓝色背景，提示内网不可达
```

### 技术实现

#### 网络检测模块 (`lib/network.ts`)
```typescript
// 检测内网是否可达
async function checkInternalNetwork(): Promise<boolean> {
  try {
    const controller = new AbortController()
    const timeoutId = setTimeout(() => controller.abort(), 2000)

    await fetch(`http://192.168.58.20:4320/api/health`, {
      method: 'HEAD',
      signal: controller.signal,
      mode: 'no-cors'
    })

    clearTimeout(timeoutId)
    return true
  } catch (error) {
    return false
  }
}
```

#### Health Check API (`app/api/health/route.ts`)
```typescript
export async function GET() {
  return NextResponse.json({ 
    status: 'ok',
    timestamp: new Date().toISOString()
  })
}

export async function HEAD() {
  return new NextResponse(null, { status: 200 })
}
```

---

## 🎨 用户界面优化

### 上传页面
- ✅ 拖拽提示："💡 提示：可以直接拖拽图片和压缩包文件到窗口"
- ✅ 拖拽时蓝色覆盖层
- ✅ 清晰的视觉反馈

### 首页网络状态
- ✅ 仅在检测完成后显示
- ✅ 绿色（内网）/ 蓝色（公网）区分
- ✅ 简洁的状态说明

---

## 📊 性能影响

### 网络检测
- **检测时间**：< 2秒
- **对加载的影响**：无（异步后台检测）
- **资源消耗**：极低（单次HEAD请求）

### 拖拽功能
- **性能影响**：无
- **资源消耗**：极低（事件监听）
- **浏览器兼容**：现代浏览器全支持

---

## 🔧 配置说明

### 网络地址配置
修改 `lib/network.ts`：
```typescript
const INTERNAL_HOST = '192.168.58.20:4320'  // 内网地址
```

### 超时时间配置
修改 `lib/network.ts`：
```typescript
const timeoutId = setTimeout(() => controller.abort(), 2000) // 超时时间（毫秒）
```

---

## ✅ 测试清单

### 拖拽上传测试
- [ ] 拖拽单个图片文件
- [ ] 拖拽单个压缩包文件
- [ ] 同时拖拽图片和压缩包
- [ ] 拖拽不支持的文件格式（应显示错误）
- [ ] 拖拽时视觉反馈正常
- [ ] 拖拽后自动填充到对应字段

### 网络切换测试
- [ ] 内网环境访问公网地址（应自动切换到内网）
- [ ] 外网环境访问公网地址（应显示公网模式）
- [ ] 直接访问内网地址（应显示内网模式）
- [ ] 网络检测不影响页面加载
- [ ] 状态显示正确
- [ ] Console显示网络检测日志

---

## 🚀 部署更新

### 本地测试
```bash
cd /Users/lanmu/Desktop/gongxiangp2
npm run dev
```

### 部署到NAS
```bash
cd /Users/lanmu/Desktop/gongxiangp2
./update-deploy.sh
```

或手动部署：
```bash
# 1. 打包
tar -czf update-v2.3.tar.gz \
  --exclude='node_modules' \
  --exclude='.next' \
  --exclude='uploads/*' \
  .

# 2. 上传
scp update-v2.3.tar.gz root@192.168.58.20:/mnt/tank/apps/youyidian-3d/

# 3. 部署
ssh root@192.168.58.20
cd /mnt/tank/apps/youyidian-3d
tar -xzf update-v2.3.tar.gz
docker compose down
docker compose up -d --build
```

---

## 💡 使用建议

### 对于内网用户
- ✅ 访问公网地址即可，系统自动切换到内网
- ✅ 无需记忆内网地址
- ✅ 享受内网的高速访问

### 对于外网用户
- ✅ 正常访问公网地址
- ✅ 系统会提示当前为公网模式
- ✅ 回到内网后，系统会自动切换

### 上传文件
- ✅ 优先使用拖拽，更快更方便
- ✅ 可同时拖入多个文件，一次完成
- ✅ 点击按钮上传仍然可用

---

## 🎯 未来优化

### 网络切换
- [ ] 添加手动刷新按钮
- [ ] 定期后台检测（自动重连）
- [ ] 网络切换动画效果
- [ ] 断线重连提示

### 拖拽上传
- [ ] 支持批量拖拽上传
- [ ] 拖拽预览功能
- [ ] 进度条优化

---

## 📞 技术支持

- **版本**：v2.3.0
- **更新日期**：2025-10-17
- **相关文档**：
  - `CARD_ENHANCEMENT.md` - 卡片增强功能
  - `LABEL_OPTIMIZATION.md` - 标签优化
  - `FEATURE_UPDATES.md` - 功能更新列表

---

**享受智能化的使用体验！** 🎉