temp-file-trans/docs/superpowers/specs/2026-05-24-temp-file-trans-client-design.md

Temp File Transfer Client - 设计规格

1. 项目概述

• 项目名称: temp_file_trans_client
• 类型: 桌面客户端应用
• 核心功能: 通过拖放或点击上传文件到临时文件传输服务器，获取分享链接
• 目标用户: 需要快速分享文件给其他人的用户

2. 技术栈

组件	技术
GUI框架	PySide6
HTTP客户端	requests
打包工具	PyInstaller
Python版本	3.8+

3. 功能列表

3.1 服务器配置

• 顶部输入框配置服务器地址
• 默认值: http://localhost:5000
• 保存到本地配置文件

3.2 文件上传

• 拖放文件到拖放区域上传
• 点击拖放区域选择文件
• 显示上传进度条
• 支持过期时间选择: 1h, 24h, 7d

3.3 结果展示

• 上传成功后显示分享链接
• 点击链接复制到剪贴板
• 显示文件ID和文件名

3.4 错误处理

• 网络错误提示
• 服务器返回错误展示
• 文件大小超限提示（参考服务器500MB限制）

4. UI设计

4.1 窗口布局

┌──────────────────────────────────────┐
│  服务器: [http://localhost:5000]  [保存] │  ← 配置栏 (40px)
├──────────────────────────────────────┤
│                                      │
│  ┌────────────────────────────────┐  │
│  │                                │  │
│  │      📁 拖放文件到此处         │  │  ← 拖放区域 (flex)
│  │        或点击选择文件          │  │
│  │                                │  │
│  └────────────────────────────────┘  │
│                                      │
│  过期时间: [24h ▼]    [上传文件]     │  ← 操作栏 (50px)
│                                      │
│  ════════════════════════════════   │  ← 进度条 (隐藏/显示)
│                                      │
│  ┌────────────────────────────────┐  │
│  │  https://xxx/file_id          │  │  ← 结果区 (隐藏/显示)
│  │              [复制链接]        │  │
│  └────────────────────────────────┘  │
│                                      │
│  状态: 就绪                          │  ← 状态栏 (30px)
└──────────────────────────────────────┘

4.2 窗口规格

• 默认尺寸: 500 x 450 px
• 最小尺寸: 400 x 350 px
• 无边框简约设计（可选）
• 居中显示

4.3 拖放区域样式

• 虚线边框 (#aaa)
• 圆角 (8px)
• 悬停时边框变蓝 (#3498db)
• 拖拽进入时背景变浅蓝 (#ecf0f1)

5. API交互

5.1 上传接口

参考 upload_client.py，使用 requests.post 上传：

POST /api/upload
Content-Type: multipart/form-data

file: <binary>
expiry: 1h|24h|7d

成功响应 (200):

{
  "id": "uuid",
  "filename": "example.pdf",
  "filesize": 1234567,
  "expiry_hours": 24,
  "share_url": "http://server/file/<id>"
}

错误响应 (400/429/500):

{
  "error": "错误描述"
}

5.2 链接格式

分享链接: {服务器地址}/file/{file_id}
直接下载: {服务器地址}/download/{file_id}

6. 文件结构

temp_file_trans_client/
├── main.py           # 入口，创建应用和主窗口
├── ui.py             # UI组件和布局
├── api.py            # API调用封装
├── config.json       # 本地配置（服务器地址等）
├── requirements.txt  # 依赖
├── build.spec        # PyInstaller配置
└── README.md         # 使用说明

7. 打包配置

PyInstaller spec

• 单文件输出
• 窗口模式（无控制台）
• 包含PySide6和requests

8. 验收标准

1. ✅ 拖放文件到拖放区域触发上传
2. ✅ 点击拖放区域可选择文件
3. ✅ 显示上传进度
4. ✅ 上传成功显示分享链接
5. ✅ 可复制分享链接
6. ✅ 可配置服务器地址
7. ✅ 错误情况有友好提示
8. ✅ 可打包成exe运行