一 个性化路线生成流程
1.1 接口设计
个性化路线生成分为基础版和增强版两个接口。基础版接收用户水平和学习方向两个核心参数，增强版增加学习目标关键词学习周期每日时长等扩展参数。
@router.post("/learning-path")asyncdefgenerate_learning_path(body:LearningPathRequest,user_id:str=Depends(get_current_user_id)):path=awaitlearning_path_service.generate_learning_path(user_level=body.user_level,learning_direction=body.learning_direction,known_concepts=body.known_concepts,)returnResponseBase(data=path)@router.post("/learning-path/enhanced")asyncdefgenerate_learning_path_enhanced(body:LearningPathRequest,user_id:str=Depends(get_current_user_id)):path=awaitlearning_path_service.generate_learning_path_enhanced(user_level=body.user_level,learning_direction=body.learning_direction,learning_goal=body.learning_goal,keywords=body.keywords,study_period=body.study_period,daily_time=body.daily_time,)returnResponseBase(data=path)1.2 生成机制
后端服务层调用 LLM 生成路线结构，包含阶段数节点数和学习目标等信息。首次生成仅返回框架数据，学习内容在用户进入节点时按需加载。
这种解耦设计的核心技术考量在于 LLM 调用成本较高，一次性生成全部内容会导致响应时间过长。通过只生成框架结构，可以快速响应用户请求，让用户尽快开始学习。节点内容的按需生成则通过会话机制实现，在用户进入具体节点时才调用 LLM 生成详细内容，同时进行缓存，避免重复调用。
1.3 路线保存与分享
用户可将生成的路线保存到热榜，通过 save_generated_path 接口将 AI 生成的路线数据转换为用户路线格式持久化。
@router.post("/learning-path/save")asyncdefsave_generated_path(body:GeneratedPathSaveRequest,user_id:str=Depends(get_current_user_id)):stages_data=[{"name":s.name,"goal":s.goal,"duration_days":s.duration_days,"nodes":[{"title":n.title,"learning_goal":n.learning_goal}fornins.nodes],}forsinbody.stages]result=awaitlearning_path_service.create_user_path(user_id=user_id,title=body.title,summary=body.summary,stages_data=stages_data,)returnResponseBase(data=result)保存的路线与用户手动创建的路线具有相同的结构和功能，支持投票收藏等互动操作。这种设计实现了内容生成和内容分享的闭环，用户不仅可以获取个性化路线，还可以将优质路线贡献给社区，形成完整的学习生态。
二 数据流转设计
2.1 三层数据模型
路线数据在三个层级间流转。展示层仅包含卡片所需的基础信息，详情层增加阶段和节点列表，学习层在用户进入节点时动态生成具体内容。
展示层数据结构示例：
{"id":"path_001","title":"零基础入门投资","summary":"从基础知识到实战操作的完整学习路径","difficulty_level":"入门","learning_direction":"股票投资","estimated_days":14,"stage_count":3,"learner_count":1256}详情层数据增加阶段和节点列表，学习层数据包含具体的教学内容块。这种分层设计使得数据可以根据使用场景进行裁剪，避免不必要的数据传输。展示层用于首页列表，详情层用于路线详情页，学习层用于节点学习页，每层数据按需加载。
2.2 渐进式加载策略
渐进式加载与用户操作流程相匹配，用户先浏览路线概览，再查看详细结构，最后进入具体学习内容，每个阶段仅加载当前需要的数据。
这种策略的技术优势在于减少初始页面加载时间，提升用户体验。同时，通过延迟加载非关键内容，可以降低服务器负载，提高系统的整体性能。渐进式加载的实现依赖于前端路由和状态管理，当用户导航到不同页面时，触发相应的数据加载逻辑。
三 技术实现亮点
3.1 状态管理优化
前端使用 Provider 模式管理全局状态，将学习路线数据集中管理。Provider 通过 ChangeNotifier 实现状态变更通知，相关 Widget 自动响应状态变化并刷新界面。这种响应式状态管理机制确保界面数据与后端数据的一致性，同时简化了状态传递逻辑。
3.2 异步处理机制
系统大量使用异步操作处理数据请求和内容生成，避免阻塞主线程影响用户体验。前端使用 async await 语法处理异步操作，后端使用 FastAPI 的异步支持实现高并发请求处理。异步操作配合状态管理，确保界面在数据加载期间保持响应，并在数据就绪后及时更新。
3.3 缓存策略
后端对生成的路线内容进行缓存，避免重复调用 LLM 生成相同内容。缓存机制结合会话管理，确保用户在同一会话中多次访问同一节点时直接返回缓存数据。缓存策略的设计考量在于减少 LLM 调用次数，降低服务成本，同时提高响应速度。
