# CrossVerse

**Repository Path**: sober1107/cross-verse

## Basic Information

- **Project Name**: CrossVerse
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 60
- **Forks**: 25
- **Created**: 2025-11-27
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cross_Verse

跨链数字内容资产交易市场。

本项目面向数字内容资产交易场景，提供一套包含前端应用、后端服务、联盟链基础设施与跨链联通能力的完整示范实现。系统覆盖用户注册登录、资产发布、交易流转、状态校验、基础设施联通与健康检查等关键环节，可用于方案展示、教学验证、部署试验及客户侧二次落地。

## 1. 项目概述

Cross_Verse 采用前后端分层架构，并接入联盟链与跨链组件作为可信底座。系统围绕数字内容资产交易生命周期设计，支持以下关键流程：

1. 资产发布与在售管理
2. 买家下单与交易创建
3. 交易状态推进，包括收据、质押、支付、交付等关键步骤
4. 交易完成、终止或追责处理
5. 基础设施状态统一检查与联通验证

本仓库既可作为本地联调示范项目使用，也已整理为面向不同场景的双交付结构：

- 演示版桌面程序
- 服务器部署版

## 2. 技术栈与系统组成

### 2.1 前端

- Vue 3
- Vue Router
- Bootstrap
- 默认访问端口：8080

### 2.2 后端

- Flask
- REST API
- 本地 JSON 持久化（当前实现）
- 默认服务端口：5000

### 2.3 基础设施

- FISCO BCOS 3.x
- WeBASE
- WeCross Router
- WeCross Account-Manager
- 独立 MySQL（13306）

## 3. 仓库结构

- `frontend/`：前端应用源码
- `backend/service/`：后端服务源码
- `backend/infra/`：基础设施脚本、运行手册与联调辅助文件
- `delivery/`：交付说明与打包脚本
- `deploy/server/`：服务器部署所需的容器化配置与一键脚本
- `releases/`：构建产物与交付包

## 4. 运行环境要求

- Windows 10/11
- WSL2 + Ubuntu-22.04
- Git
- Node.js LTS（建议 18 或 20）
- Python 3.11+
- Java 17

Windows 可选安装命令：

```powershell
winget install Git.Git
winget install OpenJS.NodeJS.LTS
winget install Python.Python.3.11
winget install EclipseAdoptium.Temurin.17.JDK
```

版本校验：

```powershell
git --version
node -v
npm -v
python --version
java -version
wsl -l -v
```

## 5. 获取项目

```bash
git clone <gitee仓库地址>
cd <仓库目录>
```

> 说明：以下命令中的 `<仓库目录>` 请替换为本机实际路径。

## 6. 基础设施初始化部署

以下步骤在 PowerShell 中执行，命令会自动进入 WSL 环境。

### 6.1 部署 FISCO BCOS

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/fisco-bcos-3/setup_wsl.sh"
```

### 6.2 部署 WeBASE

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/webase-3/setup_wsl.sh"
```

### 6.3 部署 WeCross

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/wecross/setup_wsl.sh"
```

## 7. 系统启动

### 7.1 启动 WeCross 交易栈

该脚本负责启动 MySQL（13306）、Account-Manager（8340）与 Router（8250/25500）：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/wecross/restart_stack_wsl.sh restart"
```

状态检查与健康检查：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/wecross/restart_stack_wsl.sh status"
wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/<盘符小写>/<仓库目录>; bash backend/infra/wecross/restart_stack_wsl.sh health"
```

### 7.2 启动后端服务

```powershell
cd <仓库目录>\backend\service
.\start_backend.ps1
```

### 7.3 启动前端应用

```powershell
cd <仓库目录>\frontend
npm install
npm run serve
```

## 8. 访问入口

- 前端首页：`http://127.0.0.1:8080`
- 后端健康检查：`http://127.0.0.1:5000/api/health`
- 基础设施状态：`http://127.0.0.1:5000/api/infra/status`
- WeBASE Web：`http://127.0.0.1:5500`
- WeBASE Front：`http://127.0.0.1:5502/WeBASE-Front`

## 9. 业务使用流程

### 9.1 用户注册与登录

1. 打开前端首页
2. 创建新账号或使用已有账号登录
3. 登录成功后进入交易页面

### 9.2 资产发布

在售卖页填写并提交以下信息：

1. 商品图片
2. 商品名称
3. Hash
4. Commitment
5. Cert
6. 价格

### 9.3 发起购买

1. 进入购买页
2. 选择目标商品并提交购买请求
3. 系统创建交易记录并将对应资产从在售列表移除

### 9.4 推进交易流程

买卖双方可在各自交易页面中按业务流程逐步推进状态，直至：

1. 交易完成
2. 交易终止
3. 交易进入追责/退款流程

## 10. 主要接口

- `GET /api/health`
- `GET /api/infra/status`
- `GET /api/accounts?username=xxx`
- `POST /api/accounts`
- `GET /api/onsale`
- `POST /api/onsale`
- `POST /api/trades`
- `GET /api/trades?role=buyer&username=xxx`
- `GET /api/trades?role=seller&username=xxx`
- `POST /api/trades/{productID}/update`
- `DELETE /api/trades/{productID}`

## 11. 联通性检查

### 11.1 端口检查

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "ss -lnt | grep -E ':20200|:20201|:13306|:8340|:8250|:25500|:5500|:5502|:5001|:5004'"
```

### 11.2 后端聚合状态检查

```powershell
Invoke-RestMethod http://127.0.0.1:5000/api/infra/status
```

### 11.3 服务返回码说明

- 8340 返回 `400` 可视为 Account-Manager 存活
- 8250 返回 `404` 可视为 Router 存活

## 12. 常见问题

### 12.1 前端页面无法打开或出现白屏

1. 确认 `npm run serve` 正在运行
2. 确认访问地址为 `http://127.0.0.1:8080`
3. 查看前端终端输出是否存在报错

### 12.2 登录、上架或交易接口调用失败

1. 确认后端服务已启动
2. 检查 `http://127.0.0.1:5000/api/health`
3. 查看后端终端日志输出

### 12.3 `/api/infra/status` 返回 `ok=false`

建议按以下顺序排查：

1. FISCO 节点端口（20200/20201）
2. WeBASE 端口（5500/5502）
3. 执行 `restart_stack_wsl.sh restart`
4. 执行 `restart_stack_wsl.sh health`

### 12.4 WSL 执行脚本出现 `bash\r` 错误

将脚本转换为 LF 行尾：

```bash
dos2unix backend/infra/fisco-bcos-3/setup_wsl.sh
dos2unix backend/infra/webase-3/setup_wsl.sh
dos2unix backend/infra/wecross/setup_wsl.sh
dos2unix backend/infra/wecross/restart_stack_wsl.sh
```

## 13. 相关文档

- `backend/infra/RUNBOOK.md`
- `backend/service/README.md`
- `Cross_Verse_跨链数字内容资产交易市场_完整落地实施手册.md`
- `delivery/demo/README.md`
- `delivery/server/README.md`

## 14. 交付形态

当前仓库已整理为两类标准交付形态，以适配不同使用场景：

1. 演示版
2. 服务器部署版

### 14.1 演示版

- 适用于单机演示、方案汇报、答辩展示与售前试用
- 产物：`releases/launcher/CrossVerseLauncher.exe`
- 说明文档：`delivery/demo/README.md`

### 14.2 服务器部署版

- 适用于部署到客户自有服务器、云主机或专有环境
- 部署入口：`deploy/server/install_and_run.sh`
- 容器编排：`deploy/server/docker-compose.yml`
- 配置模板：`deploy/server/.env.example`
- 说明文档：`delivery/server/README.md`

## 15. 说明

当前版本已具备完整的业务流程演示能力与基础设施联通能力。后端交易数据当前采用本地 JSON 持久化方式，适用于教学、演示、测试与方案验证场景。若用于正式生产环境，建议进一步接入标准数据库、完善安全配置，并结合服务器部署版实施上线。