# wgSysteam

**Repository Path**: phper-thinkPack/wg-systeam

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Binance 等差网格交易系统

供单一系统所有者管理的 Laravel 应用。支持 Binance Spot 现货与 USDⓈ-M USDT 永续合约，策略按 `market_type × mode × symbol` 隔离；同一组合最多一个活跃策略。`paper` 是默认模式，使用本地数据，不访问 Binance。`testnet` 和 `live` 各使用独立凭据。**实盘路径没有使用真实密钥、真实资产或生产数据库验收；不要直接启用实盘。**

## 架构

- PHP 8.3+、Laravel 13、MySQL 8、Redis、Composer 锁文件。价格、数量、手续费和盈亏使用十进制字符串、BCMath 与数据库 `DECIMAL(36,18)`。
- 浏览器只发管理动作。独立队列提交订单，定时进程检查风控与对账，独立私有 WebSocket 进程接收成交。页面读取带更新时间的数据库快照。
- `SpotGateway`、`UsdmGateway` 将引擎与 Binance 隔开；paper、testnet、live 共用对应市场的规划与风控。paper 网关只读写本地数据库。
- Spot 只使用预先分配的现货资产，不自动买入底仓。USDⓈ-M 只接受 USDT 永续、单向持仓、逐仓、关闭自动追加保证金、明确杠杆及事先授权的紧急减仓。
- USDⓈ-M 的 `USDM_MAX_MAINT_MARGIN_RATIO` 是账户级 `totalMaintMargin / totalMarginBalance` 上限，默认 `0.50`；达到阈值时停止新增开仓并进入风险处理。
- 所有者可在“账户风险上限”按市场和模式设置最大投入及合约仓位、名义价值、保证金、杠杆上限；live 必须先配置，paper/testnet 未配置则只受策略自身上限约束。账户金额以 USDT 计，设置 Spot 上限后该模式只允许 USDT 计价交易对。
- 网关只放行代码列举的 `/api/v3` Spot 与 `/fapi/v1` 至 `/fapi/v3` USDⓈ-M 具体接口；没有通用 URL 代理或划转、充值、提现路径。

状态机、表与资金口径见 [架构说明](docs/ARCHITECTURE.md)，另外有 [权限矩阵](docs/PERMISSIONS.md)、[运行手册](docs/OPERATIONS.md) 和 [实盘人工验收](docs/LIVE_ACCEPTANCE.md)。

## Docker Compose 本地启动

复制 `.env.example` 为 `.env`，复制 `.env.mysql.example` 为 `.env.mysql`。在两个本地文件中分别设置非空 `DB_PASSWORD` 与 `MYSQL_ROOT_PASSWORD`；MySQL root 密码不会传给应用容器。保持 `TRADING_MODE=paper` 和所有 live 开关为 `false`。不要提交环境文件，也不要在命令行或对话里填写交易密钥。

```bash
docker compose build
docker compose run --rm --no-deps app php artisan key:generate --show
```

把上一步生成的 `base64:...` 值只填入**本机** `.env` 的 `APP_KEY`，不要发到对话或提交仓库。然后运行：

```bash
docker compose up -d mysql redis app web queue scheduler
docker compose exec app php artisan migrate --force
docker compose exec app php artisan owner:init --email=owner@example.com --name=Owner
docker compose exec app php artisan paper:spot-seed --price=20000 --base=1 --quote=1000
docker compose exec app php artisan paper:usdm-seed --price=20000 --usdt=1000 --leverage=1
```

管理员命令在终端安全地交互读取密码。Web 入口是 `http://127.0.0.1:8000`；首次登录后设置 TOTP。Compose Web 端口只绑定到回环地址。现货和期货的模拟 `USDT` 钱包严格分开。

模拟行情不会自动前进。使用命令推进本地价格和资金费：

```bash
docker compose exec app php artisan paper:spot-price BTCUSDT 19900
docker compose exec app php artisan paper:usdm-price BTCUSDT 19900 --liquidity=0.01
docker compose exec app php artisan paper:usdm-funding BTCUSDT 0.0001
```

种子命令默认读取 `resources/paper` 中**合成示例过滤器**，不是 Binance 实时规则；`--file=...` 可指定自己的合成 JSON。已有策略历史时无法悄悄重置钱包。其他币种须先提供对应的完整模拟过滤器。

## 非 Docker 安装与进程

安装 PHP 8.3+（`bcmath`、`pdo_mysql`、`redis`、`mbstring`、`pcntl`、`zip`）、MySQL、Redis 和 Composer 2。Web 服务器根目录指向 `public/`，数据库用户仅获本应用数据库的必要权限。安装及启动：

```bash
composer install --no-interaction --prefer-dist
cp .env.example .env
php artisan key:generate
php artisan migrate --force
php artisan owner:init --email=owner@example.com --name=Owner
php artisan queue:work redis --queue=trading,default --sleep=1 --tries=1 --timeout=60
php artisan schedule:work
```

队列、调度和私有数据流必须作为独立受监控进程运行。示例在 `deploy/processes/supervisor.conf`。Testnet 监听需要各自独立密钥和显式启动：`php artisan trading:listen-spot testnet`、`php artisan trading:listen-usdm testnet`。Compose 的 `testnet` profile 也须人工显式启用；没有测试网密钥时无需启动它们。更多见 [运行手册](docs/OPERATIONS.md)。

## 管理和测试

界面提供健康、行情与余额、策略、网格、订单、成交、收益、风险和审计。新策略先预览占用与订单，再启动时重新预检；暂停或停止后恢复需先对账。常用命令：

```bash
php artisan trading:diff paper
php artisan trading:reconcile-spot paper
php artisan trading:reconcile-usdm paper
php artisan trading:diagnostics paper
php artisan test
vendor/bin/pint --test
```

`trading:resolve-risk` 需要操作者和原因，记录审计且不会自动恢复交易。回测命令与模型说明见 [运行手册](docs/OPERATIONS.md)；模拟收益不能视作收益承诺。

离线 CSV 示例（只读取 `resources/paper/sample-btcusdt.csv` 和合成过滤器）：

```bash
php artisan paper:backtest resources/paper/sample-btcusdt.csv --market=spot --lower=18000 --upper=23000 --grids=5 --qty=0.01 --max-investment=1500 --max-orders=5 --base=0.021 --quote=1000
php artisan paper:backtest resources/paper/sample-btcusdt.csv --market=usdm --lower=18000 --upper=23000 --grids=5 --qty=0.01 --max-investment=3000 --max-orders=5 --usdt=3000 --direction=long --leverage=1 --stop=17000
```

本地终端默认 `php` 是 7.4，开发验证使用 `C:\Temp\php85.exe artisan test`。当前环境没有 MySQL 或 Docker 服务，也没有测试网密钥，因此容器启动、MySQL 迁移、测试网下单和实盘路径均尚未在这里运行。实盘配置默认关闭。

2026-10-08 本地验收：PHP 8.5、SQLite 临时数据库完成迁移；自动化测试 **109 项、624 次断言全部通过**；`vendor/bin/pint --test`、`composer validate --no-check-publish`、`artisan route:list`、`artisan view:cache`、`artisan schedule:list` 与 `git diff --check` 通过。MySQL 行锁并发、Redis 队列、Docker 容器和 Binance 测试网仍须在对应环境验收。

## Binance 官方文档核查

核查日期：2026-10-08。Spot REST 使用显式 `/api/v3` 白名单与实时过滤器；用户数据流采用 WebSocket API `userDataStream.subscribe.signature`，并用 `executionReport` 与 REST 补查核对。官方说明 5xx 与超时后订单状态可能未知，429 要按 `Retry-After` 退避，418 须停止请求。Spot 测试网可能重置全部订单和余额。USDⓈ-M 通用规则确认了正式与测试网地址、签名与毫秒时间戳、请求权重和订单计数；其公开定义确认了单向仓位 `BOTH`、`PERPETUAL`、价格与数量过滤器、百分比价格、最小名义金额及最大订单数。网关只调用代码白名单列出的 `/fapi/v1` 至 `/fapi/v3` 交易、账户、仓位和用户流接口。USDⓈ-M 对执行状态未知的 503 应先核查订单，不能直接重发。

- [Spot REST 总则](https://developers.binance.com/en/docs/products/spot/rest-api)、[过滤器](https://developers.binance.com/en/docs/products/spot/filters)、[用户数据流](https://developers.binance.com/en/docs/products/spot/user-data-stream)
- [Spot 交易接口](https://developers.binance.com/en/docs/catalog/core-trading-spot-trading/api/rest-api/trade)、[账户接口](https://developers.binance.com/en/docs/catalog/core-trading-spot-trading/api/rest-api/account)、[Spot Testnet](https://developers.binance.com/en/docs/products/spot/testnet/general-info)、[WebSocket 签名订阅](https://developers.binance.com/en/docs/catalog/core-trading-spot-trading/api/ws-api/user-data-stream)
- [USDⓈ-M 通用规则](https://developers.binance.com/en/docs/products/derivatives-trading-usds-futures/general-info)、[公开定义与过滤器](https://developers.binance.com/en/docs/products/derivatives-trading-usds-futures/common-definition)、[交易接口](https://developers.binance.com/en/docs/catalog/core-trading-derivatives-trading-usd-s-m-futures/api/rest-api/trade)、[账户接口](https://developers.binance.com/en/docs/catalog/core-trading-derivatives-trading-usd-s-m-futures/api/rest-api/account)、[用户数据流](https://developers.binance.com/en/docs/products/derivatives-trading-usds-futures/user-data-streams)

## 已知限制

目标环境还需 MySQL、队列、进程重启、Binance 测试网与人工风控验收。模拟撮合只在价格严格越过挂单价后成交；K 线内路径未知时不能据此推断真实顺序。纸盘合约在逐仓权益不高于当前维护保证金时优先执行**近似强平**：按不利滑点归零仓位，保守没收剩余逐仓保证金，撤销自有普通订单，记录收入、风险和保护单终止原因，策略转待核对。若维护保证金档位不可用，则保留仓位并冻结新增订单。合成保护单与近似强平的结果都不伪装为普通 `fills`。此模型不等于 Binance 强平引擎，纸盘不模拟 ADL。实盘开启前必须执行 [人工验收](docs/LIVE_ACCEPTANCE.md)。