项目全景

1. 项目定位

xhs-miniapp-saas 是面向商家的多端内容运营 SaaS，核心目标是帮助商家完成选题、文案、封面、发布前优化与经营问答。

当前系统由四部分组成：

模块	目录	定位
后端 API	backend/	FastAPI + PostgreSQL 多租户业务服务，承载认证、文章、任务、封面、聊天、管理端接口
小程序端	miniapp/	uni-app，面向移动端商家，覆盖智米军师、文章生成、封面神器、个人中心
Web 用户端	web/	React + Ant Design，面向浏览器用户，覆盖聊天、控制台、文章管理、文案生成、封面神器、个人中心
后台管理端	admin/	React + Ant Design，面向运营/管理员，管理商家、规则、知识库、模型配置、聊天会话

2. 核心业务能力

智米军师

• 小程序首页与 Web /chat 均提供 AI 聊天助手。
• 支持 WebSocket 流式回复、历史会话、引导问题、图片/视频上传。
• 后端通过 /api/chat/ws-ticket 发放一次性 WS 票据，避免直接暴露长期 token。
• 记忆与知识库由 chat_memory_docs、global_knowledge_docs、merchant_knowledge_chunks 支撑。

文章生成

• 四步流程：方向输入、主题生成、正文生成、预览/保存。
• 后端以任务方式执行，/api/task/* 提供进度和结果轮询。
• 生成链路包含 RAG 检索、LLM 生成、合规检查、格式组装、AI 微调修复。
• Web 端支持编辑器、文章版本与来源标识，小程序端支持历史记录和文章详情。

封面神器

• 项目流程：创建项目、上传素材、AI 分析、生成风格、选择风格、生成封面、选定/下载。
• 后端表族：cover_projects、cover_images、cover_styles、cover_covers。
• 图片生成当前支持 Kimi/Jimeng 与 Ark/Doubao 兼容路径，模型配置由后台管理端热更新。
• 生成任务为后台异步流程，前端按目标 style 的 covers 数组轮询，避免旧 COMPLETED 状态误判。
• 即梦出图尺寸使用 64 倍数标准映射（3:4 → 896×1152 等），生成任务通过 _jimeng_generation_lock 串行化，规避算法 50501 与单账号 429 并发限制。
• 删除项目为硬删除：删除项目记录、素材图、生成封面图，并清理项目图片目录。

个人中心与认证

• 商家使用手机号 + 密码注册登录。
• 小程序和 Web 均支持修改密码。
• Web 使用 access token + HttpOnly refresh cookie 的双 token 体系。
• 小程序使用本地 token + 记住我偏好。

后台管理

• 管理员可管理商家、规则、知识库、全局知识、模型配置、封面 AI 配置、聊天会话。
• 管理端仅内网访问，带 noindex/noarchive 保护。
• 模型配置影响全平台 AI 能力，修改前应使用测试/诊断接口验证。

3. 后端架构

flowchart TB
    Client["miniapp / web / admin"] --> API["FastAPI routers"]
    API --> Auth["CurrentSecureUser / Admin Auth"]
    Auth --> Sign["HMAC 请求签名校验"]
    API --> Service["services/* 业务层"]
    Service --> Graph["graph/* 文章生成流水线"]
    Service --> Cover["cover_service 封面 AI 工作流"]
    Service --> Chat["chat_service / chat_ws"]
    Service --> DB["PostgreSQL + pgvector"]
    Service --> Storage["local storage uploads"]
    Service --> LLM["LLM / Kimi / Jimeng / Ark"]

关键边界：

• routers/* 只负责 HTTP 参数、认证、错误转换。
• services/* 承载业务规则、权限校验、数据组合和外部服务调用。
• models/* 是 Pydantic 请求/响应模型。
• security/* 处理请求签名、限流、加密、上传链接签名和隐私合规。
• graph/* 是文章生成流水线，不直接处理 HTTP。

4. 数据与安全模型

• 租户隔离：PostgreSQL RLS + app.current_merchant_id。
• 请求防护：JWT + HMAC-SHA256 签名 + nonce/timestamp 防重放。
• 密钥保护：后台模型 API Key 使用 Fernet 加密落库。
• 上传资源保护：/api/cover/uploads/* 与 /api/chat/uploads/* 使用短期 HMAC 签名 URL。
• 登录防爆破：认证接口按 IP、手机号、UA 指纹等维度限流。
• 管理端边界：管理员接口走 AdminDb/无 RLS，但入口受 admin JWT 与内网访问控制保护。

5. 三端说明书入口

• 小程序详细说明：../小程序端-miniapp-项目说明书.md
• Web 详细说明：../Web端-web-项目说明书.md
• 后台管理详细说明：../后台管理端-admin-项目说明书.md