研途灵伴项目周报3：管理后台与饮食纵切收口

作者：陈哲凡
日期：2026-05-01

这一周，我的工作重点从“搭好脚手架”继续向“把脚手架真正用起来”推进。上一次周报里，我已经完成了管理后台基础结构、登录鉴权、页面路由和基础布局；到了本周，重点变成两个更实际的问题：

第一，后台页面不能只是占位页面，要能承载真实业务配置；第二，后端接口不能只停留在零散函数，要能形成一条从管理后台到用户端消费的完整纵切链路。

因此，本周我主要围绕“管理后台基础功能收口”和“饮食 / 菜单业务纵切”两部分展开工作。

一、同步主分支后重新确认个人任务边界

本周开始时，我先处理了分支同步和当前进度判断的问题。由于项目是多人协作推进，主分支上可能已经合入了其他同学帮助补齐的代码，如果不先重新检查当前分支状态，很容易重复开发，或者在不清楚代码来源的情况下误改已有实现。

我重新检查了项目中的任务文档、当前分支代码和已有文件结构，把属于我，也就是陈哲凡负责的工作重新归纳为几条主线：

1. 管理后台前端与后端接口
2. 菜单管理与饮食推荐服务
3. 知识建议、Prompt 模板、关怀规则等配置管理
4. 主动关怀运行时链路
5. 学习状态分析与知识建议匹配

这一步看起来像“整理”，但对多人项目非常重要。因为它决定了后续应该继续写哪里、哪些已经完成、哪些可以直接复用、哪些需要继续补全。

在同步主分支之后，我也明确了一个原则：只要当前分支上已经存在并符合任务要求的陈哲凡负责模块，无论是我自己之前完成的，还是其他同学协助合入的，都统一计入当前完成进度，然后继续从缺口处往下推进。

二、管理后台从脚手架进入真实业务页面

上一次周报中，管理后台已经具备了基础项目结构，包括 React、TypeScript、Vite、Ant Design、React Router、Axios 和 Zustand 等基础技术栈。

本周在这个基础上，后台页面开始从“页面入口”进入“业务管理页面”阶段。

目前管理后台已经具备以下核心页面结构：

1. Dashboard
2. 题集管理
3. 题目管理
4. 菜单管理
5. 知识建议条目管理
6. Prompt 模板管理
7. 关怀规则管理
8. 用户管理

这些页面不再只是简单占位，而是逐步接入了真实的列表、查询、表单、编辑、删除等后台常见能力。

其中比较重要的是，页面实现采用了统一的后台交互方式：

1. 使用 Ant Design 的 Table 承载列表数据
2. 使用 Form、Modal、Select、InputNumber、Switch 等组件完成新增和编辑
3. 使用统一封装的 Axios 请求函数访问 /api/v1/admin/*
4. 使用分页参数 page 和 page_size 对齐后端分页结构
5. 使用统一错误提取逻辑展示接口错误

这样处理之后，后台页面的扩展成本明显降低。后续新增一个管理模块时，可以沿用相同模式，而不是每个页面都重新写一套请求、表单和错误处理逻辑。

三、管理后台后端 /api/v1/admin/* 基础能力补齐

本周另一项重点工作是继续完善管理后台对应的后端接口。

当前后台接口围绕 /api/v1/admin/* 展开，主要覆盖以下资源：

1. /admin/users
2. /admin/stats
3. /admin/question-sets
4. /admin/question-items
5. /admin/meal-menus
6. /admin/advice-items
7. /admin/prompt-templates
8. /admin/care-rules

后端实现中，我重点处理了几个问题。

首先是接口结构统一。所有后台接口统一走 FastAPI 的 APIRouter，并使用统一的响应结构 ApiResponse 和分页结构 PaginatedResponse，让前端处理数据时不用为每个接口单独写适配逻辑。

其次是字段校验前置。通过 Pydantic schema 对菜单、题目、知识建议、Prompt 模板和关怀规则等数据进行校验，避免非法数据进入数据库。例如菜单餐次只能是 breakfast/lunch/dinner/snack，预算只能是 low/medium/high，Prompt 模板的 Agent 名称必须在系统支持范围内。

第三是删除保护。后台管理类功能很容易出现“误删配置导致业务链路断掉”的问题，所以后端对部分资源增加了引用检查。例如菜单如果已经被饮食记录引用，就不能直接删除；知识建议如果已经存在匹配或推送记录，也需要避免直接删除。

这部分实现虽然不如页面效果直观，但它决定了后台系统是否稳定、是否适合多人协作和后续演示。

四、饮食 / 菜单纵切链路推进

本周最重要的业务纵切是饮食模块。

我选择先做这条链路，是因为它依赖相对较少，但又能完整体现项目的“后台配置 → 后端服务 → 用户端消费”模式。

当前饮食链路主要包括：

1. 后台维护菜单
2. 用户端获取可选菜单
3. 用户记录一餐
4. 系统获取今日饮食记录
5. 系统根据用户偏好和学习状态推荐菜品
6. 统计某段时间内的饮食规律度

对应的后端接口集中在 /api/v1/meal：

1. GET /meal/menu
2. POST /meal/record
3. GET /meal/record/today
4. GET /meal/recommend
5. GET /meal/summary
6. GET /meal/regularity

其中 /meal/recommend 是本周比较有代表性的实现。它不是简单返回菜单列表，而是综合考虑了用户饮食偏好、饮食禁忌、预算、当前是否处于学习状态、连续学习时长、是否接近晚餐等上下文信息。

推荐逻辑中，我采用了规则评分加 AI 生成理由的组合方式：

1. 菜品标签命中用户偏好时加分
2. 命中饮食禁忌时直接过滤
3. 菜品预算符合用户偏好时加分
4. 用户连续学习时间较长时，优先推荐高蛋白、易消化类菜品
5. 晚餐偏晚时，优先推荐清淡、适合晚餐类菜品
6. 如果 AI 模型可用，则为候选菜品生成更自然的推荐理由
7. 如果模型不可用，则使用后端兜底理由，保证接口稳定返回

这样做的好处是，系统不会因为模型暂时不可用就失去核心功能，同时又能在模型可用时提供更自然、更像智能助手的体验。

五、前后端字段对齐与约束统一

本周工作中，一个很重要的体会是：前后端字段名和枚举值必须严格统一。

例如菜单餐次、预算档位、启用状态、分页参数，如果前端和后端各写各的，就会出现页面能打开但提交失败、查询无结果、筛选条件不生效等问题。

因此我在开发过程中重点对齐了以下约束：

1. 菜单餐次统一使用 breakfast/lunch/dinner/snack
2. 预算档位统一使用 low/medium/high
3. 管理后台列表统一使用 page/page_size
4. 筛选关键字兼容 q
5. 启用状态统一使用 is_active
6. 删除接口统一返回资源 id 和删除结果

这类细节并不复杂，但它们是项目能否顺利联调的关键。如果每个模块都在这些小地方不一致，后面联调时会消耗大量时间。

六、本周使用到的主要技术

本周使用到的技术主要集中在前后端管理类业务和后端服务逻辑上。

后端方面主要使用：

1. FastAPI 路由组织
2. Pydantic v2 数据校验
3. SQLAlchemy AsyncSession 异步数据库访问
4. 统一业务异常 BusinessException
5. 分页查询、条件筛选和排序
6. 后端规则评分与 AI 兜底生成

前端方面主要使用：

1. React 18
2. TypeScript
3. Vite
4. Ant Design 5
5. React Router
6. Axios
7. Zustand 登录态管理

这些技术组合比较适合当前项目的管理后台形态：页面数量多、表单多、列表多、接口对接多。统一模式之后，后面扩展知识建议、Prompt 模板和关怀规则会顺很多。

七、本周进度总结

本周完成的核心内容可以概括为两件事：

第一，管理后台从基础脚手架进一步推进到真实业务管理页面，具备了列表、筛选、新增、编辑、删除等基础能力。

第二，饮食 / 菜单纵切链路基本打通，从后台菜单配置到用户端饮食记录、推荐、汇总和规律度统计，已经形成了一条比较完整的业务闭环。

这部分工作的意义在于，它把项目从“结构已经搭起来”推进到了“业务已经可以开始跑起来”。后续配置管理和主动关怀也可以沿用类似模式继续扩展。

八、下一步计划

下一阶段，我会继续推进陈哲凡负责的第二部分重点任务：

1. 完成知识建议条目、Prompt 模板、关怀规则配置的运行时生效
2. 让 Prompt 模板真正进入 Agent 调用链路
3. 让关怀规则真正影响主动关怀触发和生成
4. 补齐学习状态分析与知识建议匹配接口
5. 对管理后台和后端服务进行构建、编译和单元测试验证

下一周的目标不是单纯继续堆页面，而是把“后台配置”真正接到“运行时逻辑”里。只有配置能生效，管理后台才不只是数据录入工具，而是整个智能系统的控制台。