# PROGRESS — C-04 · AI 工具（图片放大最小闭环 + 钱包方案）

- 状态：done

> 日期 2026-09-13 · 范围：`chunyu_project/aitool`（新建）+ `chunyu_project_react`

## 选型
四件套中选**图片放大**做其一最小闭环：Pillow 本地 LANCZOS 2x/4x，
零 key、零外部依赖——mock 链路即生产链路，不被真实 key 阻塞。

## 改动
后端（`chunyu_project/aitool/`，新建 app，已注册 settings + `api/aitool/` 路由）：
1. `models.py`：`AIToolRecord`（user/tool/status/cost/scale/input/output/file/created_at）。
2. `providers.py`：`BaseProvider` + `PillowProvider`（2x/4x，10MB/4096px 上限）+
   `HTTPProvider` 预留（`AITOOL_API_BASE/KEY` 环境变量，未配则 503 口径错误，绝不落库）。
3. `views/upscale_view.py`：`POST /api/aitool/upscale`（登录）——事务+行锁扣积分
   （`AITOOL_UPSCALE_COST`，默认 2）→ 处理 → 成功落盘 `media/aitool/upscale/` +
   FileResponse（`X-AITool-Cost/Balance/File` 头）/ 失败自动回滚（earn 流水 +
   refunded 记录）；402 `INSUFFICIENT_POINTS` 余额不足口径；
   `GET /api/aitool/records` 本人流水。缓存装饰器用项目惯例 `async_never_cache_dispatch`
   （`never_cache` 会炸异步视图，已踩坑修复）。
4. `migrations/0001_initial.py`、`admin.py`、`tests/test_upscale.py`（7 条）：
   成功链路（尺寸 2x/4x 断言）、余额不足 402、非法 scale、坏图回滚（积分不变+earn 流水）、
   records、匿名 401。

前端：
5. `pages/ImageUpscaler/`（新建）：上传/2x|4x/预览/下载/扣费确认 + 402 引导签到。
6. `utils/request.ts`：`aitool.upscale`（blob）+ `getRecords`；`App.tsx` 路由
   `/utility/image-upscaler`；seed 挂 `AI 工具` 分类 + 金币标注（描述含“2 积分/次”）。
7. `docker.env.example`：`AITOOL_PROVIDER/AITOOL_UPSCALE_COST/API_BASE/API_KEY` 说明。

## 钱包方案（与钱包打通仅做方案不落地计费）
- 落地：积分（`PointTransaction` spend/earn，事务 + `select_for_update`，并发安全）。
- 不落地：y币/现金计费、异步队列（同步+超时控制，量大再评审 Celery）、本地大模型
  （rembg/Real-ESRGAN 留 Phase 2）。key 仅环境变量，grep 全仓无残留（除读取代码与示例注释）。

## 验证
```bash
DB_ENGINE=django.db.backends.sqlite3 DB_NAME=".../dev_db.sqlite3" \
python ".../manage.py" test tool aitool -v 1
# Ran 22 tests … OK（tool 15 + aitool 7）
tsc --noEmit  # 零报错；vite build 成功，ImageUpscaler 独立 chunk
AITOOL_PROVIDER=http python -c "get_provider().upscale(...)"
# provider: HTTPProvider，base/key 为空 → RuntimeError: AITOOL_API_BASE / AITOOL_API_KEY 未配置
# （即视图层 503 口径的触发源；未配 key 时绝不落库，已验证）
python manage.py test aitool -v 1  # Ran 7 tests … OK（2026-09-14 复跑）
grep -rn 真实 key 正则 aitool/*.py → 零命中（仅 API_KEY/API_BASE 读取与注释）
```

## 状态
done。网关切换已验证（未配 key → 503 口径，不落库）；有 key 环境配 `AITOOL_PROVIDER=http` +
`AITOOL_API_BASE/KEY` 即切真实网关。遗留：抠图/证件照/生图三件套待排期。