研途灵伴学习专项接口支撑与协议收口复盘

摘要前面的计划、错题本、复习、状态这些后端模块其实都已经能各自工作了聊天里的动作按钮也能执行。但是当桌面端真的开始接学习页和聊天动作时问题就出来了数据来源太散页面要自己拼。动作点完以后前端只知道“成功了”不知道该刷新什么、该往哪里跳。所以我这轮做的事情可以概括成两步给学习页补一个聚合入口让页面能一次拿到关键数据。把聊天动作执行结果补成结构化返回方便前端联调。后来又根据审查意见把公共 API 文档和save_note的联调指引一起收口。这样这轮工作才算完整。这轮任务在解决什么问题这次对应的是“学习专项接口支撑代码”。和 OCR、跟课上下文这种偏单点功能的模块不太一样这部分更像一层连接件。它不是去发明新的学习规则也不是重写 plan、wrong_book、review 这些已有能力而是把已经存在的服务往前接一层变成前端能直接消费的接口。我一开始也想过继续拆小接口比如计划一个、复习一个、错题再一个。但回头看桌面端任务文档以后我发现这样意义不大。页面真正关心的不是“你后端有几个 service”而是“我打开页面的时候今天该看的东西能不能一次拿到”。所以我最后选的是“聚合 适配”这个方向聚合解决学习页数据太散的问题。适配解决聊天动作执行后的联调问题。我这轮具体做了什么这次改动主要落在下面四块。1. 新增 learning-support 接口我加了两个接口GET /api/v1/learning-support/overviewGET /api/v1/learning-support/actions其中overview负责给学习页返回一份聚合摘要内容包括今日计划摘要错题本摘要复习任务摘要当前状态摘要actions则更像一份动作目录告诉前端这个动作是前端本地处理还是后端处理有没有对应页面可以跳动作执行完以后建议刷新哪些模块2. 扩展聊天动作执行返回原来的聊天动作执行接口返回内容比较简单主要是successresult_message这个结构适合给用户弹个提示但不太适合前端联调。因为前端还会关心这次有没有真的新建错题有没有排出新的复习任务哪些页面需要重新请求数据所以我这次把动作执行结果扩成了result_payloadrefresh_targets这样前端拿到结果之后不用再自己猜下一步该怎么处理。3. 把路由和 schema 一起补齐新增接口不只是把 service 写完就算结束还要把整个出口补完整。所以这一轮我也同步改了api/v1/router.pyschemas/learning_support.pyschemas/__init__.pyschemas/conversation.py这样一来接口路由、响应结构和对外导出都在同一轮里收口后面别人接的时候不需要再去猜。主链路是怎么搭起来的我觉得这篇里最值得记下来的不是“我新写了两个接口”而是这轮接口到底怎么接到项目主链路里的。第一步先确认学习页到底需要什么我先回头看了桌面端页面和导航文档。虽然学习相关页面分成了计划、错题本、复习任务、学习复盘这些模块但它们真正依赖的核心数据其实都绕不开下面四块planwrong_bookreviewstate也就是说页面不是缺数据而是缺一个统一入口。所以overview的目标很明确不重新定义业务规则只把学习页最关心的数据拼好直接给前端一份能用的结果。第二步聚合层只做读取不重写业务逻辑这一步我实现时比较克制。学习专项接口支撑这一层本质上是“聚合和适配”不是再造一套计划逻辑也不是在这里顺手修改错题和复习规则。所以LearningSupportService里做的事情主要是从DailyPlan和StudyTask提炼计划摘要复用WrongBookService的积压数和高频错点能力复用ReviewService的今日复习和 upcoming 能力从UserStateSnapshot取最新状态快照。这样做的好处很直接主业务规则还是留在原来的 service 里学习专项这一层只是把数据读出来整理好不会把后端逻辑越写越散。第三步把聊天动作和学习页刷新接起来这一部分其实是这轮最关键的主链路。之前聊天里的动作按钮虽然能点但点完以后前端很难优雅地知道后续该做什么。比如点“加入错题本”以后错题页要不要刷新点“加入并安排复习”以后复习页和计划页要不要一起刷新点“标记完成”以后状态面板里的完成率要不要同步更新如果这些都让前端自己写死后面只会越来越乱。所以我这次把聊天动作返回补成了结构化结果。以add_review为例现在后端会返回这次命中的wrong_question_ids新建的review_task_idsnext_review_dates新建数量和命中已存在数量以及refresh_targets[wrong_book, review, plan, state]这样前端拿到结果之后就可以明确刷新相关模块而不是自己到处写判断。第四步再补一份动作目录减少前后端各自维护一套表只有动作执行结果还不够因为页面第一次渲染按钮时也需要知道这些动作的基础信息。所以我又加了GET /learning-support/actions。这个接口统一返回action_keyhandlertarget_routerefresh_targets对前端来说它更像一份动作说明书。这样不管是聊天按钮、学习页入口还是后面联调脚本大家都可以读同一份动作目录不需要每个地方再维护一套自己的映射表。这一步做完之后前后端之间那层隐性的耦合就少了很多。写这轮代码时我的思路这轮虽然偏接口层但真正写的时候我脑子里一直在反复确认下面几个点。1. 这一层不能越权我一直提醒自己learning-support不是新的核心业务模块。它不能在聚合时顺手改业务规则也不能绕开原来的 service 直接去写核心表。所以我最后坚持的原则是读取已有数据可以聚合核心写入还是走原来的 service联动逻辑只做显式暴露不在这里偷偷扩规则。2. 结构化返回是给联调用的不是为了让字段看起来更多补result_payload的时候我想得比较清楚这不是为了把接口写得更“复杂”而是为了让前端少猜一点。如果 action 执行完只有一句文案前端后面还是得自己推断有没有真正新建数据统计要不要变页面要不要刷新那还不如直接把这些信息明确返回。这样调试也更方便出了问题也更容易定位。3. 当前项目没有的页面和读取链路就不要假装已经有了这个教训就是save_note给我的。我最开始给它配了跳转和刷新目标后来回头对照桌面端页面和业务逻辑问题文档发现现在并没有稳定的笔记读取页和对应接口。这个时候如果还继续给前端一个“跳这里、刷这里”的指引只会把联调带偏。所以我最后把它收成target_route nullrefresh_targets []这个修改看上去像是“少做了一点”但其实更符合当前项目状态。做到哪一步就写到哪一步这样后面别人接起来才不会被误导。这轮里我遇到的两个实际问题这轮后面最花时间的其实不是写overview和actions本身而是把两个看起来不大、但很容易在联调时出问题的点处理干净。1. 接口已经写出来了但公共协议还是旧的这是我改完第一版代码以后碰到的第一个问题。当时后端里其实已经有了GET /learning-support/overviewGET /learning-support/actions/chat/conversations/{id}/action新增的result_payload/chat/conversations/{id}/action新增的refresh_targets代码层面看起来已经能用了但回头一看公共 API 规范这些内容并没有正式写进去。这个问题的尴尬点在于后端自己知道自己返回了什么前端也许临时能从代码里看出来但只要开始多人协作问题马上就会冒出来别人接接口时不知道这两个新接口是不是正式协议action 返回体到底有哪些字段要不要依赖也说不清楚后面再做联调或者返修时大家会出现“代码一套、文档一套”的情况。我后面处理这个问题的方法很直接就是不拖。我把 learning-support 这两个接口和 action 新增字段的结构、示例、语义都正式补到了公共 API 规范里。这样做完以后这轮改动才算真正从“本地实现完成”变成“团队里其他人也能按同一套口径接入”。这个问题也让我更确定了一件事联调层的代码如果没有配套协议实际上还不能算交付完成。2. save_note 的联调指引写得太超前了第二个问题是save_note。我一开始给它配了一套比较完整的动作目录信息target_route/course-contextrefresh_targets[course_context, notes]当时这么写的想法很简单就是希望前端在保存笔记以后能知道要跳哪、刷哪。但后面我回头去对桌面端页面文档和业务逻辑问题文档时发现这里有个很明显的偏差当前桌面端并没有正式的/course-context页面笔记读取接口这块本身还是缺口之前也专门沉淀过业务问题文档。也就是说我这时候继续给前端一个“你点完以后跳这里、刷新这里”的指引其实是在给一个当前还接不住的能力做承诺。这个问题我后面没有硬圆而是直接收紧处理target_route改成nullrefresh_targets改成空数组聊天动作执行返回里也同步改成空数组避免前端误以为这条链路已经完整打通。我觉得这个调整虽然看起来像是在“减配置”但实际上更靠谱。因为它至少保证现在返回给前端的信息都是真能兑现的不会把后面的联调带偏。这轮最大的收获这轮做完以后我自己的感受很明显前面的 plan、wrong_book、review、state 更像一块一块砖学习专项接口支撑做的事情就是把这些砖往前搭成一段真正能走的路。它不一定是项目里最显眼的模块但它很影响联调体验。因为页面是不是能一次拿到需要的数据按钮点完后页面是不是知道该怎么刷新这些问题如果没人补最后都会变成前后端来回猜。另外我这次也更明确了一件事接口层工作不只是“把数据吐出来”还要考虑当前阶段的页面能力、协议有没有写清楚、联调指引会不会误导别人。如果只看代码量这轮不算特别大但从项目推进的角度看我觉得这次补的是一层很关键的连接件。它把聊天动作、学习页展示和公共协议真正接到了一起也给后面桌面端联调省了一些重复沟通的成本。