小程序端项目说明书

项目根目录：w:\AI-Pet-Project\xhs-miniapp-saas 小程序代码目录：miniapp/ 品牌名：智米口袋 / 智米军师（首页 Chat 页标题为「智米军师」）支持平台：微信小程序（mp-weixin）、小红书小程序（mp-xhs），基于 uni-app 一套代码多端编译

1. 项目概述

小程序端是商家（租户）使用的内容创作工具，提供四大 Tab 功能：

Tab	页面	功能
智米军师	`pages/chat/index`	AI 聊天助手（WebSocket 实时对话、图片/视频上传、AI 记忆）
生成文章	`pages/article-generate/index`	四步文章生成向导（方向→主题→生成→预览）
封面神器	`pages/cover-tool/index`	封面 AI 生成（多图分析→风格→生成封面）
个人中心	`pages/profile/index`	个人信息、公司资料、修改密码、退出登录

另有两个分包页面：subpkg-extra/pages/article-detail/index（文章详情）、subpkg-extra/pages/login/index（登录/注册）。

数据与安全：

与 Web 端、后台管理端共享同一后端 API（FastAPI）与数据库（PostgreSQL），通过 RLS 行级隔离 保证数据按商家（merchant）隔离。
所有请求携带 JWT（Authorization: Bearer）+ HMAC-SHA256 请求签名（X-Timestamp/X-Nonce/X-Signature/X-Body-SHA256），防篡改、防重放（详见第 7 节）。
小程序端沿用单 access token（TTL 长，不升级双 token）；Web 端才使用双 token 体系。

2. 技术栈

层次	技术	说明
跨端框架	uni-app（Vue 3 + Vite）	`@dcloudio/uni-app` alpha 版本，一套代码编译到微信/小红书
状态管理	Pinia ^2.1	`stores/auth.ts` 登录态
语言	TypeScript 5 + `<script setup>`	—
样式	SCSS（`uni.scss`）+ 全局 `App.vue` 样式	智米口袋浅色多色调风格
构建	Vite 5 + `@dcloudio/vite-plugin-uni`	`build:mp-weixin` / `build:mp-xhs`
请求	自封装 `uni.request`（`api/request.ts`）	签名 + token + 统一错误提示
后端	FastAPI /api/*	与 Web/Admin 共享

3. 整体架构图

mermaid

graph TB
    subgraph 小程序[uni-app 小程序（微信/小红书）]
        UI["四大 Tab 页面<br/>Chat / 生成文章 / 封面神器 / 个人中心"]
        WIZARD["useArticleWizard 生成向导"]
        CHAT_COMP["useChat + WebSocket"]
        COVER_COMP["cover-tool 封面流程"]
        API["api/* 接口封装"]
        REQ["request.ts<br/>token + HMAC 签名"]
    end

    subgraph 后端[FastAPI :8000]
        SEC["verify_request_signature<br/>HMAC + nonce 防重放"]
        AUTH["/api/auth/* 注册/登录/改密"]
        ARTICLE["/api/article/* 生成/CRUD/adjust/check"]
        TASK["/api/task/* 状态/结果/取消"]
        UPLOAD["/api/upload/* 素材AI分析"]
        COVER["/api/cover/* 封面项目/图片/风格/生成"]
        CHAT_REST["/api/chat/* REST(ws-ticket/历史/引导/上传)"]
        WS["/api/chat/ws WebSocket"]
        DBSESS["DbSession (RLS: app.current_merchant_id)"]
    end

    subgraph 数据[PostgreSQL 16 + pgvector]
        DB_TABLES["merchants/articles/tasks/images<br/>merchant_knowledge_chunks<br/>cover_projects/cover_images/cover_styles/cover_covers<br/>chat_conversations/chat_messages/chat_memory_docs<br/>platform_rules/global_knowledge_docs"]
    end

    UI --> WIZARD
    UI --> CHAT_COMP
    UI --> COVER_COMP
    WIZARD --> API
    CHAT_COMP --> API
    CHAT_COMP -->|"wss://"| WS
    COVER_COMP --> API
    API --> REQ
    REQ --> SEC
    SEC --> AUTH
    SEC --> ARTICLE
    SEC --> TASK
    SEC --> UPLOAD
    SEC --> COVER
    SEC --> CHAT_REST
    WS --> DBSESS
    AUTH --> DBSESS
    ARTICLE --> DBSESS
    TASK --> DBSESS
    UPLOAD --> DBSESS
    COVER --> DBSESS
    CHAT_REST --> DBSESS
    DBSESS --> DB_TABLES

4. 目录结构总览

miniapp/
├── env.d.ts                      # 环境变量类型声明
├── index.html                    # uni-app 的 H5 兜底入口（实际以小程序为主）
├── package.json / package-lock.json
├── project.config.json           # 微信开发者工具项目配置
├── tsconfig.json
├── vite.config.ts                # uni 插件配置
├── scripts/
│   └── strip-dcloud-preload.js   # 构建后清理 dcloud 预加载脚本（小程序兼容）
└── src/
    ├── main.ts                   # uni-app 入口（createSSRApp）
    ├── App.vue                   # 全局生命周期 onLaunch + 全局样式
    ├── manifest.json             # 应用配置（appid、权限、接口域名）
    ├── pages.json                # 页面路由 + tabBar + 分包 + 预加载
    ├── uni.scss                  # 全局 SCSS 变量
    ├── api/
    │   ├── request.ts            # 统一请求封装（签名+token+错误处理）
    │   ├── token.ts              # token 存取（记住我）
    │   ├── auth.ts               # 登录/注册/改密
    │   ├── article.ts            # 文章生成/CRUD/adjust/check
    │   ├── task.ts               # 任务状态/结果/取消
    │   ├── upload.ts             # 素材上传分析
    │   ├── cover.ts              # 封面项目全部接口
    │   └── chat.ts               # 聊天 REST + WS URL
    ├── components/
    │   ├── CustomTabBar.vue      # 自定义 TabBar
    │   ├── ProgressTracker.vue   # 步骤进度条组件
    │   └── generate/
    │       ├── StepInput.vue     # 生成第一步：方向输入
    │       ├── StepTheme.vue     # 第二步：主题选择
    │       ├── StepProgress.vue  # 第三步：生成进度
    │       └── StepPreview.vue   # 第四步：预览/编辑/微调
    ├── composables/
    │   ├── useArticleWizard.ts   # 文章生成向导状态机
    │   ├── useChat.ts            # 聊天组合式函数
    │   ├── useGenerateProgress.ts# 生成阶段进度映射
    │   ├── useKeyboardDock.ts    # 键盘弹起吸附（聊天输入）
    │   └── useTaskPolling.ts     # 任务轮询
    ├── pages/
    │   ├── chat/index.vue        # 智米军师（Tab 1）
    │   ├── article-generate/index.vue  # 生成文章（Tab 2）
    │   ├── article-list/index.vue      # 历史记录（Tab 3 上级页）
    │   ├── profile/index.vue     # 个人中心（Tab 4）
    │   └── cover-tool/index.vue  # 封面神器（Tab 3）
    ├── security/
    │   └── signature.ts          # 纯 JS 实现 HMAC-SHA256 签名
    ├── stores/
    │   └── auth.ts               # Pinia 登录态
    ├── subpkg-extra/
    │   └── pages/
    │       ├── article-detail/index.vue  # 文章详情（分包）
    │       └── login/index.vue           # 登录/注册（分包）
    ├── types/
    │   └── api.ts                # 全量接口 TS 类型
    └── utils/
        ├── authGuard.ts          # 登录守卫（未登录跳登录页）
        ├── safeArea.ts           # 安全区适配（底部内边距）
        ├── stage-progress.ts     # 阶段-进度映射常量
        └── wordCount.ts          # 字数统计（与后端口径一致）

说明：pages/article-list/index 是历史记录页，它在 pages.json 中虽非 Tab 页，但承载了「历史记录」入口（Tab 3「封面神器」与「历史记录」入口并存，见 CustomTabBar）。

5. 文件详解

5.1 工程配置

文件	作用	关联	影响
`src/pages.json`	页面路由注册：5 个主页面（chat/article-generate/article-list/profile/cover-tool）+ 分包 2 页（article-detail/login）；`tabBar` 为 `custom: true`（自定义 TabBar）；`preloadRule` 预加载 extra 分包；各页导航栏标题（智米军师/生成文章/历史记录/个人中心/封面神器）	全部页面、`CustomTabBar.vue`	新增页面必须在此注册；tabBar 配置影响自定义 TabBar 渲染
`src/manifest.json`	应用级配置：appid、微信/小红书平台配置、接口域名白名单（`mp-weixin` 的 `mp-weixin` 域）、uni-app 编译配置	平台审核	接口域名必须与后端线上域名（api.jvguang.com）一致，否则小程序请求被拦截
`src/main.ts`	`createSSRApp(App)` 创建 uni-app 实例	`App.vue`	应用入口
`src/App.vue`	`onLaunch`：`purgeTokenIfNotRemembered()`（未勾选记住我则清 token 强制重登）+ 加载 token；全局样式（浅色多色调、按钮按压反馈、输入框聚焦态）	`stores/auth.ts`、`api/token.ts`	全局启动逻辑与全局样式
`src/uni.scss`	全局 SCSS 变量（颜色/间距等）	各页面	主题变量
`vite.config.ts`	uni 插件接入 + 环境变量	全部	构建配置
`project.config.json`	微信开发者工具配置（appid、编译设置）	微信平台	开发者工具导入用
`scripts/strip-dcloud-preload.js`	构建后删除 dcloud 预加载脚本（避免影响小程序原生运行）	`package.json` postbuild	构建产物修复

5.2 API 层

文件	作用	关联后端	影响
`api/request.ts`	统一请求：自动注入 `Authorization`、HMAC 签名头、`Content-Type`；默认 60s 超时、AI 接口 180s（`AI_TIMEOUT`）；401 清 token 提示重登；按 statusCode 解析 `detail` 错误并 toast	后端全部接口	请求基础；改动影响所有页面请求
`api/token.ts`	token 读写封装：`getToken/setStoredToken/clearStoredToken` + 「记住我」偏好（勾选存 storage，否则每次启动清除）	`App.vue`、`stores/auth.ts`、`request.ts`	登录态生命周期
`api/auth.ts`	`login / register / changePassword`	`POST /api/auth/login`、`/register`、`/password`	登录注册改密
`api/article.ts`	`suggestKeywords / generateThemes / generateArticle / getArticleList / getArticle / updateArticle / deleteArticle / adjustArticle / checkArticle`	`/api/article/suggest-keywords`、`/themes`、`/generate`、`/list`、`/{id}`、`/{id}/adjust`、`/{id}/check`	文章生成与 CRUD
`api/task.ts`	`getTaskStatus / getTaskResult / cancelTask`	`/api/task/{id}/status`、`/result`、`/cancel`	生成任务轮询与取消
`api/upload.ts`	`uploadAnalyze`（单文件上传分析，uni.uploadFile）、`uploadImagesAnalyze`（多图 base64 JSON POST，因小程序不支持多文件上传）	`/api/upload/analyze`、`/api/upload/analyze-images`	素材 AI 分析（视频/图片/文本）
`api/cover.ts`	封面项目全部接口：`createCoverProject / listCoverProjects / getCoverProject / updateCoverProject / deleteCoverProject / uploadCoverImage / deleteCoverImage / analyzeCoverProject / regenerateCoverStyles / generateCovers / selectCover`	`/api/cover/projects*`	封面神器全流程
`api/chat.ts`	`getWsTicket / listMessages / getSuggestedQuestions / buildWsUrl / uploadChatMedia`	`/api/chat/ws-ticket`、`/messages`、`/suggested-questions`、`/upload`	聊天 REST + WS 连接

5.3 安全签名

文件	作用	关联	影响
`security/signature.ts`	纯 JS 手写实现 SHA-256 / HMAC-SHA256（小程序无 WebCrypto，无法用 Web 端的 `crypto.subtle`）：`stableStringify` 稳定序列化 body → `sha256Hex` → `hmacSha256Hex(token, canonical)`，canonical 为 `timestamp\nnonce\nMETHOD\npath?query\nbodyHash`；返回 `X-Timestamp/X-Nonce/X-Signature/X-Body-SHA256`	`api/request.ts`、后端 `security/request_signing.py`	与后端验签算法必须完全一致，改动任何一端都会导致 401「请求签名无效」

5.4 状态与工具

文件	作用	关联	影响
`stores/auth.ts`	Pinia store：`token/user`、`login/logout/setToken/setUser/checkAuth`；`logout` 清 token 与用户信息	全部页面、`api/auth.ts`	登录态唯一来源
`utils/authGuard.ts`	`requireLogin()`：无 token 时 `uni.navigateTo` 跳登录页	各页面 onShow/onLoad	页面访问控制
`utils/safeArea.ts`	`safeBottomPadding` 安全区适配（底部按钮不被系统手势遮挡）	各页面底部按钮	真机适配
`utils/stage-progress.ts`	任务 stage（rag_search/generating/checking/formatting）→ 进度百分比映射	`useGenerateProgress.ts`	生成进度展示
`utils/wordCount.ts`	前端字数统计（与后端 `visible_char_count` 口径一致：剥离不可见字符与 [图N] 标记）	`article-generate`、`article-detail`	字数一致性

5.5 组合式函数（composables）

文件	作用	关联	影响
`useArticleWizard.ts`	文章生成向导状态机：`WizardView`（input/theme/progress/preview）、账号类型（企业号/素人号/探店号）、关键词上限 8、标题上限 20 字；管理 step 数据流转（方向→关键词→角度→主题→生成参数）	`article-generate/index.vue`、`components/generate/*`	向导核心逻辑；改动影响生成流程状态
`useGenerateProgress.ts`	将任务 stage + 时间预估转换为进度条文案/百分比	`useTaskPolling.ts`	进度展示
`useTaskPolling.ts`	轮询任务状态（间隔 ~2-3s），到 `done` 拉取结果文章、`failed` 报错、`cancelled` 停止；支持手动 start/stop	`article-generate/index.vue`	生成任务完成闭环
`useChat.ts`	聊天组合式函数：WS 连接生命周期（ticket → `uni.connectSocket` → 心跳/重连）、消息收发、流式回显、媒体上传、AI 记忆相关；管理消息列表与连接状态	`chat/index.vue`、`api/chat.ts`	聊天核心逻辑
`useKeyboardDock.ts`	聊天输入框键盘弹起时自动吸附底部（监听键盘高度）	`chat/index.vue`	输入体验

5.6 组件

文件	作用	关联	影响
`components/CustomTabBar.vue`	自定义 TabBar（因 `tabBar.custom: true`）：智米军师/生成文章/封面神器/个人中心 4 项 + 历史记录入口，高亮当前页	`pages.json`、各 Tab 页	底部导航；新增 Tab 需同步修改 pages.json 与本组件
`components/ProgressTracker.vue`	步骤进度条（用于生成向导/封面流程）	`article-generate`、`cover-tool`	视觉组件
`components/generate/StepInput.vue`	第一步：内容方向输入（文本框 + 上传素材分析 + 账号类型选择 + 关键词推荐）	`api/upload.ts`、`api/article.ts`(suggestKeywords)	输入阶段
`components/generate/StepTheme.vue`	第二步：展示 AI 生成的 6 个主题/角度选项，选中后进入生成	`api/article.ts`(generateThemes)	主题选择
`components/generate/StepProgress.vue`	第三步：任务进度展示（阶段文案+百分比），支持取消	`useTaskPolling.ts`、`api/task.ts`(cancelTask)	生成中
`components/generate/StepPreview.vue`	第四步：预览生成文章（标题/正文/标签/图片占位），可编辑、合规自检（check）、AI 微调（adjust）、保存	`api/article.ts`(updateArticle/adjustArticle/checkArticle)	结果编辑

5.7 页面详解

pages/chat/index.vue — 智米军师（AI 聊天）

功能：完整聊天 UI——欢迎卡片 + 引导问题（getSuggestedQuestions）、历史消息（游标分页 listMessages）、WS 实时收发（getWsTicket → connectSocket → wss://.../api/chat/ws?ticket=）、流式打字回显、图片/视频上传（uploadChatMedia，HMAC 签名 URL 直接 <img> 显示）、AI 记忆回放、连接状态标签、键盘 Dock。
关联：useChat.ts、useKeyboardDock.ts、api/chat.ts、CustomTabBar.vue。
影响：聊天是商家与平台 AI 交互的主入口；后端 chat_ws.py 断开时触发 _trigger_memory_analysis 自动生成记忆。

pages/article-generate/index.vue — 生成文章

功能：四步向导容器：① 方向输入（可上传素材分析结果自动填充方向）② 主题选择 ③ 生成进度 ④ 预览编辑；调用 generateArticle 创建任务后 useTaskPolling 轮询，完成后进入预览。
关联：useArticleWizard.ts、useGenerateProgress.ts、useTaskPolling.ts、components/generate/*、api/article.ts、api/upload.ts、api/task.ts。
影响：文章的 source_client 由后端按请求头 X-Client-Type 决定（小程序发请求时不带该头，默认 mp_weixin；如需标记小红书来源可在请求头补充 X-Client-Type: mp_xhs）。

pages/article-list/index.vue — 历史记录

功能：分页拉取当前商家的文章列表（getArticleList），展示标题/主题/字数/时间，点击进入详情；未登录跳登录。
关联：api/article.ts、authGuard.ts、CustomTabBar.vue。

pages/profile/index.vue — 个人中心

功能：用户信息展示（getMe 数据来自 store）、公司资料维护（merchant profile 接口）、修改密码（changePassword，旧密码+新密码 8-64 位）、退出登录（清 token）。
关联：stores/auth.ts、api/auth.ts、api/merchant 相关（如存在）。

pages/cover-tool/index.vue — 封面神器

功能：封面项目列表 + 创建项目（标题/文案/平台 xiaohongshu|douyin|video_account）→ 上传素材图（最多 9 张）→ analyzeCoverProject AI 分析生成 4 个风格 → generateCovers 按风格生成封面（后台异步，前端轮询 getCoverProject 至 COMPLETED）→ 选定封面（每项目一张）→ 下载。
关联：api/cover.ts、api/upload.ts、authGuard.ts、safeArea.ts。
影响：封面生成在后端为后台任务（3-6 分钟），依赖「封面 AI 配置」（admin 模型配置页）的 cover_image 服务与即梦（Jimeng）凭据。

subpkg-extra/pages/article-detail/index.vue — 文章详情（分包）

功能：单篇文章详情展示与编辑（标题/正文/标签），保存调 updateArticle。
关联：api/article.ts。

功能：手机号+密码登录 / 注册（手机号 ^1[3-9]\d{9}$、密码 8-64 位、确认密码），「记住我」开关；成功后写入 token 并返回来源页。
关联：api/auth.ts、stores/auth.ts、api/token.ts。
影响：注册/登录规则必须与后端 models/auth.py 一致（后端是最终校验）。

5.8 类型

文件	作用	影响
`src/types/api.ts`	全部接口类型定义（Article、CoverProject、ChatMessage、Task、UserInfo、UploadAnalyzeResponse、常量 `DIRECTION_MAX_LENGTH`、`MAX_UPLOAD_IMAGE_COUNT` 等）	与后端 schema 对齐，改动需同步

6. 后端关联接口总表（小程序使用）

模块	方法	路径	用途	关联服务
认证	POST	`/api/auth/register`	注册	`auth_service.register_with_phone`
认证	POST	`/api/auth/login`	登录	`auth_service.login_with_password`
认证	GET	`/api/auth/me`	获取用户信息	`auth_service.get_merchant_by_id`
认证	POST	`/api/auth/password`	修改密码	`auth_service.change_password`
商家	GET/PUT	`/api/merchant/profile`	公司资料	`merchant_service`
商家	POST/DELETE	`/api/merchant/knowledge`	知识片段	`merchant_service`
文章	POST	`/api/article/suggest-keywords`	关键词推荐（同步）	`article_service.suggest_keywords`
文章	POST	`/api/article/expand`	角度扩展（同步）	`article_service.expand_keywords`
文章	POST	`/api/article/themes`	主题生成（同步）	`article_service.generate_themes`
文章	POST	`/api/article/generate`	创建生成任务（异步）	`article_service.generate_article`（LangGraph 流水线）
文章	GET	`/api/article/list`	文章列表	`article_service.list_articles`
文章	GET/PUT/DELETE	`/api/article/{id}`	文章 CRUD（PUT 带 `If-Match` 乐观锁）	`article_service`
文章	POST	`/api/article/{id}/adjust`	AI 微调	`article_adjust_service.micro_adjust` + `compliance_check`
文章	POST	`/api/article/{id}/check`	合规自检	`compliance_check.run_compliance_review`
任务	GET	`/api/task/{id}/status`	任务状态	`task_service.get_task`
任务	GET	`/api/task/{id}/result`	任务结果	`task_service` + `article_service.get_article`
任务	POST	`/api/task/{id}/cancel`	取消任务	`task_service.cancel_task`
上传	POST	`/api/upload/analyze`	素材 AI 分析（视频/图/文本）	`upload_service`
上传	POST	`/api/upload/analyze-images`	多图 base64 分析	`upload_service.analyze_multiple_images`
封面	POST/GET	`/api/cover/projects`	项目创建/列表	`cover_service`
封面	GET/PATCH/DELETE	`/api/cover/projects/{id}`	项目详情/更新/删除	`cover_service`
封面	POST	`/api/cover/projects/{id}/images`	上传素材图	`cover_service.upload_image`
封面	POST	`/api/cover/projects/{id}/analyze`	AI 分析+风格生成	`cover_service.analyze_images`
封面	POST	`/api/cover/projects/{id}/styles`	重新生成风格	`cover_service.generate_styles`
封面	POST	`/api/cover/projects/{id}/covers`	生成封面（异步）	`cover_service` + 即梦/Ark
封面	PATCH	`/api/cover/projects/{id}/covers/{coverId}`	选定封面	`cover_service.select_cover`
聊天	POST	`/api/chat/ws-ticket`	获取 WS 一次性票据（30s）	`chat_ws.create_ticket`
聊天	WS	`/api/chat/ws?ticket=`	实时聊天	`chat_ws.handle_connection`
聊天	GET	`/api/chat/messages`	历史消息（游标分页）	`chat_service.get_messages`
聊天	GET	`/api/chat/suggested-questions`	引导问题	`chat_service.get_suggested_questions`
聊天	POST	`/api/chat/upload`	聊天媒体上传	`chat_storage` + `sign_upload_url`
聊天	GET	`/api/chat/uploads/{path}`	媒体静态服务（签名 URL）	`chat_storage` + `verify_upload_signature`
规则	GET	`/api/rule/list`、`/api/rule/search`	平台规则展示/检索	`rule.py` 路由

所有接口（除登录/注册外）都经过 CurrentSecureUser（JWT + 请求签名校验）与 DbSession（RLS 注入）。

7. 安全机制（小程序端）

JWT 认证：登录后获得 access token，存放于本地存储（api/token.ts），请求头 Authorization: Bearer。
HMAC-SHA256 请求签名（security/signature.ts）：
- 签名输入：timestamp\nnonce\nMETHOD\npath?query\nbodyHash，密钥为 access token 本身；
- 后端 security/request_signing.py::verify_request_signature 用同一算法校验，并做 nonce 防重放（TTL REQUEST_SIGNATURE_TTL_SECONDS=300，重复 nonce 返回 409）与时间窗校验（±5 分钟）；
- Web 端用 WebCrypto 实现同一算法（web/src/api/signature.ts），两侧必须保持一致。
RLS 租户隔离：数据库会话由 deps.get_db_session 注入 app.current_merchant_id（取 JWT sub），PostgreSQL RLS 策略保证任何查询/写入都限定在当前商家；聊天媒体 URL 使用 HMAC 签名（10 分钟过期），防止越权访问他人文件。
登录防爆破：后端 auth.py 对登录/注册做多维度限流（IP/手机号/UA 指纹维度）。

8. 关键业务流程

8.1 登录/注册

login 页 → 勾选《用户服务协议》《隐私政策》(默认未勾选，未勾选时登录/注册按钮置灰)
→ 手机号+密码 → POST /api/auth/login（带限流） → 后端 bcrypt 校验
→ 返回 access_token → stores/auth.setToken → 返回来源页（authGuard 记录 redirect）

注册需填昵称、行业；后端创建 merchants 行（密码 bcrypt 加密）。协议/隐私为本地分包页面（agreement、privacy），个人中心可随时查看；隐私政策直接跳本地页面，不走 wx.openPrivacyContract（避免依赖后台隐私保护指引配置导致空白）。

8.2 文章生成（四步向导）

StepInput：方向文本/上传素材分析(AI 生成方向) → 选账号类型 → suggestKeywords(关键词)
StepTheme：generateThemes(方向+关键词+角度+商家知识库) → 6 主题选 1
StepProgress：generateArticle → 得 task_id → useTaskPolling 轮询 status/result
    · 后端流水线：rag_search → agent_generate → format_assemble（LangGraph）
    · 完成：_save_article 落库（source_client 按 X-Client-Type 头，小程序默认 mp_weixin）+ set_task_done
StepPreview：预览 → check(合规自检) → adjust(AI 微调) → updateArticle 保存（If-Match 乐观锁）

8.3 聊天（WebSocket）

进入 chat 页 → POST /api/chat/ws-ticket 拿一次性票据(30s) → buildWsUrl → uni.connectSocket
→ 后端 consume_ticket 校验 IP+票据 → handle_connection
→ 发消息 {type:"dm", content/mediaUrl/mediaType}
→ 后端 _save_and_echo 落库回显 + _trigger_ai_reply（流式返回，自动回复开关开启时）
→ 引导问题/欢迎语：generate_welcome；断开时 _trigger_memory_analysis 生成记忆
→ 客服接管时收到 sender_role=admin 消息实时展示

8.4 封面神器

创建项目(标题/文案/平台) → 上传素材(≤9张, 每张≤20MB) → analyze(多图AI分析→4风格)
→ 选风格 → generateCovers(后台异步, 即梦生成 3-6 分钟) → 轮询目标 style 的 covers → COMPLETED → 选定/下载

即梦出图尺寸为 64 倍数标准映射（3:4 → 896×1152）；生成任务后台串行执行（并发锁），规避算法 50501 与单账号 429 限制。

9. 构建与发布

bash

cd miniapp
npm install
npm run build:mp-weixin     # 构建微信小程序（构建后自动 strip-dcloud-preload）
npm run build:mp-xhs        # 构建小红书小程序

产物目录：dist/dev/mp-weixin（微信）、dist/dev/mp-xhs（小红书），用对应开发者工具导入。

发布前检查：

manifest.json 中接口域名白名单包含 https://api.jvguang.com（微信后台需同步配置 request/socket 合法域名）。
生产环境 VITE_API_BASE 指向线上 API 域名；本地联调指向 dev 后端。
后端 .env 中 CORS_ORIGINS 对小程序无影响（小程序请求无 Origin 预检），但 LLM 相关配置决定生成质量。

10. 影响分析汇总

变更点	影响范围	风险
修改 `security/signature.ts` 算法	全部接口签名失效（401）	高
修改 `request.ts` 超时/错误处理	全局请求行为	中
修改 `useArticleWizard` 步骤结构	生成向导全流程	中
修改 `pages.json` tabBar/路由	页面入口与自定义 TabBar	中
修改后端文章流水线（rag/generate/format）	小程序+Web 生成结果	高
修改后端聊天（chat_ai/chat_ws）	小程序+Web+Admin 会话	高
修改后端封面 AI 配置	小程序+Web 封面生成	高
修改 `models/auth.py` 注册/登录规则	小程序+Web+Admin 三端登录	高

11. 常见问题

请求报 401「缺少请求签名」：token 为空（未登录）或签名头缺失；确认 request.ts 在 getToken() 有值时才注入签名。
请求报 401「请求签名无效」：小程序 signature.ts 与后端验签算法不一致（常见于改 URL 拼接或 stableStringify）；注意签名必须用 path?query（不含域名）。
AI 响应超时：前端 60s 默认超时对 LLM 偏短，AI 类接口用 AI_TIMEOUT=180000；后端 LLM 超时 30s+重试。
登录后仍跳登录页：App.vue 的 purgeTokenIfNotRemembered 会在未勾选「记住我」时清 token——每次冷启动都需重新登录属预期行为。

小程序端项目说明书 ​

1. 项目概述 ​

2. 技术栈 ​

3. 整体架构图 ​

4. 目录结构总览 ​

5. 文件详解 ​

5.1 工程配置 ​

5.2 API 层 ​

5.3 安全签名 ​

5.4 状态与工具 ​

5.5 组合式函数（composables） ​

5.6 组件 ​

5.7 页面详解 ​

pages/chat/index.vue — 智米军师（AI 聊天） ​

pages/article-generate/index.vue — 生成文章 ​

pages/article-list/index.vue — 历史记录 ​

pages/profile/index.vue — 个人中心 ​

pages/cover-tool/index.vue — 封面神器 ​

subpkg-extra/pages/article-detail/index.vue — 文章详情（分包） ​

subpkg-extra/pages/login/index.vue — 登录/注册（分包） ​

5.8 类型 ​

6. 后端关联接口总表（小程序使用） ​

7. 安全机制（小程序端） ​

8. 关键业务流程 ​

8.1 登录/注册 ​

8.2 文章生成（四步向导） ​

8.3 聊天（WebSocket） ​

8.4 封面神器 ​

9. 构建与发布 ​

10. 影响分析汇总 ​

11. 常见问题 ​