# Web2App 需求文档

## 1. 项目概述

**项目名称**：Web2App  
**目标用户**：普通用户（提供图形界面操作）  
**目标平台**：Windows / macOS / Linux（跨平台）  

**项目目标**：开发一款桌面应用程序，允许用户导入完整的网站资源（HTML、JS、CSS、图片等），并将其打包为独立安装包。安装后生成一个可独立运行的桌面应用，内置网站的前端界面与后端服务，无需用户额外配置运行环境。

---

## 2. 核心流程

```
用户准备网站资源 → 导入 Web2App → 配置应用信息 → 打包生成安装包
→ 分发安装包 → 目标机安装 → 启动 → 独立的桌面应用运行
```

---

## 3. 功能需求

### 3.1 导入与管理网站资源

| 编号 | 功能 | 说明 |
|------|------|------|
| F1.1 | 导入 HTML 文件 | 支持单个或批量导入，自动检测入口文件（index.html） |
| F1.2 | 导入 JS 文件 | 保留目录结构导入 |
| F1.3 | 导入 CSS 文件 | 保留目录结构导入 |
| F1.4 | 导入资源文件 | 图片、字体、音视频、JSON 等静态资源 |
| F1.5 | 资源树展示 | 以目录树形式展示已导入的所有文件 |
| F1.6 | 资源增删改 | 支持在界面中删除或替换已导入的文件 |
| F1.7 | 后端代码导入 | 导入后端脚本（如 Node.js/Express 路由文件） |

### 3.2 应用配置

| 编号 | 功能 | 说明 |
|------|------|------|
| F2.1 | 应用名称 | 设置生成的桌面应用名称 |
| F2.2 | 应用图标 | 支持导入自定义图标（.ico / .png） |
| F2.3 | 应用版本号 | 设置版本号 |
| F2.4 | 窗口设置 | 配置窗口默认尺寸、最小尺寸、是否可调整大小 |
| F2.5 | 入口文件 | 指定网站入口 HTML 文件 |
| F2.6 | 后端入口 | 指定后端服务入口文件（如 server.js） |
| F2.7 | 作者/版权信息 | 设置应用版权与作者信息 |

### 3.3 打包生成安装包

| 编号 | 功能 | 说明 |
|------|------|------|
| F3.1 | 打包为安装程序 | 将所有资源打包为一个安装包文件 |
| F3.2 | 自动嵌入运行时 | 打包时自动嵌入 Electron 运行时，无需目标机预装 |
| F3.3 | 跨平台打包 | 支持在对应平台生成目标平台的安装包 |
| F3.4 | 安装包格式 | Windows 生成 .exe，macOS 生成 .dmg，Linux 生成 .AppImage 或 .deb |
| F3.5 | 进度显示 | 打包过程显示实时进度与日志 |
| F3.6 | 完整性校验 | 打包完成后生成校验值（SHA256） |

### 3.4 安装与运行

| 编号 | 功能 | 说明 |
|------|------|------|
| F4.1 | 安装引导 | 安装包提供标准的安装向导界面 |
| F4.2 | 安装路径选择 | 用户可自定义安装目录 |
| F4.3 | 桌面快捷方式 | 安装时可选创建桌面快捷方式 |
| F4.4 | 自动启动后端 | 应用启动时自动运行内置后端服务 |
| F4.5 | 独立运行 | 生成的 .exe 完全独立运行，不依赖外部 Web 服务器 |
| F4.6 | 系统托盘 | 支持最小化到系统托盘运行 |

### 3.5 后端服务

| 编号 | 功能 | 说明 |
|------|------|------|
| F5.1 | 内置服务器 | 应用内嵌 HTTP 服务器，启动时自动监听本地端口 |
| F5.2 | 后端代码执行 | 支持运行用户导入的后端脚本（基于 Node.js） |
| F5.3 | API 路由 | 支持自定义 API 路由 |
| F5.4 | 数据持久化 | 内置 SQLite 数据库支持（无需额外安装） |
| F5.5 | 端口管理 | 自动检测端口占用并分配可用端口 |

---

## 4. 非功能需求

| 编号 | 需求 | 说明 |
|------|------|------|
| NF1 | 易用性 | 全图形化操作，无需命令行 |
| NF2 | 安装包体积 | 生成的安装包应尽量精简（预计基础体积约 50-80MB，含 Electron 运行时） |
| NF3 | 启动速度 | 应用冷启动时间不超过 3 秒 |
| NF4 | 安全性 | 打包过程不向外网发送任何数据；安装包可校验完整性 |
| NF5 | 兼容性 | Windows 10+ / macOS 11+ / Ubuntu 20.04+ |
| NF6 | 离线可用 | Web2App 自身打包功能完全离线可用 |

---

## 5. 技术方案

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| 桌面框架 | Electron | 跨平台桌面应用框架，内置 Chromium 与 Node.js |
| 前端 UI | React / Vue 3 | Web2App 自身的图形界面（推荐 Vue 3） |
| 打包工具 | electron-builder | 将用户资源+运行时打包为安装包 |
| 后端引擎 | Node.js (Electron 内置) | 使用 Electron 自带的 Node.js 运行时执行用户后端代码 |
| 数据库 | better-sqlite3 | 嵌入式数据库，无需配置 |
| 安装包生成 | electron-builder / NSIS | 跨平台安装包生成 |

### 架构示意

```
┌─────────────────────────────────────────────┐
│             生成的桌面应用 (Electron)          │
│  ┌───────────────────┐  ┌────────────────┐  │
│  │  前端 (用户网站)    │  │  后端服务       │  │
│  │  HTML/JS/CSS       │  │  Node.js 脚本  │  │
│  │  Chromium 渲染     │  │  Express 路由  │  │
│  └────────┬──────────┘  │  SQLite 数据库  │  │
│           │             └────────┬───────┘  │
│           └──────────┬───────────┘          │
│                   HTTP 本地通信              │
│  ┌────────────────────────────────────────┐  │
│  │  Electron 主进程                        │  │
│  │  (窗口管理 / 系统托盘 / 自动启动后端)    │  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
```

---

## 6. 用户界面（Web2App 自身）

### 6.1 主界面布局

- **左侧**：资源管理面板（目录树）
- **中间**：文件预览 / 编辑区域
- **右侧**：应用配置面板
- **底部**：打包进度与日志

### 6.2 主要页面

| 页面 | 功能 |
|------|------|
| 首页 | 新建项目 / 打开已有项目 |
| 项目编辑页 | 资源导入与管理、应用配置 |
| 打包页面 | 打包配置、启动打包、查看日志 |
| 帮助页 | 使用说明与版本信息 |

---

## 7. 交付物

1. Web2App 桌面应用程序（安装包）
2. 项目源代码
3. 需求文档（本文档）
4. 用户使用手册

---

## 8. 开发路线（建议）

| 阶段 | 内容 |
|------|------|
| Phase 1 | Electron 项目骨架搭建、资源导入与管理功能 |
| Phase 2 | 应用配置界面、后端运行引擎集成 |
| Phase 3 | 打包流程实现（electron-builder 集成） |
| Phase 4 | 安装包生成、跨平台适配 |
| Phase 5 | 测试、性能优化、文档编写 |