167 lines
7.2 KiB
Markdown
167 lines
7.2 KiB
Markdown
# Web2App 需求文档
|
||
|
||
## 1. 项目概述
|
||
|
||
**项目名称**：Web2App
|
||
**目标用户**：普通用户（提供图形界面操作）
|
||
**目标平台**：Windows / macOS / Linux（跨平台）
|
||
|
||
**项目目标**：开发一款桌面应用程序，允许用户导入完整的网站资源（HTML、JS、CSS、图片等），并将其打包为独立安装包。安装后生成一个可独立运行的桌面应用，内置网站的前端界面与后端服务，无需用户额外配置运行环境。
|
||
|
||
---
|
||
|
||
## 2. 核心流程
|
||
|
||
```
|
||
新建/打开项目 → 设置资源路径(导入网站目录) → 配置应用信息(名称/图标/入口等)
|
||
→ 打包生成安装包 → 目标机安装 → 启动 → 独立的桌面应用运行
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 导入与管理网站资源
|
||
|
||
| 编号 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| F1.1 | 设置资源路径 | 用户选择网站目录，自动导入目录下所有文件 |
|
||
| F1.2 | 单个文件导入 | 支持选择单个或多个文件导入 |
|
||
| F1.3 | 目录结构保留 | 导入时保留原始目录结构 |
|
||
| F1.4 | 资源树展示 | 以目录树形式展示已导入的所有文件 |
|
||
| F1.5 | 资源增删改 | 支持在界面中删除已导入的文件 |
|
||
| F1.6 | 后端代码导入 | 导入后端脚本（如 Node.js/Express 路由文件） |
|
||
|
||
### 3.2 应用配置
|
||
|
||
| 编号 | 功能 | 说明 |
|
||
|------|------|------|
|
||
| F2.1 | 应用名称 | 设置生成的桌面应用名称（默认为文件夹名） |
|
||
| F2.2 | 应用图标 | 支持导入自定义图标（.ico / .png / .icns） |
|
||
| F2.3 | 应用版本号 | 设置版本号，默认 1.0.0 |
|
||
| 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 28 | 跨平台桌面应用框架，内置 Chromium 与 Node.js |
|
||
| 前端 UI | Vue 3 + Vue Router + Pinia | Web2App 自身的图形界面 |
|
||
| 构建工具 | Vite 5 | 前端构建与开发服务器 |
|
||
| 打包工具 | electron-builder + NSIS | 将用户资源+运行时打包为安装包 |
|
||
| 后端引擎 | Node.js (Electron 内置) | 使用 Electron 自带的 Node.js 运行时执行用户后端代码 |
|
||
| 安装包生成 | electron-builder / NSIS | 跨平台安装包生成（.exe / .dmg / .AppImage） |
|
||
|
||
### 架构示意
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 生成的桌面应用 (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 | 测试、性能优化、文档编写 |
|