PRD web服务重构

[A-nony-mous]

ZenlessZoneZero-OneDragon Web前端重写 PRD

版本: v2.0
日期: 2025年8月27日
状态: 开发中

1. 项目背景与目标

1.1 背景

ZenlessZoneZero-OneDragon项目当前使用PySide6作为GUI前端，存在以下问题：

• 业务逻辑与UI紧密耦合，维护成本高
• 仅支持桌面应用形态，扩展性有限
• 用户界面更新困难，开发效率低
• 无法支持远程控制和多客户端访问
• 难以实现实时状态同步和日志推送

1.2 目标

• 架构解耦: 将业务逻辑与UI完全分离，构建独立的后端服务
• 多端支持: 支持Web、Electron、移动端等多种客户端形态
• 实时通信: 实现WebSocket实时日志推送和状态同步
• 现代化UI: 提供更好的用户体验和界面设计
• 易于维护: 提高代码可维护性和开发效率

1.3 核心价值

1. 用户体验提升: 现代化Web界面，支持响应式设计
2. 功能扩展性: 易于添加新功能和第三方集成
3. 部署灵活性: 支持本地和远程部署模式
4. 开发效率: 前后端分离，并行开发，降低维护成本

2. 当前实现状态

2.1 后端API进展（FastAPI）

已实现基础架构:

• ✅ FastAPI应用框架搭建（生命周期管理、CORS、统一异常处理）
• ✅ 路由模块化（home、accounts、onedragon、runs、resources、settings、world_patrol等）
• ✅ WebSocket支持和连接管理
• ✅ 统一任务管理（RunRegistry）
• ✅ 实时日志流推送
• ✅ 依赖注入和上下文管理

已实现接口:

• ✅ 健康检查: GET /healthz
• ✅ 版本信息: GET /api/v1/home/version
• ✅ 仪表盘: 公告卡片、主页背景、更新检测
• ✅ 一条龙运行: 启动/取消/状态查询
• ✅ WebSocket事件: /ws/v1/runs/{runId}

部分实现:

• 🔄 账户管理接口（基础框架已搭建）
• 🔄 设置管理接口（路由已创建）
• 🔄 资源下载接口（基础结构已建立）

2.2 前端状态

重写计划: TBD

3. 技术架构设计

3.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    前端客户端层                          │
├─────────────────┬─────────────────┬─────────────────────┤
│   Web Client    │  Electron App   │   移动端应用（未来）   │
│   (Vue 3/React) │   (桌面版)       │                    │
└─────────┬───────┴─────────┬───────┴─────────────────────┘
          │                 │
          └─────────────────┘
                   │
           ┌───────▼───────┐
           │  API Gateway   │
           │   (FastAPI)    │
           └───────┬───────┘
                   │
    ┌──────────────┼──────────────┐
    │              │              │
┌───▼────┐   ┌────▼────┐   ┌─────▼─────┐
│REST API│   │WebSocket│   │Static Files│
│        │   │Handler  │   │   Server   │
└───┬────┘   └────┬────┘   └───────────┘
    │             │
    └─────┬───────┘
          │
  ┌───────▼───────┐
  │ Business Layer│
  │   (现有逻辑)    │
  └───────────────┘

3.2 后端技术栈

• 框架: FastAPI 0.104+
• 异步运行时: asyncio + uvicorn
• WebSocket: 原生FastAPI WebSocket
• 任务管理: 自定义RunRegistry + asyncio.Queue
• 日志系统: 自定义WebSocketHandler

3.3 前端技术栈 TBD

3.4 桌面应用（可选）

• 框架: Electron
• 打包工具: electron-builder
• 特性: 透明窗口、系统托盘、游戏内浮层

4. 功能需求规划

4.1 核心功能模块

4.1.1 仪表盘（首页）

后端状态: 🔄 部分实现

• 版本信息展示
• 公告卡片管理
• 背景图片配置
• 更新检测

4.1.2 账户管理

后端状态: 🔄 部分实现

• 多实例管理
• 游戏账号配置
• 实例切换
• 具体：包括路径、窗口、区服、账密

4.1.3 一条龙功能

后端状态: 🔄 基础运行接口已实现，有POC

• 预设队伍管理
• 体力计划配置（可能不完整）
• 恶名狩猎设置
• 咖啡计划管理（需要review）
• 式舆防卫战配置
• 运行控制（启动/暂停/取消）
• 录像店宣传员/驱动盘拆解
• 运行设置（单应用通知/结束后行为）

4.1.4 战斗助手

后端状态: ❌ 待实现

• 自动战斗配置
• 躲避助手
• 操作调试
• 模板生成

4.1.5 零号空洞/迷失之地

后端状态: ❌ 待实现

• 挑战配置管理
• 运行控制

4.1.6 游戏助手

后端状态: ❌ 待实现

• 委托助手
• 网络生存
• 鼠标灵敏度检测
• 预设队伍检查

4.1.7 锄大地

后端状态: 🔄 路由已创建，待实现

• 路线管理
• 大地图编辑
• 运行记录

4.1.8 系统设置

后端状态: 🔄 路由已创建，待实现

• 游戏设置
• 键位配置
• 模型配置
• 通知设置

4.1.9 资源管理

后端状态: 🔄 路由已创建，待实现

• 模型下载
• 环境依赖检查

4.1.10 开发工具

后端状态: ❌ 待实现

• 截图助手
• 大地图工具
• 图标编辑器

4.2 实时通信需求

• 任务状态同步: 运行进度、状态变更
• 日志推送: 实时日志输出
• 系统事件: 错误通知、完成提醒
• 性能监控: 资源使用情况

4.3 用户交互需求

• 响应式设计: 支持不同屏幕尺寸
• 暗色主题: 符合游戏风格
• 快捷操作: 常用功能快速访问
• 状态指示: 清晰的运行状态展示
• 错误处理: 友好的错误信息展示

5. 接口规范

5.1 RESTful API 设计原则

• 基础路径: /api/v1
• 统一错误格式: { error: { code, message, details? } }
• 状态码: 标准HTTP状态码
• 数据格式: JSON

5.2 WebSocket 事件规范

• 连接路径: /ws/v1/runs/{runId}, /ws/v1/logs
• 事件格式: { type, data, timestamp }
• 事件类型:
  • started - 任务开始
  • progress - 进度更新
  • log - 日志消息
  • completed - 任务完成
  • failed - 任务失败
  • cancelled - 任务取消

5.3 完整接口清单

详见现有文档 docs/fastapi/endpoints.md，需要实现约80+个接口，涵盖所有GUI功能。

6. 开发计划

6.1 第一阶段：后端API完善

P0: 框架优化

• 完善数据模型定义（Pydantic schemas）
• 统一异常处理和错误码
• 完善WebSocket事件结构
• 配置化管理（环境变量、配置文件）

P1: 核心功能接口

• [#] 一条龙完整接口（队伍、体力计划、恶名狩猎等）
• 账户管理完整实现
• 设置管理接口
• 资源管理接口

P1: 业务功能接口

• 战斗助手接口
• 零号空洞/迷失之地接口
• 游戏助手接口

6.2 第二阶段：前端开发

项目搭建

核心页面

• 登录/首页
• 一条龙控制面板
• 实时日志查看器
• 设置页面

功能页面

• 战斗助手界面
• 零号空洞/迷失之地界面
• 世界巡回界面
• 开发工具界面

6.3 第三阶段：集成测试和优化

测试

• 单元测试（后端API）
• 集成测试（前后端交互）
• 端到端测试（完整流程）

优化

• 性能优化
• 用户体验优化
• 错误处理完善
• 文档完善

6.4 第四阶段：桌面应用打包

• Electron应用搭建
• 原生功能集成（系统托盘、透明窗口等）
• 打包和分发

7. 验收标准 TBD

7.1 功能验收

• 所有原GUI功能在Web界面中可用
• 实时状态同步正常工作
• 任务控制（启动/暂停/取消）功能正常
• 错误处理和用户提示完善

7.2 性能验收

• 页面加载时间 < 3秒
• WebSocket延迟 < 100ms
• 内存占用合理

7.3 兼容性验收

• 支持主流浏览器（Chrome、Firefox、Edge）
• 支持不同屏幕尺寸
• Electron桌面应用正常运行