# reallife_asset - 真人人像素材管理模块

Sage平台的真人人像素材管理模块，支持多供应商（火山方舟等）的真人人像素材资产（Asset Group / Asset）管理。

## 功能概述

- **真人认证**: 创建H5认证链接，终端用户完成真人认证后获取素材组合ID
- **素材上传**: 上传真人人像素材（图片/视频/音频），系统自动进行面部一致性比对
- **状态同步**: 从供应商同步素材组合和素材资产状态
- **多供应商**: 可扩展架构，当前支持火山方舟，预留可灵等供应商接口

## 目录结构

```
reallife_asset/
├── reallife_asset/           # Python包
│   ├── __init__.py
│   ├── init.py               # 模块初始化 + 业务逻辑
│   └── volcengine_client.py  # 火山方舟API客户端(AK/SK签名)
├── models/                   # 数据库表定义
│   ├── rl_asset_group.json   # 素材组合表
│   └── rl_asset.json         # 素材资产表
├── json/                     # CRUD定义
│   ├── rl_asset_group_list.json
│   └── rl_asset_list.json
├── wwwroot/                  # 前端
│   ├── index.ui              # 模块入口
│   ├── group_manage.ui       # 组合管理页
│   ├── asset_manage.ui       # 资产管理页
│   ├── create_validate.ui    # 创建认证页
│   ├── upload_asset.ui       # 上传素材页
│   ├── sync_groups.ui        # 同步页
│   └── api/                  # API端点
│       ├── rl_asset_group_create.dspy
│       ├── rl_asset_group_update.dspy
│       ├── rl_asset_group_delete.dspy
│       ├── rl_asset_create.dspy
│       ├── rl_asset_update.dspy
│       ├── rl_asset_delete.dspy
│       ├── sync_asset_status.dspy
│       ├── check_validate.dspy
│       ├── sync_from_vendor.dspy
│       ├── sync_assets.dspy
│       ├── get_rl_asset_group_list.dspy
│       └── get_rl_asset_list.dspy
├── init/
│   └── data.json             # 初始化编码数据
├── scripts/
│   ├── load_path.py          # RBAC权限注册
│   └── uapi_volcengine_ark.sql  # uapi接口SQL配置
├── pyproject.toml
├── build.sh
└── README.md
```

## 数据库表

### rl_asset_group (素材组合表)
- 记录真人认证组合，每个组合对应一个真人
- 字段: vendor, vendor_group_id, name, status, byted_token, h5_link等

### rl_asset (素材资产表)
- 记录具体素材文件，关联到组合
- 字段: vendor, vendor_asset_id, asset_type, status, url, asset_uri等

## API接口

### 火山方舟 API (通过uapi系统)

| API | 功能 | 限流 |
|-----|------|------|
| CreateVisualValidateSession | 创建H5认证页 | 3 QPS |
| GetVisualValidateResult | 获取认证结果 | 3 QPS |
| CreateAsset | 上传素材(异步) | 按权益 |
| GetAsset | 查询素材 | 100 QPS |
| ListAssets | 素材列表 | 10 QPS |
| ListAssetGroups | 组合列表 | 10 QPS |
| GetAssetGroup | 查询组合 | 10 QPS |
| UpdateAsset | 更新素材 | 10 QPS |
| UpdateAssetGroup | 更新组合 | 10 QPS |
| DeleteAsset | 删除素材 | 10 QPS |
| DeleteAssetGroup | 删除组合 | 5 QPS |

## 安装部署

### 1. 安装模块
```bash
cd ~/repos/reallife_asset
bash build.sh
```

### 2. 创建数据库表
```bash
# 执行DDL
mysql -u root -p sage < mysql.ddl.sql
```

### 3. 注册RBAC权限
```bash
cd ~/repos/sage
./py3/bin/python ~/repos/reallife_asset/scripts/load_path.py
```

### 4. 配置uapi接口（可选）
```bash
mysql -u root -p sage < ~/repos/reallife_asset/scripts/uapi_volcengine_ark.sql
```

### 5. 集成到Sage
在 `app/sage.py` 中添加:
```python
from reallife_asset.init import load_reallife_asset
# 在init()中:
load_reallife_asset()
```

### 6. 重启Sage
```bash
cd ~/repos/sage && ./stop.sh && ./start.sh
```

## 使用流程

1. **创建真人认证**: 提供回调URL和AK/SK → 获取H5认证链接
2. **终端用户认证**: 用户通过H5链接完成真人认证
3. **获取组合ID**: 认证成功后查询获取供应商端Group ID
4. **上传素材**: 向已认证的组合上传图片/视频素材
5. **同步状态**: 轮询素材处理状态直到Active
6. **使用素材**: 使用 `asset://<asset_id>` URI 进行视频生成

## 扩展新供应商

1. 在 `volcengine_client.py` 中实现新的客户端类
2. 在 `_PROVIDERS` 字典中注册
3. 添加对应的uapi SQL配置

## 技术要点

- AK/SK签名: 使用HMAC-SHA256实现火山方舟V4签名（纯stdlib，无外部依赖）
- 多租户: 所有数据按org_id隔离
- 异步处理: CreateAsset为异步接口，需轮询状态