Bug 修复记录

本文档记录项目中反复影响开发、构建、真机和生产体验的问题。格式：现象 → 原因 → 修复 → 验证。

1. 小程序隐私政策不合规

现象：

• 协议默认自动同意。
• 用户未体验功能即被要求授权登录。
• 用户协议、隐私政策入口点击无响应。
• 点击登录页《隐私政策》后打开一片空白（依赖微信官方隐私弹窗时）。

原因：

• 登录流程前置，且协议勾选状态默认偏向同意。
• 协议/隐私分包页面入口和返回链路不完整。
• openPrivacy() 优先调用 wx.openPrivacyContract，该弹窗内容依赖小程序后台配置《用户隐私保护指引》，未配置时打开为空白或无响应。

修复：

• 登录页协议默认不勾选，未勾选时登录/注册按钮置灰不可点击。
• 首页/功能页允许先浏览，登录按需触发。
• 新增/完善 agreement、privacy 页面和跳转。
• 隐私政策链接改为直接跳转小程序内置 privacy 页面，不再依赖微信官方隐私弹窗。
• 个人中心新增「用户服务协议 / 隐私政策」入口，登录前后均可随时查看。

验证：

• 微信小程序真机打开首页不强制授权。
• 登录页必须用户主动勾选后才可提交。
• 协议/隐私页面可打开、可返回，内容不再空白。

2. 微信 DevTools 上传质量不通过与 EMFILE

现象：

• 上传小程序时质量检查失败。
• DevTools 报 EMFILE: too many open files，打开 miniprogram-builder/types/index.js 失败。

原因：

• 生成产物或构建配置导致 DevTools 文件监听压力过大。
• 需要按微信文档启用合理的懒加载/按需注入配置，并减少无效 preload 注入。

修复：

• 保留 lazyCodeLoading 等小程序性能配置。
• 构建后执行 scripts/strip-dcloud-preload.js 移除 dcloud 预加载注入。
• 减少 DevTools watch 压力。

验证：

• npm.cmd run build:mp-weixin
• 使用微信 DevTools 重新导入 miniapp/dist/build/mp-weixin。

3. 小程序聊天输入框被键盘遮挡

现象：

• 手机真机点击智米军师输入框，键盘弹起后输入框仍沉在底部，看不到正在输入内容。

原因：

• 输入栏定位未正确响应移动端键盘高度和安全区。
• 部分平台下 position、viewport 高度与键盘事件不同步。

修复：

• 提取 miniapp/src/composables/useKeyboardDock.ts。
• 输入栏使用键盘高度和 safe area 计算动态 bottom。
• 页面滚动和消息列表高度配合输入栏变化。

验证：

• 微信真机键盘弹起时输入框可见。
• 发送消息后列表滚动到底部。

4. 封面生成“生成了但前端仍报失败”

现象：

• 生成封面需要几分钟，前端显示“生成失败，请重试”。
• 退出项目再进入后又看到封面已生成。

原因：

• 前端用全局项目状态判断完成，旧的 COMPLETED 状态可能来自风格生成。
• 轮询等待时间与即梦真实耗时不匹配。
• 后台生成任务与前端轮询目标 style 不一致时会误判。

修复：

• /covers 返回后设置 GENERATING，后台任务独立 DB 连接执行。
• 前端轮询目标 style 的 covers 数组，只有目标风格出现封面才认为完成。
• 延长并限制合理轮询时长，重入项目时恢复正在生成状态。

验证：

• backend/.venv/Scripts/python.exe -m pytest backend/tests/test_cover_ai_config.py -q
• 小程序从生成页退出再进入，可恢复对应项目状态。

5. 即梦参数、尺寸与轮询问题

现象：

• 即梦接口报错、生成失败或控制台无请求记录。
• 部分请求 5xx，或尺寸参数不被官方 v4.0/v4.6 接受。
• 真机封面生成约 1-3 分钟后提示「封面生成失败，请重试」，后台项目状态为 FAILED。

原因：

• 请求参数与官方接口不完全一致。
• _resolve_jimeng_dimensions 按面积反推宽高（如 3:4 + 1K → 887×1182），不是 64 的倍数，即梦 t2i_v40 算法（comfyui BADataProcessingTransform）直接拒绝，返回 50501 Internal RPC Error / height or width invalid。
• 尺寸、scale、req_key、poll timeout 未按模型差异处理。
• 即梦单账号在途任务并发有限，多任务同时提交触发 429 concurrent limit。
• “后台显示 API key configured” 不能证明真正发起了即梦请求。

修复：

• 使用官方 v4.0/v4.6 参数。
• 尺寸改为标准映射表（1K：3:4 → 896×1152、1:1 → 1024×1024、9:16 → 832×1216 等；2K 同比例放大），宽高均为 64 的倍数且在 [512, 2048]（1K）/ [512, 4096]（2K）内；未知比例自动向下对齐 64 倍数。
• 50500/50501 为算法内部错误（官方标注「不需要重试」），直接抛错快速失败，不再无谓重试 3 次（3s+9s+27s）。
• 封面生成后台任务加 asyncio.Lock 并发锁，进程内同时只执行 1 个即梦生成任务，规避 429 雪崩。
• 日志记录 task_id、req_key、poll_count、provider 错误边界。

验证：

• 后端封面测试。
• 生产排查时查看 /var/log/xhs-saas-backend.log（systemd 服务 stdout/stderr 重定向），搜索 Jimeng HTTP 500、Jimeng poll failed、background generate covers。
• 服务器验证尺寸映射输出均为 64 倍数，systemctl restart xhs-saas-backend 后 /health 正常。

6. 封面图片 401 与签名 URL

现象：

• 小程序渲染层报 Failed to load image ... 401。
• 服务器来源显示 127.0.0.1 或签名参数丢失。

原因：

• 封面/聊天上传资源需要短期签名 URL。
• 前端拼接、刷新项目或重入页面时可能丢失签名参数。

修复：

• 后端 sign_upload_url 给 /api/cover/uploads/*、/api/chat/uploads/* 加 exp/sig。
• 前端 normalize URL 时保留 query。
• 项目刷新时重新获取带签名的图片 URL。

验证：

• 真机打开项目列表、工作流、封面网格，图片均可加载。

7. 上传图片自动旋转

现象：

• 用户上传图片后方向异常，出现自动旋转。

原因：

• 手机照片带 EXIF orientation，压缩或生成流程未统一转正。

修复：

• _compress_reference_image 使用 ImageOps.exif_transpose。
• 保存前统一转成正确方向并压缩。

验证：

• 竖拍/横拍照片上传后方向正确。

8. 封面流程只能后退不能前进

现象：

• 用户退回上一步后无法回到已生成的风格或封面，只能重新生成。

原因：

• 前端 step 状态只按线性新流程推进，未根据项目已有 images/styles/covers/selected_cover 派生可进入步骤。

修复：

• 根据项目详情派生 step。
• 若已有 styles，可回到风格选择。
• 若目标 style 已有 covers，可直接查看封面。

验证：

• 打开历史封面项目，可在上传、风格、封面、完成之间按已有数据跳转。

9. 封面项目删除不彻底

现象：

• 用户需要删除不想要的记录和图片，要求“删了别的地方不要还存着”。

原因：

• 只有 API 封装不等于用户有列表入口。
• 仅删除数据库记录可能留下本地图片目录或临时残留。

修复：

• 小程序列表新增删除按钮，Web 删除确认文案改为永久删除。
• 后端删除项目时收集素材图和生成图 storage_key，删除数据库记录后清理文件和项目目录。

验证：

• test_delete_cover_project_removes_db_records_files_and_project_dir
• npm.cmd run build:mp-weixin
• npm.cmd run build

10. 封面中文字出现乱码或不清晰

现象：

• 生成封面时模型可能在图片上添加无意义文字、伪中文、随机字母或模糊文字。

原因：

• 文生图模型对文字渲染能力不稳定，原 prompt 仅分散约束“文字完整清晰”，缺少集中硬约束。

修复：

• 新增 TEXT_RENDERING_CONSTRAINT。
• 风格生成、风格补强、最终出图 prompt 均注入该约束。
• 即梦 800 字 prompt 压缩保留“字体必须清晰”“乱码文字”等关键规则。

验证：

• backend/.venv/Scripts/python.exe -m pytest backend/tests/test_cover_ai_config.py -q

11. Web 401、签名与刷新问题

现象：

• Web 刷新或 query 请求触发 401。
• Ant Design message 在 App wrapper 外使用时报错。

原因：

• 签名 canonical URL 未覆盖 query。
• axios 刷新重放和 UI message 容器初始化顺序不一致。

修复：

• Web signature.ts 对 path?query 签名。
• client.ts 使用 refresh 单例和 Ant Design App wrapper。

验证：

• npm.cmd run build
• 运行 Web 测试。

12. 文章生成关键词推荐不稳定

现象：

• 推荐关键词 LLM 超时或返回异常时，前端流程被打断。

原因：

• 关键词建议依赖 LLM，未完全兜底。

修复：

• suggest_keywords() 加 15 秒 asyncio.wait_for。
• 异常、超时、非法 payload 均返回本地提取/补充关键词。

验证：

• backend/.venv/Scripts/python.exe -m pytest backend/tests/test_article_service_keywords.py -q