feat: initial commit for wtfx orchestrator with 4 submodules

2026-08-30 23:19:11 +08:00
commit 09730b69bd
11 changed files with 627 additions and 0 deletions
@@ -0,0 +1,12 @@
+[submodule "wtf-contract"]
+	path = wtf-contract
+	url = http://152.32.146.53/wtfx/wtf-contract.git
+[submodule "wtf-backend"]
+	path = wtf-backend
+	url = http://152.32.146.53/wtfx/wtf-backend.git
+[submodule "wtf-frontend"]
+	path = wtf-frontend
+	url = http://152.32.146.53/wtfx/wtf-frontend.git
+[submodule "wtf-indexer"]
+	path = wtf-indexer
+	url = http://152.32.146.53/wtfx/wtf-indexer.git
@@ -0,0 +1,3 @@
+{
+    "wake.compiler.solc.remappings": []
+}
@@ -0,0 +1,24 @@
+# WTFX Protocol
+
+WTFX is a high-performance prediction market protocol powered by a multi-outcome Power LDA continuous bonding curve.
+
+## 仓库架构 (Architecture)
+
+本仓库为主仓（Orchestrator），采用 **Git Submodules** 统一管理各个独立核心模块：
+
+- `docs/`：规范文档、协作手册与部署指南
+- `wtf-contract/`：智能合约子仓（Solidity 0.8.29, PowerLDACurveV2, WTFMarketV2）
+- `wtf-backend/`：后端服务子仓（订单撮合、业务 API 与 WebSocket 网关）
+- `wtf-frontend/`：前端子仓（Next.js 高频交易终端与 TradingView 图表）
+- `wtf-indexer/`：索引器子仓（链上事件监听与 GraphQL 查询）
+
+## 快速克隆与协作 (Getting Started)
+
+```bash
+git clone http://152.32.146.53/wtfx/wtfx.git
+cd wtfx
+git submodule sync --recursive
+git submodule update --init --recursive
+```
+
+详细分支工作流与全栈蓝绿部署规范请参考 `docs/` 目录。
@@ -0,0 +1,99 @@
+# WTFX Gitea 代码托管与协作使用指南
+
+> **服务地址**：[http://152.32.146.53/](http://152.32.146.53/)  
+> **组织命名空间**：`wtfx`  
+> **协议支持**：HTTP (`http://152.32.146.53/...`) / SSH (`git@152.32.146.53:...`)
+
+---
+
+## 1. 仓库矩阵与访问地址
+
+WTFX 采用 **1 个主仓 (Orchestrator) + 4 个独立子仓 (Submodules)** 架构：
+
+| 仓库名称 | 模块定位 | HTTP 访问地址 | SSH 访问地址 |
+| :--- | :--- | :--- | :--- |
+| **主仓 (wtfx)** | 全栈调度与部署配置 | `http://152.32.146.53/wtfx/wtfx.git` | `git@152.32.146.53:wtfx/wtfx.git` |
+| **wtf-contract** | 智能合约核心库与联合曲线 | `http://152.32.146.53/wtfx/wtf-contract.git` | `git@152.32.146.53:wtfx/wtf-contract.git` |
+| **wtf-backend** | 业务服务、撮合与 WebSocket | `http://152.32.146.53/wtfx/wtf-backend.git` | `git@152.32.146.53:wtfx/wtf-backend.git` |
+| **wtf-frontend** | Web 高频交易终端与图表 | `http://152.32.146.53/wtfx/wtf-frontend.git` | `git@152.32.146.53:wtfx/wtf-frontend.git` |
+| **wtf-indexer** | 链上事件监听与 GraphQL 查询 | `http://152.32.146.53/wtfx/wtf-indexer.git` | `git@152.32.146.53:wtfx/wtf-indexer.git` |
+
+---
+
+## 2. 协作者快速切入与初始化
+
+开发者日常仅需拉取主仓并递归同步子仓即可，**无需手动配置各个子仓的 remote**。
+
+### 2.1 首次克隆完整项目
+```bash
+# 1. 克隆主仓
+git clone http://152.32.146.53/wtfx/wtfx.git
+cd wtfx
+
+# 2. 一键递归初始化所有子仓
+git submodule sync --recursive
+git submodule update --init --recursive
+```
+
+### 2.2 存量本地仓库切换至 Gitea
+若本地已有项目目录，切换远程源：
+```bash
+git remote set-url origin http://152.32.146.53/wtfx/wtfx.git
+git fetch origin
+git checkout develop && git pull origin develop
+git submodule sync --recursive
+git submodule update --init --recursive
+```
+
+> **注意**：必须先切到包含最新 `.gitmodules` 的分支（如 `develop` 或 `deploy`）再执行 `sync`，避免将 remote 回退。
+
+---
+
+## 3. 开发者权限与环境配置
+
+1. **登录平台**：访问 [http://152.32.146.53/](http://152.32.146.53/)。
+2. **配置 SSH 密钥（推荐）**：
+   - 点击右上角头像 $
+ightarrow$【个人设置】$
+ightarrow$【SSH / GPG 密钥】；
+   - 点击【增加密钥】，将本机 `~/.ssh/id_rsa.pub` 或 `~/.ssh/id_ed25519.pub` 公钥粘贴并保存。
+3. **界面语言设置**：
+   - 头像 $
+ightarrow$【个人设置】$
+ightarrow$【个人信息】$
+ightarrow$【语言与地区】选择「简体中文」。
+
+---
+
+## 4. 管理员配置与分支保护规范
+
+为保障生产环境绝对安全，管理员须在 Gitea 上完成以下设置：
+
+### 4.1 创建组织与子仓
+1. 点击右上角 `+` $
+ightarrow$【创建组织】命名为 `wtfx`；
+2. 在 `wtfx` 组织下创建对应的 5 个仓库（`wtfx`, `wtf-contract`, `wtf-backend`, `wtf-frontend`, `wtf-indexer`）；
+3. 在【组织设置】$
+ightarrow$【团队】中添加开发者团队并赋予读写（Write）权限。
+
+### 4.2 严格分支保护规则（必配）
+
+#### 1) 主仓 (`wtfx`)：
+- 进入仓库【设置】$
+ightarrow$【分支】$
+ightarrow$【分支保护规则】；
+- 对 **`deploy`** 分支添加保护：
+  - 勾选 **「启用分支保护」**；
+  - 勾选 **「禁止直接推送」**；
+  - 勾选 **「启用合并请求（Pull Request），禁止直接 Merge」**；
+  - 勾选 **「需要至少 1 位管理员 Review」**。
+
+#### 2) 各子仓 (`wtf-contract`, `wtf-backend`, `wtf-frontend`, `wtf-indexer`)：
+- 进入各个子仓【设置】$
+ightarrow$【分支】$
+ightarrow$【分支保护规则】；
+- 对 **`main`** 分支添加保护：
+  - 勾选 **「启用分支保护」**；
+  - 勾选 **「禁止直接推送（Force Push 亦禁止）」**；
+  - 勾选 **「必须通过合并请求（Pull Request）合并」**。
+- `develop` 分支**不设保护**，作为联调集成线允许团队自由 push/merge。
@@ -0,0 +1,161 @@
+---
+name: wtfx-git-collaboration
+description: WTFX 主仓+四大子仓（contract/backend/frontend/indexer）双环境分支协作与全栈蓝绿部署规范（唯一维护源）。涵盖 feature/develop/main 分工、A/A′ 测试策略、主仓指针更新、子仓 PR、管理员 release、全栈蓝绿部署（零停机切换）与秒级回滚机制。
+---
+
+# WTFX 分支协作与全栈蓝绿部署生产规范
+
+> **本 Skill 为 WTFX 分支协作与发布规范的唯一维护源**。命令速查与决策树详见 [reference.md](reference.md)。
+
+---
+
+## 1. 协作模型（必记）
+
+| 层级 | 测试环境 (Dev / Test) | 正式环境 (Prod / Mainnet) |
+| :--- | :--- | :--- |
+| **主仓分支** | `develop` → 部署到测试环境 | `deploy`（**严格保护，禁止直推，必须走 PR**） |
+| **各子仓 (4个)** | `feature/*` → `develop` | 仅 `main` 上已通过 PR 验收的内容 |
+| **部署触发** | push 主仓 `develop`（触发 dev-deploy） | PR 合入主仓 `deploy`（触发 prod-deploy **全栈蓝绿发布**） |
+
+- **仓库矩阵**：主仓 `wtfx` + 四个子仓（`wtf-contract`、`wtf-backend`、`wtf-frontend`、`wtf-indexer`）。
+- **主仓本质**：主仓每个分支记录的是各个子仓某个具体 commit 的 SHA（Git Submodule 指针）。
+- **子仓分支规范**：`feature/*` (开发) → `develop` (测试集成) → `main` (发布基准线)。
+- **子仓保护规则**：子仓 `develop` 不开启保护，可自由 merge/push 做联调；子仓 `main` **强制开启分支保护，严禁直推，必须走 PR**。
+
+---
+
+## 2. 核心铁律
+
+1. **源分支 A（`feature/*`）保持绝对纯净**：
+   - 永远从子仓 `main` 切出，只承载当前需求的改动；
+   - **严禁**把 `develop` 合入 A 分支（防止测试环境他人未完成代码污染生产 PR）。
+2. **上测试的唯一入口**：
+   - 变更必须 **merge 进子仓 `develop`**——无 migration 且无冲突时 **A** 直 merge；否则走 **A′** merge 进 develop。
+   - 禁止主仓指针直接挂 feature SHA 跳过子仓 develop。
+3. **A′ 测试隔离分支机制**：
+   - 从 A 切 `A′`（如 `feature/xxx-test-deploy`），在 A′ 上 merge `develop` 以对齐测试环境，再把 **A′ merge 进 develop**；
+   - A′ 上修复的 Bug **只能 cherry-pick 回 A**，严禁把 A′ 或 develop 整个 merge 回 A。
+   - **典型场景**：包含数据库 Migration 链版本对齐，或 A 直接 merge develop 会与他人正在测试的内容冲突。
+4. **何时可跳过 A′（A 直 merge develop）**：
+   - **同时**满足：(1) 本需求不含 DB migration；(2) A merge 进 `develop` 无冲突。
+5. **测试期间改动**：
+   - 只在 **A** 上改，改完再 merge 进 develop 并主仓 bump 指针。
+6. **生产发布的双重门禁（PR 过了之后的 Deploy 流程）**：
+   - **第一道门禁（子仓）**：子仓 A 对齐 `main` 后，发起 Gitea PR → `main`，经评审后合入；
+   - **第二道门禁（主仓）**：发布管理员在主仓从 `deploy` 切 `release/YYYY-MM-DD` 分支，将子仓指针更新到各自 `main` 尖端，发起主仓 PR → `deploy`；
+   - **触发正式部署**：主仓 PR 合并进入 `deploy` 后，自动触发 Gitea Actions 的 `prod-deploy` **全栈蓝绿发布流水线**。
+
+---
+
+## 3. 全栈蓝绿部署 (Blue-Green Deployment) 架构与实现
+
+针对高频预测市场（WTFX），**前端、后端、Indexer** 各自特性不同，必须实施差异化的蓝绿热切换方案，确保用户无感知、无交易中断、无链上数据丢包。
+
+### 3.1 蓝绿端口与服务矩阵 (Blue/Green Slots)
+
+| 服务组件 | 生产流量端口 (Caddy Upstream) | Blue 槽位 (当前) | Green 槽位 (新版待切) | 切换机制 |
+| :--- | :--- | :--- | :--- | :--- |
+| **前端 (Next.js)** | `wtfx.io` (443) | `127.0.0.1:3000` | `127.0.0.1:3002` | Caddy API 零停机重载上游端口 |
+| **后端 API/WS** | `api.wtfx.io` (443) | `127.0.0.1:8080` | `127.0.0.1:8082` | 平滑优雅停机 (Graceful Shutdown) |
+| **索引器 (Indexer)** | `indexer.wtfx.io` (443) | `127.0.0.1:4200` | `127.0.0.1:4202` | **主从 Worker 抢占锁 + 追高水位探针** |
+
+---
+
+### 3.2 各组件蓝绿切换核心设计
+
+#### 1) 前端（Next.js SSR / Static）蓝绿切换
+- **构建隔离**：在独立目录完成 `next build`，绿色槽位（如 `:3002`）独立启动并自检；
+- **探针验证**：脚本通过 `curl -f http://127.0.0.1:3002/health` 验证 HTML 渲染与静态资源状态；
+- **切流**：调用 Caddy Admin API（或热重载配置），瞬间将生产流量切至新槽位；旧槽位保留 2 分钟以承接存量缓存请求后关闭。
+
+#### 2) 后端（Go / Node / Rust 撮合与 API）蓝绿切换
+- **无状态 API**：绿色槽位（`:8082`）先完成 DB 预连接与缓存预热，通过 `/api/v1/health` 深度自检；
+- **WebSocket 长连接平滑过渡**：
+  1. Caddy 切流后，所有**新连接**直接路由到 Green 槽位；
+  2. Blue 槽位进入 `Graceful Shutdown` 模式，停止接受新请求，等待存量撮合/订单请求在 30 秒内处理完毕后安全断开。
+
+#### 3) 索引器（Indexer）链上状态与双写防爆设计（核心关键）
+> **难点**：Indexer 持续监听链上 RPC，若蓝绿两套服务同时向同一个数据库写事件，会引发**主键冲突/重复入库**；若直接停旧启新，追块期间又会导致 API 数据落后。
+
+- **双写防爆机制（Redis 分布式租约锁 / PG Advisory Lock）**：
+  - **查询层 (GraphQL/RPC)**：蓝绿两套均可提供只读查询；
+  - **写入层 (Ingestion Worker)**：采用分布式抢占锁。
+- **平滑切换 4 步法**：
+  1. **影子追高 (Shadow Sync)**：Green Indexer 启动，以只读/独立 schema 模式快速追赶链上最新区块高度；
+  2. **水位探针检查 (Lag Check)**：校验 Green 抓块水位与当前链上高度差 $\le 1$ 个区块；
+  3. **租约转移 (Lease Handoff)**：Blue Indexer 释放 Ingestion 锁并停止抓块，Green Indexer 立即接管 Ingestion 锁开始实时写入；
+  4. **流量切换**：Caddy 将 `indexer.wtfx.io` 的 GraphQL 查询流量无缝指向 Green 端口。
+
+---
+
+## 4. 蓝绿部署流水线执行流程 (6 步防爆)
+
+```
+[1. 识别当前槽位] ──> [2. 在闲置槽位拉起新版] ──> [3. 深度探活与追高检查]
+ (Blue 运行中)          (Green: 3002/8082/4202)       (Health Probe 200 OK)
+                                                          │
+                                                          ▼ (失败立即回滚)
+[6. 旧版本优雅停机] <── [5. Caddy 流量热切换] <── [4. 租约转移 (Indexer)]
+ (保留快照 5分钟)         (微秒级完成重定向)           (无锁冲突/无数据丢失)
+```
+
+---
+
+## 5. 开发者与管理员标准操作
+
+### 5.1 开启新需求与测试联调
+```bash
+# 1. 在子仓开发
+cd wtf-backend
+git checkout main && git pull origin main
+git checkout -b feature/xxx
+# ... 编码开发 ...
+git push -u origin feature/xxx
+
+# 2. 上测试环境
+git checkout develop && git pull origin develop
+git merge feature/xxx
+git push origin develop
+
+# 3. 主仓 bump develop 指针
+cd /path/to/wtfx
+git checkout develop && git pull origin develop
+cd wtf-backend && git fetch origin && git checkout develop && git pull origin develop && cd ..
+git add wtf-backend
+git commit -m "chore(test): sync wtf-backend develop pointer"
+git push origin develop
+```
+
+### 5.2 生产发布 (Deploy) 全栈蓝绿上线
+```bash
+# 1. 子仓完成 PR 合并进子仓 main (Gitea 界面操作)
+
+# 2. 管理员在主仓切 release 分支
+cd /path/to/wtfx
+git checkout deploy && git pull origin deploy
+git checkout -b release/2026-08-30
+
+# 3. 主仓同步 4 个子仓 main 尖端
+cd wtf-contract && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-backend  && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-frontend && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-indexer  && git fetch origin && git checkout main && git pull origin main && cd ..
+
+# 4. 提交并推送到 Gitea
+git add wtf-contract wtf-backend wtf-frontend wtf-indexer
+git commit -m "release: point deploy at submodules main 2026-08-30"
+git push -u origin release/2026-08-30
+
+# 5. Gitea 发起 PR: release/2026-08-30 -> deploy
+#    合并后自动触发【全栈蓝绿部署流水线】
+```
+
+### 5.3 生产秒级一键回滚 (Emergency Rollback)
+若上线后出现异常，管理员无需重启任何容器，直接在 Caddy / 主仓切回 Blue 槽位：
+```bash
+cd /path/to/wtfx
+git checkout deploy
+git revert HEAD -m "revert: emergency rollback to previous slot"
+git push origin deploy
+# ---> Caddy 瞬间重载流量回上一个蓝槽位端口
+```
@@ -0,0 +1,177 @@
+---
+name: wtfx-git-collaboration
+description: WTFX 主仓+四大子仓（contract/indexer/backend/frontend）双环境分支协作与全栈蓝绿部署规范。涵盖 feature/dev/main 分工、A/A′ 测试策略、Submodule 指针管理、Gitea PR 与 Caddy 生产拓扑、生产发布与回滚安全机制。
+---
+
+# WTFX 研发协作与全栈蓝绿部署生产规范 (WTFX Production Release & Safety Specification)
+
+> 本文档融合了 Git Submodules 多仓架构、双环境自动化部署（Dev/Prod）、A/A′ 测试隔离体系、Caddy/Gitea 服务拓扑以及**全栈蓝绿部署（零停机切换）与秒级回滚机制**。
+
+---
+
+## 1. 仓库与环境全景
+
+### 1.1 仓库划分（1 个主仓 + 4 个子仓）
+Gitea 服务地址：`http://152.32.146.53/`（组织名：`wtfx`）
+
+| 仓库名称 | 目录名 | 语言/技术栈 | 职责范围 |
+| :--- | :--- | :--- | :--- |
+| **主仓 (Orchestrator)** | `wtfx` | Shell / Gitea Actions | 统一调度，管理 4 个 Submodule 指针与环境部署 |
+| **合约子仓** | `wtf-contract` | Solidity 0.8.29 / Foundry | 核心联合曲线、预测市场、Controller 与多代币标准 |
+| **索引器子仓** | `wtf-indexer` | Node.js / Envio / Ponder / Go | 链上事件监听、RPC 抓取、状态持久化与 GraphQL 暴露 |
+| **后端子仓** | `wtf-backend` | Go / Node.js / Rust | 业务逻辑、订单/预测撮合、用户鉴权、WebSocket 推送 |
+| **前端子仓** | `wtf-frontend` | Next.js / React / Tailwind | Web / H5 高频交易终端与 TradingView 图表交互 |
+
+### 1.2 双环境部署拓扑
+
+| 环境 | 主仓分支 | 部署策略 | 服务端对应域名/端口（Caddy 反代） | 分支保护 |
+| :--- | :--- | :--- | :--- | :--- |
+| **Dev / 测试网** | `develop` | Push 触发 `dev-deploy` | `dev.wtfx.io` (API: 8081, Indexer: 4201, Web: 3001) | 自由 merge / push |
+| **Prod / 生产网** | `deploy` | 合并 PR 触发 `prod-deploy` (蓝绿发布) | `wtfx.io` (API: 8080, Indexer: 4200, Web: 3000) | **严格保护，禁止直推** |
+
+---
+
+## 2. 分支职责与生命周期规范
+
+```
+[子仓 main] ──────────────────────────> [提 PR 经 Code Review] ──> [合并到子仓 main]
+     │                                                                   │
+     ▼ (切出开发分支)                                                       ▼
+[A: feat/xxx 或 fix/xxx]                                         [主仓切 release/xxx 提 PR -> deploy]
+     │                                                                   │
+     ▼ (合并上测试网)                                                       ▼
+[子仓 develop] ──> [主仓 bump develop 指针] ──> (触发 dev-deploy)    [全栈蓝绿流水线: 编译->备份->探针->Caddy切流]
+```
+
+### 核心铁律：
+1. **源分支 A（`feat/*` 或 `fix/*`）必须保持纯净**：
+   - 永远从子仓的 `main` 切出，只承载当前需求的改动；
+   - **严禁**直接将 `develop` 合入 A 分支（防止测试环境脏代码污染生产 PR）。
+2. **所有子仓 `main` 禁止直接 Push**：
+   - 必须通过 Gitea 发起 Pull Request（`feat/*` -> `main`），经 Code Review 确认后方可合入。
+3. **上测试环境的标准路径**：
+   - 开发完成后，将 A 合并进子仓 `develop` 并 Push；
+   - 然后到主仓切 `develop` 分支，更新该子仓指针并 Push，触发测试环境部署。
+4. **测试隔离分支 A′ 机制（适用于有 DB Migration 或与 develop 冲突时）**：
+   - 若需求包含数据库 Migration 链对齐，或 A 直接合入 `develop` 会与他人正在测试的代码产生冲突；
+   - 必须从 A 切出 `A′`（如 `feat/xxx-dev-test`），在 `A′` 上 merge `develop` 联调；
+   - 测试通过后，**仅将属于本需求的 Fix Commit 逐个 cherry-pick 回 A**，严禁把 `A′` 或 `develop` 直接 merge 回 A。
+
+---
+
+## 3. 全栈蓝绿部署 (Blue-Green Deployment) 架构与实现
+
+针对高频预测市场（WTFX），实施差异化的蓝绿热切换方案：
+
+| 服务组件 | 生产流量端口 (Caddy Upstream) | Blue 槽位 (当前) | Green 槽位 (新版待切) | 切换机制 |
+| :--- | :--- | :--- | :--- | :--- |
+| **前端 (Next.js)** | `wtfx.io` (443) | `127.0.0.1:3000` | `127.0.0.1:3002` | Caddy API 零停机重载上游端口 |
+| **后端 API/WS** | `api.wtfx.io` (443) | `127.0.0.1:8080` | `127.0.0.1:8082` | 平滑优雅停机 (Graceful Shutdown) |
+| **索引器 (Indexer)** | `indexer.wtfx.io` (443) | `127.0.0.1:4200` | `127.0.0.1:4202` | **主从 Worker 抢占锁 + 追高水位探针** |
+
+---
+
+## 4. 标准操作工作流（开发者与管理员手册）
+
+### 4.1 开启新需求开发
+```bash
+# 进入对应子仓（例如后端）
+cd wtf-backend
+git checkout main
+git pull origin main
+git checkout -b feat/market-order-api
+```
+
+### 4.2 开发完成，上 Dev 测试环境
+```bash
+# 1. 将代码合并进子仓 develop
+git checkout develop
+git pull origin develop
+git merge feat/market-order-api
+git push origin develop
+
+# 2. 回到主仓，将子仓指针更新到 develop 尖端
+cd ..
+git checkout develop
+git pull origin develop
+git add wtf-backend
+git commit -m "chore(dev): bump wtf-backend for market order API"
+git push origin develop
+# ---> 此时触发 Gitea Actions 的 dev-deploy 自动化部署
+```
+
+### 4.3 验收通过，发起生产上线 PR
+```bash
+# 1. 确保源分支与最新生产 main 对齐
+cd wtf-backend
+git checkout feat/market-order-api
+git fetch origin
+git merge origin/main   # 在本地解决可能存在的冲突
+git push origin feat/market-order-api
+
+# 2. 在 Gitea 页面上发起子仓 PR:
+#    源分支: feat/market-order-api -> 目标分支: main
+
+# 3. 审核人 Review 并 Merge 子仓 PR 后，管理员切 release 发起主仓 PR:
+cd ..
+git checkout deploy
+git pull origin deploy
+git checkout -b release/2026-08-30
+cd wtf-backend && git checkout main && git pull origin main && cd ..
+git add wtf-backend
+git commit -m "release: bump wtf-backend to main $(date +%Y-%m-%d)"
+git push origin release/2026-08-30
+
+# 4. 在 Gitea 页面发起主仓 PR: release/2026-08-30 -> deploy
+#    管理员确认合并后，触发 Gitea Actions 的 prod-deploy 全栈蓝绿部署流水线
+```
+
+---
+
+## 5. 生产应急手册：一键回滚操作 (Emergency Rollback)
+
+若生产上线后发现严重业务 Bug，管理员直接在主仓执行**原子指针回滚**：
+
+```bash
+cd wtfx
+git checkout deploy
+git revert HEAD -m "revert: emergency rollback to previous slot"
+git push origin deploy
+# ---> 触发流水线自动将 Caddy 流量切回上一个已验证的槽位
+```
+
+---
+
+## 6. 服务器基础设施与 Caddy 配置规范
+
+当前服务器（`152.32.146.53`）已部署 Gitea，后续服务通过 **Caddy** 统一管理反向代理和自动 SSL 证书申请。
+
+### 标准 `/etc/caddy/Caddyfile` 生产模板：
+```caddy
+# Gitea 代码托管
+gitea.wtfx.io {
+    reverse_proxy localhost:3000
+}
+
+# 生产环境 (Prod)
+wtfx.io {
+    reverse_proxy localhost:3000        # 前端 Next.js
+}
+api.wtfx.io {
+    reverse_proxy localhost:8080        # 后端 REST/WS
+}
+indexer.wtfx.io {
+    reverse_proxy localhost:4200        # Indexer GraphQL/RPC
+}
+
+# 测试环境 (Dev)
+dev.wtfx.io {
+    reverse_proxy localhost:3001        # Dev 前端
+}
+dev-api.wtfx.io {
+    reverse_proxy localhost:8081        # Dev 后端
+}
+dev-indexer.wtfx.io {
+    reverse_proxy localhost:4201        # Dev Indexer
+}
+```
@@ -0,0 +1,147 @@
+# WTFX 分支协作 — 命令速查与决策树
+
+> 规范正文以 [SKILL.md](SKILL.md) 为准；本文件提供完整命令速查与分支决策树。
+
+---
+
+## 1. 仓库与分支一览
+
+| 仓库 | Gitea URL | develop 分支 | main 分支保护 |
+| :--- | :--- | :--- | :--- |
+| **主仓** | `http://152.32.146.53/wtfx/wtfx.git` | 有（触发 test 部署） | `deploy` 分支强制保护，须走 PR |
+| **wtf-contract** | `http://152.32.146.53/wtfx/wtf-contract.git` | **使用** | `main` 强制保护，禁止直推 |
+| **wtf-backend** | `http://152.32.146.53/wtfx/wtf-backend.git` | **使用** | `main` 强制保护，禁止直推 |
+| **wtf-frontend** | `http://152.32.146.53/wtfx/wtf-frontend.git` | **使用** | `main` 强制保护，禁止直推 |
+| **wtf-indexer** | `http://152.32.146.53/wtfx/wtf-indexer.git` | **使用** | `main` 强制保护，禁止直推 |
+
+| 主仓分支 | 部署环境 | 触发机制 | 访问域名 | 权限保护 |
+| :--- | :--- | :--- | :--- | :--- |
+| `develop` | 测试网 / Dev | Push 触发 `dev-deploy` | `dev.wtfx.io` | 无（可自由 merge） |
+| `deploy` | 生产网 / Prod | 合并 PR 触发 `prod-deploy` | `wtfx.io` | **须 PR（禁止直推）** |
+
+---
+
+## 2. 开发者日常流：A → develop → main
+
+```bash
+# 1. 在子仓（如 wtf-backend）开发
+cd wtf-backend
+git checkout main && git pull origin main
+git checkout -b feature/xxx
+# ... 编码开发 ...
+git push -u origin feature/xxx
+
+# 2. 上 test 服务端：A merge 进 develop
+git checkout develop && git pull origin develop
+git merge feature/xxx
+git push origin develop
+
+# 3. 主仓：指针跟到子仓 develop 尖端（触发 Dev 部署）
+cd /path/to/wtfx
+git checkout develop && git pull origin develop
+cd wtf-backend && git fetch origin && git checkout develop && git pull origin develop && cd ..
+git add wtf-backend
+git commit -m "chore(test): sync wtf-backend develop pointer"
+git push origin develop
+
+# --- 验收完成 → 准备提子仓 PR ---
+
+# 4. 对齐生产 main 并 push（若用过 A′ 先 cherry-pick）
+git checkout feature/xxx
+git fetch origin
+git merge origin/main
+git push origin feature/xxx
+
+# 5. Gitea 网页操作：创建 PR: feature/xxx -> main
+```
+
+---
+
+## 3. A′ 测试隔离分支（适用于 DB Migration 或冲突）
+
+**何时用 A′**（满足任一即走 A′，勿 A 直 merge develop）：
+1. **含有 DB migration**：须依 `develop` 的 migration 链对齐版本；
+2. **与他人代码冲突**：A merge 进 `develop` 会与 `develop` 上他人已测内容冲突。
+
+```bash
+# A = feature/xxx（干净 PR 线，永不 merge develop）
+git checkout main && git pull origin main
+git checkout -b feature/xxx
+
+# A′ = 仅测试用，从 A 切出
+git checkout -b feature/xxx-test-deploy
+git merge origin/develop
+git push -u origin feature/xxx-test-deploy
+
+# 将 A′ 合入 develop 并推送到 Gitea
+git checkout develop && git pull origin develop
+git merge feature/xxx-test-deploy
+git push origin develop
+
+# 主仓 bump 子仓 develop 指针上测试
+```
+
+**测试完成，将 A′ 修复收回 A（仅 cherry-pick 本需求相关 commit）**：
+```bash
+# 查看 A′ 相对 A 多出的 commit
+git log feature/xxx..feature/xxx-test-deploy --oneline
+
+git checkout feature/xxx
+git cherry-pick <commit-sha>   # 逐个摘；严禁 merge A′ 或 develop 进 A
+git push origin feature/xxx
+```
+
+---
+
+## 4. 管理员生产发布流程 (PR 过了之后的正式 Deploy)
+
+子仓 PR 合入 `main` 后，管理员在主仓执行：
+
+```bash
+# 1. 切换到主仓 deploy 分支
+cd /path/to/wtfx
+git checkout deploy && git pull origin deploy
+
+# 2. 切出发布分支
+git checkout -b release/2026-08-30
+
+# 3. 同步各个子仓指针到 main 尖端
+cd wtf-contract && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-backend  && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-frontend && git fetch origin && git checkout main && git pull origin main && cd ..
+cd wtf-indexer  && git fetch origin && git checkout main && git pull origin main && cd ..
+
+# 4. 提交并推送到 Gitea
+git add wtf-contract wtf-backend wtf-frontend wtf-indexer
+git commit -m "release: point deploy at submodules main 2026-08-30"
+git push -u origin release/2026-08-30
+
+# 5. Gitea 网页端操作：发起主仓 PR: release/2026-08-30 -> deploy
+#    Review 全栈指针 Diff 后点击 Merge，触发正式 prod-deploy
+```
+
+---
+
+## 5. 分支流转决策树
+
+```
+开始新需求开发
+│
+├─ 1. 从子仓 main 切出 feature/xxx (A)
+│
+├─ 2. 开发完毕，准备上测试网（develop）？
+│  ├─ 有 DB migration，或与 develop 冲突？
+│  │  ├─ 是 ──> 切 A′ (feature/xxx-test-deploy) ──> A′ merge develop ──> 主仓 bump develop 指针
+│  │  └─ 否 ──> A 直 merge develop ──> 主仓 bump develop 指针
+│  └─ 测出问题？──> 只在 A 改 ──> 重新 merge 上测试
+│
+└─ 3. 测试网验收通过，准备上生产？
+   ├─ 用过 A′？──> 仅 cherry-pick 自身修复 commit 回 A（不带 develop 借来的内容）
+   ├─ 在 A 上执行 git merge origin/main，本地解决冲突并 push
+   ├─ Gitea 网页提子仓 PR: feature/xxx ──> main（禁止直推 main）
+   │
+   └─ 子仓 PR 合并后，管理员执行生产 Deploy：
+      ├─ 主仓从 deploy 切 release/YYYY-MM-DD
+      ├─ 将子仓指针更新到各自 main 尖端
+      └─ Gitea 提主仓 PR: release/xxx ──> deploy ──> 合并触发 prod-deploy
+```