# 毫秒数仿（MilliSim）详细需求文档

> 版本：v1.0  
> 更新日期：2026-06-19  
> 状态：已确认，可进入设计开发阶段

---

## 0. 技术栈与项目约束

### 0.1 前端技术栈
| 项 | 选型 |
|----|------|
| 框架 | Vue 3 + TypeScript |
| 构建工具 | Vite |
| UI 框架 | Element Plus（浅色模式定制） |
| 状态管理 | Pinia |
| 路由 | Vue Router 4 |
| HTTP | Axios |
| 图表 | ECharts 5 |
| 富文本 | WangEditor 5 |
| 视频播放 | Video.js |
| 图标 | 全局 SVG 图标（iconify 或本地 SVG sprite） |
| 国际化 | 仅中文，不引入 i18n |

### 0.2 后端技术栈
| 项 | 选型 |
|----|------|
| 框架 | .NET Core 10（ASP.NET Core Web API） |
| ORM | Entity Framework Core 10 + Pomelo MySQL Provider |
| 数据库 | MySQL 5.7 |
| 认证 | JWT Bearer Token（7天有效期） |
| 密码哈希 | BCrypt.Net-Next |
| 日志 | Serilog（文件 + 数据库） |
| 对象存储 | 腾讯云 COS SDK + 本地文件系统（双模式动态切换） |
| 验证码 | Lazy.Captcha.Net |

### 0.3 数据库连接
```
Server=sh-cdb-67f2jqfa.sql.tencentcdb.com;Port=27319;Database=millisim4;Uid=unity;Pwd=unity@1478;CharSet=utf8mb4;
```

### 0.4 部署方式
- 前后端均部署于 IIS
- 前端构建为静态文件，IIS 站点托管
- 后端发布为 DLL，IIS 应用程序池托管（ASP.NET Core Module V2）
- 静态资源由 IIS 直接响应，API 请求反代至 Kestrel

### 0.5 全局设计规范
- **浅色模式**：全局浅色背景，科技蓝主色调（#1677FF / #0958D9 渐变）
- **SVG 图标**：所有交互元素、导航、状态指示均使用 SVG 图标，禁止使用字体图标
- **设计感**：圆角卡片、柔和阴影、渐变点缀、微交互动画、留白克制
- **全响应式**：前台完整响应式（PC / 平板 / 手机），管理后台以 PC 为主
- **字体**：系统字体栈，中文优先 `"PingFang SC", "Microsoft YaHei", sans-serif`

---

## 1. 产品定位

一站式虚拟仿真项目资产库 + 商业化展示平台 + 精细化权限管控系统。

面向虚拟仿真行业，提供项目展示、在线体验、客户授权、销售管理、内容运营的一体化解决方案。

---

## 2. 用户角色与权限

### 2.1 角色定义

| 角色 | 说明 | 数据范围 |
|------|------|----------|
| 访客 | 浏览公开项目，无需登录 | 公开项目 |
| 客户 | 浏览 + 授权体验 + 收藏 + 个人中心 | 本人数据 |
| 销售 | 客户管理 + 授权管理 + 咨询消息 | 仅本人创建的客户 |
| 产品经理 | 项目管理 + 内容管理 + 无需授权即可体验 | 全部项目 |
| 管理员 | 全部权限 | 全部数据 |

### 2.2 权限矩阵

| 功能模块 | 访客 | 客户 | 销售 | 产品经理 | 管理员 |
|----------|:----:|:----:|:----:|:--------:|:------:|
| 前台浏览项目 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 在线体验 WebGL | ✗ | 需授权 | ✓ | ✓ | ✓ |
| 收藏 / 个人中心 | ✗ | ✓ | ✓ | ✓ | ✓ |
| 管理后台访问 | ✗ | ✗ | ✓ | ✓ | ✓ |
| 项目管理 | ✗ | ✗ | ✗ | ✓ | ✓ |
| 客户管理 | ✗ | ✗ | 仅本人 | ✗ | ✓ |
| 授权管理 | ✗ | ✗ | 仅本人客户 | ✗ | ✓ |
| 员工管理 | ✗ | ✗ | ✗ | ✗ | ✓ |
| 系统设置 | ✗ | ✗ | ✗ | ✗ | ✓ |

### 2.3 销售数据隔离规则
- 销售仅能查看、编辑、授权**自己创建**的客户
- 销售之间客户数据完全隔离
- 管理员可查看全部客户数据
- 客户创建时自动绑定创建人（销售）ID

---

## 3. 前台功能详细需求

### 3.1 首页

#### 3.1.1 轮播 Banner
- 支持后台配置，可上传图片 / 设置标题 / 跳转链接 / 排序
- 默认科技风格背景图
- 自动轮播（5秒间隔），支持手动切换
- 响应式适配（PC 1920×600 / 平板 1024×400 / 手机 750×360）

#### 3.1.2 核心优势展示
- 4 个优势卡片，图标 + 标题 + 描述
- 后台可配置内容

#### 3.1.3 精选项目推荐
- 展示 8 个精选项目（后台标记为推荐）
- 纵向网格卡片布局（PC 4列 / 平板 2列 / 手机 1列）

#### 3.1.4 分类快捷导航
- 展示所有启用的项目分类
- 图标 + 名称，点击跳转项目中心并筛选

#### 3.1.5 合作伙伴展示
- 可控制显隐（后台开关）
- Logo 滚动展示

#### 3.1.6 CTA 引导区
- 引导注册 / 联系咨询
- 渐变背景 + 行动按钮

### 3.2 项目中心

#### 3.2.1 筛选区
- **关键词搜索**：SQL LIKE 查询项目名称和描述
- **分类筛选**：单选下拉
- **平台筛选**：多选（WebGL / Android / Windows / Mac / VR）
- **排序**：最新发布 / 最多浏览 / 最多体验 / 最多收藏

#### 3.2.2 项目卡片列表
- **纵向网格卡片**布局
- 卡片内容：封面图、名称、分类标签、平台标签、浏览数、体验数、收藏数、收藏按钮
- 悬浮效果：卡片上浮 + 阴影增强 + 封面缩放
- 响应式：PC 4列 / 平板 2列 / 手机 1列

#### 3.2.3 分页
- 默认每页 12 条
- 页码展示 + 上一页 / 下一页

### 3.3 项目详情

#### 3.3.1 基础信息
- 项目名称、分类、平台标签、浏览数、体验数、收藏数
- 发布时间、更新时间
- 特性标签展示

#### 3.3.2 视频播放
- **格式支持**：MP4 + WebM
- **防盗链**：代理模式隐藏 COS URL，Blob URL 加载
- **水印**：动态水印（用户名 + 时间戳）
- **封面**：支持设置视频封面图
- **控件**：播放/暂停、进度条、音量、全屏、倍速
- **快捷键**：空格暂停、左右快进、上下音量、F 全屏

#### 3.3.3 截图画廊
- 缩略图列表 + 点击放大查看
- 支持左右切换、键盘导航

#### 3.3.4 富文本详情
- WangEditor 渲染，支持图片、视频、代码块、表格

#### 3.3.5 交互操作
- **收藏 / 取消收藏**：登录后可用
- **分享**：复制链接 + 二维码
- **在线运行**：WebGL 项目展示，需授权
- **下载**：安卓 APK / 桌面端压缩包，需授权
- **唤醒**：桌面端协议唤醒（custom://protocol）

#### 3.3.6 相关项目推荐
- 同分类下取 4 个项目（排除当前）
- 纵向网格卡片

### 3.4 WebGL 在线运行

#### 3.4.1 运行环境
- 全屏 iframe 加载 Unity WebGL 项目
- 加载进度动画（百分比 + 旋转图标）
- 运行计时显示（右上角）

#### 3.4.2 安全措施
- **动态水印**：半透明用户名 + 时间戳，随机位置
- **禁用右键**：contextmenu 事件拦截
- **防盗链**：HTML/JSON 代理模式改写资源引用

#### 3.4.3 自适应
- 代理注入 CSS，解决 Unity 固定分辨率适配问题
- 全屏切换支持

#### 3.4.4 限制策略
- **不限制**运行时长和并发数
- 记录每次体验日志（用户、项目、开始时间、时长）

### 3.5 个人中心

#### 3.5.1 个人信息
- 头像、昵称、手机号、邮箱编辑
- 用户名只读

#### 3.5.2 我的收藏
- 收藏项目列表，支持取消收藏
- 纵向网格卡片展示

#### 3.5.3 体验记录
- 体验历史列表（项目名、体验时长、体验时间）
- 分页展示

#### 3.5.4 修改密码
- 需验证旧密码
- 新密码强度校验（8位以上，含字母数字）

### 3.6 其他页面

| 页面 | 说明 |
|------|------|
| 用户登录 | 账号密码 + 图形验证码 |
| 技术能力 | 富文本静态页，展示技术栈 |
| 关于我们 | 公司介绍，富文本 |
| 联系咨询 | 表单提交（姓名、联系方式、需求描述） |
| 隐私政策 | 静态文本 |
| 服务条款 | 静态文本 |

---

## 4. 管理后台功能详细需求

### 4.1 工作台

#### 4.1.1 统计卡片
- 项目总数、客户总数、今日访问量、有效授权数
- 卡片含图标 + 数值 + 同比环比

#### 4.1.2 趋势图
- 访问 / 体验趋势折线图（近 7 天 / 30 天切换）
- ECharts 渲染

#### 4.1.3 分类分布
- 饼图展示项目分类分布

#### 4.1.4 其他面板
- 最近动态（操作日志摘要，10 条）
- 热门项目 Top 5
- 未读消息数 + 快捷查看

### 4.2 项目管理

#### 4.2.1 项目列表
- 搜索（名称）+ 筛选（分类 / 平台 / 状态）
- 列表展示：封面、名称、分类、平台、状态、浏览数、体验数、操作
- 状态切换：发布 / 下架（开关）
- 操作：编辑、删除、资源包管理

#### 4.2.2 项目编辑
- **基础信息**：名称、分类、平台（多选）、封面图、简介
- **特性标签**：多选关联
- **截图管理**：多图上传 + 拖拽排序
- **视频管理**：上传 MP4/WebM + 设置封面
- **富文本详情**：WangEditor 编辑
- **发布配置**：发布状态、发布时间、是否推荐、排序权重

#### 4.2.3 资源包管理
- **WebGL**：zip 上传自动解压部署到指定目录
- **Android**：APK 上传
- **桌面端**：压缩包上传（zip/rar）
- 每个资源包记录版本号、上传时间、文件大小

#### 4.2.4 编辑方式
- 弹窗快速编辑（基础字段）
- 独立页面完整编辑（所有字段）

### 4.3 客户管理

#### 4.3.1 客户列表
- 搜索（用户名 / 昵称 / 手机号）
- 筛选（创建人 / 授权状态）
- 列表：头像、用户名、昵称、联系方式、授权状态、到期时间、创建人、操作

#### 4.3.2 客户 CRUD
- **新增**：自动生成用户名（`user` + 6位随机数），默认密码 `123456`（BCrypt 哈希）
- **编辑**：昵称、手机号、邮箱、状态
- **删除**：软删除，关联数据级联处理
- **重置密码**：重置为默认密码

#### 4.3.3 授权管理
- **授权**：选择项目 + 天数（默认 365 天）
- **续期**：在原到期时间基础上增加天数
- **取消授权**：立即失效
- 授权记录可查看历史

### 4.4 授权管理

#### 4.4.1 授权记录
- 查看所有授权记录（客户、项目、授权人、开始时间、到期时间、状态）
- 按状态筛选（有效 / 已过期 / 已取消）

#### 4.4.2 批量授权
- 选择多个客户 + 多个项目
- 统一设置授权天数

### 4.5 员工管理（仅管理员）

#### 4.5.1 员工列表
- 搜索 + 筛选角色 / 状态
- 列表：头像、用户名、姓名、角色、状态、创建时间、操作

#### 4.5.2 员工 CRUD
- 新增：用户名 + 密码 + 角色 + 基本信息
- 编辑：基本信息 + 角色
- 启用 / 禁用
- 重置密码

### 4.6 系统设置

#### 4.6.1 基础配置
- 平台名称、标语、公司名称、联系方式、备案号
- 存储模式切换（COS / 本地）

#### 4.6.2 Logo 管理
- 5 个位置：前台顶部、前台页脚、浏览器图标、后台登录页、后台顶部
- 支持上传 SVG / PNG

#### 4.6.3 上传限制
| 类型 | 默认限制 |
|------|----------|
| 图片 | 5 MB |
| 视频 | 500 MB |
| 资源包 | 2 GB |
| 文档 | 20 MB |

#### 4.6.4 分类管理
- CRUD + 拖拽排序 + 图标上传（SVG）
- 字段：名称、图标、排序、状态、描述

#### 4.6.5 平台类型管理
- CRUD + 排序 + 图标
- 字段：名称、图标、排序、状态

#### 4.6.6 特性标签管理
- CRUD + 排序 + 图标
- 字段：名称、图标、排序、状态

#### 4.6.7 操作日志
- 记录所有后台操作（操作人、操作类型、模块、详情、IP、时间）
- 查询（按操作人 / 模块 / 时间范围）
- 清理（手动清理 + 自动清理配置，默认保留 90 天）

#### 4.6.8 数据备份
- **手动备份**：一键触发，生成 .sql 文件
- **自动备份**：定时任务（默认每日凌晨 2:00）
- **保留策略**：默认保留 30 天，可配置
- 备份记录列表：文件名、大小、类型（手动/自动）、创建时间
- 操作：下载、删除

### 4.7 内容管理

#### 4.7.1 轮播图管理
- CRUD + 图片上传 + 排序 + 跳转链接
- 字段：标题、图片、链接、排序、状态

#### 4.7.2 合作伙伴管理
- CRUD + Logo 上传 + 排序 + 显隐控制

#### 4.7.3 咨询消息管理
- 列表查看（姓名、联系方式、需求、提交时间、状态）
- 标记已读 / 未读
- 删除

### 4.8 唤醒协议对接
- 配置各终端（Windows / Mac）唤醒协议
- 字段：终端类型、协议前缀、协议参数模板、状态

---

## 5. 核心机制

### 5.1 存储双模式

| 模式 | 说明 | 使用场景 |
|------|------|----------|
| COS 模式 | 腾讯云 COS 对象存储 | 生产环境 |
| 本地模式 | 服务器本地文件系统 | 开发环境 |

- 通过系统设置动态切换
- 切换后新上传文件使用新模式，历史文件保持原模式
- 配置项：COS SecretId / SecretKey / Bucket / Region / 自定义域名

### 5.2 COS 资源访问策略

| 资源类型 | 访问方式 | 说明 |
|----------|----------|------|
| HTML / JSON | 代理模式 | 改写资源引用路径，隐藏真实 URL |
| 详情页视频 | 代理模式防盗链 | `?proxy=1` 参数，Blob URL 加载 |
| WebGL 内视频 | 302 重定向 | 签名 URL 临时跳转 |
| 下载文件 | 签名 URL + attachment 头 | 强制下载，不在线预览 |
| 其他文件 | 302 重定向 | 签名 URL 临时跳转 |

### 5.3 视频防盗链
- 代理模式隐藏 COS 真实 URL
- Blob URL 加载视频流
- Canvas 渲染（可选，增强防盗）
- 动态水印（用户名 + 时间戳）

### 5.4 WebGL 自适应
- 代理注入 CSS 脚本
- 解决 Unity 固定分辨率适配问题
- 全屏自适应 + 宽高比保持

### 5.5 认证授权

#### 5.5.1 JWT 认证
- Bearer Token 模式
- 有效期 7 天
- Token 中包含：UserId、Username、Role、CreateTime
- 刷新机制：过期前 1 天可刷新

#### 5.5.2 RBAC 权限
- 基于角色的权限控制
- 接口级权限校验（中间件）
- 数据级权限校验（销售数据隔离）

#### 5.5.3 密码安全
- BCrypt 哈希存储（cost factor = 12）
- 默认密码：`123456`
- 密码强度校验：8位以上，含字母 + 数字

### 5.6 通知系统

#### 5.6.1 通知类型
| 类型 | 触发场景 | 接收人 |
|------|----------|--------|
| 系统通知 | 系统公告、维护通知 | 全部用户 |
| 项目通知 | 新项目发布、项目更新 | 关注相关分类的用户 |
| 账号通知 | 密码重置、授权变更 | 当事用户 |
| 授权通知 | 授权即将到期、已到期 | 当事客户 + 创建销售 |

#### 5.6.2 推送机制
- **仅站内消息**：用户登录后在消息中心查看
- **轮询拉取**：前端每 30 秒轮询未读消息数
- 防重复同步机制：基于业务事件 ID 去重

---

## 6. 数据库设计概要

### 6.1 核心表结构

```
users                -- 用户表（员工 + 客户）
roles                -- 角色表
projects             -- 项目表
project_categories   -- 项目分类表
project_platforms    -- 平台类型表
project_tags         -- 特性标签表
project_tag_relations-- 项目标签关联表
project_screenshots  -- 项目截图表
project_packages     -- 项目资源包表
favorites            -- 收藏表
experience_logs      -- 体验记录表
authorizations       -- 授权记录表
banners              -- 轮播图表
partners             -- 合作伙伴表
consultations        -- 咨询消息表
notifications        -- 通知表
notification_reads   -- 通知已读记录表
operation_logs       -- 操作日志表
system_settings      -- 系统设置表
backups              -- 备份记录表
wake_protocols       -- 唤醒协议配置表
```

### 6.2 关键字段说明

#### users 表
| 字段 | 类型 | 说明 |
|------|------|------|
| Id | bigint PK | 主键 |
| Username | varchar(50) | 用户名（唯一） |
| Password | varchar(255) | BCrypt 哈希 |
| Nickname | varchar(50) | 昵称 |
| Avatar | varchar(500) | 头像 URL |
| Phone | varchar(20) | 手机号 |
| Email | varchar(100) | 邮箱 |
| Role | tinyint | 角色：0访客 1客户 2销售 3产品经理 4管理员 |
| Status | tinyint | 状态：0禁用 1启用 |
| CreatedBy | bigint? | 创建人 ID（销售创建客户时记录） |
| CreatedAt | datetime | 创建时间 |
| UpdatedAt | datetime | 更新时间 |
| IsDeleted | bit | 软删除标记 |

#### projects 表
| 字段 | 类型 | 说明 |
|------|------|------|
| Id | bigint PK | 主键 |
| Name | varchar(100) | 项目名称 |
| CategoryId | bigint | 分类 ID |
| CoverImage | varchar(500) | 封面图 URL |
| VideoUrl | varchar(500) | 视频 URL |
| VideoCover | varchar(500) | 视频封面 |
| Description | text | 简介 |
| Content | longtext | 富文本详情 |
| Platforms | varchar(200) | 平台标签（逗号分隔） |
| Status | tinyint | 0下架 1发布 |
| IsFeatured | bit | 是否推荐 |
| SortOrder | int | 排序权重 |
| ViewCount | int | 浏览数 |
| ExperienceCount | int | 体验数 |
| FavoriteCount | int | 收藏数 |
| PublishedAt | datetime? | 发布时间 |
| CreatedAt | datetime | 创建时间 |
| UpdatedAt | datetime | 更新时间 |
| IsDeleted | bit | 软删除 |

#### authorizations 表
| 字段 | 类型 | 说明 |
|------|------|------|
| Id | bigint PK | 主键 |
| UserId | bigint | 客户 ID |
| ProjectId | bigint | 项目 ID |
| AuthorizedBy | bigint | 授权人 ID（销售/管理员） |
| StartTime | datetime | 开始时间 |
| EndTime | datetime | 到期时间 |
| Status | tinyint | 0已取消 1有效 2已过期 |
| CreatedAt | datetime | 创建时间 |

---

## 7. API 设计规范

### 7.1 RESTful 规范
- 基础路径：`/api`
- 资源命名：复数形式（`/api/projects`、`/api/users`）
- HTTP 方法：GET 查询、POST 新增、PUT 更新、DELETE 删除
- 分页参数：`pageIndex`、`pageSize`，返回 `total`、`items`

### 7.2 统一响应格式
```json
{
  "code": 200,
  "message": "success",
  "data": { }
}
```

### 7.3 认证
- Header：`Authorization: Bearer {token}`
- 未授权返回 401，无权限返回 403

---

## 8. UI/UX 设计规范

### 8.1 色彩系统

| 用途 | 色值 |
|------|------|
| 主色 | #1677FF |
| 主色悬浮 | #4096FF |
| 主色点击 | #0958D9 |
| 主色浅底 | #E6F4FF |
| 成功 | #52C41A |
| 警告 | #FAAD14 |
| 错误 | #FF4D4F |
| 背景 | #F5F7FA |
| 卡片背景 | #FFFFFF |
| 主文字 | #1F2937 |
| 次文字 | #6B7280 |
| 边框 | #E5E7EB |

### 8.2 圆角与阴影
- 卡片圆角：12px
- 按钮圆角：8px
- 输入框圆角：8px
- 卡片阴影：`0 2px 8px rgba(0, 0, 0, 0.08)`
- 悬浮阴影：`0 8px 24px rgba(22, 119, 255, 0.15)`

### 8.3 间距系统
- 基础单位：8px
- 常用：8 / 16 / 24 / 32 / 48

### 8.4 图标规范
- **全部使用 SVG 格式**
- 线性风格，stroke-width: 1.5
- 尺寸：16px / 20px / 24px / 32px
- 颜色继承 currentColor
- 统一封装为 Vue 组件 `<SvgIcon name="xxx" />`

### 8.5 管理后台布局
- **侧边栏布局**：左侧菜单 + 顶部导航 + 内容区
- 侧边栏：可折叠，宽度 240px / 折叠后 64px
- 顶部导航：面包屑 + 用户信息 + 消息通知
- 内容区：卡片式布局，留白充足

### 8.6 前台布局
- 顶部导航栏：Logo + 菜单 + 搜索 + 登录/用户
- 内容区：最大宽度 1200px，居中
- 页脚：公司信息 + 友链 + 备案号

### 8.7 交互动画
- 页面切换：淡入淡出 300ms
- 卡片悬浮：transform 200ms ease
- 按钮：ripple 涟漪效果
- 加载：骨架屏 + 旋转图标
- 消息提示：顶部滑入 300ms

---

## 9. 非功能性需求

### 9.1 性能
- 首屏加载 < 3 秒（PC）
- API 响应 < 500ms（常规接口）
- 列表查询支持索引优化
- 图片懒加载 + WebP 格式

### 9.2 安全
- SQL 参数化查询（EF Core 默认）
- XSS 防护（富文本内容过滤）
- CSRF Token
- 接口限流（同 IP 每分钟 60 次）
- 敏感操作二次确认

### 9.3 兼容性
- 前台：Chrome 90+ / Edge 90+ / Safari 14+ / Firefox 88+
- 后台：Chrome / Edge 最新版
- WebGL：WebGL 2.0 支持的浏览器

### 9.4 可维护性
- 代码分层：Controller → Service → Repository
- DTO 与 Entity 分离
- 统一异常处理中间件
- 配置项集中管理（appsettings.json + 数据库）

---

## 10. 项目里程碑

| 阶段 | 内容 |
|------|------|
| 阶段一 | 数据库设计 + 后端基础框架 + 认证授权 |
| 阶段二 | 前端基础框架 + UI 组件库 + 前台首页 + 项目中心 |
| 阶段三 | 项目详情 + WebGL 运行 + 个人中心 |
| 阶段四 | 管理后台工作台 + 项目管理 + 客户/授权管理 |
| 阶段五 | 系统设置 + 内容管理 + 员工管理 |
| 阶段六 | 通知系统 + 操作日志 + 数据备份 |
| 阶段七 | 联调测试 + 性能优化 + 部署上线 |

---

## 附录 A：确认决策汇总

| 决策项 | 选择 |
|--------|------|
| 用户注册方式 | 仅管理员创建 |
| 登录认证 | 账号密码 + 图形验证码 |
| 多语言 | 仅中文 |
| 响应式 | 全响应式（前台 PC/平板/手机，后台 PC） |
| 销售数据隔离 | 销售间数据隔离 |
| 通知渠道 | 仅站内消息 |
| 实时性 | 轮询拉取（30秒） |
| 搜索能力 | 简单关键词查询（SQL LIKE） |
| 视频格式 | MP4 + WebM |
| 部署方式 | 前后端均部署 IIS |
| 数据备份 | 手动 + 自动备份 |
| WebGL 限制 | 不限制 |
| 主题色 | 科技蓝（#1677FF） |
| 后台布局 | 侧边栏布局 |
| 项目卡片 | 纵向网格卡片 |
| 图表库 | ECharts |