diff --git a/README.md b/README.md
index 053c357..d285d5f 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,236 @@
-# supplychain
+# supplychain — 供应商和分销商管理模块
 
+## 概述
+
+supplychain 模块为 Sage 平台提供供应商和分销商的全链路管理功能，包括：
+
+- **供应商管理**：添加和管理供应商基本信息、联系方式、财务信息
+- **供销合同管理**：运营人员创建与供应商的供销合同，设置合同有效期和产品折扣
+- **二级分销商管理**：销售人员添加和管理二级分销商
+- **分销协议管理**：销售人员与二级分销商签署分销协议，设置产品分销折扣
+- **供销记账**：产品销售时自动计算供销关系的记账金额（进货金额、分销金额、利润）
+
+## 目录结构
+
+```
+supplychain/
+├── supplychain/          # Python 包
+│   ├── __init__.py
+│   └── init.py           # 模块初始化 + ServerEnv 注册
+├── wwwroot/              # 前端文件
+│   ├── index.ui          # 模块入口页
+│   ├── menu.ui           # 导航菜单
+│   ├── suppliers.ui      # 供应商管理页
+│   ├── supply_contracts.ui  # 供销合同页
+│   ├── sub_distributors.ui  # 二级分销商页
+│   ├── distribution_agreements.ui  # 分销协议页
+│   ├── accounting.ui     # 供销记账页
+│   └── api/              # API 端点
+│       ├── *_create.dspy
+│       ├── *_update.dspy
+│       ├── *_delete.dspy
+│       ├── calculate_accounting.dspy   # 记账计算 API
+│       ├── query_supply_discount.dspy  # 查询进货折扣
+│       └── query_dist_discount.dspy    # 查询分销折扣
+├── models/               # 数据库表定义
+│   ├── suppliers.json
+│   ├── supply_contracts.json
+│   ├── supply_contract_items.json
+│   ├── sub_distributors.json
+│   ├── distribution_agreements.json
+│   ├── distribution_agreement_items.json
+│   └── supplychain_accounting.json
+├── json/                 # CRUD 配置
+│   ├── suppliers_list.json
+│   ├── supply_contracts_list.json
+│   ├── supply_contract_items_list.json
+│   ├── sub_distributors_list.json
+│   ├── distribution_agreements_list.json
+│   ├── distribution_agreement_items_list.json
+│   └── supplychain_accounting_list.json
+├── init/
+│   └── data.json         # 初始化数据（可选）
+├── scripts/
+│   └── load_path.py      # RBAC 权限管理脚本
+├── pyproject.toml
+├── build.sh
+└── README.md
+```
+
+## 数据库表
+
+| 表名 | 说明 | 类别 |
+|------|------|------|
+| suppliers | 供应商表 | entity |
+| supply_contracts | 供销合同表 | entity |
+| supply_contract_items | 供销合同产品折扣明细 | relation |
+| sub_distributors | 二级分销商表 | entity |
+| distribution_agreements | 分销协议表 | entity |
+| distribution_agreement_items | 分销协议产品折扣明细 | relation |
+| supplychain_accounting | 供销记账表 | relation |
+
+## 角色权限
+
+| 角色 | 权限范围 |
+|------|----------|
+| 运营 (operator) | 供应商管理、供销合同管理（含产品折扣） |
+| 销售 (sale) | 二级分销商管理、分销协议管理（含产品折扣） |
+| 所有登录用户 | 供销记账查看 |
+
+## 折扣计算规则
+
+### 进货折扣（供应商 → 分销商）
+
+查找优先级：
+1. 供销合同 → 产品明细（精确匹配 productid）
+2. 供销合同 → 产品明细（匹配 prodtypeid）
+3. 供销合同 → 默认折扣（default_discount）
+
+### 分销折扣（分销商 → 二级分销商）
+
+查找优先级：
+1. 分销协议 → 产品明细（精确匹配 productid）
+2. 分销协议 → 产品明细（匹配 prodtypeid）
+3. 分销协议 → 默认折扣（default_discount）
+
+### 记账金额计算
+
+```
+销售总额 = 单价 × 数量
+进货金额 = 销售总额 × 进货折扣 (或 结算单价 × 数量)
+分销金额 = 销售总额 × 分销折扣 (或 结算单价 × 数量)
+利润金额 = 分销金额 - 进货金额
+```
+
+## API 接口
+
+### 记账计算 API
+
+**端点**: `/supplychain/api/calculate_accounting.dspy`
+
+**请求方法**: POST
+
+**参数**:
+```json
+{
+    "productid": "产品ID",
+    "prodtypeid": "产品分类ID (可选)",
+    "quantity": 10,
+    "unit_price": 100.00,
+    "sub_distributor_id": "二级分销商ID (可选)",
+    "sale_date": "2026-05-25 (可选, 默认今天)",
+    "source_type": "2 (来源类型: 1=手动, 2=API)",
+    "source_id": "来源记录ID (可选)",
+    "remark": "备注 (可选)"
+}
+```
+
+**返回**:
+```json
+{
+    "status": "ok",
+    "data": {...},
+    "summary": {
+        "total_amount": 1000.00,
+        "supply_amount": 700.00,
+        "dist_amount": 900.00,
+        "profit_amount": 200.00,
+        "supply_discount": 0.7,
+        "dist_discount": 0.9
+    }
+}
+```
+
+### 折扣查询 API
+
+**进货折扣查询**: `/supplychain/api/query_supply_discount.dspy`
+- 参数: `productid`, `prodtypeid` (可选)
+
+**分销折扣查询**: `/supplychain/api/query_dist_discount.dspy`
+- 参数: `sub_distributor_id`, `productid`, `prodtypeid` (可选)
+
+## Python 模块函数
+
+通过 `ServerEnv` 注册后可在 .dspy 文件中直接调用：
+
+```python
+# 获取进货折扣
+supply_info = await get_active_supply_discount(sor, resellerid, productid, prodtypeid, sale_date)
+
+# 获取分销折扣
+dist_info = await get_active_dist_discount(sor, resellerid, sub_distributor_id, productid, prodtypeid, sale_date)
+
+# 计算并创建记账记录
+record = await calculate_sale_accounting(sor, resellerid, productid, quantity, unit_price,
+                                          sub_distributor_id, prodtypeid, sale_date, source_type, source_id, created_by, remark)
+```
+
+## 安装步骤
+
+### 1. 克隆模块
+
+```bash
+cd ~/repos
+git clone git@git.opencomputing.cn:yumoqing/supplychain.git
+```
+
+### 2. 构建模块
+
+```bash
+cd ~/repos/supplychain
+chmod +x build.sh
+./build.sh
+```
+
+### 3. 生成 DDL 并创建数据库表
+
+```bash
+cd ~/repos/supplychain/models
+mysql -h <host> -u <user> -p <dbname> < mysql.ddl.sql
+```
+
+### 4. 集成到 Sage
+
+**a. 修改 `app/sage.py`**:
+```python
+from supplychain.init import load_supplychain
+# 在 init() 函数中添加:
+load_supplychain()
+```
+
+**b. 修改 `build.sh`** (Sage 根目录):
+```bash
+for m in ... supplychain
+```
+
+### 5. 注册 RBAC 权限
+
+模块提供 `scripts/load_path.py` 权限管理脚本，自动注册所有路径：
+
+```bash
+cd ~/repos/sage
+./py3/bin/python ~/repos/supplychain/scripts/load_path.py
+```
+
+脚本按角色分类注册:
+- `any`: 静态资源/CRUD 别名目录
+- `logined`: 所有页面和 API
+- `reseller.operator`: 供应商、供销合同管理
+- `reseller.sale`: 二级分销商、分销协议管理
+
+**维护规则**: 每次代码变更如有新 path 出现，需同步更新 `scripts/load_path.py` 中的路径列表。
+
+### 6. 重启 Sage
+
+```bash
+cd ~/repos/sage
+./stop.sh && ./start.sh
+```
+
+## 产品模块引用
+
+本模块的 `productid` 和 `prodtypeid` 字段引用 product 模块的 `products` 和 `product_types` 表。
+已在以下模型的 `codes` 段添加引用配置：
+- `models/supply_contract_items.json`
+- `models/distribution_agreement_items.json`
+- `models/supplychain_accounting.json`