AI 媒体生成与作业提交交互流程

本文梳理 AI 生成图片/视频 与 作业提交 的端到端交互逻辑，说明涉及的接口、数据结构以及前后端协作方式。

一、角色与对象

• 学生/老师（前端用户）
• AI 聊天/生成模块（t2i 文生图、t2v 文生视频）
• 上传与静态资源服务（/upload/save-b64-image、/static/...）
• 作业模块（提交、批改、广场展示）

二、核心数据结构

• 作业提交实体 assignment_submissions 关键字段：
  • answer_text: 文本答案
  • work_name, work_description: 作品名称/描述
  • ai_session_id: 关联 AI 会话
  • attachments: 附件清单（数组），建议元素结构：{ url, type, title?, size?, meta? }
  • grading_status: 批改状态（not_submitted/submitted/grading/graded）
  • is_public: 是否公开到广场

引用：

  - SubmissionUpsert
    - work_name: str | None
    - work_description: str | None
    - ai_session_id: int | None
    - attachments: list[object] | None（附件对象数组，字段示例：{ url, type, title?, size?, meta? }）
    - grading_status: GradingStatus（默认 'submitted'）

三、端到端交互时序

1. 意图识别与生成

• 前端通过 /ai/chat 进行对话，服务端根据意图将请求路由到 t2i（文生图）或 t2v（文生视频）流程。
• 文生图返回可选的 b64_json；文生视频一般为任务制，前端轮询获取成片地址/HLS。

2. 生成结果保存（图片）

• 若拿到 b64_json，前端调用 POST /upload/save-b64-image 将 base64 PNG 保存到静态目录，返回形如 /static/ai/<file>.png 的 URL。

3. 生成结果使用（提交作业）

• 前端在调用 POST /assignments/{assignment_id}/submission 时，将得到的图片/视频 URL 作为 attachments 传入，同时可记录 ai_session_id 以溯源本次 AI 生成。

4. 教师批改与广场展示

• 教师可对提交进行评分与反馈；广场列表 /square/works 会将公开的作品（is_public=true）连同 attachments 一同展示。

四、相关接口清单

• 保存 AI 生成图片（PNG）：

@router.post("/save-b64-image")
async def save_b64_image(data: str, request: Request, user: User | None = Depends(get_current_user_optional)):
    """
    将前端/AI返回的 `b64_json` 字符串保存为 PNG 文件，并返回 `/static/...` URL。
    入参：纯 base64（不带 data:image/png;base64, 前缀）。
    """
    ...
    return {"url": url}

• 提交/更新作业（支持附件、AI 会话溯源）：

@router.post("/assignments/{assignment_id}/submission", response_model=SubmissionOut)
async def submit_assignment(...):
    """提交/更新作业"""

• 通用图片上传（表单文件）：

@router.post("/images")
async def upload_image(file: UploadFile = File(...)) -> {"url": str}

用途：上传任意图片（.png/.jpg/.jpeg/.webp/.gif/.bmp），返回可公开访问的 /static/images/... URL，可直接用于作业附件或学校 Logo 等。

• 广场作品列表（读取附件并展示）：

async def list_square_works(...):
    query = select(..., AssignmentSubmission.attachments, ...)
    ...

五、时序图（示意）

sequenceDiagram
  participant U as 前端用户
  participant AI as AI 聊天/生成
  participant UP as 上传服务
  participant AS as 作业服务

  U->>AI: /ai/chat （识别为 t2i/t2v）
  AI-->>U: 返回生成计划/结果（图片 b64 或视频任务）
  alt 图片b64
    U->>UP: POST /upload/save-b64-image
    UP-->>U: 返回 /static/ai/xxx.png
  else 视频
    U->>AI: 提交/轮询 t2v 任务
    AI-->>U: 返回可播放 URL（或 HLS）
  end
  U->>AS: POST /assignments/{id}/submission（attachments 含 URL, ai_session_id）
  AS-->>U: 返回 SubmissionOut（含评分/状态/时间等）

六、前端提交示例

{
  "answer_text": "我的思路与步骤…",
  "work_name": "AI 生成作品",
  "attachments": [
    { "url": "/static/ai/abcd.png", "type": "image", "title": "草图1" },
    { "url": "https://example.com/hls/xyz.m3u8", "type": "video", "title": "成片" }
  ],
  "ai_session_id": 123,
  "grading_status": "submitted"
}

七、权限与限流

• POST /upload/save-b64-image 与 /ai/* 接口在默认配置下需要鉴权（AI_REQUIRE_AUTH）并受每分钟限流（AI_RATE_LIMIT_PER_MINUTE）。

八、运维与定位建议

• 生成失败或资源不可读时，优先检查：
  • 上传目录 /uploads/ai、/uploads/courseware 权限
  • 反向代理与 StaticFiles 的 /static 挂载
  • AI 上游返回内容是否为合规的 b64_json 或合法可访问的视频 URL