跳转至

[ISSUE-0046] 质量分可配置

用户问:"质量分如何计算的?可以在设置中设置?" 选定方案 B:3 预设 + 自定义。

原算法(v0.10.0 - v0.10.65,硬编码)

5 维度总分 100:

维度 加分 触发条件
邮箱 40 emails 非空
电话 20 phone 非空
高评分 20 rating ≥ 4.5
评论多 10 commentCount ≥ 50
资料完善 10 scrape_status === 2(已挖过官网)

等级 80/60/40 为 高/良/一般 cutoff。

不同用户场景对"质量"定义不同:邮件营销 → 邮箱最重要;电销 → 电话最重要; 高端市场 → 评分/评论最重要。硬编码不灵活。

1. merchant-quality.ts 重构

QualityConfig interface(5 权重 + 2 阈值 + 3 等级门槛)+ DEFAULT_QUALITY_CONFIG(保留 v0.10.0 数值)+ 4 个 QUALITY_PRESETS

Preset 邮箱 电话 高评分 评论多 完善 适合
默认通用 40 20 20 10 10 综合场景
邮件营销侧重 60 10 15 10 5 主要做邮件
电销侧重 20 50 15 10 5 主要做电销/WhatsApp
高端市场 25 15 35 20 5 高端商家/品牌服务

2. Storage + Sync 缓存

export const qualityConfigItem = storage.defineItem<QualityConfig>('local:qualityConfig', {
  defaultValue: DEFAULT_QUALITY_CONFIG,
});

let cachedConfig: QualityConfig = DEFAULT_QUALITY_CONFIG;
export async function initQualityConfigCache(): Promise<void> {
  cachedConfig = sanitize(await qualityConfigItem.getValue());
  qualityConfigItem.watch((newCfg) => { cachedConfig = sanitize(newCfg); });
}

为什么 sync 缓存:computeQualityScore 在 cell render / sort 多处同步调用, 不能 await。main-layout mount 时异步拉到 cache,后续都同步读。

3. main-layout 启动时 init

useEffect(() => { initQualityConfigCache(); }, []);

4. Settings UI(本地设置顶部,显示比例下方)

SectionCard "质量分(找高价值客户)": - 行 1:4 个预设按钮(命中当前 config 自动高亮)+ 恢复默认按钮 - 行 2:5 个维度权重 TextField(带 helperText 提示条件) - 行 3:2 个阈值(评分门槛 / 评论数门槛)+ 满分 chip(≠ 100 时变 warning 黄) - 行 4:3 个等级门槛(高/良/一般 cutoff) - 底部 hint:警告满分 ≠ 100 时等级门槛可能要相应调整

5. 改完即时生效

qualityConfigItem.setValuewatchcachedConfig 更新 → 列表下次刷新 (轮询 3s)按新算法显示分数 + 等级。点表头排序也用新算法。

audit_grep(无 — 这是 feature 不是反模式)

注意点

  • 不强制总和 100:用户可以让"邮箱 = 80, 电话 = 10"如果他真这么想。 满分 chip ≠ 100 时显示 warning 提示,但不阻止。
  • 等级门槛独立可调:满分 100 时 80/60/40 合理;若用户改了权重和导致满分 150, 门槛要相应调整(UI 有提示)。
  • 默认值 = 旧硬编码值 → 老用户升级后看到的分数完全不变。
  • merchant-quality.ts 同一份代码两处用:客户端 React 组件(cell render)+ api/search.ts client-sort(quality 列排序)。Cache 让两处都用最新 config。

元洞察

算法暴露给用户配置 = 把"业务判断"还给业务方。

上一版我硬编码了对"质量"的判断(v0.10.0 默认权重)— 这其实是一个假设 ("邮箱最重要"对所有营销场景成立)。用户场景多样时假设就是限制。

解药是 预设 + 自定义:90% 用户选预设(成本极低),10% 进阶用户自定义 (成本可控)。

相关

  • [[0045-quality-score-real-sort-client-side|0045-质量分真排序-撤unsortable改client-sort]] — 这次"真排序"用的就是 cachedConfig
  • [[0044-screenshot-6-ux-feedback-batch|0044-用户截图6项UX反馈-缩放-按钮色-排序-分页-顶部CTA]] — 显示比例同模式(sync cache + 即时持久化)