寻宝小分队——CodeArts团队实战总结

[寻宝小分队]

作业基本信息

项目	内容
这个作业属于哪个课程	202501 福大-软件工程实践-w 班
这个作业要求在哪里	团队作业——CodeArts团队实战总结
这个作业的目标	CodeArts团队实战总结

目录

• 作业基本信息
• 仓库地址
• github（我们主要使用的仓库）：
• CodeArt：
• apk文件：
• 测试用例：
• 1.体系结构设计
• 1.1使用前后端分离开发，后端项目部署到服务器上，前端项目运行时直接向服务器发请求
• 1.2技术栈基础：
• 2.接口设计
• 3.关键模块设计
• 4. LLM 接口设计
• 4.程序展示
• 4.1提交commit日志
• 4.1.1后端：
• 4.1.2前端：
• 4.1.3统计各组员commit次数
• 4.2程序截图及说明
• 4.2.1后端
• 4.2.2前端
• 5.工作流程、组员分工、组员贡献度比例
• 5.1完成这次作业的工作流程
• 5.2完成这次作业的组员分工、组员贡献度比例
• 5.3合作中遇到的困难及解决方法
• 5.4PSP表格
• 6.附加功能实现
• 6.1附加功能1
• 6.2附加功能2（未实现）
• 6.3附加功能3（未实现）

仓库地址

github（我们主要使用的仓库）：

前端：https://github.com/shubin45410292/car_buying_advice

后端：https://devcloud.cn-north-4.huaweicloud.com/codehub/project/8af2d8792b5049e5a9ee6c40b36c524f/codehub/3023910/home?ref=main

CodeArt：

https://devcloud.cn-north-4.huaweicloud.com/codehub/project/8af2d8792b5049e5a9ee6c40b36c524f/codehub/prjcode/home

apk文件：

car_buying_advice_main.apk.1 16.65M

测试用例：

（普通用户） 账号：123 密码：456

##修复了上一个apk因为没有进行签名就打包而无法联网的问题
改进情况：这次上传的apk已经可以正常使用
反思：应该早点尝试打包、考虑整个打包问题

1.体系结构设计

1.1使用前后端分离开发，后端项目部署到服务器上，前端项目运行时直接向服务器发请求

1.2技术栈基础：

前端：Flutter + Dart + Material Design

后端：

1）数据存储：MySQL（存储用户咨询记录、积分、订单等结构化数据）

2）异步任务：Task Queue（用于积分更新等非实时任务）

3）AI 集成：OpenAI API（提供智能购车建议生成能力）

4）容器化：Docker（环境一致性与部署便捷性）

核心分层：

1）API 层：基于 Hertz 框架定义 HTTP 接口（如 /api/consult/purchase 处理购车咨询），通过 Thrift IDL 定义接口规范（idl/consult.thrift）。

2）服务层（Service）：实现业务逻辑，协调数据访问层与外部接口

3）数据访问层（DAL）：通过 GORM 操作 MySQL 数据库，处理数据的增删改查（如 biz/dal/mysql/consult.go 保存咨询结果）。

4）工具层（Utils）：封装通用功能，如 OpenAI API 调用（pkg/utils/OpenAi.go）、配置解析等。

5）配置层：通过 Viper 管理配置（config/config.yaml），支持 MySQL、OpenAI 等服务的参数配置。

6）框架：Hertz（高性能 Golang HTTP 框架，负责路由、请求处理）

2.接口设计

1）购车咨询接口：

GET /api/consult/purchase：接收用户购车需求（预算、车型偏好等），返回 AI 生成的购车建议。

请求参数：预算范围、车型偏好、使用场景等

返回结果：包含需求分析、推荐车型列表、总建议

GET /api/consult/query：查询咨询记录，可以查询到用户以往所有的咨询记录

2）积分与积分兑换接口：

GET /api/score/user/query：查看用户积分

POST /api/score/gift/purchase：兑换汽车周边

GET /api/score/gift/query：查看汽车周边

GET /api/score/order/query：查看用户的兑换记录

3）用户接口：

POST /api/user/login：用户登录

POST /api/user/register：用户注册

POST /api/user/feedback：用户提供反馈

PUT /api/user/update/Info：上传用户个人信息

GET /api/user/query/Info：查询用户基本信息

4）管理员接口：

GET /api/admin/consult/query：查看所有咨询记录

POST /api/admin/user/add：添加用户

DELETE /api/admin/user/delete：删除用户

GET /api/admin/query：查看用户行为分析、热门话题报告

6）接口规范：所有接口返回统一格式 BaseResp，包含错误码（code）和消息（msg），确保前端处理一致性。

3.关键模块设计

1）智能咨询模块：

核心逻辑：接收用户需求 → 调用AI生成建议 → 存储结果到 MySQL

实现：pkg/utils/OpenAi.go 封装 AI 调用，biz/dal/mysql/consult.go 负责结果持久化

2）用户积分模块：

功能：管理用户积分获取、查询、礼品兑换。

依赖：Task Queue 处理积分更新（异步任务，避免阻塞主流程）

3）数据存储模块：

MySQL 表结构：通过 GORM 模型定义（如 biz/dal/mysql/model.go 中的 Consultation 表存储咨询记录）

配置：config/config.yaml 中 mysql 字段指定数据库连接信息

4）配置管理模块：

基于 Viper 实现，config/config.go 解析配置文件，支持动态重载（如 OpenAI 密钥、数据库地址）

4. LLM 接口设计

请求构造：

• 输入：用户购车需求（预算、车型、场景等），通过格式化字符串生成提示词（pkg/utils/OpenAi.go 中 prompt 模板）。

• 格式约束：要求 LLM 返回 JSON 结构，包含 analysis、result（车型列表）、proposal 字段，确保解析一致性。

API 调用：

• 封装：CallOpenAIWithConsult 函数负责 HTTP 请求构建、发送与响应处理。

• 配置：从 config/config.yaml 读取 openai.api-key、api-url、api-model

• 响应处理：清理 LLM 响应中的 Markdown 格式（如去除 ```json 标记），解析为 model.ConsultResult 结构体。

• 错误处理：处理网络错误、API 状态码非 200、JSON 解析失败等异常。

4.程序展示

4.1提交commit日志

4.1.1后端：

4.1.2前端：

4.1.3统计各组员commit次数

组员	commit次数
102300104李冬仙	6
102300205吴诗涵	7
102300217梁伟彬	8
102300220张宇亮	5
102300301陈珞瑶	3
102300305刘静芸	3
102300332叶远涛	1
102300407黎淑平	8
222100112陈俊南	3

4.2程序截图及说明

4.2.1后端

调用ai的api接口部分程序截图

用户登录、注册接口部分程序截图

购车咨询接口部分程序截图

管理员端查询咨询、查询用户部分程序截图

4.2.2前端

用户登录页面：用户输入账号和密码进行登录，可以选择记住密码，忘记密码也可以找回，下方提供链接跳转至注册账号

购车咨询页面：用户可以选择预算、偏好车型、主要使用场景、燃料类型偏好等需求（标注*表示必填选项），填写完毕后点击“获取购车建议”即可

咨询结果页面：先分析用户的需求，然后给出2-3款汽车推荐，显示汽车的图片、动力、驱动、座位等信息，最后给出推荐这一款车型的理由。

查看咨询记录：显示用户所有咨询记录，包括咨询时间、预算范围、燃油类型、使用场景等信息，以及推荐的车型数量

我的页：显示用户名、ID、积分、收藏车型等信息，可以编辑个人资料（地址、预算、偏好车型、品牌偏好等），底部有“退出登录”按钮

编辑个人资料

显示用户收藏的车型及具体信息

5.工作流程、组员分工、组员贡献度比例

5.1完成这次作业的工作流程

需求分析、原型设计、设计数据库、设计接口、前后端制定任务开始分工、后端先完成重要接口，在服务器上部署项目，以便前端调用测试、后端补足部分接口、前后端进行联调

部署到服务器上

5.2完成这次作业的组员分工、组员贡献度比例

成员	工作内容	贡献度
102300104李冬仙	登录和我的部分相关内容	9.5
102300205吴诗涵	制作用户端购车咨询界面、积分记录界面，管理员端咨询记录界面、用户账号管理界面	11
102300217梁伟彬	设计接口，完成积分与兑换接口、完成管理员端接口、将项目部署到服务器	14
102300220张宇亮	完成购车咨询接口、完成用户提供反馈接口，接口测试	13.5
102300301陈珞瑶	完成用户注册、用户上传信息接口，辅助接口测试，博客撰写	9
102300305刘静芸	原型设计、数据库设计、完成用户登录接口、用户信息查询接口、跟踪项目进度、博客撰写	12.5
102300332叶远涛	积分中心页面，咨询记录页面，统计与分析界面	9.5
102300407黎淑平	购车咨询结果跟兑换礼品界面	12.5
222100112陈俊南	完成咨询记录保存和查看模块	8.5

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

102300407 黎淑平

遇到的困难：进度不统一，导致仓库内代码拉取困难、曾经做好的页面被覆盖，前端做页面响应有时不知要接后端的哪个接口

解决方法：与后端人员积极沟通，和他们面对面商讨解决问题，与前端人员进行合作开发时要确定代码推送的详细规范

102300104 李东仙

接口调试问题

在前后端联调过程中，出现了请求返回 404 或无法获取完整 Token 的问题。

原因分析：前端最初使用了 queryParameters 拼接参数，而后端要求以 JSON Body 方式提交。

解决方法：调整请求方式，使用 jsonEncode() 发送数据；同时检查 Apifox 中的接口配置，确认后端接收格式为 application/json，最终接口调用成功。

Token 存储异常

登录后 Token 未正确保存，导致后续请求无权限访问。

原因分析：后端将 Access-token 与 Refresh-token 放在响应 Header 中，而不是返回体。

解决方法：在前端读取 response.headers 中的 Token 并使用 SharedPreferences 本地存储，确保会话状态能持续。

模拟器与本地服务器连接失败

在 MuMu 模拟器上运行时出现 SocketException: Connection refused。

原因分析：Flutter 模拟器访问 127.0.0.1 实际指向的是模拟器自身，而不是主机。

解决方法：将接口地址替换为宿主机的局域网 IP（如 http://192.168.x.x:8080），保证设备间网络互通。

注册接口返回错误码（400/404）

原因分析：参数名与后端字段不匹配，例如后端使用 phone_number 而前端传递了 phone。

解决方法：通过 Apifox 对照后端接口文档统一字段名称并重新测试。

UI 调整与表单验证

登录和注册页面在初期缺少输入校验与状态提示。

解决方法：增加 TextEditingController 绑定及 Snackbar 弹出提示，优化用户体验。

102300305 刘静芸

遇到的问题：第一次遇到开发时间这么短的任务，一开始对于项目要怎么完成、怎么设置计划如何进行分工毫无头绪

解决方法：按照之前的程序开发流程一步步进行

102300205 吴诗涵

遇到的问题和解决方法:

开发过程中多次遇到对接口信息了解不清晰的情况，通过和后端人员交流，明确了接口信息。

102300217 梁伟彬

问题：AI返回结果格式混乱

- 解决办法：优化Prompt模板，明确传入参数（预算、车型偏好、用途等）的格式约束；后端添加结果校验逻辑，过滤无效信息并标准化返回格式。

问题：服务器环境配置复杂（依赖冲突）、部署效率低

- 解决办法：使用Docker容器化打包应用及依赖，编写Docker Compose一键启动服务；采用CI/CD工具（如Jenkins/GitHub Actions），实现代码提交后自动构建、测试、部署。

102300220 张宇亮

遇到的问题和解决方法

- 问题1：用户咨询数据统计延迟、维度不全（如未按预算/车型分类）

- 解决办法：采用ELK栈或数据仓库存储咨询日志，定时离线计算统计指标（T+1更新）；提前定义分析维度（预算区间、车型偏好、咨询频次等），后端接口按维度返回聚合数据。

- 问题2：系统宕机、数据丢失风险

- 解决办法：部署主从数据库（如MySQL主从复制），定期自动备份数据（每日全量+增量备份）；使用Nginx实现负载均衡，部署多节点服务，单个节点故障时自动切换。

102300301 陈珞瑶

1. 跨角色沟通对齐难：前后端对接口参数、数据格式理解存在偏差，导致联调效率低。解决方法：制定统一接口文档规范，明确字段类型与返回格式，每日简短同步联调进度。
2. 技术实现思路分歧：团队成员对后端功能（如数据存储、接口设计）的实现方案有差异。解决方法：结合项目需求与技术选型，共同评估方案优劣，以 “高效落地、便于维护” 为原则达成共识。
3. 任务衔接不顺畅：模块间依赖关系未提前梳理，部分开发任务阻塞。解决方法：明确任务依赖顺序，提前同步关键节点进度，预留缓冲时间处理衔接问题。

102300332 叶远涛

遇到的困难:合作开发时会因为开发进度不同导致没法顺利进行

解决方法:沟通后合理分工把控进度

222100112 陈俊南

遇到的困难：在前后端联调初期，由于产品逻辑未完全定型，前端需求与数据结构频繁变更，导致后端接口需要不断调整甚至重构，增加了不必要的工作量并影响了开发进度

解决方法：与后端团队共同制定了严格的RESTful API设计规范与版本管理机制。引入Swagger进行接口文档化管理，并要求需求变更必须经过评审，从而减少了沟通成本与随意改动

5.4PSP表格

102300407 黎淑平

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	40 分钟	50 分钟
需求分析（包括学习新技术）	2 小时	2.5 小时
生成设计文档	1.3 小时	1 小时
代码规范（为目前的开发制定合适规范）	40 分钟	1 小时
具体设计	1.5 小时	2 小时
具体编码	5 小时	8 小时
代码复审	30 分钟	40 分钟
测试（自我测试，修改代码，提交修改）	1 小时	1.5 小时
计算工作量	20 分钟	15 分钟
事后总结，并提出过程改进计划	40 分钟	50 分钟
合计	13 小时 20 分钟	17 小时 5 分钟

102300104 李东仙

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	0.2 天	0.2 天
需求分析（包括学习新技术）	0.3 天	0.3 天
生成设计文档	0.2 天	0.2 天
代码规范（为目前的开发制定合适规范）	0.1 天	0.1 天
具体设计	0.3 天	0.4 天
具体编码	0.5 天	0.6 天
代码复审	0.1 天	0.1 天
测试（自我测试，修改代码，提交修改）	0.2 天	0.2 天
计算工作量	0.05 天	0.05 天
事后总结，并提出过程改进计划	0.05 天	0.05 天
合计	2.0 天	2.2 天

102300305 刘静芸

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	40分钟	35分钟
需求分析（包括学习新技术）	100分钟	120分钟
生成设计文档	30分钟	30分钟
代码规范（为目前的开发制定合适规范）	18分钟	15分钟
具体设计	50分钟	53分钟
具体编码	560分钟	600分钟
代码复审	50分钟	60分钟
测试（自我测试，修改代码，提交修改）	55分钟	77分钟
计算工作量	10分钟	10分钟
事后总结，并提出过程改进计划	30分钟	25分钟
合计	943分钟	965分钟

102300205 吴诗涵

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	15 min	18 min
需求分析（包括学习新技术）	60 min	90 min
生成设计文档	30 min	30 min
代码规范（为目前的开发制定合适规范）	18 min	30 min
具体设计	60 min	60 min
具体编码	600 min	660 min
代码复审	30 min	60 min
测试（自我测试，修改代码，提交修改）	120 min	180 min
计算工作量	12 min	12 min
事后总结，并提出过程改进计划	18 min	12 min
合计	963 min	1 152 min

102300217 梁伟彬

任务类型	预估耗时	实际耗时
需求分析（包括学习新技术）	3.0	4.0
生成设计文档	2.0	3.0
代码规范（为目前的开发制定合适规范）	2.0	2.0
具体设计	2.0	2.0
具体编码	8.0	8.0
代码复审	3.5	4.0
测试（自我测试，修改代码，提交修改）	5.0	5.0
计算工作量	1.0	1.0
事后总结，并提出过程改进计划	1.0	1.0
合计	27.05	30.0

102300220 张宇亮

任务类型	预估耗时	实际耗时
需求分析（包括学习新技术）	3.0	4.0
生成设计文档	2.0	3.0
代码规范（为目前的开发制定合适规范）	2.0	2.0
具体设计	2.0	2.0
具体编码	6.0	8.0
代码复审	3.0	4.0
测试（自我测试，修改代码，提交修改）	4.0	5.0
计算工作量	1.0	1.0
事后总结，并提出过程改进计划	1.0	1.0
合计	24.0	30.0

102300301 陈珞瑶

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	1h	0.5h
需求分析（包括学习新技术）	2h	1.5h
生成设计文档	2h	2h
代码规范（为目前的开发制定合适规范）	1h	0.5h
具体设计	3h	3h
具体编码	12h	15h
代码复审	2h	2h
测试（自我测试，修改代码，提交修改）	4h	4h
计算工作量	1h	0.5h
事后总结，并提出过程改进计划	1h	1h
合计	29h	30h

102300332 叶远涛

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	0.5小时	0.5小时
需求分析（包括学习新技术）	3小时	2小时
生成设计文档	2小时	1.5小时
代码规范（为目前的开发制定合适规范）	0.5小时	0.5小时
具体设计	2小时	1.5小时
具体编码	20小时	22小时
代码复审	2小时	2小时
测试（自我测试，修改代码，提交修改）	2小时	2小时
计算工作量	0.5小时	0.5小时
事后总结，并提出过程改进计划	2小时	2小时
合计	34.5小时	34.5小时

222100112 陈俊南

任务类型	预估耗时	实际耗时
估计这个任务需要多长时间	15分钟	15分钟
需求分析（包括学习新技术）	50分钟	60分钟
生成设计文档	30分钟	30分钟
代码规范（为目前的开发制定合适规范）	20分钟	15分钟
具体设计	40分钟	43分钟
具体编码	195分钟	220分钟
代码复审	50分钟	60分钟
测试（自我测试，修改代码，提交修改）	60分钟	77分钟
计算工作量	10分钟	10分钟
事后总结，并提出过程改进计划	25分钟	25分钟
合计	495分钟	555分钟

6.附加功能实现

6.1附加功能1

积分兑换商城和兑换记录

6.2附加功能2（未实现）

未实现

6.3附加功能3（未实现）

未实现