规约范例：设计

设计这份文件的作用不是描述实现，而是固定取舍：让后来接手的人知道当时放弃了什么、代价由谁承担。

1第二份：design.md

选型、分层与关键取舍，三条足够。

# 设计：course-material-search

## 选型
- 关键字检索：MySQL FULLTEXT，成本低、可解释，负责精确词命中
- 向量检索：Qdrant，负责同义与改写后的命中
- 结果融合：倒数名次融合（RRF），score = Σ 1/(k + rank)，k 取 60

## 分层
internal/search 只依赖 internal/db 与向量库的适配层（adapter）；
接口层负责参数校验与错误码映射。依赖方向单一，不允许反向依赖。

## 关键取舍
1. 用 RRF 而非加权求和：两路得分量纲不同，加权需要反复调参；
   RRF 只看名次，换资料集不需要重调
2. 放弃「向量召回 + 模型重排」：多一次模型调用，延迟翻倍，
   本轮收益不足以抵消
3. 阈值做成环境变量：不同课程的资料密度差异大，写死只能改代码

阈值为什么外置：不同课程的资料密度差异很大，写死在代码里，调一次就要改一次代码、发一次版本；写成环境变量，改配置即可生效，且启动缺项立即失败，不会静默降级。

2取舍的三条写法

一条取舍写不出这三项，等于没记。

先说选了什么。关键字走 MySQL FULLTEXT、向量走 Qdrant、融合用 RRF——每一处都要写出具体技术，不写「成熟的检索方案」这类无信息量的表述。
再说放弃的候选是什么。本例放弃了向量召回后再用模型重排的做法。不写候选，下次讨论会原样重来一遍。
最后说代价由谁承担。放弃重排的代价是相关性略低，收益是延迟减半；这类话要写进文件，不能只留在讨论里。

对应的课程知识点：软件架构中的权衡分析、依赖倒置（业务层不依赖具体检索实现，外部能力收在适配层）、配置外置。k 取 60 这类参数必须写出数值：它决定名次靠前的命中占多大权重。