# 游铛铛 - 需求规格说明书

**版本号**：V1.0
**编写日期**：2026年1月1日
**编写人员**：需求数字员工
**审核人员**：待定

## 1. 引言

### 1.1 目的
本文档详细描述了游铛铛产品的功能需求、非功能需求及验收标准，为开发团队提供明确的技术实现指导，确保产品能够满足用户需求，实现BUFF平台选品和Steam平台扫货的业务目标。

### 1.2 范围
本文档涵盖了游铛铛产品的所有功能模块，包括：
- 客户端exe程序（Windows平台）
- 管理端Web管理系统
- 后端API服务
- 数据库设计

**不在范围内的内容**：
- BUFF选品和Steam扫货的具体算法实现（暂作黑盒处理）
- 第三方服务的具体实现细节

### 1.3 定义和缩略语

| 术语 | 定义 |
|------|------|
| BUFF | 网易BUFF平台，游戏饰品交易平台 |
| Steam | Valve公司游戏平台 |
| exe客户端 | Windows可执行程序客户端 |
| 选品 | 从BUFF平台筛选符合条件的商品 |
| 扫货 | 在Steam平台批量采购商品 |
| 卡密 | 充值激活码 |
| P0 | 关键功能，必须第一阶段完成 |
| P1 | 重要功能，第二阶段完成 |
| P2 | 次要功能，第三阶段完成 |

### 1.4 参考文献
- [产品原始需求V3.0版本.md](./产品原始需求V3.0版本.md)
- [产品原始需求整理.md](./产品原始需求整理.md)
- admin工程代码
- backend工程代码
- client-tauri工程代码

## 2. 总体描述

### 2.1 产品前景

#### 产品定位
游铛铛是一款专业的BUFF平台选品和Steam平台扫货工具，旨在帮助用户提高饰品交易的效率，降低人工成本。

#### 目标市场
- 游戏饰品交易从业者
- 需要批量采购Steam商品的用户
- 对效率和安全性有较高要求的交易者

#### 竞争优势
- 高度自动化的选品扫货流程
- 强有力的安全保护机制
- 现代化的用户界面
- 完善的日志审计系统

### 2.2 产品功能

#### 核心功能
1. **BUFF选品**：基于用户配置自动筛选BUFF平台的商品
2. **Steam扫货**：模拟人工操作在Steam平台批量采购
3. **用户管理**：登录注册、充值、权限控制
4. **数据管理**：商品数据、交易记录、日志审计

#### 辅助功能
1. **公告系统**：平台公告发布和查看
2. **软件更新**：自动更新和强制更新机制
3. **设置管理**：个性化配置和系统设置

### 2.3 用户特征

#### 终端用户
- **数量**：预期支持100+并发用户
- **技术水平**：普通计算机用户，无需专业技术背景
- **使用频率**：每日使用，高频操作
- **业务目标**：提高选品扫货效率，降低人工成本

#### 管理员用户
- **数量**：5-10个系统管理员
- **技术水平**：具备基本计算机操作能力
- **使用频率**：每日监控，处理异常情况
- **职责**：用户管理、系统监控、公告发布

### 2.4 约束条件

#### 技术约束
- **客户端平台**：仅支持Windows操作系统
- **网络环境**：需要稳定的互联网连接
- **硬件要求**：详见兼容性要求部分

#### 业务约束
- **互斥运行**：选品和扫货功能不能同时执行
- **安全优先**：防破解措施为最高优先级
- **合规要求**：遵守相关平台的使用条款

#### 时间约束
- **第一阶段**：完成P0级功能（防破解、安全机制、基础功能）
- **第二阶段**：完成P1级功能（完善用户体验）
- **第三阶段**：完成P2级功能（辅助功能优化）

## 3. 具体需求

### 3.1 功能需求

#### 3.1.1 客户端功能需求

##### REQ-CLIENT-001: 用户认证管理
**优先级**：P0
**描述**：支持用户的注册、登录、找回密码、机器绑定解绑功能
**验收标准**：
- 用户名密码登录成功率100%
- 邮箱注册流程完整
- 找回密码邮件发送正常
- 机器绑定解绑操作正确

##### REQ-CLIENT-002: 充值管理
**优先级**：P0
**描述**：支持卡密激活和充值记录查看
**验收标准**：
- 卡密激活成功后有效期正确计算
- 充值记录按时间倒序显示
- 分页显示正常
- 充值失败有明确错误提示

##### REQ-CLIENT-003: Steam账号管理
**优先级**：P0
**描述**：本地存储和管理Steam账号信息
**验收标准**：
- 账号密码本地加密存储
- 密钥文件上传和解析正常
- 账号信息仅本地存储，不上传服务器

##### REQ-CLIENT-004: 选品功能
**优先级**：P0
**描述**：配置选品参数并启动选品服务
**验收标准**：
- 配置界面tab页展示正常
- 参数保存和加载正确
- 启动/停止操作响应正常
- 与扫货功能互斥控制生效

##### REQ-CLIENT-005: 扫货功能
**优先级**：P0
**描述**：配置扫货参数并启动扫货服务
**验收标准**：
- 配置界面tab页展示正常
- 参数保存和加载正确
- 启动/停止操作响应正常
- 与选品功能互斥控制生效

##### REQ-CLIENT-006: 公告查看
**优先级**：P1
**描述**：查看平台发布的公告信息
**验收标准**：
- 公告列表按重要性和时间排序
- 支持搜索功能
- 详情查看正常
- 支持纵向滚动

##### REQ-CLIENT-007: 设置管理
**优先级**：P1
**描述**：个人信息查看、密码修改、软件更新
**验收标准**：
- 个人信息显示完整
- 密码修改成功后立即生效
- 软件版本检查正常
- 更新提示准确

##### REQ-CLIENT-008: 互斥控制
**优先级**：P0
**描述**：确保选品和扫货功能不能同时运行
**验收标准**：
- 启动一个功能时自动停止另一个
- UI界面有明确的运行状态显示
- 后台进程正确终止

#### 3.1.2 管理端功能需求

##### REQ-ADMIN-001: 客户管理
**优先级**：P0
**描述**：管理系统注册客户的信息
**验收标准**：
- 客户列表分页显示
- 支持按状态、时间筛选
- 客户详情查看完整
- 状态控制（启用/禁用）正常

##### REQ-ADMIN-002: 管理员管理
**优先级**：P0
**描述**：管理系统管理员用户
**验收标准**：
- 管理员列表管理
- 权限分配正确
- 默认管理员：admin/admin123

##### REQ-ADMIN-003: 软件管理
**优先级**：P0
**描述**：管理客户端软件版本和更新策略
**验收标准**：
- 版本信息维护正确
- 强制更新配置生效
- 版本兼容性检查

##### REQ-ADMIN-004: 卡密管理
**优先级**：P0
**描述**：生成和管理充值卡密
**验收标准**：
- 卡密生成算法正确
- 激活记录完整记录
- 卡密状态跟踪准确

##### REQ-ADMIN-005: 密钥管理
**优先级**：P0
**描述**：管理API通信的公钥私钥
**验收标准**：
- 密钥对生成正确
- 定期轮换机制正常
- 历史密钥保存完整

##### REQ-ADMIN-006: 日志管理
**优先级**：P1
**描述**：查看和分析系统日志
**验收标准**：
- 日志分类显示正确
- 支持多条件筛选
- 日志详情查看完整

##### REQ-ADMIN-007: 公告管理
**优先级**：P1
**描述**：发布和管理平台公告
**验收标准**：
- 公告发布成功
- 编辑修改功能正常
- 删除操作安全确认

#### 3.1.3 后端服务功能需求

##### REQ-BACKEND-001: API接口服务
**优先级**：P0
**描述**：提供统一的API接口服务
**验收标准**：
- 所有接口响应正常
- 数据格式符合规范
- 错误处理完善

##### REQ-BACKEND-002: 数据同步服务
**优先级**：P0
**描述**：定时同步BUFF平台商品数据
**验收标准**：
- 同步周期可配置
- 数据完整性保证
- 异常情况自动重试

##### REQ-BACKEND-003: 选品服务
**优先级**：P0
**描述**：提供高并发的选品处理服务
**验收标准**：
- 支持100+用户并发
- 动态扩容机制正常
- 结果返回准确及时

##### REQ-BACKEND-004: 安全机制
**优先级**：P0
**描述**：实现全面的安全保护机制
**验收标准**：
- API通信加密正常
- 密钥轮换机制有效
- 访问控制严格执行

### 3.2 非功能需求

#### 3.2.1 性能需求

##### PERF-001: 响应时间
- 界面切换响应时间 ≤ 1秒
- 数据加载时间 ≤ 2秒
- 用户操作响应时间 ≤ 3秒
- 核心功能启动时间 ≤ 5秒

##### PERF-002: 并发处理能力
- 支持至少100个用户同时在线
- 选品服务支持动态扩容
- 数据处理支持10万+商品信息

##### PERF-003: 资源使用限制
- 客户端正常运行内存 ≤ 500MB
- 选品/扫货运行时内存 ≤ 800MB
- CPU使用率正常状态 ≤ 20%，操作时 ≤ 60%

#### 3.2.2 安全需求

##### SEC-001: 防破解措施
- 使用Rust编译提高逆向工程难度
- 文件完整性检查机制
- 运行时反调试保护
- 代码混淆和保护

##### SEC-002: 数据安全
- 所有API接口使用RSA加密通信
- Steam账号信息只本地存储
- 密钥定期轮换（默认10天）
- 本地配置文件AES-256加密

##### SEC-003: 访问控制
- 单账号单机器绑定限制
- 会话token安全管理
- 心跳检测机制
- 权限分级控制

##### SEC-004: 审计要求
- 全面记录用户操作日志
- 业务操作完整记录
- 系统异常日志记录
- 安全事件日志记录
- 所有日志存储到数据库
- 支持多条件日志查询

#### 3.2.3 兼容性需求

##### COMPAT-001: 操作系统支持
- 主要支持：Windows 10/11（64位）
- 向下兼容：Windows 7 SP1+
- 不支持：macOS、Linux

##### COMPAT-002: 网络环境要求
- 需要稳定的互联网连接
- 支持HTTP/HTTPS代理配置
- 建议网络延迟 ≤ 200ms

##### COMPAT-003: 内置组件要求
- 完整内置Chromium浏览器内核
- 内置Steam相关插件
- 浏览器与系统隔离运行

##### COMPAT-004: 硬件兼容性
- CPU：双核2.0GHz以上
- 内存：4GB以上
- 磁盘：500MB可用空间

#### 3.2.4 可用性需求

##### AVAIL-001: 系统可用性
- 目标可用性：99.5%以上
- 计划维护时间单独安排
- 异常情况有降级处理机制

##### AVAIL-002: 故障恢复
- 自动重连网络断开
- 程序重启后状态恢复
- 数据不因故障丢失

##### AVAIL-003: 异常处理
- 用户友好的错误提示
- 自动重试临时性错误
- 完整的异常处理流程

#### 3.2.5 可维护性需求

##### MAINT-001: 更新机制
- 支持强制更新和手工更新
- 更新只能向前不能回退
- 完善的更新流程和回滚机制
- 管理端控制更新策略

##### MAINT-002: 日志管理
- 日志分级：ERROR、WARN、INFO、DEBUG
- 日志保留期根据重要性设置
- 日志存储位置可配置

##### MAINT-003: 监控告警
- 关键指标监控
- 异常情况自动告警
- 性能指标跟踪

#### 3.2.6 可扩展性需求

##### SCALE-001: 功能扩展
- 预留扩展接口
- 插件化架构设计
- 模块化功能组织

##### SCALE-002: 数据扩展
- 支持数据量动态增长
- 数据库性能优化
- 历史数据归档机制

##### SCALE-003: 用户扩展
- 支持用户规模增长
- 负载均衡机制
- 缓存策略优化

### 3.3 接口需求

#### 3.3.1 客户端接口需求

##### API-CLIENT-001: 用户认证接口
- POST /api/client/auth/login - 用户登录
- POST /api/client/auth/register - 用户注册
- POST /api/client/auth/reset-password - 找回密码
- POST /api/client/auth/bind-machine - 机器绑定
- POST /api/client/auth/unbind-machine - 机器解绑

##### API-CLIENT-002: 充值接口
- POST /api/client/recharge/activate - 卡密激活
- GET /api/client/recharge/records - 充值记录查询

##### API-CLIENT-003: 选品接口
- POST /api/client/selection/start - 启动选品
- POST /api/client/selection/stop - 停止选品
- GET /api/client/selection/config - 获取配置
- POST /api/client/selection/config - 保存配置

##### API-CLIENT-004: 扫货接口
- POST /api/client/sweep/start - 启动扫货
- POST /api/client/sweep/stop - 停止扫货
- GET /api/client/sweep/config - 获取配置
- POST /api/client/sweep/config - 保存配置

##### API-CLIENT-005: 系统接口
- GET /api/client/announcements - 获取公告
- GET /api/client/version - 检查版本
- POST /api/client/heartbeat - 心跳检测

#### 3.3.2 管理端接口需求

##### API-ADMIN-001: 用户管理接口
- GET /api/admin/users - 用户列表
- GET /api/admin/users/{id} - 用户详情
- PUT /api/admin/users/{id}/status - 更新用户状态
- DELETE /api/admin/users/{id} - 删除用户

##### API-ADMIN-002: 卡密管理接口
- POST /api/admin/cards/generate - 生成卡密
- GET /api/admin/cards/records - 激活记录
- GET /api/admin/cards/{code} - 卡密详情

##### API-ADMIN-003: 系统管理接口
- GET /api/admin/logs - 日志查询
- POST /api/admin/announcements - 发布公告
- PUT /api/admin/announcements/{id} - 编辑公告
- DELETE /api/admin/announcements/{id} - 删除公告

##### API-ADMIN-004: 密钥管理接口
- GET /api/admin/keys - 密钥列表
- POST /api/admin/keys/rotate - 轮换密钥
- GET /api/admin/keys/history - 历史密钥

## 4. 验收标准

### 4.1 功能验收标准

#### 客户端功能验收
- ✅ 登录注册：支持用户名密码登录、邮箱注册、找回密码、机器绑定解绑
- ✅ 充值管理：卡密激活、充值记录查看（按时间倒序、分页显示）
- ✅ Steam账号：账号密码管理（本地存储）、密钥文件上传
- ✅ 选品功能：配置界面正常、启动/停止操作响应正常
- ✅ 扫货功能：配置界面正常、启动/停止操作响应正常
- ✅ 公告查看：公告列表显示、搜索功能、详情查看
- ✅ 设置管理：个人信息查看、密码修改、软件更新检查
- ✅ 互斥控制：选品和扫货同时只能运行一个

#### 管理端功能验收
- ✅ 客户管理：客户列表查看、状态控制、详情查看、删除操作
- ✅ 管理员管理：管理员用户管理、权限控制
- ✅ 软件管理：版本控制、强制更新配置
- ✅ 卡密管理：卡密生成、激活记录查看
- ✅ 密钥管理：公钥私钥查看、更新周期配置
- ✅ 日志管理：各类日志查询、筛选功能
- ✅ 公告管理：公告发布、编辑、删除

#### 后端服务验收
- ✅ API接口：所有接口正常响应、数据格式正确
- ✅ 数据同步：BUFF数据定时同步、数据完整性
- ✅ 选品服务：支持多用户并发、动态扩容、结果返回正确
- ✅ 安全机制：加密通信、密钥轮换、访问控制

### 4.2 性能验收标准
- ✅ 响应时间：界面切换≤1秒，数据加载≤2秒，业务操作≤3秒
- ✅ 并发能力：支持100+用户同时在线，处理10万+商品数据
- ✅ 资源使用：内存≤500MB（选品/扫货时≤800MB），CPU使用合理

### 4.3 安全验收标准
- ✅ 防破解：Rust编译保护、完整性检查、运行时保护
- ✅ 数据安全：API加密、敏感数据本地存储、访问控制
- ✅ 日志完整性：全面日志记录、数据库存储、多条件查询

### 4.4 用户体验验收标准
- ✅ 界面体验：现代UI设计、操作直观、无卡顿、错误提示清晰
- ✅ 功能完整性：功能闭环、异常处理完善、状态同步正常

## 5. 附录

### 5.1 数据库表结构

#### 用户表 (users)
```sql
CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  username VARCHAR(50) UNIQUE NOT NULL,
  email VARCHAR(100),
  password_hash VARCHAR(255) NOT NULL,
  machine_code VARCHAR(100),
  expire_time DATETIME,
  last_login_time DATETIME,
  last_login_ip VARCHAR(45),
  status TINYINT DEFAULT 1,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 充值记录表 (recharge_records)
```sql
CREATE TABLE recharge_records (
  id INT PRIMARY KEY AUTO_INCREMENT,
  user_id INT NOT NULL,
  card_code VARCHAR(100) NOT NULL,
  software_code VARCHAR(50) NOT NULL,
  days INT NOT NULL,
  activated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);
```

#### 日志表 (logs)
```sql
CREATE TABLE logs (
  id INT PRIMARY KEY AUTO_INCREMENT,
  user_id INT,
  action VARCHAR(100) NOT NULL,
  level ENUM('ERROR', 'WARN', 'INFO', 'DEBUG') DEFAULT 'INFO',
  message TEXT,
  ip_address VARCHAR(45),
  user_agent TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 5.2 错误代码定义

| 错误代码 | 描述 |
|----------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 账号过期或被禁用 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |

### 5.3 版本历史

| 版本 | 日期 | 修改内容 | 修改人 |
|------|------|----------|--------|
| V1.0 | 2026-01-01 | 初始版本 | 需求数字员工 |

---

**文档状态**：已完成需求调研和规格定义
**下一步**：进入开发实施阶段
**联系方式**：需求数字员工