这个作业属于哪个课程	2501_CS_SE_FZU
这个作业要求在哪里	软工实践——CodeArts团队实战总结
团队名称	因为把dll看成ddl而急死
这个作业的目标	极限编程，实现基于大语言模型的购车意向咨询系统，博客撰写
其他参考文献	无

目录

一、项目地址

CodeArts仓库

二、CodeArt 的提交日志截图

学号	姓名	提交次数
102300229	叶达	15
102300206	张钰婷	4
102300109	郑天浩	3
032201218	陈彦哲	4
102300127	李严	3
102300225	吴嘉鑫	4
102300221	苏峻	3
032201109	朱添驰	3
102300214	陈雨昕	3
102300202	陈雨桐	3

三、程序运行环境

-前端：Flutter 3.35.7
-后端：Python 3.11 + FastAPI
-数据库：MySQL 8.4，开发/CI 用 SQLite 内存库
-依赖与环境管理：uv包管理器

四、功能实现思路描述

模块划分与逻辑

遵循参考博客的模块划分，结合当前实现与规划，分为「用户管理」「咨询请求处理」「结果展示与格式化」「数据安全」四个模块：

1) 用户管理模块（规划/前端已接入）

-功能描述
-账号注册、登录、令牌刷新与退出登录。
-登录成功后持久化访问令牌与刷新令牌（SharedPreferences/Hive）。

-接口定义（RESTful，统一前缀 /api/v1/users）

接口	方法	入参（JSON）	出参（JSON）
/api/v1/users/register	POST	username、email?、phone?、password	{ code, message, data }
/api/v1/users/login	POST	identifier、password	{ code, message, data: { access_token, refresh_token } }
/api/v1/users/refresh	POST	refresh_token	{ code, message, data: { access_token } }

-实现要点
-服务端统一响应结构与错误码；异常统一由 routes.py 注册的处理器返回：backend/app/api/v1/routes.py:36-52。
-前端 API 客户端自动刷新令牌与重试：frontend/llm_app/lib/services/api_client.dart:21-84。

2) 咨询请求处理模块（已实现 + 规划）

-功能描述
-查询系统中已注册的 LLM 模型，选择模型启动咨询。
-按四阶段提示词契约执行咨询流程，结果以 Markdown 列表与表格输出，便于解析与渲染。

-接口定义

接口	方法	入参	出参
/api/v1/llm/models	GET	-	{ code, message, data: { items: [...] }, request_id }
/api/v1/consult/start	POST	{ modelId? , customModel? } 二选一	{ code, message, data: { consultId, modelSource }, request_id }
/api/v1/llm/consultations	POST	{ credentials, modelId? , customModel? }	{ code, message, data: { consultations_id } }
/api/v1/llm/consultations/phase1	POST	需求关键字/预算等	{ code, message, data: { candidates: [...] } }
/api/v1/llm/consultations/phase2	POST	需求关键词修正	{ code, message, data: { updated: [...] } }
/api/v1/llm/consultations/phase3	POST	参数对比维度	{ code, message, data: { table: ... } }
/api/v1/llm/consultations/phase4	GET	consultations_id	{ code, message, data: { final: ... } }

-LLM 接口调用设计
-固定 system prompt 与结构化输出（严格）：backend/app/services/llm/prompts.py:7-13
-Builder 模式封装客户端、上下文记忆与阶段提示词注入：backend/app/services/llm/client.py:155-213
-请求重试与指数退避、统一异常：backend/app/services/llm/client.py:102-153

3) 结果展示与格式化模块（前端）

-功能描述
-将 LLM 输出按约定格式渲染，列表项遵循 - 车型名 - 一句话理由；表格列固定为：车型|价格(万元)|动力类型|续航/油耗|空间|安全配置|适合人群|总评。
-采用 flutter_markdown 渲染 Markdown 文本，配合业务解析器保证稳定展示。

-实现要点
-前端服务封装与仓储解耦：frontend/llm_app/lib/services/consultation_service.dart:1-32、frontend/llm_app/lib/repositories/consultation_repository.dart:1-46。
-Provider 统一状态：frontend/llm_app/lib/providers/consultation_provider.dart:1-31。

4) 数据安全模块

-功能描述
-身份认证：JWT（访问令牌与刷新令牌），令牌拦截器自动注入。
-配置安全：通过环境变量注入（Pydantic Settings），禁止硬编码密钥与连接串。
-访问控制：限流（SlowAPI）、结构化日志与 request_id 贯穿。

-实现要点
-后端配置：backend/app/core/config.py:20-60（.env 加载、字段说明）。
-令牌拦截与自动刷新：frontend/llm_app/lib/services/api_client.dart:21-84。

类图

系统用例图

系统顺序图

---

五、程序截图说明

1.服务器运行响应日志

2.apifox配置

3.登录的请求响应

4.获取用户基本信息响应

5.获取用户详细资料响应

6.获取最近一次咨询响应

7.建立咨询会话id响应

8.输入基本信息，模型给出初步候选响应

9.最终推荐响应

六、组员分工及贡献比例

学号	姓名	工作内容	贡献度
102300229	叶达	后端框架搭建	13
102300206	张钰婷	前端 咨询模块 编写	12
102300109	郑天浩	后端数据库模型定义	8
032201218	陈彦哲	后端 测试模块 编写	8
102300127	李严	后端schema接口输入输出结构定义	8
102300225	吴嘉鑫	前端“推荐”模块编写	11
102300221	苏峻	前端“我的”模块编写	10
032201109	朱添驰	前端“咨询模块编写”	12
102300214	陈雨昕	博客随笔内容的编写	10
102300202	陈雨桐	后端api端点编写	8

七、合作中遇到的困难及解决方法

1.1 叶达（102300229）

遇到的困难

每次咨询会话存在内存管理问题，如果用户不完成会话

解决方法

当模型客户端长时间未接受输入，则自动结束会话

1.2 张钰婷（102300206）

遇到的困难

对前端实现不够熟练

解决方法

加强学习，询问组长

1.3 郑天浩（102300109）

遇到的困难

模块的输入输出的格式不符合要求

解决方法

和其他模块的同学沟通，了解整个流程

1.4 陈彦哲（032201218）

遇到的困难

在编写测试代码的时候，经常会测试失败。这些失败有时候是队友代码的问题，但有的时候是我自己的代码的问题。
所以我经常会误以为是队友代码的问题，然后和队友沟通，结果发现是自己的问题，这样大大增加了沟通成本。

解决方法

为我的测试代码编写对应的测试代码，也就是“测试的测试”。在我自己对自己测试没有问题之后，我再去测试队友的代码。
这样大大减少了沟通成本，提升了沟通效率。

1.5 李严（102300127）

遇到的困难

功能实现不够熟练

解决方法

加强学习

1.6 苏峻（102300221）

遇到的困难

与服务器进行连接时无法获取到正确的数据

解决方法

借助ai进行错误查询以找出问题所在，然后再进行测试所得数据。

1.7 朱添驰（032201109）

遇到的困难

因数设计时考虑不够周到导致部分接口设计时存在一定问题

解决方法

与其他组员交流，重新设计接口

1.8 陈雨昕（102300214）

遇到的困难

开发时间短，学习使用框架的时间紧张，不熟悉前后端交互

解决方法

上网查询，与队友交流解决办法

1.9 陈雨桐（102300202）

遇到的困难

使用git不太熟练；一开始api设计不够合理

解决方法

通过ai查不同的git指令；和队友沟通满满解决了

1.10 吴嘉鑫（102300225）

遇到的困难

1.布局与内容溢出（BOTTOM OVERFLOWED）的冲突：
最初的需求是顶部卡片1（推荐信息）固定不动，而下方的卡片（2, 3, 4）在剩余空间中滚动。
当卡片1的“推荐理由”内容过多时，导致其 SizedBox（固定 30% 屏幕高度）发生内容溢出（出现黄色警告条）。
尝试“点击放大卡片1”的方案（即动态改变 SizedBox 的 height）导致了更严重的布局冲突：Column 无法计算一个“固定”组件和一个“动态高度”组件的布局，导致整个页面溢出。
2.动态数据绑定与状态管理：
如何实现顶部的 DropdownButton（下拉框）能够同时控制页面上所有卡片（推荐卡、基本信息卡、详细信息卡、参数对比卡）的数据显示。
在 initState 中加载一次数据后，如何在切换下拉框时，让所有卡片都接收到对应的新数据并刷新。
3.复杂UI组件的实现：
卡片3 (详细信息): 需要显示“核心需求”和“偏好设置”等标签 (Chips)，这些标签必须能在空间不足时自动换行。
卡片4 (参数对比): 需要显示一个多列的表格，而这个表格的宽度远超屏幕宽度，必须能横向滚动，且不能显示滚动条。
4.项目结构与代码可维护性：
随着四个卡片的功能全部实现，所有的数据模型（如 RecommendationInfo）、模拟数据（如 teslaComparisonData）和UI构建逻辑（所有 _build... 方法）全部堆积在 main.dart 一个文件中。
这导致 main.dart 文件变得极其臃肿，难以阅读、修改和维护。

解决方法

1.采用“固定高度 + 弹窗”方案解决布局冲突：
放弃了“点击放大”方案，回到了 Column + Expanded 的稳定布局。卡片1被包裹在 SizedBox(height: screenHeight * 0.25) 中，保持其高度固定。
为了显示卡片1的完整内容，我们移除了内部滚动条，并对“推荐理由”文本设置 maxLines: 1 和 overflow: TextOverflow.ellipsis（显示省略号）。
关键解决方案：为卡片1添加 GestureDetector，当用户点击时，调用 showDialog 方法弹出一个 AlertDialog (详情弹窗)。这个弹窗在新的图层显示，可以自由滚动并展示全部的推荐理由，完美解决了固定高度和内容溢出的矛盾。
2.创建统一的数据模型与服务层：
统一数据模型: 创建了一个总的 AppScreenData 类，它封装了该页面所有需要变化的数据（卡片1、2、3、4的数据模型）。
建立“数据库”: 在 _DropdownCardPageState 中，创建了一个 Map<String, AppScreenData> _mainDatabase 变量。
数据驱动UI: initState 时，从 MockApiService 加载所有数据并填充 _mainDatabase。DropdownButton 的 onChanged 回调中只负责 setState 更改 _selectedOption（选中的车型名称）。build 方法根据 _selectedOption 从 _mainDatabase 查找对应的 AppScreenData，然后将数据分发给各个卡片。
3.使用 Wrap 和 SingleChildScrollView 构建复杂UI：
卡片3 (自动换行): 在 ConsultationDetailCard 中，使用 Wrap Widget 来布局标签 (Chips)。Wrap 会自动根据屏幕宽度计算布局，当一行放不下时，自动将下一个 Chip 折到新的一行，完美实现了响应式布局。
卡片4 (横向滚动): 在 ComparisonTableCard 中，使用 SingleChildScrollView(scrollDirection: Axis.horizontal) 包裹一个 Row（Row 中包含多个 Column）。这使得表格可以横向滚动。最后用 ScrollConfiguration 包裹它，并设置 scrollbars: false 来隐藏滚动条。
重构项目（关注点分离）：
4.按照专业项目结构，将代码分离到三个独立的文件夹中：
lib/models/: 存放所有的数据结构文件（如 recommend_model.dart）。
lib/services/mock/: 存放模拟API服务（如 mock_recomend_service.dart），它负责提供数据。
lib/widgets/: 存放所有独立的UI组件（如 recommendation_card.dart, comparison_table_card.dart 等）。
main.dart 文件现在变得非常简洁，只负责页面骨架、状态管理和 import 导入需要的服务与 Widgets，大大提高了代码的可读性和可维护性。

八、PSP表格

1.1 叶达（102300229）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	80	60
• Estimate	• 估计这个任务需要多少时间	80	60
Development	开发	680	620
• Analysis	• 需求分析 (包括学习新技术）	100	90
• Design Spec	• 生成设计文档	80	70
• Design Review	• 设计复审	40	30
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	30	25
• Design	• 具体设计	80	70
• Coding	• 具体编码	240	210
• Code Review	• 代码复审	40	30
• Test	• 测试（自我测试，修改代码，提交修改）	150	160
Reporting	报告	70	60
• Test Report	• 测试报告	40	30
• Size Measurement	• 计算工作量	20	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	30	30
	合计	760	680

1.2 张钰婷（102300206）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	60	45
• Estimate	• 估计这个任务需要多少时间	60	45
Development	开发	620	570
• Analysis	• 需求分析 (包括学习新技术）	90	80
• Design Spec	• 生成设计文档	60	50
• Design Review	• 设计复审	30	25
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	20	15
• Design	• 具体设计	60	55
• Coding	• 具体编码	200	180
• Code Review	• 代码复审	30	25
• Test	• 测试（自我测试，修改代码，提交修改）	130	140
Reporting	报告	60	50
• Test Report	• 测试报告	30	20
• Size Measurement	• 计算工作量	10	10
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	20	20
	合计	740	665

1.3 郑天浩（102300109）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	70	50
• Estimate	• 估计这个任务需要多少时间	70	50
Development	开发	640	600
• Analysis	• 需求分析 (包括学习新技术）	100	90
• Design Spec	• 生成设计文档	70	60
• Design Review	• 设计复审	40	35
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	30	25
• Design	• 具体设计	70	65
• Coding	• 具体编码	220	200
• Code Review	• 代码复审	40	30
• Test	• 测试（自我测试，修改代码，提交修改）	140	150
Reporting	报告	70	60
• Test Report	• 测试报告	40	25
• Size Measurement	• 计算工作量	15	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	25	20
	合计	810	735

1.4 陈彦哲（032201218）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	100	85
• Estimate	• 估计这个任务需要多少时间	80	55
Development	开发	400	370
• Analysis	• 需求分析 (包括学习新技术）	110	95
• Design Spec	• 生成设计文档	80	70
• Design Review	• 设计复审	50	40
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	25	20
• Design	• 具体设计	80	75
• Coding	• 具体编码	240	220
• Code Review	• 代码复审	50	40
• Test	• 测试（自我测试，修改代码，提交修改）	200	180
Reporting	报告	100	95
• Test Report	• 测试报告	55	50
• Size Measurement	• 计算工作量	20	20
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	25	15
	合计	710	625

1.5 李严（102300127）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	80	70
• Estimate	• 估计这个任务需要多少时间	80	70
Development	开发	860	780
• Analysis	• 需求分析 (包括学习新技术）	70	60
• Design Spec	• 生成设计文档	60	50
• Design Review	• 设计复审	50	40
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	40	35
• Design	• 具体设计	60	55
• Coding	• 具体编码	360	360
• Code Review	• 代码复审	50	40
• Test	• 测试（自我测试，修改代码，提交修改）	90	80
Reporting	报告	70	60
• Test Report	• 测试报告	40	25
• Size Measurement	• 计算工作量	15	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	25	20
	合计	930	850

1.6 苏峻（102300221）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	30	25
• Estimate	• 估计这个任务需要多少时间	20	15
Development	开发	500	550
• Analysis	• 需求分析 (包括学习新技术）	50	40
• Design Spec	• 生成设计文档	50	55
• Design Review	• 设计复审	35	40
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	35	20
• Design	• 具体设计	55	60
• Coding	• 具体编码	150	170
• Code Review	• 代码复审	20	25
• Test	• 测试（自我测试，修改代码，提交修改）	30	100
Reporting	报告	80	90
• Test Report	• 测试报告	50	30
• Size Measurement	• 计算工作量	20	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	40	60
	合计	1165	1295

1.7 朱添驰（032201109）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	80	70
• Estimate	• 估计这个任务需要多少时间	80	70
Development	开发	600	580
• Analysis	• 需求分析 (包括学习新技术）	70	60
• Design Spec	• 生成设计文档	60	50
• Design Review	• 设计复审	50	40
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	40	35
• Design	• 具体设计	60	55
• Coding	• 具体编码	360	360
• Code Review	• 代码复审	50	40
• Test	• 测试（自我测试，修改代码，提交修改）	90	80
Reporting	报告	70	60
• Test Report	• 测试报告	40	25
• Size Measurement	• 计算工作量	15	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	25	20
	合计	670	600

1.8 陈雨昕（102300214）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	60	70
• Estimate	• 估计这个任务需要多少时间	60	70
Development	开发	645	695
• Analysis	• 需求分析 (包括学习新技术）	30	40
• Design Spec	• 生成设计文档	50	60
• Design Review	• 设计复审	50	40
• Coding Standard	• 代码规范 (为目前的开发制定合适的规范)	30	20
• Design	• 具体设计	30	25
• Coding	• 具体编码	300	320
• Code Review	• 代码复审	120	150
• Test	• 测试（自我测试，修改代码，提交修改）	50	40
Reporting	报告	65	60
• Test Report	• 测试报告	30	25
• Size Measurement	• 计算工作量	10	15
• Postmortem & Process Improvement Plan	• 事后总结, 并提出过程改进计划	25	20
	合计	785	835

1.9 陈雨桐（102300202）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	15	20
Estimate	估计这个任务需要多少时间	15	20
Development	开发	675	740
Analysis	需求分析 （包括学习新技术）	130	120
Design Spec	生成设计文档	30	30
Design Review	设计复审	20	25
Design	具体设计	60	75
Coding	具体编码	300	330
Code Review	代码复审	20	40
Test	测试（自我测试，修改代码，提交修改）	115	120
Reporting	报告	50	50
Test Repor	测试报告	30	30
Size Measurement	计算工作量	20	20
	合计	740	810

1.10 吴嘉鑫（102300225）

PSP	Personal Software Process Stages	预估耗时（分钟）	实际耗时（分钟）
Planning	计划	15	20
Estimate	估计这个任务需要多少时间	15	20
Development	开发	705	740
Analysis	需求分析 （包括学习新技术）	140	120
Design Spec	生成设计文档	30	30
Design Review	设计复审	20	25
Design	具体设计	60	75
Coding	具体编码	320	330
Code Review	代码复审	25	40
Test	测试（自我测试，修改代码，提交修改）	110	120
Reporting	报告	50	50
Test Repor	测试报告	30	30
Size Measurement	计算工作量	20	20
	合计	740	810