vscode-workbench/PLANNING/tasks/C-04-AI工具四件套.md

C-04 · AI 工具四件套（抠图/证件照/放大/生图）

字段	值
项目	可乐工具 · 后端新建 aitool app + chunyu_project_react
优先级	P0 · M2
建议模型	deepseek-v4.1-flash（主）/ gemini-3.8-flash（图像质量验收）
依赖	无
预估	4 天

一、背景（为什么做）

2026 年工具站最大流量来源已全线 AI 化（ToolFk：文生图、图生视频、抠图、证件照、图片放大、TTS）；本产品 AI 能力仅百度翻译一项（docs/产品问题分析与改造路线.md P0-2）。四件套是流量 + 金币消费场景的双重补位。

二、目标（交付物）

后端：新建 aitool app

1. 四个端点（全部异步、adrf 风格）：
   • POST /api/aitool/matting 抠图（输入图片 → 透明底 PNG）
   • POST /api/aitool/id-photo 证件照（输入人像 → 背景色可选，1 寸/2 寸规格裁剪）
   • POST /api/aitool/upscale 图片放大（输入图 → 2x/4x）
   • POST /api/aitool/text2img 文生图（prompt → 图片）
2. Provider 抽象层（关键设计）：
   • BaseProvider 接口 + MockProvider（无 key 也能全链路跑通，产出占位图）+ HTTPProvider（可配置第三方 API 网关，baseURL/key 全走环境变量）
   • .env.example 增 AITOOL_PROVIDER=mock|http、AITOOL_API_BASE、AITOOL_API_KEY
   • 绝不把 key 落库、绝不出现在响应里
3. 钱包打通：每次调用扣金币（单价按工具配置，如抠图 2 币/张）；扣减与流水复用现有 PointTransaction；处理失败自动回滚金币；余额不足返回明确错误码。
4. 处理产物存储：复用现有媒体存储惯例（media 目录），产出可下载 URL。

前端

5. Utility.tsx 增"AI 工具"分类 + 4 个工具页（上传/参数/预览/下载/扣费确认）。
6. 工具卡标注消耗金币数。

三、执行步骤

1. 侦察现有 wallet/PointTransaction 扣减接口与前端金币组件（复用，不重造）
2. aitool app：模型可省（先用现有 media 存储 + 记录表：id/user/tool/status/cost/created_at）
3. Provider 抽象 + Mock 全链路先行（不阻塞于真实 key）
4. 钱包接入：扣减 → 处理 → 成功落账 / 失败回滚（事务化）
5. 前端 4 页 + 分类
6. 真实 provider 接入说明（文档：如何配 key 切换）

四、验收标准

• mock 模式下四工具全链路：上传 → 处理 → 预览 → 下载
• 金币：调用扣减正确；失败回滚（断网/超时模拟）；流水记录可查
• 并发同用户两次调用扣减不串（事务正确）
• 前端分类与四个页面可用，余额不足有明确引导
• key 仅环境变量；grep 仓库无任何 key 残留
• 图像质量抽查：抠图边缘、放大对比、证件照裁剪规格（gemini 视觉验收）

五、验收命令（参考）

cd chunyu_project && python manage.py test aitool -v 2
# 手工链路（mock）：
# 上传测试图 → POST /api/aitool/matting → 下载 PNG → 查看透明底

六、边界（不许做）

• 不在 MVP 引入本地大模型部署（rembg/Real-ESRGAN 本地化留待 Phase 2 评审）
• 不动现有百度翻译链路
• 不做异步队列（先同步 + 超时控制；量大再评审 Celery/Dramatiq）

七、交接

写 PROGRESS_C-04.md（含 mock 链路输出、回滚用例证据、视觉验收结论）。