docs: add Downapp API documentation

- New table rl_app_user for application tracking
- APIs: rl_apply, rl_verify, rl_upload, rl_status, rl_check_app_status
- Ops CRUD for managing applications and keys
- Multi-vendor support reserved via vendor field

docs/api_downapp.md

@@ -0,0 +1,192 @@
+# Downapp API 接口文档
+
+## 概述
+本文档说明下游应用（Downapp）如何调用 `reallife_asset` 模块接口，完成真人人像素材的申请、认证、上传及状态查询。
+
+**核心机制**：
+- 所有接口均通过 `downapp_id` 标识调用方。
+- 模块内部会自动检查调用方是否已开通服务（状态为 `active`）。
+- 密钥（AK/SK）由营运人员在后台维护，调用方无需在请求中传递。
+
+## 业务流程
+
+1. **申请开通**：调用方提交申请 (`rl_apply`)。
+2. **人工审批**：营运人员审核申请，回填火山引擎 AK/SK，并激活账户 (`active`)。
+3. **真人认证**：调用方发起认证请求，获取 H5 链接供终端用户完成人脸识别 (`rl_verify`)。
+4. **上传素材**：认证成功后，使用获取到的 `Group ID` 上传图片/视频 (`rl_upload`)。
+5. **状态同步**：轮询检查素材处理状态，直到变为 `Active` 可用 (`rl_status`)。
+
+---
+
+## 1. 申请开通服务
+**Endpoint**: `/reallife_asset/api/rl_apply.dspy`
+
+登记调用方信息，申请开通真人素材上传权限。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `vendor` | 是 | 供应商名称，如 `volcengine` |
+| `callback_url` | 是 | 真人认证完成后的回调地址 |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_apply.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "vendor": "volcengine",
+  "callback_url": "https://example.com/callback"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "app_id": "record_id_xxx",
+  "status": "pending"
+}
+```
+**失败**（已存在记录）：
+```json
+{
+  "success": false,
+  "message": "已提交申请，请等待审批"
+}
+```
+
+---
+
+## 2. 获取真人认证链接 (H5)
+**Endpoint**: `/reallife_asset/api/rl_verify.dspy`
+
+检查审批状态通过后，调用供应商接口创建认证会话。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `project_name` | 否 | 项目名称，默认 `default` |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_verify.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "project_name": "default"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "id": "local_group_id_xxx",
+  "h5_link": "https://... (H5页面链接，120秒有效)",
+  "byted_token": "..."
+}
+```
+**失败**（未开通）：
+```json
+{
+  "success": false,
+  "message": "申请状态: pending，未通过审批"
+}
+```
+
+**注意**：终端用户在 H5 页面完成认证后，供应商将回调 `rl_apply` 中设置的 `callback_url`。
+
+---
+
+## 3. 上传素材
+**Endpoint**: `/reallife_asset/api/rl_upload.dspy`
+
+向已认证的素材组合上传图片或视频素材。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `group_id` | 是 | 真人认证成功后获取的本地组合 ID |
+| `source_url` | 是 | 素材的公网可访问 URL |
+| `asset_type` | 否 | 素材类型：`Image` (默认) 或 `Video` |
+| `name` | 否 | 素材名称 |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_upload.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "group_id": "local_group_id_xxx",
+  "source_url": "https://bucket.oss.com/photo.jpg",
+  "asset_type": "Image",
+  "name": "模特A"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "id": "asset_record_id_xxx",
+  "vendor_asset_id": "asset-2026...",
+  "status": "Processing"
+}
+```
+
+**注意**：上传是异步操作，初始状态为 `Processing`，需调用第 4 个接口轮询状态。
+
+---
+
+## 4. 查询素材状态
+**Endpoint**: `/reallife_asset/api/rl_status.dspy`
+
+查询素材的处理状态（Processing / Active / Failed）。
+
+### 请求参数
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `downapp_id` | 是 | 下游应用唯一标识 |
+| `asset_id` | 是 | 上传素材时返回的本地记录 ID |
+
+### 请求示例
+```http
+POST /reallife_asset/api/rl_status.dspy
+Content-Type: application/json
+
+{
+  "downapp_id": "app_123",
+  "asset_id": "asset_record_id_xxx"
+}
+```
+
+### 返回示例
+**成功**：
+```json
+{
+  "success": true,
+  "status": "Active",
+  "url": "https://... (素材下载链接，12小时有效)"
+}
+```
+
+---
+
+## 错误代码说明
+
+| 错误信息 | 原因 | 解决方案 |
+|----------|------|----------|
+| `未申请或供应商不支持` | `downapp_id` 不存在 | 确认是否已调用申请接口 |
+| `申请状态: xxx，未通过审批` | 状态非 `active` | 联系营运人员审核 |
+| `素材组合不存在` | `group_id` 无效 | 确认是否已通过认证获取有效 ID |
+| `参数缺失` | 缺少必填参数 | 检查请求 Body |

json/rl_app_user_list.json

@@ -0,0 +1,43 @@
+{
+    "tblname": "rl_app_user",
+    "alias": "rl_app_user_list",
+    "title": "真人素材申请管理",
+    "params": {
+        "logined_userorgid": "org_id",
+        "browserfields": {
+            "id": {
+                "title": "ID",
+                "widgettype": "Text"
+            },
+            "downapp_id": {
+                "title": "用户ID",
+                "widgettype": "Text"
+            },
+            "vendor": {
+                "title": "供应商",
+                "widgettype": "Text"
+            },
+            "status": {
+                "title": "状态",
+                "widgettype": "Text"
+            },
+            "callback_url": {
+                "title": "回调URL",
+                "widgettype": "Text"
+            },
+            "create_time": {
+                "title": "申请时间",
+                "widgettype": "Text"
+            },
+            "update_time": {
+                "title": "更新时间",
+                "widgettype": "Text"
+            }
+        },
+        "editable": {
+            "new_data_url": "{{entire_url('../api/rl_app_user_create.dspy')}}",
+            "update_data_url": "{{entire_url('../api/rl_app_user_update.dspy')}}",
+            "delete_data_url": "{{entire_url('../api/rl_app_user_delete.dspy')}}"
+        }
+    }
+}

models/rl_app_user.json

@@ -0,0 +1,109 @@
+{
+    "summary": [
+        {
+            "name": "rl_app_user",
+            "title": "用户真人素材申请",
+            "primary": [
+                "id"
+            ]
+        }
+    ],
+    "fields": [
+        {
+            "name": "id",
+            "title": "主键",
+            "type": "str",
+            "length": 32,
+            "nullable": "no"
+        },
+        {
+            "name": "org_id",
+            "title": "机构",
+            "type": "str",
+            "length": 32,
+            "default": "0"
+        },
+        {
+            "name": "downapp_id",
+            "title": "申请用户ID",
+            "type": "str",
+            "length": 32
+        },
+        {
+            "name": "vendor",
+            "title": "供应商",
+            "type": "str",
+            "length": 50
+        },
+        {
+            "name": "status",
+            "title": "状态",
+            "type": "str",
+            "length": 20,
+            "default": "pending"
+        },
+        {
+            "name": "ak",
+            "title": "AccessKey(加密)",
+            "type": "text"
+        },
+        {
+            "name": "sk",
+            "title": "SecretKey(加密)",
+            "type": "text"
+        },
+        {
+            "name": "callback_url",
+            "title": "回调URL",
+            "type": "str",
+            "length": 500
+        },
+        {
+            "name": "remark",
+            "title": "备注",
+            "type": "text"
+        },
+        {
+            "name": "create_time",
+            "title": "创建时间",
+            "type": "datetime"
+        },
+        {
+            "name": "update_time",
+            "title": "更新时间",
+            "type": "datetime"
+        }
+    ],
+    "indexes": [
+        {
+            "name": "idx_rl_app_user_org",
+            "idxtype": "index",
+            "idxfields": [
+                "org_id"
+            ]
+        },
+        {
+            "name": "idx_rl_app_user_user",
+            "idxtype": "index",
+            "idxfields": [
+                "downapp_id"
+            ]
+        }
+    ],
+    "codes": [
+        {
+            "field": "vendor",
+            "table": "appcodes_kv",
+            "valuefield": "k",
+            "textfield": "v",
+            "cond": "parentid='rl_vendor'"
+        },
+        {
+            "field": "status",
+            "table": "appcodes_kv",
+            "valuefield": "k",
+            "textfield": "v",
+            "cond": "parentid='rl_app_status'"
+        }
+    ]
+}

reallife_asset/init.py

@@ -387,6 +387,122 @@ async def rl_sync_assets_from_vendor(org_id, local_group_id,
     return {"success": True, "synced": synced}
 
 
+# ============================================================
+# Downapp User API Proxies
+# ============================================================
+
+async def _get_user_keys(downapp_id, vendor="volcengine"):
+    """Helper: Check application status and return decrypted keys."""
+    dbname = _get_dbname()
+    db = DBPools()
+    async with db.sqlorContext(dbname) as sor:
+        recs = await sor.R("rl_app_user", {"downapp_id": downapp_id, "vendor": vendor})
+        if not recs:
+            return {"success": False, "message": "未申请或供应商不支持"}
+        rec = recs[0]
+        if rec.status != "active":
+            return {"success": False, "message": f"申请状态: {rec.status}，未通过审批"}
+        
+        env = ServerEnv()
+        ak = env.password_decode(rec.ak)
+        sk = env.password_decode(rec.sk)
+        return {"success": True, "ak": ak, "sk": sk, "callback_url": rec.callback_url}
+
+
+async def rl_apply(org_id, downapp_id, vendor, callback_url):
+    """User applies for real person asset service."""
+    dbname = _get_dbname()
+    db = DBPools()
+    async with db.sqlorContext(dbname) as sor:
+        # Check if already exists
+        existing = await sor.R("rl_app_user", {"downapp_id": downapp_id, "vendor": vendor})
+        if existing:
+            return {"success": False, "message": "已提交申请，请等待审批"}
+        
+        aid = getID()
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        await sor.I("rl_app_user", {
+            "id": aid,
+            "org_id": org_id,
+            "downapp_id": downapp_id,
+            "vendor": vendor,
+            "status": "pending",
+            "callback_url": callback_url,
+            "create_time": now,
+            "update_time": now,
+        })
+    return {"success": True, "app_id": aid, "status": "pending"}
+
+
+async def rl_verify_user(org_id, group_id, downapp_id, project_name="default"):
+    """User proxy: Check app -> Get keys -> Call vendor."""
+    keys = await _get_user_keys(downapp_id)
+    if not keys.get("success"):
+        return keys
+    
+    # Check if group exists locally (optional, or just call vendor)
+    # For user proxy, we might not have local group_id yet if this is the first step.
+    # The user provides group_id? No, user gets group_id after verification.
+    # Wait, the prompt says "按照groupid上传素材" for step 3.
+    # Step 2 is "真人认证". The user calls this to get the H5 link.
+    # So we call rl_create_validate_session with the user's keys.
+    
+    result = await rl_create_validate_session(
+        org_id, keys.get("vendor", "volcengine"),
+        keys["callback_url"], project_name,
+        apikey=keys["ak"], secretkey=keys["sk"],
+        user_id=downapp_id
+    )
+    return result
+
+
+async def rl_upload_user(org_id, group_id, source_url, asset_type, name, downapp_id):
+    """User proxy: Check app -> Get keys -> Upload asset."""
+    keys = await _get_user_keys(downapp_id)
+    if not keys.get("success"):
+        return keys
+    
+    # We need the vendor from the keys or the record
+    # _get_user_keys returns the record, but I only extracted ak/sk.
+    # Let's fetch vendor too.
+    vendor = "volcengine" # Default or fetch from record
+    # Refetch to get vendor
+    dbname = _get_dbname()
+    db = DBPools()
+    async with db.sqlorContext(dbname) as sor:
+        recs = await sor.R("rl_app_user", {"downapp_id": downapp_id})
+        if recs:
+            vendor = recs[0].vendor
+
+    result = await rl_create_asset(
+        org_id, group_id, source_url, asset_type, name,
+        vendor=vendor, apikey=keys["ak"], secretkey=keys["sk"],
+        user_id=downapp_id
+    )
+    return result
+
+
+async def rl_sync_asset_status_user(org_id, asset_id, downapp_id):
+    """User proxy: Check app -> Get keys -> Sync status."""
+    keys = await _get_user_keys(downapp_id)
+    if not keys.get("success"):
+        return keys
+    
+    vendor = "volcengine"
+    dbname = _get_dbname()
+    db = DBPools()
+    async with db.sqlorContext(dbname) as sor:
+        recs = await sor.R("rl_app_user", {"downapp_id": downapp_id})
+        if recs:
+            vendor = recs[0].vendor
+
+    result = await rl_sync_asset_status(
+        asset_id, vendor=vendor,
+        apikey=keys["ak"], secretkey=keys["sk"]
+    )
+    return result
+
+
 # ============================================================
 # Module loader
 # ============================================================
@@ -402,4 +518,11 @@ def load_reallife_asset():
     g.rl_delete_group = rl_delete_group
     g.rl_sync_group_from_vendor = rl_sync_group_from_vendor
     g.rl_sync_assets_from_vendor = rl_sync_assets_from_vendor
+    
+    # Downapp user APIs
+    g.rl_apply = rl_apply
+    g.rl_verify_user = rl_verify_user
+    g.rl_upload_user = rl_upload_user
+    g.rl_sync_asset_status_user = rl_sync_asset_status_user
+    
     return True

scripts/load_path.py

@@ -46,6 +46,17 @@ paths_logined = [
     "/reallife_asset/api/sync_assets.dspy",
     "/reallife_asset/api/get_rl_asset_group_list.dspy",
     "/reallife_asset/api/get_rl_asset_list.dspy",
+    # Downapp user APIs
+    "/reallife_asset/api/rl_apply.dspy",
+    "/reallife_asset/api/rl_verify.dspy",
+    "/reallife_asset/api/rl_upload.dspy",
+    "/reallife_asset/api/rl_status.dspy",
+    # Ops management CRUD
+    "/reallife_asset/api/rl_app_user_create.dspy",
+    "/reallife_asset/api/rl_app_user_update.dspy",
+    "/reallife_asset/api/rl_app_user_delete.dspy",
+    "/reallife_asset/rl_app_user_list",
+    "/reallife_asset/rl_app_user_list/index.ui",
 ]
 
 def run_set_perm(role, path):

wwwroot/api/rl_app_user_create.dspy

@@ -0,0 +1,32 @@
+# Create app record
+org_id = params_kw.get('org_id', (await get_userorgid()) or '0')
+id = params_kw.get('id', getID())
+now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+# Decrypt keys if provided by form? No, usually Ops enters plain text, we encrypt.
+ak = params_kw.get('ak', '')
+sk = params_kw.get('sk', '')
+env = ServerEnv()
+if ak: ak = env.password_encode(ak)
+if sk: sk = env.password_encode(sk)
+
+data = {
+    "id": id,
+    "org_id": org_id,
+    "downapp_id": params_kw.get('downapp_id', ''),
+    "vendor": params_kw.get('vendor', 'volcengine'),
+    "status": params_kw.get('status', 'pending'),
+    "ak": ak,
+    "sk": sk,
+    "callback_url": params_kw.get('callback_url', ''),
+    "remark": params_kw.get('remark', ''),
+    "create_time": now,
+    "update_time": now
+}
+
+db = DBPools()
+dbname = get_module_dbname('reallife_asset')
+async with db.sqlorContext(dbname) as sor:
+    await sor.I("rl_app_user", data)
+
+return {"success": True, "id": id}

wwwroot/api/rl_app_user_delete.dspy

@@ -0,0 +1,9 @@
+id = params_kw.get('id', '')
+if not id: return {"success": False, "message": "id required"}
+
+db = DBPools()
+dbname = get_module_dbname('reallife_asset')
+async with db.sqlorContext(dbname) as sor:
+    await sor.D("rl_app_user", {"id": id})
+
+return {"success": True}

wwwroot/api/rl_app_user_update.dspy

@@ -0,0 +1,31 @@
+id = params_kw.get('id', '')
+if not id: return {"success": False, "message": "id required"}
+
+db = DBPools()
+dbname = get_module_dbname('reallife_asset')
+async with db.sqlorContext(dbname) as sor:
+    recs = await sor.R("rl_app_user", {"id": id})
+    if not recs: return {"success": False, "message": "Not found"}
+
+# Prepare update data
+upd = {}
+for k in ['status', 'remark', 'callback_url', 'vendor']:
+    if params_kw.get(k):
+        upd[k] = params_kw.get(k)
+
+# Handle keys encryption
+ak = params_kw.get('ak', None)
+sk = params_kw.get('sk', None)
+if ak is not None:
+    env = ServerEnv()
+    upd['ak'] = env.password_encode(ak)
+if sk is not None:
+    env = ServerEnv()
+    upd['sk'] = env.password_encode(sk)
+
+upd['update_time'] = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+async with db.sqlorContext(dbname) as sor:
+    await sor.U("rl_app_user", upd, {"id": id})
+
+return {"success": True}

wwwroot/api/rl_apply.dspy

@@ -0,0 +1,11 @@
+downapp_id = params_kw.get('downapp_id', '')
+vendor = params_kw.get('vendor', 'volcengine')
+callback_url = params_kw.get('callback_url', '')
+
+if not downapp_id:
+    return {"success": False, "message": "downapp_id 不能为空"}
+if not callback_url:
+    return {"success": False, "message": "callback_url 不能为空"}
+
+result = await rl_apply((await get_userorgid()) or '0', downapp_id, vendor, callback_url)
+return result

wwwroot/api/rl_check_app_status.dspy

@@ -0,0 +1,16 @@
+downapp_id = params_kw.get('downapp_id', '')
+vendor = params_kw.get('vendor', 'volcengine')
+
+if not downapp_id:
+    return {"success": False, "message": "downapp_id 不能为空"}
+
+keys = await _get_user_keys(downapp_id, vendor)
+if keys.get("success"):
+    # Get full record info
+    dbname = get_module_dbname('reallife_asset')
+    db = DBPools()
+    async with db.sqlorContext(dbname) as sor:
+        recs = await sor.R("rl_app_user", {"downapp_id": downapp_id, "vendor": vendor})
+        if recs:
+            return {"success": True, "status": recs[0].status, "id": recs[0].id, "callback_url": recs[0].callback_url}
+return keys

wwwroot/api/rl_status.dspy

@@ -0,0 +1,8 @@
+asset_id = params_kw.get('asset_id', '')
+downapp_id = params_kw.get('downapp_id', '')
+
+if not asset_id or not downapp_id:
+    return {"success": False, "message": "参数缺失"}
+
+result = await rl_sync_asset_status_user((await get_userorgid()) or '0', asset_id, downapp_id)
+return result

wwwroot/api/rl_upload.dspy

@@ -0,0 +1,11 @@
+group_id = params_kw.get('group_id', '')
+source_url = params_kw.get('source_url', '')
+asset_type = params_kw.get('asset_type', 'Image')
+name = params_kw.get('name', '')
+downapp_id = params_kw.get('downapp_id', '')
+
+if not group_id or not source_url or not downapp_id:
+    return {"success": False, "message": "参数缺失"}
+
+result = await rl_upload_user((await get_userorgid()) or '0', group_id, source_url, asset_type, name, downapp_id)
+return result

wwwroot/api/rl_verify.dspy

@@ -0,0 +1,11 @@
+group_id = params_kw.get('group_id', '') # Optional, if re-creating
+downapp_id = params_kw.get('downapp_id', '')
+project_name = params_kw.get('project_name', 'default')
+
+if not downapp_id:
+    return {"success": False, "message": "downapp_id 不能为空"}
+
+# If group_id is provided, we might be refreshing the link for an existing group?
+# For simplicity, always create new session for user.
+result = await rl_verify_user((await get_userorgid()) or '0', group_id, downapp_id, project_name)
+return result