refactor: extract generation core service

docs/00-ai-start-here.md

@@ -38,7 +38,7 @@
 
 ## 当前阶段
 
-当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」、T-611「用户端品牌名统一为虾皮圈」与 T-612「生图同步接口止血」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615：T-612 已先做同步接口上游硬截止止血；下一步 T-613 抽共享生成 core，随后 T-614 新增异步提交轮询接口，T-615 观察旧同步接口用量。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。
+当前项目处于：**Phase 6 增强任务推进期**。Phase 2 计费核心已完成到 T-204；Phase 3 已完成 T-301 API Key 鉴权、T-302 生成标题 / 图片接口、T-303 余额查询接口、T-304 充值回调、T-305 扫码充值下单 + 轮询与 T-306 对外 API 安全加固；Phase 4 已完成 T-501 注册 / 登录（allauth）、T-502 API Key 自助管理页、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化；Phase 5 已完成 T-401 运营后台完善、T-402 MVP 完整验收与 T-403 部署 / 运行文档；Phase 6 已完成 T-601「可用别名发现」、T-602「django-admin 中文化第 1-3 层」、T-603「django-admin 字段级中文化」、T-604「中文敏感词本地过滤」、T-605「免邮箱验证策略落地」、T-606「公开首页 + 客户端下载入口」、T-607「桌面端最新版本检查接口」、T-608「新用户注册赠送 100 点试用点数」、T-609「桌面端版本检查接口增加强制更新标记」、T-610「首页导入模板下载入口」、T-611「用户端品牌名统一为虾皮圈」、T-612「生图同步接口止血」与 T-613「抽生成核心 service」。生图慢 / 504 / 客户端超时已拆为 T-612~T-615：T-612 已先做同步接口上游硬截止止血，T-613 已抽共享生成 core；下一步 T-614 新增异步提交轮询接口，随后 T-615 观察旧同步接口用量。生产侧仍需补真实支付回调到账闭环；邮件服务仅用于后续密码找回/通知等邮件能力，不阻塞注册登录。
 
 优先路径：
 
@@ -48,7 +48,7 @@
 4. Phase 3：对外 API 与充值 —— T-301 Key 鉴权、T-302 生成接口、T-303 余额查询、T-304 充值回调、T-305 扫码下单与轮询、T-306 安全加固已完成。
 5. Phase 4：用户端（Django 模板 SSR）—— T-501 注册登录、T-502 API Key 管理、T-503 个人中心 / 记录页、T-504 充值页与 T-505 用户端审核优化已完成。
 6. Phase 5：后台与发布 —— T-401 运营后台完善、T-402 完整验收 MVP、T-403 部署 / 运行文档已完成；计划内 MVP 任务已收尾。
-7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612 已完成生图同步接口止血；当前下一个可领取任务为 T-613。
+7. Phase 6：增强（MVP 后）—— T-601 可用别名发现已完成，实现 `/api/v1/models` 与 portal 只读「可用模型」页；T-602 已完成 django-admin 分组/表名中文化；T-603 已完成字段级中文标签代码与 no-op 迁移并人工确认 admin 字段中文化；T-604 已完成中文敏感词本地过滤；T-605 已完成免邮箱验证策略落地；T-606 已完成公开首页 + 客户端下载入口；T-607 已完成桌面端最新版本检查接口；T-608 已完成新用户注册赠送 100 点试用点数；T-609 已完成桌面端版本检查接口增加强制更新标记；T-610 已完成首页导入模板下载入口；T-611 已完成用户端品牌名统一为虾皮圈；T-612 已完成生图同步接口止血；T-613 已完成抽生成核心 service；当前下一个可领取任务为 T-614。
 
 ## 领取任务规则
 

docs/04-architecture.md

@@ -34,12 +34,12 @@
 
 - API Key 鉴权（自定义 DRF Authentication，哈希比对），把请求绑定到 Key 所属的注册用户。
 - 参数校验、请求/响应序列化、错误码统一。
-- 编排单次调用：调用计费层预扣 → 调 AI 层 → 成功确认 / 失败退点 → 写调用记录。
+- 编排单次调用：通过生成核心 service 组织「审核 → 图片输入处理 → 别名 / 计费 → 预扣 → 调 AI 层 → 成功确认 / 失败退点 → 写调用记录」。
 - 不直接写点数余额字段，必须走计费层提供的方法。
 
 T-301 已实现 `ApiKeyAuthentication` 与 `ExternalApiView`：外部 API 使用 `Authorization: Bearer <API_KEY>`，通过 SHA-256 hash 定位 `ApiKey -> User`，成功后 `request.user` 为所属用户、`request.auth` 为本次 API Key；缺失/无效 Key 返回 `401 unauthorized`，用户或 Key 禁用返回 `403 account_disabled`。生成/余额等外部 API 应继承 `ExternalApiView`，不要挂 `SessionAuthentication`。
 
-T-302 已实现 `/api/v1/generate/title` 与 `/api/v1/generate/image`：API 层只做鉴权、参数校验和编排；别名解析、Provider 选择、计费计算、预扣、成功确认、失败退点分别调用 `apps.ai` / `apps.billing` 既有模块。图片结果 MVP 先用本地 `default_storage` 保存到 `MEDIA_ROOT/generated/images/...` 并返回 `image_url`；`CallRecord` 只写 URL / 摘要，不保存 provider `raw` 或 base64。
+T-302 已实现 `/api/v1/generate/title` 与 `/api/v1/generate/image`：API 层只做鉴权、参数校验和编排；别名解析、Provider 选择、计费计算、预扣、成功确认、失败退点分别调用 `apps.ai` / `apps.billing` 既有模块。T-613 已把生成链路抽为 `apps.api.generation` 的核心阶段：`prepare_generation()` 负责审核、图片输入、别名、Provider 与计费准备；`precharge_generation()` 只调用 billing 预扣；`execute_precharged_generation()` 复用已预扣 `CallRecord` 调上游并成功确认或失败退点，供旧同步接口和后续异步 worker 共用。图片结果 MVP 先用本地 `default_storage` 保存到 `MEDIA_ROOT/generated/images/...` 并返回 `image_url`；核心阶段通过 URL 构建器生成外部 URL，不依赖 DRF `Request`；`CallRecord` 只写 URL / 摘要，不保存 provider `raw` 或 base64。
 
 T-303 已实现 `/api/v1/balance`：外部 API 继续只认 API Key，API 层调用 `apps.billing.services.get_balance_snapshot()` 读取当前钱包余额；测试覆盖余额响应与流水累加一致的场景。
 

docs/api.md

@@ -21,7 +21,7 @@
 
 T-301 已实现对外 API 鉴权基线：`apps.api.authentication.ApiKeyAuthentication` 只解析 `Authorization: Bearer <API_KEY>`；生成、余额等外部 API 视图应继承 `apps.api.views.ExternalApiView`，不接受 Web session。
 
-T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api/v1/generate/image` 已接入 API Key 鉴权、别名解析、计费规则、预扣点、Provider 调用、成功确认和失败退点；图片结果当前以本地 `MEDIA_ROOT` 保存并返回 `image_url`，后续可替换为对象存储。
+T-302 已实现生成接口基线：`POST /api/v1/generate/title` 与 `POST /api/v1/generate/image` 已接入 API Key 鉴权、别名解析、计费规则、预扣点、Provider 调用、成功确认和失败退点；图片结果当前以本地 `MEDIA_ROOT` 保存并返回 `image_url`，后续可替换为对象存储。T-613 起内部实现已抽为生成核心 service，旧同步接口仍保持原字段、状态码和错误语义；后续异步 worker 必须复用同一套预扣、执行、确认和退点阶段，不得复制第二套资金逻辑。
 
 T-303 已实现余额查询基线：`GET /api/v1/balance` 已接入 API Key 鉴权，返回当前 `UserWallet.points_balance`，并保留旧字段同时新增不含邮箱的 `account` 账号展示对象；测试覆盖响应余额与 `PointsLedger.points_delta` 累加值一致的账务场景，并确认 Web session 不能调用该外部接口。