beige/plans/Clover完整修改清单与方案.md

Clover 完整修改清单 + 方案（基于全量代码扒解）

来源：汇总《链路缺失诊断》《真实能力盘点》《前端逻辑诊断》三份扒解结论，去重去错判后的可执行清单。 口径：每条带【问题】【位置】【改法】【冲突】【工作量】。冲突=与另一窗口改前端的碰撞风险。 ⚠️ 另一窗口在改前端，🔴冲突项落地前必须先 git status + 与那边对齐。 日期：2026-06-12

---

总览：四类问题

类	条数	性质
A. Bug类（必修）	1	死链404，立刻劝退用户
B. 前端数据流（交互弱根因）	7	后端数据进了前端没组织好
C. 前端展示薄（能力没露）	4	后端算了前端没显示
D. 后端真缺口（从0做）	3	改稿信号/数据复盘/爆款拆解AI

关键认知：A+B+C 共12条都是"前端接线/重构"，不依赖后端加功能。D类3条才是真·新功能。先做A/B/C投入产出比最高——把后端已有能力露出来，界面立刻"饱满"。

---

A 类 · Bug（必修）

A1. Sidebar 导航死链 404 🔴必修

• 问题：侧边栏4个入口指向不存在的路由，一点就404。
• 位置：frontend/src/components/layout/Sidebar.tsx:22-25，写死 /tasks、/images、/tasks/build、/tasks/list，真实只有 /tasks/[id]/text、/tasks/[id]/images，且需taskId。
• 改法：导航语义改成"任务流"——侧栏只放真实可达的全局页（工作台/开新任务/审核台/历史/配置），删掉"选择文案/选择图片/建立任务/任务列表"这类需taskId的环节级入口；环节入口由"当前任务"动态带id跳转（dashboard已有RecentTasksBar可复用）。
• 冲突：🟢低（Sidebar是导航文件，另一窗口大概率没动，先 git status 确认）
• 工作量：0.5天

---

B 类 · 前端数据流（交互弱的根因，7条）

B1. 生图策略 A/B/C 维度被前端抹平 🔴最关键

• 问题：后端按3套叙事策略各N张生图（要6张→生18张），SSE带strategy字段、前端也收到了，但存成一维平铺数组，images页一堆散图看不出分组。
• 位置：stores/generationStore.ts(imageCandidates平铺) + app/tasks/[id]/images/page.tsx:55-68(grid平铺) + useSse.ts:101-108(收了strategy没用来分组)。
• 改法：generationStore 的 imageCandidates 改成按 strategy 分组（{A:[], B:[], C:[]} 或 groupBy）；images页改成3列/3段分策略展示，每套标注"方向A/B/C"，让用户在3个叙事方向间对比挑选。这正是俊达"多方向选优"的呈现。
• 冲突：🔴高（直接改前端核心store+页面，另一窗口最可能在这一带）
• 工作量：1-2天

B2. 五维分二次请求 + 每条重拉全量task 🔴

• 问题：SSE只推总分，五维明细靠再GET整个task补全，且每来一条候选就GET一次全量(8条=8次重复全量请求)，分数先0后跳变。
• 位置：useSse.ts:75-94。
• 改法（二选一）：①推荐——让后端SSE的text_candidate事件直接带五维明细(score_detail)，前端一次到位不用补拉（要后端配合改sse事件payload，碰后端）；②纯前端——补拉改成全部候选生成完后只GET一次批量补分，不要每条拉。
• 冲突：🟡中（改useSse；方案①还要碰后端sse_utils）
• 工作量：0.5-1天

B3. 选择态纯本地、刷新即丢、不批量 🟡

• 问题：selectedTextIds/selectedImageIds只在内存，刷新全没；点下一步才for循环逐个POST(N条N请求)。
• 位置：stores/taskStore.ts:13 + app/tasks/[id]/text/page.tsx:29-32。
• 改法：①选择即时 POST select（或localStorage暂存），刷新可恢复；②或保留本地但提供批量select接口一次提交（要后端加批量端点）。最低成本：选择态存localStorage按taskId隔离，进页面恢复。
• 冲突：🟡中（改taskStore）
• 工作量：0.5天

B4. 页面级跳转，每页 reset+重连SSE 🟡

• 问题：text→images→confirm独立页，每进一页useSse都reset再重新GET+重建SSE，无连续流感。
• 位置：useSse.ts:21,30(每次reset+hydrate) + 各页independent。
• 改法：①已完成阶段的候选不必重连SSE（只生成中才连）——按task.status判断要不要建SSE连接，已selection/review态只拉一次数据不连流；②或用单一任务容器布局保留store不reset跨环节。
• 冲突：🟡中
• 工作量：1天

B5. confirm页数据来源脆弱（跨store错位）🟡

• 问题：confirm用 generationStore.textCandidates.filter(taskStore.selectedTextIds) 拼已选，两store生命周期不一致，reset一边另一边错位就显空。
• 位置：app/tasks/[id]/confirm/page.tsx:22-23。
• 改法：confirm页独立GET /tasks/{id} 拿权威的is_selected候选，不依赖两个store的内存拼接。后端get_task已返is_selected，直接用。
• 冲突：🟡中
• 工作量：0.5天

B6. 错误静默吞掉，放大"空"感 🟡

• 问题：多处 .catch(()=>{}) 空吞，数据没拉到用户只见空白，不知是没数据还是出错。
• 位置：useSse.ts:37,93、preferenceStore.ts:31 等。
• 改法：catch里至少 set一个error态，页面区分"加载中/空数据/出错可重试"三态，给空状态配文案+重试按钮（review页已有空态范例可抄）。
• 冲突：🟢低（加错误态，不动主逻辑）
• 工作量：0.5天

B7. 关键SSE事件(task_done/error)空处理 🟡

• 问题：task_done生成完不提示不跳转、error出错不告知，状态机关键节点前端是哑的。
• 位置：useSse.ts:123-127(全部break)。
• 改法：task_done→toast"生成完成"+按钮去挑选/自动滚动；error→显式错误条+重试入口；heartbeat可继续忽略。
• 冲突：🟢低
• 工作量：0.5天

---

C 类 · 前端展示薄（后端算了没露，4条）

C1. dashboard 门面空 🔴

• 问题：工作台只有1句问候+3个按钮，后端那么多能力(今日生成/待审/飞轮进度/近期任务)一个没露。第一眼就"空"。
• 位置：app/dashboard/page.tsx。
• 改法：加数据看板——今日生成任务数/待审数/已通过数(GET /tasks?status=统计)、近期任务流(RecentTasksBar已有)、飞轮已学信号数(GET preference/context)。把后端有的数字摆出来。
• 冲突：🟢低（dashboard另一窗口少碰，新增展示）
• 工作量：1天

C2. 审核卡不显示七维分 🔴

• 问题：审核员通过/打回时看不到AI评委打分，盲拍。后端有score但review队列没返、卡没显。
• 位置：components/review/ReviewCard.tsx(只显product/theme/正文2行) + api/v1/review.py:_fmt_queue_item(没返score_json)。
• 改法：_fmt_queue_item补返已选文案的score_json+verdict+summary；ReviewCard复用ScoreDimBars组件显分。让审核基于分数。
• 冲突：🟡中（碰review.py，但approve/reject逻辑不动，只加返回字段）
• 工作量：0.5天

C3. 图片候选只显url+role 🟡

• 问题：后端storyboard算了每张图的goal/卖点/视觉策略/角色，_fmt_image只返role/url/strategy/seq，前端只显url+role。
• 位置：api/v1/tasks.py:_fmt_image + images页/ImageProgressCard。
• 改法：先定要不要把分镜role中文化(hook→"封面钩子")+显示该图承担的叙事角色；进阶可让后端存storyboard的overlay_text等供前端显示"这张图要表达什么"。
• 冲突：🟡中
• 工作量：0.5-1天

C4. ConfigPreviewPanel 注释与实现不符 🟢

• 问题：注释说"显示成分/质地/参考图3张"，实际代码只渲染名称/品类/卖点/风格/角度，没参考图没成分。
• 位置：components/tasks/ConfigPreviewPanel.tsx。
• 改法：要么补上参考图缩略(product.image_path后端有)+目标人群target_audience/brand_keyword(后端012字段已有)，要么改注释对齐实现。建议补字段，产品档案信息更全。
• 冲突：🟢低
• 工作量：0.5天

---

D 类 · 后端真缺口（从0做，3条）

D1. 改稿→飞轮信号（最强信号）🔴价值最高

• 问题：俊达最强飞轮信号是"人改AI稿"，Clover完全没有。enums无text_edit、TextCandidate无edited字段。
• 位置：constants/enums.py:57(SignalType)+ai_engine/constants.py(FLYWHEEL_WEIGHTS两处)、models/task.py:TextCandidate、新端点、preference_aggregator.py(注入改稿示范)、TextCandidateCard.tsx(加可编辑)。
• 改法：已有独立细案《俊达增量①-改稿diff-实施细案.md》，S1-S5全拆好+并发避让(走task_actions不碰review.py)。直接按那份做。
• 冲突：🔴高(碰enums，两处权重要手工merge；细案已设计绕开review.py)
• 工作量：2-3天

D2. 数据复盘——发布后数据回收 🔴真缺

• 问题：链路止于下载交付包，发出去的赞藏评/转化完全不回收，飞轮缺"结果反馈"闭环。全后端无此模块。
• 位置：全新——新表(note_performance)+录入入口(手填或导入)+复盘页+回灌飞轮。
• 改法：一期可极简——人工回填"这篇发布后数据如何"(赞藏评/是否爆)，进库当强信号回灌。不必自动抓小红书(合规+反爬风险高)。
• 冲突：🟢低(全新模块)
• 工作量：3-5天（含UI）

D3. 爆款拆解 AI 解析逻辑 🟡

• 问题：BenchmarkNote有features_json+analyze_status字段、fission.py有裂变引擎，但爆款8特征的AI解析逻辑+UI没接。
• 位置：models/product.py:BenchmarkNote(字段已建)、fission.py(引擎已建)、缺service+缺UI入口。
• 改法：补"标杆笔记→AI拆8特征→写features_json"的service+触发按钮；裂变引擎接前端入口(选爆款→设套数→生成)。字段和引擎都在，主要是接线+AI prompt。
• 冲突：🟢低(基本全新接线)
• 工作量：2-3天

---

执行顺序建议（按ROI + 并发安全）

原则：先低冲突高收益、把后端已有能力露出来，再碰高冲突和从0做的。具体哪些交AI、哪些你亲自看，你拍。

第一波·低冲突立竿见影（可立刻做，避开另一窗口热区）：

• A1死链(0.5d) + B6错误态(0.5d) + B7关键事件(0.5d) + C4配置面板(0.5d) + C1 dashboard看板(1d)
• 小计~3天，界面立刻不报错+变饱满，几乎不碰另一窗口核心文件

第二波·数据流重构（需与另一窗口对齐后做）：

• B1策略分组(1-2d，最关键) + B2五维分(0.5-1d) + C2审核显分(0.5d) + B5 confirm独立拉(0.5d)
• 小计~3-4天，解决"交互弱"主因

第三波·收尾前端：

• B3选择持久(0.5d) + B4跳转优化(1d) + C3图片信息(0.5-1d)

第四波·后端新功能（从0做，独立推进）：

• D1改稿diff(2-3d，价值最高) → D3爆款拆解接线(2-3d) → D2数据复盘(3-5d)

⚠️ 三条铁律：①🔴冲突项动手前必 git status + 跟另一窗口对齐 ②D1严格按已有细案走(绕开review.py) ③每波做完先验证(build+跑通)再下一波。

---

一句话给倩倩姐

12条前端问题(A+B+C)本质是"接线/重构"，把后端已经做好的能力露出来，界面立刻饱满、交互立刻顺——这是性价比最高的。3条后端缺口(D)才是真新功能，其中改稿diff价值最高、细案已就绪。

待另一窗口改完，B/C类要按《前端逻辑诊断》第五节6项重扒对比，确认哪些那边已经改了，避免重复劳动。