# CrossVerse

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

## Basic Information

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

## Statistics

- **Stars**: 69
- **Forks**: 28
- **Created**: 2025-11-27
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cross_Verse 使用手册

Cross_Verse 是一套面向数字内容资产交易的跨链可信交易系统。用户可以完成账号注册、资产发布、资产购买、买卖双方交易推进，并通过 FISCO BCOS、WeBASE 与 WeCross 相关服务校验关键链上交易哈希。

这份文档面向第一次接触系统的用户和部署人员编写。请按顺序阅读：先选择运行方式，再启动系统，最后按业务流程完成一笔交易。

当前版本要求交易流程中的每一步都填写链上真实可查的交易哈希。请先在链上查询页面确认交易已经发生，再把对应哈希复制回系统。

## 1. 先看这里

### 1.1 业务场景是什么

Cross_Verse 面向的是两条联盟链之间的数字内容资产交易。一个典型场景如下：

- 资产链：记录数字内容资产的存证、上架锚定、收据审计等信息。
- 结算链：记录质押、支付、内容提供确认、交易完成或追责退款等信息。
- 卖家：在资产链上证明自己发布的数字内容资产真实存在，并在交易过程中提供分片信息。
- 买家：在业务系统中购买资产，并在链上提交收据、支付、完成或追责退款相关交易。
- 使用方：通常既是 Cross_Verse 的业务用户，也是联盟链平台的管理员或运维人员，因此可以登录 WeBASE-Front、WeCross WebApp 等区块链平台查看区块、交易、回执，并复制真实的 Transaction Hash 回填到 Cross_Verse。

也就是说，Cross_Verse 不是让普通用户随便填写一串字符串，而是让具备链平台访问权限的使用方把链上已经发生的关键交易作为凭证填入业务流程。每一步填写的 hash 都应来自对应联盟链的真实交易记录。

当前页面中会看到 `asset`、`payment`、`delivery` 等步骤链选项。面向两条联盟链理解时，可按下面方式使用：

- `asset`：资产链，主要用于资产上架锚定和收据审计。
- `payment`：结算链，主要用于质押、支付和追责退款。
- `delivery`：内容提供与完成确认对应的链路标识，通常映射到内容提供/结算相关链路；实际部署时可由管理员按本单位链路规划映射到对应联盟链。

### 1.2 你可以用 Cross_Verse 做什么

- 注册和登录业务账号。
- 发布一个数字内容资产。
- 购买其他用户发布的资产。
- 在买入交易和卖出交易页面推进交易状态。
- 为资产上架、收据审计、质押、支付、内容提供、交易完成或追责退款填写链上 Transaction Hash。
- 通过后端接口查看本机链、跨链与应用服务是否正常。

### 1.3 你会接触到哪些地址

本机运行时常用地址如下：

| 地址 | 用途 |
| --- | --- |
| `http://127.0.0.1:8080/` | 前端页面，源码运行时使用 |
| `http://127.0.0.1:5000/` | 桌面程序或后端直接提供的页面 |
| `http://127.0.0.1:5000/api/health` | 后端健康检查 |
| `http://127.0.0.1:5000/api/infra/status` | 基础设施状态检查 |
| `http://127.0.0.1:5500/` | WeBASE-Web |
| `http://127.0.0.1:5502/WeBASE-Front` | WeBASE-Front，查看区块、交易和回执，并复制 Transaction Hash |
| `http://127.0.0.1:18250/` | WeCross WebApp，查看跨链路由和链资源 |

### 1.4 本文中的路径怎么理解

本文使用 `<项目目录>` 表示 Cross_Verse 所在目录。请替换成你自己电脑上的真实目录。

示例：

```powershell
cd <项目目录>
```

如果你是在项目根目录打开终端，就不需要再关心项目放在哪个盘、哪个文件夹。

## 2. 选择运行方式

建议按你的目标选择一种方式，不必一开始全部尝试。

### 2.1 方式一：直接打开桌面程序

适合只想使用图形界面的用户。

Windows：

```text
Gitee Release 附件：CrossVerse.exe
```

Linux：

```text
Gitee Release 附件：CrossVerse
```

如果需要观察启动日志，再使用启动器：

```text
Gitee Release 附件：CrossVerseLauncher.exe
Gitee Release 附件：CrossVerseLauncher
```

启动成功后，预期看到：

- 桌面窗口或浏览器页面打开。
- `http://127.0.0.1:5000/api/health` 返回 `ok: true`。

### 2.2 方式二：从源码运行

适合需要调试、修改代码或查看前后端日志的用户。

源码运行会启动两个服务：

- 后端 Flask：`5000`
- 前端 Vue：`8080`

启动后访问：

```text
http://127.0.0.1:8080/
```

### 2.3 方式三：部署到服务器

适合需要让多人通过服务器访问系统的场景。

服务器运行使用：

```text
deploy/server/
```

启动后访问：

```text
http://<server-ip>:8080
```

## 3. 环境要求

### 3.1 基础环境

推荐环境：

- Windows 10/11，或 Linux 服务器。
- WSL2 + Ubuntu 22.04，用于本机运行 FISCO BCOS、WeBASE、WeCross。
- Node.js 20 LTS 或 22 LTS。
- npm 10.x 或随 Node.js 安装的版本。
- Python 3.11.x。
- Java 17 LTS。
- Docker Desktop 或 Docker Engine，只有服务器部署时必须。

当前项目已在以下版本组合中验证过：

- Node.js `22.19.0`
- npm `10.9.3`
- Python `3.11.9`
- FISCO BCOS `v3.12.2`
- WeCross `v1.3.1`
- WSL2 Ubuntu 22.04

### 3.2 Windows 安装命令

可以用 PowerShell 执行：

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

Docker 只在服务器部署或容器化运行时需要。如果只运行源码前后端，可以暂时不装 Docker。

### 3.3 检查版本

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

预期结果：

- `node -v` 能输出版本号。
- `python --version` 输出 `Python 3.11.x`。
- `wsl -l -v` 能看到 `Ubuntu-22.04`，且版本为 `2`。
- 如果安装了 Docker，`docker compose version` 能输出版本号。

### 3.4 仓库级校验入口

评委或维护者在根目录可以直接执行以下命令做基础校验：

```powershell
npm test
npm run test:smoke
```

这两条命令分别用于：

- `npm test`：执行仓库级静态校验，包括后端编译检查、后端接口烟测和前端生产构建
- `npm run test:smoke`：单独执行后端健康检查、认证与基础接口烟测

## 4. 项目结构

```text
Cross_Verse/
  backend/
    service/          后端服务、桌面程序入口、后端依赖
    infra/            FISCO BCOS、WeBASE、WeCross 初始化与运维脚本
    sol/              Solidity 合约文件
    legacy/           历史链工具与参考资料
  frontend/           Vue 前端源码
  deploy/server/      服务器部署配置
  docs/               测试记录和补充说明
  releases/apps/      维护者本地打包后的桌面程序输出目录
```

新用户最常用的目录：

- `backend/service/`：启动后端。
- `frontend/`：启动前端。
- `backend/infra/`：启动链和跨链服务。
- `deploy/server/`：服务器部署。

如果你是从远端仓库直接浏览源码，通常不会看到现成的桌面程序文件。对使用者来说，默认入口应当是 Gitee Release 附件，而不是仓库中的 `releases/` 目录。

## 5. 直接使用桌面程序

### 5.1 Windows 使用

请先从 Gitee Release 页面下载附件中的以下文件之一：

```text
CrossVerse.exe
```

优先双击：

```text
CrossVerse.exe
```

如果没有窗口、页面没有打开，或需要看日志，再双击：

```text
CrossVerseLauncher.exe
```

预期结果：

- 系统窗口打开，或浏览器打开 `http://127.0.0.1:5000`。
- 健康检查 `http://127.0.0.1:5000/api/health` 返回 `ok: true`。

### 5.2 Linux 使用

如果你已经从 Gitee Release 页面下载了 Linux 版本程序，请在下载后的附件目录中执行：

```bash
chmod +x ./CrossVerse
chmod +x ./CrossVerseLauncher
./CrossVerse
```

查看日志时执行：

```bash
./CrossVerseLauncher
```

### 5.3 桌面程序的运行逻辑

桌面程序会：

- 启动本机后端服务。
- 加载已构建好的前端页面。
- 使用本机用户目录保存运行数据。
- 在能识别项目根目录时，尝试通过 WSL 拉起链和跨链相关服务。

桌面程序不会：

- 替你安装 WSL、Ubuntu、Java、Docker 等系统环境。
- 在没有链环境时生成真实链上 Transaction Hash。
- 自动解决端口占用、防火墙拦截或杀毒软件隔离。

## 6. 从源码运行

本节适合希望看到完整前后端日志的用户。建议打开两个 PowerShell 终端，一个用于后端，一个用于前端。

### 6.1 获取代码

```powershell
git clone https://gitee.com/sober1107/cross-verse.git
cd cross-verse
```

如果你已经拿到项目文件，直接进入项目根目录：

```powershell
cd <项目目录>
```

### 6.2 启动后端

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

这个脚本会：

- 创建或复用 `.venv` 虚拟环境。
- 安装后端依赖。
- 启动 Flask 服务。

预期结果：

- 终端显示 Flask 正在运行。
- 打开 `http://127.0.0.1:5000/api/health` 能看到 `ok: true`。

如果不想使用虚拟环境：

```powershell
cd <项目目录>\backend\service
.\start_backend.ps1 -NoVenv
```

如果想手动执行：

```powershell
cd <项目目录>\backend\service
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py
```

### 6.3 启动前端

新开一个 PowerShell：

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

预期结果：

- 终端显示前端服务启动成功。
- 浏览器访问 `http://127.0.0.1:8080/` 能看到登录页面。

### 6.4 第一次启动后的检查

```powershell
Invoke-RestMethod http://127.0.0.1:5000/api/health
(Invoke-WebRequest -Uri http://127.0.0.1:8080/ -UseBasicParsing).StatusCode
```

预期结果：

- 第一个命令返回 `ok: true`。
- 第二个命令返回 `200`。

如果还没有启动链和跨链服务，`/api/infra/status` 返回 `ok: false` 是正常的。此时可以登录和查看页面，但发布资产和交易步骤中的链上哈希校验可能无法通过。

## 7. 启动链与跨链服务

完整交易流程需要 FISCO BCOS、WeBASE 与 WeCross 正常运行。Windows 用户推荐使用 WSL2 Ubuntu 22.04 运行这些服务。

### 7.1 PowerShell 中准备项目 WSL 路径

如果你不确定 `<项目目录>` 在 WSL 中对应什么路径，可以在项目根目录执行：

```powershell
cd <项目目录>
$repo = (Get-Location).Path
wsl -d Ubuntu-22.04 -- wslpath -a "$repo"
```

PowerShell 会输出类似：

```text
/mnt/c/Users/xxx/Cross_Verse
```

后续命令中的 `<项目WSL目录>` 就替换成这个输出。

### 7.2 首次初始化 FISCO BCOS

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/fisco-bcos-3/setup_wsl.sh"
```

预期结果：

- 终端输出 `FISCO BCOS local chain is ready`。
- WSL 中能看到 `fisco-bcos` 进程。
- `20200`、`20201` 端口可监听。

检查命令：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "ps -ef | grep fisco-bcos | grep -v grep"
wsl -d Ubuntu-22.04 -- bash -lc "ss -lnt | grep -E ':20200|:20201'"
```

### 7.3 首次初始化 WeBASE

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/webase-3/setup_wsl.sh"
```

预期结果：

- WeBASE-Web 可访问：`http://127.0.0.1:5500/`
- WeBASE-Front 可访问：`http://127.0.0.1:5502/WeBASE-Front`
- `5500`、`5502`、`5001`、`5004` 端口可监听。

### 7.4 首次初始化 WeCross

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/wecross/setup_wsl.sh"
```

预期结果：

- WeCross Router 端口 `8250`、`25500` 可监听。
- WeCross 相关文件位于 WSL 用户目录下的 `~/crossverse/wecross`。

如果需要使用“发布资产时自动生成 `assetTxHash`”功能，还需要在 WSL 中准备 WeCross Console、自动交易账号和示例资源：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd ~/crossverse/wecross/WeCross && bash ./download_console.sh"
wsl -d Ubuntu-22.04 -- bash -lc "openssl ec -in /root/crossverse/wecross/routers-payment/127.0.0.1-8250-25500/conf/chains/bcos3/admin/0xa8a18eb2f1ff3b64b7886a278b76891c35e4c434_secp256k1.key -pubout -out /root/crossverse/wecross/routers-payment/127.0.0.1-8250-25500/conf/chains/bcos3/admin/0xa8a18eb2f1ff3b64b7886a278b76891c35e4c434_secp256k1.pub"
wsl -d Ubuntu-22.04 -- bash -lc "cd ~/crossverse/wecross/WeCross/WeCross-Console && printf '%s\n' 'registerAccount autogrow_bot 123456' 'login autogrow_bot 123456' 'addChainAccount BCOS3_ECDSA_EVM /root/crossverse/wecross/routers-payment/127.0.0.1-8250-25500/conf/chains/bcos3/admin/0xa8a18eb2f1ff3b64b7886a278b76891c35e4c434_secp256k1.pub /root/crossverse/wecross/routers-payment/127.0.0.1-8250-25500/conf/chains/bcos3/admin/0xa8a18eb2f1ff3b64b7886a278b76891c35e4c434_secp256k1.key 0xa8a18eb2f1ff3b64b7886a278b76891c35e4c434 true' 'bcosDeploy payment.bcos3.HelloAuto0527a contracts/solidity/HelloWeCross.sol HelloWeCross' 'bcosDeploy payment.bcos3.HelloAuto0527b contracts/solidity/HelloWeCross.sol HelloWeCross' 'bcosDeploy payment.bcos3.HelloAuto0527c contracts/solidity/HelloWeCross.sol HelloWeCross' 'listResources' 'quit' | ./start.sh"
```

`registerAccount` 如果提示账号已存在，可以忽略，继续执行登录、绑定链账户和部署资源。执行成功后，`listResources` 应能看到 `payment.bcos3.HelloAuto0527a`、`payment.bcos3.HelloAuto0527b`、`payment.bcos3.HelloAuto0527c`。

### 7.5 日常启动

首次初始化完成后，日常通常只需要执行：

```powershell
cd <项目目录>
powershell -ExecutionPolicy Bypass -File backend\infra\open_all_pages.ps1
```

它会尝试：

- 重启 WeCross MySQL、Account-Manager、Router。
- 重启 WeCross WebApp 代理。
- 检查 WeBASE 是否可访问。
- 打开相关页面。

也可以单独重启 WeCross：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/wecross/restart_stack_wsl.sh restart"
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/wecross/restart_webapp_proxy_wsl.sh restart"
```

检查整体状态：

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

## 8. 服务器运行

如果需要部署到服务器，请使用 `deploy/server/`。

### 8.1 Linux 服务器

进入项目根目录后执行：

```bash
cd deploy/server
bash install_and_run.sh same-host
```

如果区块链与跨链服务在另一台机器：

```bash
cd deploy/server
bash install_and_run.sh remote-chain
```

预期结果：

- Docker 构建并启动前后端容器。
- 访问 `http://<server-ip>:8080` 能打开系统页面。
- 访问 `http://<server-ip>:5000/api/health` 返回 `ok: true`。

### 8.2 Windows Docker

```powershell
cd <项目目录>\deploy\server
.\install_and_run.ps1 -EnvTemplate same-host
```

如果区块链与跨链服务在另一台机器：

```powershell
cd <项目目录>\deploy\server
.\install_and_run.ps1 -EnvTemplate remote-chain
```

### 8.3 配置文件

首次启动时会生成：

```text
deploy/server/.env
```

常用配置：

```env
FRONTEND_PUBLIC_PORT=8080
BACKEND_PUBLIC_PORT=5000
HOST=0.0.0.0
PORT=5000
DATA_DIR=/app/data
FISCO_RPC_HOST=host.docker.internal
FISCO_RPC_PORTS=20200,20201
WEBASE_WEB_BASE_URLS=http://host.docker.internal:5500
WEBASE_FRONT_BASE_URLS=http://host.docker.internal:5502/WeBASE-Front
WEBASE_GROUP_ID=group0
WECROSS_ROUTER_HOST=host.docker.internal
WECROSS_ROUTER_RPC_PORT=8250
WECROSS_ROUTER_P2P_PORT=25500
WECROSS_WEBAPP_URL=http://host.docker.internal:18250/
PROOF_SIGNING_KEY=change-this-before-production
```

上线前建议修改：

- `PROOF_SIGNING_KEY`
- FISCO 地址
- WeBASE 地址
- WeCross 地址
- 对外端口

### 8.4 查看状态和停止

Windows：

```powershell
cd <项目目录>\deploy\server
.\status.ps1
.\stop_and_remove.ps1
```

Linux：

```bash
cd deploy/server
bash status.sh
bash stop_and_remove.sh
```

## 9. 第一次完成一笔交易

为了理解系统，建议准备两个业务账号：

- 卖家账号：自己注册一个，例如 `seller01`
- 买家账号：自己注册另一个，例如 `buyer01`

这两个账号用于 Cross_Verse 业务页面。与此同时，使用方还需要具备联盟链平台访问权限，例如能打开 WeBASE-Front 查看区块、交易和回执。实际使用中，业务操作者可能就是链平台管理员，也可能由管理员先在链平台完成交易操作，再把对应 Transaction Hash 提供给业务操作者回填。

### 9.1 注册和登录

1. 打开系统首页。
2. 点击 `Sign Up`。
3. 输入用户名、密码、确认密码。
4. 点击 `Sign Up`。
5. 注册成功后会自动登录并进入 `买东西` 页面。

账号规则：

- 用户名长度 3 到 32 位。
- 用户名只能包含字母、数字、下划线。
- 密码至少 6 位。

### 9.2 卖家发布资产

卖家登录后：

1. 点击左侧菜单 `卖东西`。
2. 上传一张 100 KB 以内的图片；不上传也可以使用默认图。
3. 输入商品名称。
4. 输入价格。
5. 点击 `自动生成`，生成 `Hash`、`承诺`、`证书`。
6. 如果已经准备好链上交易哈希，填写 `assetTxHash`；如果本地自动链上交易环境已初始化，也可以留空，由后端自动生成。
7. 资产锚定所在链默认选择 `asset`。
8. 点击 `提交商品`。

预期结果：

- 页面提示商品信息已上传。
- 买家在 `买东西` 页面可以看到该商品。

重要说明：

- `Hash`、`承诺`、`证书` 是业务字段。
- `assetTxHash` 是链上交易哈希。手动模式下必须来自 WeBASE-Front 或其他链上查询工具；既可以是部署类交易，也可以是当前资产锚定合约调用产生的真实交易。
- 如果启用了默认的自动链上交易环境，`assetTxHash` 可以留空。后端会通过 WeCross Console 调用 `HelloAuto0527a` 资源生成真实链上交易，并自动回填该哈希。
- `assetTxHash` 一旦填写，格式必须是 `0x` 加 64 位十六进制字符。
- 后端会检查它是否真实存在、回执是否成功、是否已被使用。

### 9.3 买家购买资产

买家登录后：

1. 点击 `买东西`。
2. 找到卖家发布的商品。
3. 点击 `立即抢购`。
4. 在弹窗中确认商品信息。
5. 点击 `Submit`。

预期结果：

- 页面提示抢购成功。
- 商品从在售列表移除。
- 买家在 `买入交易` 页面看到订单。
- 卖家在 `卖出交易` 页面看到订单。
- 初始交易状态为 `1`。

### 9.4 交易状态说明

| 状态 | 含义 | 谁操作 |
| --- | --- | --- |
| `1` | 等待卖家提交分片信息 | 卖家 |
| `2` | 等待买家验证分片并提交收据审计哈希 | 买家 |
| `3` | 等待卖家提交质押哈希 | 卖家 |
| `4` | 等待买家提交支付哈希 | 买家 |
| `5` | 等待卖家提交内容提供哈希 | 卖家 |
| `6` | 等待买家确认完成或追责退款 | 买家 |
| `7` | 交易完成 | 无 |
| `8` | 追责退款完成 | 无 |
| `-1` | 交易终止 | 无 |

### 9.5 状态 1 到 2：卖家提交分片

卖家进入 `卖出交易`：

1. 点击订单的 `更新`。
2. 填写 `spiece`，至少 8 位。
3. 填写 `secretKey`，至少 12 位，并包含大写字母、小写字母和数字。
4. `pieceCom` 可以留空。
5. 点击 `确认`。

预期结果：

- 状态变为 `2`。
- 页面显示 `spiece` 和 `pieceCom`。
- 卖家需要把 `secretKey` 提供给买家。

### 9.6 状态 2 到 3：买家验证分片

买家进入 `买入交易`：

1. 点击订单的 `更新`。
2. 输入卖家提供的 `secretKey`。
3. 点击 `验证分片`。
4. 验证通过后填写收据审计 Transaction Hash。
5. 步骤链选择 `asset`。
6. 点击 `确认`。

预期结果：

- 状态变为 `3`。

### 9.7 状态 3 到 4：卖家提交质押哈希

卖家进入 `卖出交易`：

1. 点击订单的 `更新`。
2. 填写质押 Transaction Hash。
3. 步骤链选择 `payment`。
4. 点击 `确认`。

预期结果：

- 状态变为 `4`。

### 9.8 状态 4 到 5：买家提交支付哈希

买家进入 `买入交易`：

1. 点击订单的 `更新`。
2. 填写支付 Transaction Hash。
3. 步骤链选择 `payment`。
4. 点击 `确认`。

预期结果：

- 状态变为 `5`。

### 9.9 状态 5 到 6：卖家提交内容提供哈希

卖家进入 `卖出交易`：

1. 点击订单的 `更新`。
2. 填写内容提供 Transaction Hash。
3. 步骤链选择 `delivery`。
4. 点击 `确认`。

预期结果：

- 状态变为 `6`。

### 9.10 状态 6 到 7：买家确认完成

买家进入 `买入交易`：

1. 点击订单的 `更新`。
2. 交易结果选择 `交易完成`。
3. 步骤链选择 `delivery`。
4. 填写完成 Transaction Hash。
5. 点击 `确认`。

预期结果：

- 状态变为 `7`。
- 页面提示交易成功。

### 9.11 状态 6 到 8：买家追责退款

如果交易结果不符合预期，买家可以选择追责退款：

1. 点击订单的 `更新`。
2. 交易结果选择 `追责退款`。
3. 步骤链选择 `payment`。
4. 填写追责退款对应的 Transaction Hash。
5. 点击 `确认`。

预期结果：

- 状态变为 `8`。

## 10. Transaction Hash 从哪里来

系统中需要填写的链上哈希包括：

- `assetTxHash`
- `receipt`
- `stakeTx`
- `paymentTx`
- `consignTx`
- `completionTx`
- `refund`

### 10.1 先理解要复制哪个 hash

在 Cross_Verse 中需要复制的是链上交易的 `hash` 字段，也就是 Transaction Hash。不要复制区块哈希、合约地址、账户地址、业务商品 Hash 或回执里的其他字段。

每一步建议复制的 hash 如下：

| Cross_Verse 字段 | 页面步骤 | 建议来源链 | 复制内容 |
| --- | --- | --- | --- |
| `assetTxHash` | 卖家发布资产 | `asset` 资产链 | 资产存证、资产上架锚定或相关合约调用产生的交易 `hash` |
| `receipt` | 买家提交收据审计 | `asset` 资产链 | 收据审计合约调用产生的交易 `hash` |
| `stakeTx` | 卖家提交质押 | `payment` 结算链 | 质押合约调用产生的交易 `hash` |
| `paymentTx` | 买家提交支付 | `payment` 结算链 | 支付合约调用产生的交易 `hash` |
| `consignTx` | 卖家提交内容提供 | `delivery` 对应链路 | 内容提供、内容确认或相关合约调用产生的交易 `hash` |
| `completionTx` | 买家确认交易完成 | `delivery` 对应链路 | 交易完成确认合约调用产生的交易 `hash` |
| `refund` | 买家追责退款 | `payment` 结算链 | 追责、退款或索赔合约调用产生的交易 `hash` |

如果当前环境暂时只有一条本地链，也仍然要为不同步骤选择不同的真实交易 `hash`；不要把同一个 hash 反复填入多个步骤。正式两条联盟链部署时，应由管理员根据本单位链路规划，把 `asset`、`payment`、`delivery` 映射到真实的联盟链和链上合约。

### 10.2 通过 WeBASE-Front 页面复制

以下步骤适合使用方已经能访问 WeBASE-Front 的情况：

1. 打开 `http://127.0.0.1:5502/WeBASE-Front`。
2. 如果页面要求登录，使用链平台管理员账号登录。
3. 在节点或群组列表中确认当前查看的是目标链和目标群组，例如 `group0`。
4. 进入区块浏览、区块列表、交易列表或类似页面。
5. 先查看最新区块高度，确认链正在出块或已有交易记录。
6. 打开最新区块，查看该区块中的 `transactions` 或交易列表。
7. 找到与你刚才执行的链上动作对应的交易记录。
8. 复制该交易记录的 `hash` 字段，格式应类似 `0x` 加 64 位十六进制字符。
9. 回到 Cross_Verse 对应页面，把该 hash 粘贴到当前步骤的 Transaction Hash 输入框。
10. 选择对应步骤链，例如资产上架和收据审计选 `asset`，质押和支付选 `payment`，内容提供和完成选 `delivery`。
11. 点击 `确认` 或 `提交商品`。

如何判断复制的是正确字段：

- 正确：交易详情里的 `hash`、`transactionHash` 或交易列表中的交易哈希。
- 不要复制：`blockHash`、`parentHash`、`contractAddress`、账户地址、商品业务 `Hash`。
- 格式检查：必须满足 `0x` 加 64 位十六进制字符。

### 10.3 每一步具体怎么复制和回填

资产上架 `assetTxHash`：

1. 管理员在资产链执行资产存证、资产上架锚定或相关合约调用。
2. 在 WeBASE-Front 中打开资产链对应群组。
3. 找到该链上动作产生的交易记录。
4. 复制交易记录的 `hash`。
5. 回到 Cross_Verse 的 `卖东西` 页面。
6. 将该 hash 填入 `链上锚定交易哈希(assetTxHash)`。
7. `资产锚定所在链(assetChain)` 选择 `asset`。
8. 点击 `提交商品`。

收据审计 `receipt`：

1. 买家完成分片验证后，由管理员或买家在资产链提交收据审计相关交易。
2. 在 WeBASE-Front 中打开资产链对应群组。
3. 找到收据审计交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `买入交易` 页面。
6. 在状态 `2` 的更新弹窗中填入收据审计 Transaction Hash。
7. 步骤链选择 `asset`。
8. 点击 `确认`，预期状态进入 `3`。

质押 `stakeTx`：

1. 卖家或管理员在结算链提交质押相关交易。
2. 在 WeBASE-Front 中打开结算链对应群组。
3. 找到质押交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `卖出交易` 页面。
6. 在状态 `3` 的更新弹窗中填入质押 Transaction Hash。
7. 步骤链选择 `payment`。
8. 点击 `确认`，预期状态进入 `4`。

支付 `paymentTx`：

1. 买家或管理员在结算链提交支付相关交易。
2. 在 WeBASE-Front 中打开结算链对应群组。
3. 找到支付交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `买入交易` 页面。
6. 在状态 `4` 的更新弹窗中填入支付 Transaction Hash。
7. 步骤链选择 `payment`。
8. 点击 `确认`，预期状态进入 `5`。

内容提供 `consignTx`：

1. 卖家或管理员在内容提供对应链路提交内容提供、内容确认或相关合约交易。
2. 在 WeBASE-Front 中打开对应群组。
3. 找到内容提供相关交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `卖出交易` 页面。
6. 在状态 `5` 的更新弹窗中填入内容提供 Transaction Hash。
7. 步骤链选择 `delivery`。
8. 点击 `确认`，预期状态进入 `6`。

交易完成 `completionTx`：

1. 买家确认内容无误后，在内容提供或结算相关链路提交交易完成确认。
2. 在 WeBASE-Front 中打开对应群组。
3. 找到完成确认交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `买入交易` 页面。
6. 在状态 `6` 的更新弹窗中选择 `交易完成`。
7. 填入完成 Transaction Hash。
8. 步骤链选择 `delivery`。
9. 点击 `确认`，预期状态进入 `7`。

追责退款 `refund`：

1. 如果内容验证失败或交易出现争议，买家或管理员在结算链提交追责、退款或索赔相关交易。
2. 在 WeBASE-Front 中打开结算链对应群组。
3. 找到追责退款相关交易。
4. 复制交易 `hash`。
5. 回到 Cross_Verse 的 `买入交易` 页面。
6. 在状态 `6` 的更新弹窗中选择 `追责退款`。
7. 填入追责退款 Transaction Hash。
8. 步骤链选择 `payment`。
9. 点击 `确认`，预期状态进入 `8`。

### 10.4 通过接口复制

查看最新块高：

```powershell
curl.exe -s "http://127.0.0.1:5502/WeBASE-Front/group0/web3/blockNumber"
```

查看某个区块详情：

```powershell
curl.exe -s "http://127.0.0.1:5502/WeBASE-Front/group0/web3/blockByNumber/10?fullTrans=true"
```

返回内容中重点看：

- `transactions`
- 每条交易里的 `hash`

如果想直接筛出交易 hash，可以先把区块详情复制到格式化工具中查看，也可以在 PowerShell 中人工查找 `hash` 字段。确认后只复制交易对象中的 `hash` 值，不复制区块对象中的 `hash`。

### 10.5 填写规则

- 必须是 `0x` 加 64 位十六进制字符。
- 必须是真实存在的链上交易。
- 回执状态必须成功。
- 同一笔交易流程中不要重复使用同一个哈希。
- 步骤链要与业务步骤匹配，例如收据审计选 `asset`，质押和支付选 `payment`，内容提供和完成选 `delivery`。

## 11. API 速查

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/health` | 后端健康检查 |
| `GET` | `/api/infra/status` | 基础设施状态 |
| `GET` | `/api/infra/tx-binding-config` | 交易哈希绑定配置 |
| `POST` | `/api/auth/login` | 登录 |
| `POST` | `/api/auth/logout` | 登出 |
| `GET` | `/api/accounts?username=xxx` | 查询账号 |
| `POST` | `/api/accounts` | 注册账号 |
| `GET` | `/api/onsale` | 查询在售资产 |
| `POST` | `/api/onsale` | 发布资产 |
| `GET` | `/api/onsale/{id}/proof` | 查看资产证明 |
| `POST` | `/api/trades` | 创建交易 |
| `GET` | `/api/trades?role=buyer` | 查询买入交易 |
| `GET` | `/api/trades?role=seller` | 查询卖出交易 |
| `POST` | `/api/trades/{productID}/verify-piece` | 验证分片密钥 |
| `GET` | `/api/trades/{productID}/turn` | 查询下一步操作人 |
| `POST` | `/api/trades/{productID}/update` | 推进交易状态 |
| `DELETE` | `/api/trades/{productID}?actor=xxx` | 终止交易 |

需要登录的接口必须带请求头：

```text
Authorization: Bearer <登录后返回的 token>
```

登录成功后返回值中会包含：

- `token`
- `tokenExpiresInSec`

默认 token 有效期是 12 小时，可通过 `TOKEN_TTL_SECONDS` 调整。

## 12. 数据保存位置

源码运行时，后端默认保存到：

```text
backend/service/data/users.json
backend/service/data/onsale.json
backend/service/data/trades.json
```

桌面程序会保存到当前系统用户的应用数据目录。Windows 通常位于：

```text
%LOCALAPPDATA%\CrossVerse\data
```

长期运行建议：

- 使用数据库替代 JSON 文件。
- 设置强随机 `PROOF_SIGNING_KEY`。
- 配置 HTTPS、反向代理、访问控制和备份策略。
- 不要在公开环境复用默认密钥、样例账号或样例哈希。

## 13. 常见问题

### 13.1 前端打不开

现象：

- `http://127.0.0.1:8080/` 无法访问。
- 浏览器提示连接失败。

处理：

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

如果 `npm install` 报权限或缓存问题：

```powershell
cd <项目目录>\frontend
npm config set cache .npm-cache --location=project
cmd /c rmdir /s /q node_modules
npm install
```

### 13.2 后端不可用

现象：

- 登录时报后端不可用。
- `http://127.0.0.1:5000/api/health` 无法访问。

处理：

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

如果提示缺少 Flask：

```powershell
cd <项目目录>\backend\service
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py
```

### 13.3 端口被占用

检查 `5000`：

```powershell
netstat -ano | findstr :5000
```

检查 `8080`：

```powershell
netstat -ano | findstr :8080
```

处理：

- 关闭占用端口的程序。
- 或修改对应服务端口后重新启动。

### 13.4 `/api/infra/status` 返回 `ok: false`

按顺序检查：

1. FISCO 端口 `20200`、`20201`。
2. WeBASE 地址 `5500`、`5502`。
3. WeCross 端口 `8250`、`25500`、`8340`。
4. WeCross WebApp 地址 `18250`。

命令：

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

重启 WeCross：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/wecross/restart_stack_wsl.sh restart"
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; bash backend/infra/wecross/restart_webapp_proxy_wsl.sh restart"
```

说明：

- `8250` 返回 `404` 不一定异常，端口可连通常表示 Router 存活。
- `8340` 返回 `400` 不一定异常，端口可连通常表示 Account-Manager 存活。

### 13.5 `assetTxHash` 格式错误

现象：

```text
assetTxHash must be a tx hash like 0x + 64 hex
```

处理：

- 如果发布资产时没有手动填写 `assetTxHash`，通常是自动链上交易没有生成出真实哈希。请确认 `~/crossverse/wecross/WeCross/WeCross-Console` 存在，`autogrow_bot / 123456` 能登录，并且 `listResources` 能看到 `payment.bcos3.HelloAuto0527a`。
- 确认以 `0x` 开头。
- 确认后面是 64 位十六进制字符。
- 不要填写商品业务 `Hash`、文件摘要或普通字符串。

### 13.6 `assetTxHash` 在链上不存在

可能原因：

- 哈希不是链上交易哈希。
- WeBASE-Front 没有启动。
- 选择的链不正确。

处理：

- 从 `http://127.0.0.1:5502/WeBASE-Front` 重新复制真实交易哈希。
- 检查 `/api/infra/status` 中 `webase_front` 是否为 `true`。
- 确认上架时选择的链为正确链。

### 13.7 哈希已被使用

现象：

```text
tx hash is already used
```

处理：

- 为每个步骤准备不同的真实 Transaction Hash。
- 不要在同一笔交易或不同交易中重复使用同一个哈希。

### 13.8 状态流转错误

现象：

```text
invalid status transition
```

处理：

- 查看当前状态数字。
- 按第 9.4 节状态表确认当前应该由谁操作。
- 用正确角色账号进入对应页面操作。

### 13.9 分片验证失败或返回 `429`

可能原因：

- 买家输入的 `secretKey` 不正确。
- 连续错误次数过多，触发临时锁定。

处理：

- 向卖家确认完整 `secretKey`，注意大小写和空格。
- 如果响应中有 `retryAfterSec`，等待锁定时间结束后再试。
- 卖家提交分片时建议让 `pieceCom` 留空，由后端计算。

### 13.10 WSL 脚本出现 `$'\r': command not found`

原因：

- Shell 脚本是 Windows CRLF 行尾。

处理：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd <项目WSL目录>; dos2unix backend/infra/fisco-bcos-3/setup_wsl.sh backend/infra/webase-3/setup_wsl.sh backend/infra/wecross/*.sh"
```

### 13.11 WeBASE 返回 502

处理：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "cd ~/crossverse/webase3/WeBASE/deploy; env JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 python3 deploy.py startAll"
```

然后检查：

```powershell
wsl -d Ubuntu-22.04 -- bash -lc "ss -lnt | grep -E ':5500|:5502|:5001|:5004'"
```

### 13.12 Docker 页面能打开但接口失败

处理：

- 检查 `deploy/server/.env` 中的 `WEBASE_FRONT_BASE_URLS`、`FISCO_RPC_HOST`、`WECROSS_ROUTER_HOST`。
- 同机部署优先使用 `host.docker.internal`。
- 远程链服务填写真实 IP。
- 修改 `.env` 后重启容器。

```powershell
cd <项目目录>\deploy\server
docker compose -f docker-compose.yml --env-file .env up -d --build
```

## 14. 未来工作

当前版本要求使用方手动进入 WeBASE-Front 或相关链平台，完成底层链上操作后复制 Transaction Hash，再回填到 Cross_Verse。这个方式便于审计和理解链上凭证来源，但对普通业务用户仍然不够友好。

后续可引入 AI Agent 作为区块链底层操作代理，让系统从“用户手动查链和复制 hash”升级为“用户确认业务意图，Agent 自动协助完成链上操作”。规划方向包括：

- Agent 根据当前交易状态判断下一步应操作资产链还是结算链。
- Agent 自动调用对应链平台、合约或中间件接口，完成资产锚定、收据审计、质押、支付、内容提供确认、交易完成或追责退款。
- Agent 自动等待链上回执，确认交易成功后把正确的 Transaction Hash 写回 Cross_Verse。
- Agent 自动校验 hash 是否属于正确链、正确合约、正确方法和正确业务订单。
- Agent 在用户界面中解释每一步链上操作的含义，让业务用户不需要理解区块高度、回执、合约方法等底层细节。
- 管理员仍保留审批、密钥管理、权限控制和审计追踪能力，避免自动化代理越权操作。

目标是让最终用户只需要表达“我要发布资产”“我要确认支付”“我要完成交易”这类业务意图，底层跨链调用、交易确认和 hash 回填由 AI Agent 协助完成，从而提升系统易用性和可落地性。

## 15. 贡献方式

如果你希望为 `Cross_Verse` 提交改进，建议先阅读贡献说明：

- [CONTRIBUTING.md](./CONTRIBUTING.md)

仓库已补充 Gitee 的 Issue / Pull Request 模板，适合提交以下类型的改动：

- 文档修正与部署说明完善
- 自动化测试与校验脚本增强
- 不改变现有业务逻辑的兼容性修复
- 开源治理与协作流程改进

## 附录 A. 构建程序

### A.1 构建前端

```powershell
cd <项目目录>\frontend
npm install
npm run build
```

预期结果：

- 生成 `frontend/dist/`。
- 后端可通过 `http://127.0.0.1:5000` 直接提供构建后的前端页面。

### A.2 构建 Windows 桌面程序

```powershell
cd <项目目录>\frontend
npm install
npm run build

cd <项目目录>\backend\service
.\start_backend.ps1
.\build_launcher.ps1
```

如果已有程序正在运行：

```powershell
.\build_launcher.ps1 -StopRunningLauncher
```

预期结果：

- 在本地生成 `releases/apps/windows/CrossVerse.exe`。
- 在本地生成 `releases/apps/windows/CrossVerseLauncher.exe`。

### A.3 构建 Linux 桌面程序

```bash
cd <项目目录>
bash backend/service/build_launcher_linux.sh
```

预期结果：

- 在本地生成 `releases/apps/linux/CrossVerse`。
- 在本地生成 `releases/apps/linux/CrossVerseLauncher`。