开发与验证指南

1. 本地目录

xhs-miniapp-saas/
├── backend/   # FastAPI 后端
├── miniapp/   # uni-app 小程序端
├── web/       # React Web 用户端
├── admin/     # React 后台管理端
└── docs/      # 项目文档

2. 常用命令

后端

cd W:\AI-Pet-Project\xhs-miniapp-saas
backend\.venv\Scripts\python.exe -m pytest backend\tests -q
backend\.venv\Scripts\python.exe -m compileall -q backend\app

按模块测试：

backend\.venv\Scripts\python.exe -m pytest backend\tests\test_cover_ai_config.py -q
backend\.venv\Scripts\python.exe -m pytest backend\tests\test_auth_password.py -q
backend\.venv\Scripts\python.exe -m pytest backend\tests\test_article_service_keywords.py -q

小程序

cd W:\AI-Pet-Project\xhs-miniapp-saas\miniapp
npm.cmd run build:mp-weixin
npm.cmd run build:mp-xhs

说明：

• Windows 下优先使用 npm.cmd，避免 PowerShell 执行策略拦截 npm.ps1。
• 微信开发者工具导入 miniapp/dist/build/mp-weixin。
• 构建后会执行 scripts/strip-dcloud-preload.js，减少微信 DevTools 文件监听和无效 preload 注入。

Web 用户端

cd W:\AI-Pet-Project\xhs-miniapp-saas\web
npm.cmd run build
npm.cmd run test

后台管理端

cd W:\AI-Pet-Project\xhs-miniapp-saas\admin
npm.cmd run build

3. 变更前检查

git status --short
git log --oneline -n 20

注意：

• 工作区经常存在用户的其它改动，提交前必须选择性暂存。
• 封面、认证、安全、隐私相关改动不要 git add .。
• 提交前使用 git diff --cached --name-status 检查暂存范围。

4. 推荐验证矩阵

改动类型	必跑验证
后端通用	pytest backend/tests -q、compileall backend/app
认证/改密	test_auth_password.py、test_auth_refresh.py，Web/小程序登录手测
请求签名	Web build + 小程序 build + 真机接口请求
小程序 UI	build:mp-weixin，必要时真机看键盘、安全区、滚动
Web UI	npm.cmd run build，必要时浏览器移动断点
封面神器	test_cover_ai_config.py、小程序 build、Web build、真机生成流程
文章生成	test_article_*、任务轮询、生成/取消/预览
管理后台	admin build，模型配置保存/测试接口

5. 封面神器排障流程

5.1 前端显示失败但后台可能已生成

检查：

• 当前项目的目标 style 下是否已有 covers。
• 前端是否只看了 project.status === COMPLETED。
• 小程序本地是否保存 cover-tool:generating-style:{projectId}。

应对：

• 以目标 style 的 covers 数组作为完成依据。
• 重进项目时刷新详情并恢复 step。

5.2 即梦无请求或生成失败

检查：

• 后台管理端 /api/admin/cover-ai/diagnose。
• cover_ai_configs.cover_image 是否 enabled，provider 是否 Jimeng，api_key 是否 AK:SK。
• 后端日志是否出现 Jimeng task submitted、Missing JIMENG、Jimeng HTTP failed。

生产日志位置（systemd 服务 stdout/stderr 重定向到文件）：

tail -n 300 /var/log/xhs-saas-backend.log
grep -nE "Jimeng HTTP|Jimeng poll|generate covers|50501" /var/log/xhs-saas-backend.log | tail -50

若日志出现：

Jimeng HTTP 500: {"code":50501,"message":"Internal RPC Error ... height or width invalid"}

说明出图尺寸非法：即梦 t2i_v40 算法要求宽高为 64 的倍数标准组合（如 3:4 → 896×1152），禁止按面积反推非标准宽高。检查 _resolve_jimeng_dimensions 映射与 JIMENG_IMAGE_SIZE 配置，并确认生成任务并发锁（_jimeng_generation_lock）未被绕过。

若日志出现：

Jimeng API concurrent limit exceeded after 5 retries

说明触发即梦单账号在途任务并发限制（429），应串行生成任务，避免多项目/多用户同时提交。

注意：

• “后台显示 API key configured” 只表示有非空值，不代表即梦请求真的发出。
• 不要在未确认服务名和部署路径前重启或覆盖生产文件。

5.3 图片加载 401

检查：

• 图片 URL 是否包含 exp 和 sig。
• 前端 normalize URL 是否保留 query。
• 是否重入项目后使用了旧签名 URL。

应对：

• 重新请求项目详情获取新签名 URL。
• 确认后端 sign_upload_url 覆盖 /api/cover/uploads/。

6. 小程序质量检查

关注点：

• lazyCodeLoading、分包、preloadRule。
• 生成产物是否包含无效 wx.preloadAssets。
• DevTools 是否因文件过多触发 EMFILE。
• 真机键盘与安全区是否正常。

验证建议：

1. npm.cmd run build:mp-weixin
2. 微信 DevTools 清缓存并重新导入 dist/build/mp-weixin
3. 真机检查首页、登录协议、聊天键盘、封面生成

7. 发布前 Checklist

• [ ] git status --short 已确认只包含本次目标变更。
• [ ] 后端相关测试通过。
• [ ] 端侧构建通过。
• [ ] 隐私、认证、请求签名相关改动已做真机/浏览器验证。
• [ ] AI 生成相关改动有超时、失败和兜底策略。
• [ ] 生产部署前确认目标服务、路径、备份和回滚命令。

8. 文档维护 Checklist

• 新功能：更新 docs/requirements/需求记录.md。
• Bug 修复：更新 docs/bugs/修复记录.md。
• 架构变化：更新 docs/project/项目全景.md。
• 重要里程碑：更新 docs/history/历史提交与里程碑.md。
• 三端页面/API 变化：同步对应三端项目说明书。