产品需求总览¶
面向测试与新成员的「系统全景」。看完本文你能知道：图现 AI 有哪些功能、谁来用、各模块在哪。 验收清单见各端 requirements.md；上手命令见 新手上手指南；跨模块流程见 业务流程图集。
1. 系统定位¶
图现 AI（tuxianai.com） 是面向纺织/家纺行业的 AI 生图平台。核心能力：用户上传产品图 → 选模板/场景/面料 → AI 生成营销图。配套会员计费、代理商推广分账、运营后台。
四端 + 后端微服务：
| 端 | 角色 | 目录 | 端口 |
|---|---|---|---|
| infinitecanvas | 终端用户（生图/画布/账号） | src/infinitecanvas/ |
5173 |
| agent-system | 代理商（客户/分账/提现） | src/agent-system/ |
5174 |
| admin-system | 运营（Canvas Admin） | src/admin-system/ |
5175 |
| chat | 图现 Chat（Hermes 流式） | src/chat/ |
5178 |
| backend | 主 API | src/backend/ |
8001 |
| storage | OSS 微服务（AK 隔离） | src/storage/ |
8002 |
端口以各
vite.config.ts/Settings.port为准。backend-worker消费 Redis Stream 无端口。
2. 功能模块全景¶
后端（按业务域）¶
| 业务域 | 职责 | 路由前缀 | 关键文件 |
|---|---|---|---|
| 认证 | 短信登录、JWT、as_agent 开通 | /api/auth、/api/admin/auth |
api/auth.py、api/admin/auth.py |
| 产品与面料 | 大类/子类/面料类型/面料材质 CRUD + 关联 | /api/admin/product-*、/api/admin/fabric-* |
api/admin/products.py |
| 模板库 | 构图/场景/模特/主图/详情/复刻/虚拟影棚 + Word 导入 | /api/admin/*-templates、/api/admin/word/* |
api/admin/library_templates.py |
| AI 模型与任务 | 物理模型/模型池/共享账号/任务调度 | /api/admin/ai-models、/api/admin/tasks |
api/admin/ai_models.py |
| 画布 | 项目 CRUD（乐观锁）、文件夹、生图、资产预签名 | /api/canvas |
api/canvas/router.py |
| 计费订单支付 | 方案/下单/预支付/回调/退款 | /api/billing、/api/payment |
api/user_billing.py、api/payment.py |
| 代理分账提现 | 代理档案/客户绑定/分账计提/月结/提现 | /api/agents、/api/billing/agents、/api/settlement |
api/agents.py、api/admin/billing/ |
| 月结对账 | 月结关账、日终对账、单户回放 | /api/admin/commission-settlements、/api/admin/billing/recon |
api/admin/billing/commissions.py、recon.py |
| 储存限容 | storage 配额桶、上传占容、生成图占容、释容 | /api/billing/storage、/api/canvas/assets/* |
core/services/storage_usage_service.py |
| 用户资产 | 资产库 CRUD + 上传 | /api/user-assets |
api/user_assets.py |
| 用户目录与生图 | C 端目录、单条/批量生图 | /api/user |
api/user/router.py |
| 爆款 | 爆款样式配置 + 图片 | /api/admin/hot-styles |
api/admin/hot_styles.py |
| 视频 | 视频提示词组/试跑/死信 | /api/admin/video/* |
api/admin/video.py |
| 系统配置统计 | banner/功能卡/配置/操作日志/统计 | /api/admin/system-configs、/api/admin/statistics |
api/admin/system.py |
前端页面速查¶
infinitecanvas（用户端）：首页、无限二创画布 /canvas、虚拟影棚 /hot-shoot、电商主图 /main-image、电商详情图 /detail-image、产品换视角 /product-view、模特生成 /model-gen、爆款模板 /hot-template、场景替换 /scene-replace、爆款复刻 /hot-replicate、资产库 /assets-library、账号中心 /account。
agent-system（代理商）：仪表盘、客户列表/详情、二级代理、推广链接、分账记录、提现、结算、设置。
admin-system（运营）：产品管理（大类/子类/面料）、模板管理（构图/场景/模特/主图/详情/复刻/虚拟影棚）、图模板、视频、用户计费（收入看板/会员方案/订单/消费/分账规则/分账记录/佣金月结/日终对账/提现审核/代理商/统一流水）、用户管理、AI 模型、爆款、系统配置、统计。
3. 近期新增功能（NEW）¶
| 功能 | 说明 | 关键字段/文件 |
|---|---|---|
| 储存限容 | usage_quotas(storage) 字节桶，按会员方案 storage_gb 限容；上传超限拒绝 |
storage_usage_service.py、GET /api/billing/storage |
| 生成图占容 | AI 生图结果必须落用户 OSS 并占容；删任务释容 | generation_storage_persist.py、image_object_keys/image_sizes |
| L1/L2 分账 | 一级代理可提拔二级并设 sub_agent_share_rate；二级客户成交从一级佣金池按比例拆分 |
agents.sub_agent_share_rate、promote-sub-agent |
| 月结关账 | 按月把 accrued 计提汇总入可提现余额（幂等，重复不双加） | commission_settlements/close |
| 日终对账 | 每日对账批次 + 单户回放修复 | billing/recon/*、billing/replay/* |
| 登录积分 | 每日登录领取积分，不可重复 | /api/billing/login-points/* |
| 中文日期/月份 | Admin 用户计费各页统一中文日期/月份选择器 | ChineseDateInput、ChineseMonthInput |
| 主图/详情风格选型 | 品类→风格→模板套（取代小类×面料）；页内一键/复刻；自定义提示词产品/材质必填 | CV-REQ-022~024、BE-REQ-012/012b/055b、ADM-REQ-012/020；设计草案、入模逻辑 |
4. 角色与权限矩阵¶
| 功能域 | 匿名 | User | Agent | Admin |
|---|---|---|---|---|
| 浏览方案/落地页 | 读 | 读 | 读 | — |
| 短信登录 | 发码 | — | — | 发码（admin） |
| 画布/生图 | — | 读写 | — | — |
| 用户资产 | — | 读写 | — | — |
| 下单/支付 | — | 操作 | — | 退款 |
| 账号中心/配额 | — | 读 | — | 调整配额 |
| 推广绑客 | 落地读 | 绑定 | — | — |
| 代理门户/客户/分账 | — | — | 读写 | 全量管理 |
| 提现 | — | — | 申请 | 审批 |
| 月结/对账 | — | — | — | 操作 |
| 产品/模板/模型配置 | — | — | — | CRUD |
| 用户管理/系统配置 | — | — | — | 操作 |
鉴权：User JWT 访问
/api/*；Agent = User JWT +agents行；Admin JWT 访问/api/admin/*。
5. 文档导航¶
| 想了解 | 去哪看 |
|---|---|
| 系统怎么跑起来 | 新手上手指南 |
| 某功能端到端流程 | 业务流程图集 |
| 某端验收清单 | backend / admin / agent / canvas |
| 表结构与全量接口 | 表见 data-model.md；业务见 membership-agent-sales-guide.md |
| 术语 | glossary.md |
| 测试矩阵 | test-matrix.md |
| 部署运维 | runbooks |