# 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. 工具卡标注消耗金币数。

## 三、执行步骤

```text
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 视觉验收）

## 五、验收命令（参考）

```bash
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 链路输出、回滚用例证据、视觉验收结论）。