Skip to content

总表接口加上关键词、类型和是否截止的筛选 - #145

Merged
JunieXD merged 2 commits into
mainfrom
program-filters
Nov 21, 2026
Merged

JunieXD merged 2 commits into
mainfrom
program-filters

Conversation

@JunieXD

@JunieXD JunieXD commented Nov 21, 2026

Copy link
Copy Markdown
Contributor

关联

路线图 #2 里的 Agent 接入(MCP 是 #144),没有单独的 Issue。

改了什么

MCP 的 search_programs 对应 GET /programs,一次返回一整届。2027 届现在 92 个项目就有约 52KB,项目多了 Agent 读不完。所以给接口加上可选的服务端筛选;不带时和原来一样,网页还是在浏览器里筛(总体设计 §14)。

  • GET /programs 加上 q(学校名、简称、学院名或项目名里有它,不分大小写)、kind、closed(是否已截止)。关键词用 programs/search.ts 里的同一个函数,「已截止」用 statusOf(从 app/time.ts 挪到 programs/time.ts);网页和接口的规则只有一份。
  • 访客和冻结的账号只在预览的 5 条里筛,拿不到预览以外的项目。
  • 只有和网页一样、单独带一次 cohort 的请求才带 ETag。带筛选的结果会随时间变(closed);中间件又在路由校验之前运行,参数重复的请求原来会错拿 304。
  • 布尔的查询参数用 BoolParam,OpenAPI 里是 boolean,MCP 工具的参数照样从文档生成。
  • api.md §3、总体设计 §13 写上这几个参数。

怎么验证的

  • 网站 pnpm check(162 个测试)、pnpm build 都通过;pnpm openapi 重新生成后 openapi/crawler.json 没有变化。
  • 新测试:三个参数各自和组合起来的结果,包括只靠活动结束算出已截止的项目;空关键词算不带;访客的筛选拿不到预览以外的项目;带筛选的和参数重复的请求不带 ETag,重复的返回 400 而不是 304。MCP 测试断言 search_programs 公布的 closed 是布尔值,传 true 能被接口认出来。
  • 实测空关键词的开销:3000 个项目、每次筛选跑 7 遍,不提前返回时在电脑上要多花约 1.5 毫秒,所以空关键词直接算匹配。

影响

  • 接口:GET /programs 多了三个可选参数,不带时响应和原来一样;400 的说明改成「届或筛选的格式有误」。
  • MCP:search_programs 多了这三个参数,说明里写着可以先筛。已有的调用不受影响。
  • 抓取节点、表结构、已有数据:无。

MCP 的 search_programs 一次拿一整届,2027 届现在就有 52KB,项目多了 Agent 读不完。接口加上可选的筛选,让服务端先筛;不带时和原来一样,网页照旧在浏览器里筛。

- GET /programs 加 q、kind、closed,关键词和网页的搜索用同一个函数
- 访客只在预览的 5 条里筛,筛选拿不到预览以外的项目
- 带筛选的响应不带 ETag:是否截止随时间变,网页也不用
- 布尔的查询参数用 BoolParam,OpenAPI 里是 boolean,MCP 工具照样生成
- ETag 的中间件在路由校验之前跑:只给单独、只带一次 cohort 的请求打标签,参数重复的不再错拿 304
- statusOf 挪到 programs/time.ts,网页和接口的「已截止」用同一个判断
- 空关键词直接算匹配,网页每次筛选不多花时间
- 400 的说明写上筛选,测试补上靠活动结束算截止的项目和 MCP 公布的布尔参数
@JunieXD
JunieXD merged commit 2fe45b4 into main Nov 21, 2026
2 checks passed
@JunieXD
JunieXD deleted the program-filters branch November 21, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant