diff --git a/README.md b/README.md
index 302822e..cb3919e 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,58 @@
-# 统一支付
+# unipay — 统一支付模块
 
-支持微信，支付宝，paypal支持
+多渠道统一支付：微信支付（Native/H5）、支付宝、PayPal、Stripe、银行转账码。
+凭据全部走环境变量（不落库、不进 git），渠道初始化失败自动降级为 disabled，不影响宿主启动。
 
-## 支付重要信息
-支付重要信息都通过环境变量设置
+## 数据表（models/*.json）
 
-### 微信支付
+| 表 | 说明 | 关键字段 |
+|---|------|---------|
+| paychannel | 支付渠道 | id, name, enabled_date, expired_date |
+| payfee | 支付费率（挂渠道） | id, channelid, fee_rate, enabled_date, expired_date |
+| payment_log | 支付流水 | id, customerid, channelid, channel_trade_id, payment_name, amount_total, pay_feerate, pay_fee, currency, payment_status, init_timestamp, payed_timestamp, cancel_timestamp, userid, payer_client_ip |
+| transfercode | 银行转账码（线下打款对账） | id, customerid, amount, tcode, curtime, curdate, status |
 
-### 支付宝
+CRUD 定义在 `json/`（paychannel/payfee/payment_log/transfercode），由宿主 build.sh 的 xls2ui 生成页面。
 
-### paypal
+## 环境变量凭据（CONF_ENV 映射，unipay/init.py）
 
+| 渠道 | 环境变量 |
+|------|---------|
+| wechat | `WXP_MCHID`、`WXP_SERIAL`（证书序列号）、`WXP_PRIVKEY`（私钥 pem 文件路径）、`WXP_API_V3_KEY` |
+| alipay | `ALIPAY_APPID`、`ALIPAY_PRIV`（应用私钥文件路径）、`ALIPAY_PUB`（支付宝公钥文件路径） |
+| paypal | `PP_ID`、`PP_SECRET`（sandbox=True 为静态默认） |
+| stripe | `STRIPE_KEY` |
+| transfer | 无凭据（转账码为平台自管） |
+
+缺失凭据的渠道在 `load_unipay()` 里初始化为 None（disabled），运行期调用会得到明确的渠道不可用错误。
+
+## 注册到 ServerEnv 的函数（宿主/dspy 调用面）
+
+`load_unipay()`（unipay/init.py:244）向 ServerEnv 注册：
+
+- `get_paychannels()` / `get_pay_feerate(sor, channelid)` / `get_pay_fee(providerid, amount)` / `sor_get_pay_fee(...)` — 渠道与费率查询（payfee.py）
+- `create_payment` / `query_payment` / `refund_payment` — 支付生命周期（core.py）
+- `PaymentLog` — 流水记录类（paylog.py）
+- `PROVIDERS` — 渠道实例字典 {transfer, wechat, paypal, alipay, stripe}
+
+另有 `add_startup(setup_callback_path)` 注册回调路径（notify.py：`get_provider_channel(name)`、`get_provider(name, conf)`）。
+
+## 前端入口（wwwroot/）
+
+- `recharge.ui/.dspy`、`user_recharge.dspy` — 用户充值
+- `manual_recharge.ui/.dspy`、`transfer_check.dspy`、`transfer_info.ui` — 转账码人工核对（手动按钮触发，不自动轮询）
+- `refund.ui/.dspy` — 退款
+- `usermenu.ui` — 用户菜单挂载
+
+providers/ 下按渠道一个文件：wechat.py、alipay.py、paypal.py、stripe.py、transfer.py。
+
+## 宿主集成
+
+- build.sh 第 5/6 步：clone + `pip install pkgs/unipay/`（普通 install 非 editable，改代码后必须重装）
+- 宿主 `init()` 里调用 `load_unipay()`；wwwroot symlink 由 build.sh 第 8 步统一挂
+
+## 部署注意
+
+- 凭据文件（私钥 pem）路径由环境变量给出，文件本身不入仓库
+- payment_log 金额字段落库前经 payfee 计算（费率×金额），改费率逻辑需回归 get_pay_fee
+- 转账码核对是人工动作（manual_recharge），不要恢复自动轮询