Backend 功能规格

按业务域描述后端能力、业务规则与状态机。接口细节见 api.md；表结构见 data-model.md。

1. 认证

1.1 Admin

• 短信：POST /api/admin/auth/send-sms → POST /api/admin/auth/login
• 仅 admin_users 且 is_active=true 可登录
• Token 用于全部 /api/admin/*（auth 除外）

1.2 用户 / 代理

• POST /api/auth/send-code / login / GET /me
• login 支持 as_agent=true：首次可为该手机号开通代理档案
• Agent 专属接口需 CurrentAgent

规则：禁用用户（users.status=0）不可登录业务接口。

2. 产品、面料与风格

• Admin CRUD：大类、子类（树）、面料类型/材质、子类-材质关联（含批量）
• 模板风格 product_styles：挂在品类下；主图/详情 C 端选型用
• 子类 applicable_functions 控制虚拟影棚等适用；主图/详情工作台改走品类×风格
• C 端只读目录：/api/user/catalog/*（含 styles、image-templates）、/api/sub-types

3. 模板

能力	规则
构图/场景/模特	CRUD + 姿势；子类关联 PUT 覆盖式
主图/详情	CRUD + 子图 CRUD/排序；匹配键 品类×风格（product_category_ids ∩ style_ids）；同风格可多套；match 返回首条，list 返回全量摘要
复刻（爆款）	仍按 HotStyle / hot_style_id（不走品类×风格）
Word 导入	主图/详情传 product_category_id+style_id（可选目标套）→ word_sessions/items → 图片入模板
库模板测试	preview / test-generate / 历史 runs
Prompt 测试	Admin 预览与生图，落 prompt_test_runs
C 端生图 params	task_type=main_image\|detail_image；mode=auto\|copy；必填 custom_product/custom_material；复刻必填 input_images.reference；不再提交子类/面料

4. AI 模型与任务

• 物理模型 + Key；模型池成员增删改与健康检查
• 共享账号创建/绑定/解绑
• Admin 任务列表、取消、重试、软删；预览与测试生成
• C 端：/api/user/tasks/* 正式生成与批量任务；/api/tasks 任务查询创建
• 扣费：成功路径写 consumption_records 与配额/账本

任务状态机：pending → processing → completed | failed；可 cancelled；失败可 retry。

5. 画布

• 项目 CRUD：document JSONB；revision 乐观锁（冲突 409）
• 文件夹单层；删文件夹项目归未分组
• 上传 / 预签名 / resolve-urls / proxy-image
• generate / generate-text；RunningHub config + run
• GET /config 下发前端画布配置

6. 用户资产

• 用户维度资产库，独立于画布项目软删
• 上传走 storage；列表签发下载 URL

7. 计费（C 端）

• 浏览在售方案 → 下单 → prepay → 支付回调/mock
• 查询订单、配额、并发、消费、账本
• 代理注册/提现（billing 路径，部分前端未接）

订单状态机：pending → paid / completed / cancelled / refunded。

支付成功副作用：订阅/配额更新、流水、可选佣金记录。

8. 代理门户 API

• 资料、dashboard、客户与交易、佣金列表
• PUT .../commission-rate：语义为客户优惠比例 customer_discount_rate
• 落地：GET/POST /api/landing/{code} — 点击统计 + 永久绑定
• 结算：扫码会话轮询 / 商户资料
• 导出：customers / transactions / commissions / summary（blob）

绑定规则：customer_id 唯一；已绑定不可改绑。

分账状态机：pending → settled → withdrawn；可 clawed_back。

提现状态机：pending → approved | rejected（Admin）。

9. Admin 计费运营

• 方案 CRUD/排序；订单查询与退款
• 代理 CRUD；分账规则；分账结算；提现审批
• 流水/消费查询；配额重置；收入汇总

10. 运营配置与统计

• system_configs、banners、feature_cards
• operation_logs 只读
• statistics：overview / usage / tasks / revenue

11. 功能 ↔ 表映射（摘要）

功能域	主表
登录用户	users, admin_users
产品面料	product_, fabric_, sub_type_fabric_materials
模板	templates, template_images, sub_type
AI	ai_model*, tasks, task_params
画布	canvas_projects, canvas_folders
计费	member_plans, orders, payment_, usage_quotas, consumption_, transaction_ledger
代理	agents, customer_agent_bindings, commission_*, agent_withdrawals, agent_link_clicks