feat

README.md

@@ -1,3 +1,84 @@
 # coin
 
-coin quant trade 
+基于 **Binance 现货 USDT** 的定时轮询量化服务：按配置多标的运行，使用 Postgres 持久化持仓状态，策略在 `internal/logic` 中实现。
+
+## 功能概览
+
+- **入口**：`cmd/main/main.go` 加载配置、初始化 DB/Redis、`go logic.Boot()` 启动策略协程，主线程跑 Gin HTTP（端口见配置 `Port`）。
+- **策略**：`logic.runBinanceSpotStrategy` 每 `pollInterval`（默认 60s）拉账户余额与批量现价，对 `SpotWatchList` 中每个交易对执行决策并写回 `spot_positions`。
+- **无 WebSocket**：全部为 REST 轮询，实现简单、对网络抖动相对不敏感，但成交与价格存在轮询间隔内的滞后。
+
+## 配置说明
+
+配置文件见 `etc/coin_<env>.yaml`（由 bsm-sdk `conf.New` 按服务名加载），与策略相关的字段包括：
+
+| 字段 | 含义 |
+|------|------|
+| `BinanceApiKey` / `BinanceApiSecret` | 现货 API；需在 Binance 开启**现货交易**权限 |
+| `SpotWatchList` | 标的列表；为空则跳过整个现货策略 |
+| `SpotWatchList[].Symbol` | 交易对，如 `BTCUSDT` |
+| `SpotWatchList[].OrderQty` | 每次**开仓**与**加仓**买入的**基础币数量**（按 LOT_SIZE 向下取整） |
+| `Databases` / `Cache` | 由 `impl.NewImpl` 初始化，供迁移与其它模块使用 |
+
+## 策略逻辑（按执行顺序）
+
+对配置中每个 `Symbol`，在单次轮询内大致顺序如下（详见 `spot_binance.go` 的 `processOne`）。
+
+### 1. 空仓（持仓市值 &lt; `minHoldUSDT`，默认 10 USDT）
+
+- 重置：`DipAddsDone`、`DipLegLocked`、跟踪止盈状态、`OpenReboundLow` 等。
+- **反弹过滤**：用 `OpenReboundLow` 记录阶段低价；价格**持续创新低**时不买；现价相对该低点**反弹 ≥ `buyReboundPct`（0.39%）** 后才允许首买。
+- 按 `OrderQty` 取整后下**市价买单**（`Quantity`），更新加权成本与数量。
+
+### 2. 有仓
+
+- 若本地成本未写过（如手工划转），用当前价初始化 `AvgCostUSDT`。
+- **分档超跌加仓**（相对**当前加权均价**，每档最多一次，且需反弹与波段锁）：
+  - 第 1～4 次加仓对应跌幅阈值：**5% / 15% / 30% / 50%**（`dipAddDrawdowns`）。
+  - 现价 ≤ `均价 × (1 − 当前档跌幅)` 时进入该档观察；同样用 `DipReboundLow` 要求**先反弹 ≥ `buyReboundPct`** 再下单。
+  - 每次加仓后 `DipLegLocked`，需现价 ≥ `均价 × (1 + dipRecoverPct)`（默认 3%）才解锁，避免同一低位反复买。
+  - `DipAddsDone == 4` 后不再加仓。
+- **跟踪止盈全平**：
+  - 浮盈 ≥ **`profitArmPct`（5%）** 后进入跟踪，记录阶段最高价；**不在刚达 5% 时直接卖**。
+  - 现价从跟踪最高价回撤 ≥ **`trailPullbackPct`（0.5%）** 时，**市价卖出全部可用基础币**（按 LOT 取整，且名义需 ≥ `minSellNotional`）。
+
+### 3. 常量一览（改代码后需重新编译）
+
+| 常量 | 默认值 | 说明 |
+|------|--------|------|
+| `pollInterval` | 60s | 轮询周期 |
+| `minHoldUSDT` | 10 | 低于视为空仓 |
+| `buyReboundPct` | 0.39% | 开/加仓前相对阶段低点的最小反弹 |
+| `maxDipAdds` | 4 | 最大加仓次数 |
+| `dipAddDrawdowns` | 5%,15%,30%,50% | 各次加仓相对均价的跌幅门槛 |
+| `dipRecoverPct` | 3% | 加仓后解锁下一档所需相对均价的涨幅 |
+| `profitArmPct` | 5% | 开始跟踪高点的浮盈线 |
+| `trailPullbackPct` | 0.5% | 从跟踪高点回撤触发全平 |
+| `minSellNotional` | 10 USDT | 卖单名义过小则跳过 |
+
+## 数据表 `spot_positions`
+
+由 GORM 迁移（`models.SpotPosition`），按 `BaseAsset` 唯一一行，主要字段包括：均价、数量、加仓次数与锁、`TrailArmed` / `TrailPeakUSDT`、开/加仓反弹低点、`DipReboundLow` 等。策略重启后会从库加载到内存再继续。
+
+## 代码结构（策略相关）
+
+| 文件 | 职责 |
+|------|------|
+| `spot_binance.go` | 轮询入口、`processOne`、配置解析、反弹判断、分档跌幅表 |
+| `spot_binance_open.go` | 首买、分档加仓、市价买统一执行、成交更新成本 |
+| `spot_binance_close.go` | 跟踪止盈全平、`spotLotStep`、`formatQtyToLotStep` |
+| `spot_binance_account.go` | 精度、持仓加载/保存、余额解析 |
+
+## 运行
+
+```bash
+# 在正确 GOPATH / module 环境下
+go build -o coin.exe ./cmd/main
+./coin.exe
+```
+
+需保证配置中数据库、Binance 密钥与 `SpotWatchList` 正确；**实盘有资金风险**，请在测试网或小资金下验证后再使用。
+
+## 免责声明
+
+本仓库代码仅供学习与研究，不构成投资建议。使用本软件进行交易的一切损失由使用者自行承担。