Backend 接口文档
权威来源：src/backend/api/ + schemas/。本地可对照 FastAPI /docs。
响应包络：{ "code": number, "message": string, "data": T | null }；成功默认 code=200。
Auth：Authorization: Bearer <token>，除非标注「公开」。
路径前缀约定：Admin 路由相对 /api/admin；其余相对 /api（sub_types 自带 /api）。
1. 通用约定
| 项 |
说明 |
| 分页 |
常见 page / page_size；返回 PageResult 或 PaginatedOut |
| 错误 |
业务错误 code≠200；HTTP 401/403/404/409（如乐观锁） |
| 文件上传 |
multipart/form-data；经 storage 落 OSS，返回 URL 或 object_key |
| 副作用 |
下列「副作用」列标注写库表 |
2. Admin 认证（公开）
| Method |
Path |
Auth |
Body |
说明 |
| POST |
/api/admin/auth/send-sms |
公开 |
{ phone } |
发短信 |
| POST |
/api/admin/auth/login |
公开 |
{ phone, code } |
返回 Admin JWT |
3. Admin — 产品、面料与风格
| Method |
Path |
副作用 |
| GET/POST |
/api/admin/product-categories |
写 categories |
| GET/PUT/DELETE |
/api/admin/product-categories/{id} |
|
| PUT |
/api/admin/product-categories/sort |
排序 |
| GET/POST |
/api/admin/product-sub-types |
|
| GET/PUT/DELETE |
/api/admin/product-sub-types/{id} |
|
| GET |
.../{id}/fabric-materials / .../suggested |
|
| POST |
/api/admin/product-sub-types/fabric-materials/batch |
批量关联 |
| CRUD |
/api/admin/fabric-types |
|
| CRUD |
/api/admin/fabric-materials |
|
| CRUD |
/api/admin/product-styles |
模板风格（挂品类；主图/详情选型） |
| GET/PUT |
/api/admin/product-sub-types/{id}/comp-templates 等 scene/model |
关联覆盖 |
Schema：schemas/admin/product.py、风格相关 schema。
4. Admin — 模板
4.1 构图 / 场景 / 模特
| 资源 |
路径前缀 |
| 构图 |
/api/admin/comp-templates GET/POST/PUT/DELETE |
| 场景 |
/api/admin/scene-templates |
| 模特 |
/api/admin/model-templates + /{id}/poses CRUD |
4.2 主图 / 详情 / 复刻
路径模式（以 main 为例，detail/replica 同构）：
| Method |
Path |
| GET |
/api/admin/main-image-templates |
| GET |
/api/admin/main-image-templates/match |
| POST/PUT/DELETE |
/api/admin/main-image-templates / {id} |
| GET/POST |
/{id}/images |
| PUT/DELETE |
/{id}/images/{image_id} (+ /sort) |
主图/详情 match 现网：优先 query product_category_id + style_id（品类×风格）；同风格可多套。Create/Update body 写 product_category_ids / style_ids。旧 product_sub_type_id+fabric_material_id 兼容仍保留，C 端主路径不再使用。
4.3 Word / 库模板 / Prompt 测试
| Method |
Path |
说明 |
| POST |
/api/admin/word/upload |
上传 docx；主图/详情传 product_category_id+style_id（可选目标套） |
| GET/DELETE |
/api/admin/word/sessions / {id} |
|
| GET/DELETE |
/api/admin/word/prompt-items / {id} |
|
| GET/POST |
/api/admin/word/batch-test-* |
批量测试与重试（含 stream） |
| POST |
/api/admin/library-templates/word-batch-import |
|
| POST |
/api/admin/library-templates/{library_type}/{template_id}/test-generate |
|
| GET |
/api/admin/library-templates/.../test-runs |
|
| GET |
/api/admin/prompt-test-runs / {run_id} |
|
| POST |
/api/admin/tasks/preview-prompt |
预览组装 |
| POST |
/api/admin/tasks/test-generate |
测试生图 |
5. Admin — AI 模型与任务
| Method |
Path |
说明 |
| CRUD |
/api/admin/ai-models |
物理模型 |
| CRUD |
/api/admin/ai-models/{id}/keys |
私有 Key |
| CRUD |
/api/admin/ai-model-groups |
模型池 |
| POST/PUT/DELETE |
.../members / health |
成员与健康 |
| CRUD |
/api/admin/api-accounts |
共享账号 |
| POST/DELETE |
.../bind |
绑定模型 |
| CRUD |
/api/admin/model-generation-attributes |
模特属性 |
| GET |
/api/admin/tasks |
任务列表 |
| GET/DELETE |
/api/admin/tasks/{id} |
|
| POST |
/api/admin/tasks/{id}/cancel / retry |
|
副作用：tasks / ai_* / prompt_test_runs。
6. Admin — 用户 / 配置 / 统计 / 存储
| Method |
Path |
说明 |
| GET |
/api/admin/users / {id} |
|
| PUT |
/api/admin/users/{id}/status |
启停 |
| POST/DELETE |
/api/admin/users/{id}/admin |
授予/撤销管理员 |
| GET/POST |
/api/admin/users/{id}/subscriptions |
|
| GET/PUT |
/api/admin/users/{id}/quotas / {quota_id} |
|
| GET |
/api/admin/users/{id}/models |
用户模特 |
| GET/PUT |
/api/admin/system-configs / {config_key} |
|
| CRUD |
/api/admin/banners / feature-cards |
|
| GET |
/api/admin/operation-logs |
|
| GET |
/api/admin/statistics/overview\|usage\|tasks\|revenue |
|
| POST |
/api/admin/storage/upload |
经 storage 上传 |
7. Admin — 计费运营
挂载于 /api/admin（billing router 无额外 prefix）：
| Method |
Path |
说明 |
| GET/POST |
/api/admin/plans |
方案 |
| GET/PUT |
/api/admin/plans/{id} |
|
| POST |
/api/admin/plans/reorder |
|
| GET |
/api/admin/orders / {id} |
|
| POST |
/api/admin/orders/{id}/refund |
退款 |
| GET |
/api/admin/withdrawals |
|
| POST |
/api/admin/withdrawals/{id}/approve\|reject |
|
| GET/POST |
/api/admin/agents |
|
| GET/PUT |
/api/admin/agents/{id} |
|
| GET/POST/PUT |
/api/admin/commission-rules |
|
| GET |
/api/admin/commission-records |
|
| POST |
/api/admin/commission-records/settle |
批量结算 |
| GET |
/api/admin/ledger / consumption |
|
| POST |
/api/admin/quota-reset |
|
| GET |
/api/admin/revenue-summary |
|
| POST |
/api/admin/commission-settlements/close |
月结关账（幂等） |
| GET |
/api/admin/commission-settlements |
月结批次列表（settle_month） |
| GET |
/api/admin/billing/recon/batches |
日终对账批次（biz_date） |
| POST |
/api/admin/billing/recon/run |
触发日终对账 |
| POST |
/api/admin/billing/replay/user |
单户回放（用户手机号） |
| POST |
/api/admin/billing/replay/agent |
单户回放（代理手机号） |
Schema：schemas/billing.py、schemas/admin/*。业务规则见 membership-agent-sales-guide.md；表结构见 data-model/billing.md。
8. 用户认证（Canvas / Agent）
| Method |
Path |
Auth |
Body / 说明 |
| POST |
/api/auth/send-code |
公开 |
{ phone } |
| POST |
/api/auth/login |
公开 |
{ phone, code, as_agent? } → JWT |
| GET |
/api/auth/me |
User |
当前用户 |
9. 代理门户与落地 / 结算 / 导出
9.1 Agents
| Method |
Path |
Auth |
| POST |
/api/agents/register |
视实现（公开注册，前端可能未挂） |
| GET |
/api/agents/me |
Agent |
| PUT |
/api/agents/me/commission-rate |
Agent；body 优惠比例 → customer_discount_rate |
| GET |
/api/agents/me/dashboard |
Agent |
| GET |
/api/agents/me/customers / {id} |
Agent |
| POST |
/api/agents/me/customers/{customer_id}/promote-sub-agent |
Agent；提拔客户为二级代理（设 sub_agent_share_rate） |
| GET |
/api/agents/me/sub-agents |
Agent；二级代理列表 |
| GET |
/api/agents/me/transactions |
Agent |
| GET |
/api/agents/me/commissions |
Agent |
9.2 Landing
| Method |
Path |
Auth |
副作用 |
| GET |
/api/landing/{referral_code} |
公开 |
agent_link_clicks |
| POST |
/api/landing/{referral_code}/bind |
User |
customer_agent_bindings |
9.3 Settlement
| Method |
Path |
Auth |
| GET |
/api/settlement/status |
Agent |
| POST |
/api/settlement/scan/alipay / wechat |
Agent → 扫码会话 |
| GET |
/api/settlement/scan/{token}/status |
Agent |
| POST |
/api/settlement/scan/{token}/mock-confirm |
Agent（开发） |
| POST |
/api/settlement/merchant-info |
Agent |
9.4 Export（blob）
| Method |
Path |
| GET |
/api/export/customers / transactions / commissions / summary |
10. C 端计费与支付
| Method |
Path |
Auth |
说明 |
| GET |
/api/billing/plans |
公开/User |
在售方案 |
| GET |
/api/billing/plans/{plan_id}/quote |
User |
新购/升级报价（含代理折扣） |
| POST |
/api/billing/orders |
User |
创建订单 |
| POST |
/api/billing/orders/{id}/prepay |
User |
预支付参数 |
| POST |
/api/billing/orders/{id}/sync-pay |
User |
主动查单（回调丢失兜底） |
| GET |
/api/billing/orders / {id} |
User |
|
| GET |
/api/billing/quotas |
User |
按 quota_type 的 total/used |
| GET |
/api/billing/concurrency |
User |
{ concurrent_tasks } |
| GET |
/api/billing/storage |
User |
储存用量 { storage_gb, total_bytes, used_bytes, remaining_bytes } |
| GET |
/api/billing/consumption |
User |
扣点记录 |
| GET |
/api/billing/ledger |
User |
用户流水 |
| GET |
/api/billing/login-points/today |
User |
今日登录积分状态 |
| POST |
/api/billing/login-points/claim |
User |
领取今日登录积分 |
| POST |
/api/billing/agents/register |
User |
|
| GET |
/api/billing/agents/me |
Agent |
|
| POST |
/api/billing/agents/me/withdraw |
Agent |
提现申请 |
| GET |
/api/billing/agents/me/commissions |
Agent |
|
| GET |
/api/billing/agents/me/withdrawals |
Agent |
我的提现记录 |
| POST |
/api/payment/notify/{method} |
渠道 |
回调验签 |
| GET |
/api/payment/return |
公开 |
跳转回 |
| POST |
/api/payment/mock-pay/{order_no} |
开发 |
mock 支付成功 |
订单副作用：orders、payment_records、subscriptions/usage_quotas、transaction_ledger、commission_records。
储存限容口径见 membership-agent-sales-guide.md：上传成功即占容；AI 生成图落 OSS 同样占容。
11. 画布 /api/canvas
| Method |
Path |
Auth |
说明 |
| GET |
/config |
User |
画布配置 |
| POST |
/upload |
User |
上传 |
| POST |
/generate |
User |
文生图 |
| POST |
/generate-text |
User |
文生文 |
| GET/POST |
/projects |
User |
列表/创建 |
| GET/PUT/PATCH/DELETE |
/projects/{id} |
User |
含 revision |
| PUT |
/projects/{id}/folder |
User |
移动文件夹 |
| GET/POST |
/folders |
User |
|
| PUT |
/folders/sort / {id} |
User |
|
| DELETE |
/folders/{id} |
User |
项目归未分组 |
| POST |
/assets/presign-upload |
User |
预签名上传（预检容量） |
| POST |
/assets/confirm-upload |
User |
预签名 PUT 成功后确认占容 { object_key, size } |
| POST |
/assets/release-storage |
User |
画布删资产时释容 { object_key, size } |
| POST |
/assets/resolve-urls |
User |
批量解析下载 URL |
| POST |
/assets/proxy-image |
User |
代拉远程图 |
| GET |
/runninghub/config |
User |
|
| POST |
/runninghub/run |
User |
|
Schema：schemas/canvas.py。冲突：revision 不匹配 → HTTP 409。
12. C 端目录与生图 /api/user
| Method |
Path |
Auth |
| GET |
/api/user/task-types |
User |
| GET |
/api/user/catalog/categories |
User |
| GET |
/api/user/catalog/sub-types |
User |
| GET |
/api/user/catalog/fabric-materials/{sub_type_id} |
User |
| GET |
/api/user/catalog/styles |
User |
| GET |
/api/user/catalog/hot-styles |
User |
| GET |
/api/user/catalog/hot-styles/{hot_style_id} |
User |
| GET |
/api/user/catalog/image-templates |
User |
| GET |
/api/user/catalog/image-template/match |
User |
| GET |
/api/user/catalog/image-template/{id}/images |
User |
| GET |
/api/user/catalog/ai-models |
User |
| GET |
/api/user/catalog/comp-templates 等 scene/model(+poses) / fabric-types |
User |
| POST |
/api/user/storage/upload |
User |
| POST |
/api/user/tasks/preview-prompt |
User |
| POST |
/api/user/tasks/generate |
User |
| POST |
/api/user/tasks/batch-generate |
User |
| GET |
/api/user/batch-jobs/{job_id} |
User |
| POST |
/api/user/batch-jobs/{job_id}/items/{item_index}/retry |
User |
爆款模板：
GET /catalog/hot-styles：可选 category_id / product_sub_type_id 过滤启用款式GET /catalog/hot-styles/{id}：详情含模板图摘要batch-generate 支持 task_type=hot_template；params 需 hot_style_id + product_sub_type_id + ai_model_id + 产品参考图等，不要求 fabric_material_id；进度与 retry 与主图/详情相同
主图 / 详情（品类×风格）：
GET /catalog/styles?category_id=：品类下启用风格GET /catalog/image-templates?template_type=main|detail&product_category_id=&style_id=：同风格多套摘要（封面优先 Admin 指定，否则首图）GET /catalog/image-template/match：同上参时返回首条（兼容）batch-generate task_type=main_image|detail_image：params 含 product_category_id、style_id、image_template_id、mode=auto|copy、custom_product/custom_material（必填）、可选 custom_other；mode=copy 须 input_images.reference；不再提交 product_sub_type_id / fabric_material_id
图现 Chat 会话归属（正文在 Hermes，backend 只存映射）：
| Method |
Path |
Auth |
| GET/POST |
/api/user/chat/sessions |
User |
| PATCH/DELETE |
/api/user/chat/sessions/{id} |
User |
| GET |
/api/user/chat/sessions/{id}/messages |
User |
公开子类：
| Method |
Path |
| GET |
/api/sub-types |
| GET |
/api/sub-types/{id}/fabric-materials |
13. 用户资产与任务
| Method |
Path |
Auth |
| GET/POST |
/api/user-assets / upload |
User |
| GET/PUT/DELETE |
/api/user-assets/{id} |
User |
| POST |
/api/tasks |
User 创建 |
| GET |
/api/tasks / {id} |
User |
14. 接口完整清单（方法 + 相对路径）
以下为从路由装饰器抽取的清单。Admin 项需加前缀 /api/admin；已含 /api 或 /canvas 等的按表内路径理解。
Admin（前缀 /api/admin）
GET/POST/PUT/DELETE /ai-model-groups[/...]
GET/POST/PUT/DELETE /ai-models[/.../keys]
GET/POST/PUT/DELETE /api-accounts[/.../bind]
POST /auth/send-sms|/auth/login
CRUD /banners|/feature-cards|/comp-templates|/scene-templates
CRUD /model-templates[+poses]
CRUD+match+images /main-image-templates|/detail-image-templates|/replica-image-templates
CRUD /fabric-types|/fabric-materials|/product-categories|/product-sub-types
子类模板关联 /product-sub-types/{id}/(comp|scene|model)-templates
CRUD /model-generation-attributes|/users[...]
GET/POST... /tasks|/prompt-test-runs|/word/*|/library-templates/*
GET/PUT /system-configs|/operation-logs|/statistics/*
POST /storage/upload
计费 /plans|/orders|/withdrawals|/agents|/commission-*|/ledger|/consumption|/quota-reset|/revenue-summary
非 Admin（前缀多为 /api）
/auth/* /agents/* /landing/* /settlement/* /export/*
/payment/* /billing/* /canvas/* /user/* /user-assets/* /tasks/*
/api/sub-types/*
完整逐行列表可由 scripts/_extract_routes.py（开发辅助）再生；以代码为准。
15. 联调提示
- Admin 前端
adminHttpClient baseURL=/api/admin
- Agent/Canvas
httpClient baseURL=/api
- Vite 开发代理将
/api → localhost:8001
- 密钥类字段响应中脱敏；请求勿提交真实生产密钥到文档仓库