历史提交与里程碑

来源：当前 Git 历史和仓库文档。此文档记录主干方向，不替代 git log。

2026-09-05/09-07：封面神器额度体系上线与安全部署核验

代表提交：

• 78f314f feat(backend,web,miniapp,admin): 封面神器次数额度体系 - 免费3次+后台人工充值/用量管理; 随附后台审计与注册同意等既有待提交改动
• 7c8eefe fix(backend): 封面额度 SQL 参数显式类型标注, 修复 asyncpg AmbiguousParameterError(text vs varchar)
• 86ce71e fix(storage cleanup): 修正存储清理注释中的DB引用路径错误并新增单元测试
• eadb9c5 test(backend): cover refresh token cleanup lifespan
• 99c671b feat(deploy): 新增 Windows 一键部署脚本 deploy.ps1

发布内容：

• 封面神器引入次数额度体系：新商户/存量商户免费 3 次（终身有效），仅「生成封面」计次，图片分析与风格生成免费；后台支持充值/调整并写审计日志。
• 迁移 0014_cover_quota 新增 cover_quota_accounts / cover_quota_transactions（RLS 租户隔离、存量回填、流水台账）；随附 0012_admin_audit_log、0013_registration_consents。
• 出图提交预扣（reserved）→ 成功确认 consumed → 失败/取消/判死/删项目 refunded 退回；余额不足出图 HTTP 402。
• Web / 小程序封面页展示余额、0 余额禁用引导、失败回退提示；后台商户详情含额度卡片与流水时间线。

部署核验（2026-09-07，服务器 121.41.54.90 /opt/xhs-saas/backend）：

• 上线前核对：服务端后端目录与仓库 HEAD（99c671b）逐文件哈希一致（207 个受跟踪文件），迁移 0014 已应用，服务运行 HEAD 代码，未覆盖任何无关服务器改动。
• 安全步骤：pg_dump 备份 quota-release-db-20260907-135428.dump；迁移幂等重跑无待执行项。
• 边界实测（一次性测试商户，验证后级联删除，未触碰真实商户/AI 出图）：商户/管理端余额展示与 initial_grant 流水 PASS；余额耗尽提交出图返回 402 PASS；生成中(已预扣)删除项目退回 PASS（balance 1→2）；后台充值 +5/负调整拒绝/审计落库 PASS。
• 回滚点：DB 用 quota-release-db-20260907-135428.dump，代码用 backend-20260907-114103.tar.gz。

2026-07-20：项目初始化与文章生成基础

代表提交：

• cf8284e chore: 初始化项目并提交至本地仓库
• 4b6bb7f feat: 增强文章生成与上传服务，清理 TS 编译产物

阶段成果：

• 建立 FastAPI 后端、PostgreSQL、RLS、文章生成基础链路。
• 初步形成文章任务、图片上传、RAG/LLM 生成能力。

2026-07-23：封面神器迁移与后台模型配置

代表提交：

• 9d867dc feat(cover-tool): 重构 face-god 为小程序版封面神器
• 929f1d3 feat(cover-tool): 新增封面神器 AI 模型配置管理
• 4cb97c1 feat(admin): 后台管理系统添加封面神器 AI 模型配置模块

阶段成果：

• 将 face-god 的商家图片到封面流程迁移进本项目。
• 新增 cover_projects / cover_images / cover_styles / cover_covers 表族。
• 后台管理端新增封面 AI 配置，支持 cover_vision / cover_text / cover_image。
• 封面上传、分析、风格、生成、选择形成完整接口族。

2026-07-24：安全整合与 Kimi/Jimeng 稳定化

代表提交：

• 0155098 chore: consolidate backend security helpers
• 3beff20 feat: consolidate auth security and kimi jimeng workflow
• db2f9a1 fix: stabilize cover kimi jimeng workflow
• 9c6d38e fix: align miniapp network timeout config

阶段成果：

• 合并请求签名、安全工具、租户边界和上传 URL 签名逻辑。
• Kimi/Jimeng 封面链路可按后台配置选择服务。
• 小程序 AI 超时与后端长任务耗时对齐，减少真机误报失败。

2026-07-27：封面生成多问题修复

代表提交：

• fd49562 fix(cover-tool): 修复封面生成多问题 - 标题输入框高度/即梦4.6模型/切换风格重生成/DeepSeek模型名/后台任务GC回收/管理后台内网隔离

阶段成果：

• 修复封面工作流中的标题输入、模型参数、风格切换、后台任务生命周期等问题。
• 加强管理后台内网隔离。

2026-07-30：Web Phase 1 与认证升级

代表提交：

• 5981967 docs(spec): add web-end design with cross-client interop (Phase 1 MVP)
• 46f7dce chore: 统一小程序名称为智子工具箱, 清理诊断脚本与安全报告
• 3c59c30 feat(db): add articles.source_client/version + merchant_refresh_tokens table
• 56ff222 feat(config): add access/refresh token TTL settings
• 053fd67 feat(jwt): add type field and refresh token issuance
• ef97c6d feat(auth): add refresh token issue/verify/revoke service functions
• 2593c8d feat(auth): add /api/auth/refresh and /api/auth/logout endpoints with cookie + rate limit
• f757d78 feat(article): inject source_client + add optimistic lock via If-Match
• a8dbf66 feat(web): add Phase 1 web client + backend tests

阶段成果：

• Web 用户端正式进入 MVP：登录、文章、封面、控制台、个人中心等能力上线。
• Web 使用 refresh token cookie，支持 401 自动刷新与登出。
• 文章新增来源端与版本号，支持 Web/小程序跨端协作与乐观锁。

2026-07-31 至 2026-08-01：Web 稳定化与文章生成性能

代表提交：

• e1cb00d fix(web): sign query params + antd App.useApp message
• cf7956d fix(web): enable CORS allow_credentials + antd App wrapper
• 608f179 perf(article): optimize copy generation pipeline + sync pending changes
• 653ed02 fix(web): raise nginx body limit for analyze-images + unify CoverTool button sizes
• 77f09e8 fix(web): unify ALL CoverTool buttons to 44px height + large size
• 5e189a7 perf(article): raise LLM fallback timeouts for production stability

阶段成果：

• Web 请求签名补齐 query 参数，修复 401 类问题；CORS 允许携带凭证。
• 文章生成超时与兜底策略增强。
• Web 封面神器按钮、上传体积限制和部署配置趋于统一。

2026-08-02：智米军师迁移与账号规则统一

代表提交：

• 1956993 feat(auth,chat): unify account rules + sync chat sessions with merchant accounts
• 993e93e feat(miniapp,web,backend): add mini-program chat/profile modules + unify account rules + UI improvements
• fc7e9f4 fix(chat): fix web token expired error on re-entry and miniapp unknown message type
• 5609918 fix(miniapp): same ws reconnect fixes as web - allow 4001 retry + auto-reconnect on ticket error
• a3497f2 fix(chat): add handoff type to WsOutboundMessage
• 314aa3c feat(web): optimize UI responsiveness + merge tokens project + delete original tokens dir
• 72b1599 feat(miniapp): swap profile/cover-tool tab order, add back button to history page, highlight generate tab in history

阶段成果：

• 智米军师作为小程序首页，迁移 Web 聊天能力到小程序。
• 聊天会话按商家账号打通；Web 与小程序共享账号规则、WS 票据和重连策略。
• 合并 tokens 聊天项目（tokens 目录已删除），Web 端 UI 响应式优化。
• 小程序 Tab 顺序调整（个人中心后移）、历史记录页返回按钮与生成 Tab 高亮。

2026-08-03：合规、质量、封面稳定与体验收口

代表提交：

• 7451e0d fix(miniapp): improve privacy consent flow
• e8da9c9 chore(miniapp): reduce wechat devtools file watching
• 143030a fix(cover): extend jimeng generation polling
• e9eedd3 fix(cover): clamp jimeng poll timeout
• 7edbac6 fix(cover): constrain jimeng v40 dimensions
• d5ccd73 fix(cover): use official jimeng v40 request params
• 6b5ef53 fix(cover): stabilize miniapp workflow state
• 66170a9 feat(cover): add guizang social card prompt skill
• 91fd85e feat(cover): hard delete cover projects
• 665ac5b fix(cover): constrain generated text clarity
• 56d3bef feat: 新增用户协议与隐私政策相关功能
• 283c96b feat(miniapp): add back button to article detail action bar for 4-column layout
• c0eca38 / f841611 / e594799 fix(miniapp) chat keyboard dock
• e1bde4c refactor(miniapp): extract keyboard dock logic to composable
• 7debdf0 fix(miniapp): move auth API from subpkg-extra to shared api/
• cc9afa4 fix(miniapp): add preload rule for profile page to load subpkg-extra
• 3c72355 fix(cover): 封面项目列表聚合返回真实图片数/风格数/封面数
• ed9af56 feat(chat): 移动端键盘适配与用户切换重置, 多平台话术与防臆造约束
• f15f33f fix(miniapp): 封面列表统计用兼容写法并修复新建按钮右上对齐
• d489604 fix(web): 修复移动端键盘遮挡和页面布局适配问题
• 2756970 feat(web): 新增帮助中心页面, 侧边栏帮助入口跳转并移除版本字样
• 77e375d fix(web): 侧边栏受控折叠不再挤压文字, 路由守卫刷新后自动拉取用户信息
• 09def4a docs: 删除rag-agent-web下的小红书创作者中心文档
• e908627 docs: organize project history and development records

阶段成果：

• 小程序隐私协议改为用户主动阅读后勾选，不再默认同意；登录授权后置。
• 隐私政策链接改为直接跳转小程序内置页面，修复 wx.openPrivacyContract 打开空白问题；个人中心新增协议/隐私入口。
• 根据微信 DevTools 质量要求减少 watch 文件量，并保留 lazyCodeLoading 等配置。
• 封面生成从“状态完成”改为“目标风格已有封面”作为前端完成依据。
• 即梦封面生成修复生产级问题：尺寸改为 64 倍数标准映射（3:4 → 896×1152，替代按面积反推的 887×1182），解决 t2i_v40 报 50501 height or width invalid；50500/50501 快速失败不重试；生成任务并发锁规避 429。
• 引入归藏社交卡片 prompt skill，增强封面视觉结构、文字安全区和版式差异。
• 封面项目支持硬删除，清理记录、素材图、生成图和项目目录。
• 增加文字渲染硬约束，避免封面中文字模糊或乱码。
• 小程序聊天键盘上浮适配（useKeyboardDock composable）、用户切换状态重置、多平台话术与防臆造约束。
• Web 端新增帮助中心、侧边栏受控折叠、移动端键盘与布局适配。
• 封面项目列表聚合返回真实图片数/风格数/封面数；auth API 移出分包避免跨包依赖；profile 页分包预加载。