diff --git a/README.md b/README.md
index b044b74..e188ec2 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,142 @@
-# showcase
+# Showcase — 产品展示平台
 
+Sage 平台的内容展示模块，支持多种媒体类型发布、社交互动和 KTV 付费下载。
+
+## 功能概览
+
+### 展示平台
+- **5 种媒体类型**：音乐、MTV、短视频、长视频、KTV
+- **Feed 流**：按类型筛选、分页浏览、卡片瀑布流布局
+- **社交互动**：点赞（toggle 防刷）、评论（支持嵌套回复）、浏览计数
+- **作品详情**：完整信息展示、点赞状态、购买状态
+
+### KTV 付费下载
+- 付费作品购买下载（模拟支付）
+- 购买记录管理（防重复购买）
+- 下载计数统计
+
+## 数据表（4 张）
+
+| 表名 | 说明 | 关键字段 |
+|------|------|----------|
+| `showcase_posts` | 作品主表 (24 字段) | media_type, content_url, price, like_count, view_count |
+| `showcase_comments` | 评论表 (12 字段) | parent_id (嵌套回复), reply_count |
+| `showcase_likes` | 点赞表 (4 字段) | UNIQUE(post_id, user_id) 防刷 |
+| `showcase_downloads` | KTV 下载记录 (8 字段) | payment_status, UNIQUE(post_id, user_id) |
+
+所有表使用 `sage` 数据库。
+
+## API 端点（11 个）
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `showcase_feed.dspy` | GET | Feed 列表（分页 + media_type 筛选） |
+| `showcase_post_detail.dspy` | GET | 作品详情（含点赞/购买状态，自动 +view_count） |
+| `showcase_post_create.dspy` | POST | 创建作品（自动填充 author_id） |
+| `showcase_post_update.dspy` | POST | 更新作品 |
+| `showcase_post_delete.dspy` | POST | 删除作品 |
+| `showcase_comment_create.dspy` | POST | 创建评论/回复（自动更新 comment_count 和 reply_count） |
+| `showcase_comment_update.dspy` | POST | 更新评论 |
+| `showcase_comment_delete.dspy` | POST | 删除评论 |
+| `showcase_comments_list.dspy` | GET | 获取某作品全部评论 |
+| `showcase_like_toggle.dspy` | POST | 切换点赞（返回 liked: true/false） |
+| `showcase_download_purchase.dspy` | POST | KTV 购买下载（检查重复购买） |
+
+## CRUD 管理界面（3 个）
+
+| CRUD 别名 | 表 | 功能 |
+|-----------|------|------|
+| `showcase_posts_list` | showcase_posts | 作品管理（搜索：标题/类型/状态） |
+| `showcase_comments_list` | showcase_comments | 评论管理 |
+| `showcase_downloads_list` | showcase_downloads | 下载记录管理 |
+
+通过 `xls2crud` 自动生成，运行时由 `build.sh` 产出。
+
+## 目录结构
+
+```
+showcase/
+├── showcase/                    # Python 包
+│   ├── __init__.py              # 导出所有函数
+│   └── init.py                  # ServerEnv 注册 + 业务逻辑
+├── models/                      # 数据表定义 (JSON)
+│   ├── showcase_posts.json
+│   ├── showcase_comments.json
+│   ├── showcase_likes.json
+│   └── showcase_downloads.json
+├── json/                        # CRUD 定义 (JSON)
+│   ├── showcase_posts_list.json
+│   ├── showcase_comments_list.json
+│   └── showcase_downloads_list.json
+├── wwwroot/
+│   ├── index.ui                 # Feed 主页（卡片流 + 类型筛选）
+│   ├── detail.ui                # 作品详情页
+│   ├── showcase.css             # 样式
+│   ├── showcase.js              # 前端逻辑（feed 加载/卡片渲染）
+│   └── api/                     # 11 个 dspy 端点
+├── init/
+│   └── data.json                # 初始化数据（media_type 编码）
+├── scripts/
+│   └── load_path.py             # RBAC 权限注册
+├── pyproject.toml
+└── README.md
+```
+
+## Sage 集成步骤
+
+### 1. 安装模块
+```bash
+cd ~/repos/showcase && ~/repos/sage/py3/bin/pip install .
+```
+
+### 2. 注册模块加载
+编辑 `~/repos/sage/app/sage.py`：
+```python
+from showcase.init import load_showcase
+# 在 init() 函数中添加：
+load_showcase()
+```
+
+### 3. 添加到 build.sh
+编辑 `~/repos/sage/build.sh`，在安装循环中添加 `showcase`：
+```bash
+for m in appbase rbac ... showcase
+```
+
+### 4. wwwroot 软链接
+```bash
+cd ~/repos/sage/wwwroot
+ln -sf ~/repos/showcase/wwwroot showcase
+```
+
+### 5. RBAC 权限
+```bash
+cd ~/repos/sage && ./py3/bin/python ~/repos/showcase/scripts/load_path.py
+```
+
+### 6. 菜单入口
+编辑 `~/repos/sage/wwwroot/global_menu.ui`，在 items 数组中添加：
+```json
+,{"name":"showcase","label":"展示平台","icon":"fa fa-photo-film","url":"{{entire_url('/showcase/index.ui')}}","target":"app.sage_main_content"}
+```
+
+### 7. 建表
+```bash
+cd ~/repos/showcase
+~/repos/sage/py3/bin/json2ddl mysql models/ > mysql.ddl.sql
+# 然后在 MySQL 中执行 mysql.ddl.sql
+```
+
+### 8. 生成 CRUD 界面
+```bash
+cd ~/repos/showcase
+~/repos/sage/py3/bin/xls2crud -m models -o wwwroot showcase json/*.json
+```
+
+## 技术要点
+
+- **点赞防刷**：`showcase_likes` 表有 `UNIQUE(post_id, user_id)` 唯一索引
+- **计数冗余**：`like_count`/`comment_count`/`view_count` 冗余存储在 posts 表，避免 Feed 流 COUNT 查询
+- **嵌套评论**：`parent_id` 指向同表 id，支持无限层级回复
+- **付费隔离**：KTV 作品设置 `price > 0`，购买后 `is_purchased=True` 才返回 content_url
+- **dspy 规范**：零 import、零 print、零 uuid，使用预加载全局函数