docs: 补全README — 功能/API/部署/集成完整文档
This commit is contained in:
parent
1cce05a119
commit
9b3c5ff041
142
README.md
142
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，使用预加载全局函数
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user