s''

README.md

@@ -1,6 +1,53 @@
 # PayJS API
 
-支付 API 服务，支持多支付渠道切换（XorPay、ZPAY）。
+支付 API 服务，支持多支付渠道（XorPay、ZPAY），按项目模块化拆分。
+
+## 路由与项目对应
+
+| 项目 | 路由前缀 | 说明 |
+|------|----------|------|
+| nomadvip | `/nomadvip/*` | 固定 ZPAY，独立实例 |
+| digital | `/digital/*` | 使用 PAYMENT_PROVIDER |
+| cnomadcna | `/cnomadcna/*` | 使用 PAYMENT_PROVIDER |
+| nomadlms | `/nomadlms/*` | 使用 PAYMENT_PROVIDER |
+| legacy | `/payh5`、`/zpay_notify` 等 | 向后兼容 |
+
+各项目业务互不影响，可单独配置。
+
+## 环境
+
+本地调试：`BASE_URL` 需为 ZPAY 可访问地址（如 ngrok 暴露 8700 端口）  
+线上部署：`BASE_URL=https://api.hackrobot.cn`
+
+## 模块结构
+
+```
+app/
+├── config.py          # 配置（环境变量）
+├── main.py            # FastAPI 入口，挂载路由
+├── sdk/               # SDK 组件化封装
+│   ├── payment/       # 支付网关（ZPAY/XorPay）
+│   ├── pocketbase.py  # PocketBase 数据库
+│   ├── minio.py       # MinIO 对象存储
+│   └── memos.py       # Memos 用户（仅 nomadvip 使用）
+├── services/          # 共享业务逻辑（基于 SDK）
+│   ├── pb.py          # PocketBase 客户端
+│   ├── memos.py       # Memos 用户创建
+│   ├── minio.py       # MinIO 上传
+│   └── payment.py     # 支付成功处理
+├── routers/           # 项目路由
+│   ├── nomadvip.py    # /nomadvip/*
+│   ├── digital.py    # /digital/*
+│   ├── cnomadcna.py  # /cnomadcna/*
+│   ├── nomadlms.py   # /nomadlms/*
+│   ├── legacy.py     # /payh5 等（向后兼容）
+│   └── common.py     # /submit_meetup_application、/create_user
+└── payment/
+    ├── base.py        # 支付抽象基类
+    ├── xorpay.py      # XorPay 实现
+    ├── zpay.py        # ZPAY 实现（易支付兼容）
+    └── factory.py     # 渠道工厂
+```
 
 ## 支付渠道
 
@@ -11,17 +58,28 @@
 
 切换渠道：设置环境变量 `PAYMENT_PROVIDER=xorpay` 或 `zpay`，参考 `.env.example`。
 
-## 模块结构
+## 本地调试
 
+```bash
+# 复制配置
+cp .env.example .env
+
+# 本地调试时 BASE_URL 需 ZPAY 可访问，可用 ngrok：
+# ngrok http 8700  -> 将 BASE_URL 设为 ngrok 提供的 https 地址
+
+python run.py
+# 或 uvicorn app.main:app --host 0.0.0.0 --port 8700 --reload
 ```
-app/
-├── config.py          # 配置（环境变量）
-├── main.py            # FastAPI 入口
-└── payment/
-    ├── base.py        # 支付抽象基类
-    ├── xorpay.py      # XorPay 实现
-    ├── zpay.py        # ZPAY 实现（易支付兼容）
-    └── factory.py     # 渠道工厂
+
+## 线上部署
+
+域名：`https://api.hackrobot.cn`
+
+```bash
+# .env 中设置
+BASE_URL=https://api.hackrobot.cn
+PAYMENT_PROVIDER=zpay
+# 其他 ZPAY、PocketBase、Memos 配置见 .env.example
 ```
 
 ## Getting started