月下调试人——CodeArts团队实战总结

月下调试人 2025-11-12 23:44:55

这个作业属于哪个课程	202501福大-软件工程实践W班
这个作业要求在哪里	CodeArts团队实战总结
团队名称	月下调试人
作业目标	CodeArts团队实战总结

一、项目相关地址
二、功能实现思路描述
a.RedisConfig（Redis序列化配置）
b.AdminController / UserController（用户与管理员接口）
c.GlobalExceptionHandler（全局异常处理）
d.PersistentChatMemoryStore（对话记忆持久化）
e.CarCounselorAgent（AI提示词代理）
f.AgentConfig（AI代理配置）
g.MessageDTO（消息传输对象）
h.MessageDTOConverter（消息转换工具）
i.JWT 无状态认证系统
j.购车辅助服务核心逻辑
三、程序截图说明
四、遇到的困难以及解决方式
五、PSP表格

一、项目相关地址

仓库地址

项目地址

二、功能实现思路描述

a.RedisConfig（Redis序列化配置）

该配置类用于实现 Redis 序列化支持，核心功能为解决 ChatMessage 对象（含 SystemMessage、UserMessage、AiMessage 子类） 的多态序列化问题。

实现思路：

定义多态类型标识

通过 @JsonTypeInfo 和 @JsonSubTypes 定义多态类型标识（type 属性），指定各子类映射关系，实现反序列化时的类型识别。
配置 Jackson 的 ObjectMapper
禁用 FAIL_ON_EMPTY_BEANS，避免空对象序列化错误。
启用 BasicPolymorphicTypeValidator 验证多态类型安全性。
注册 ChatMessage 子类并绑定 MixIn 机制。
Redis 序列化方案
使用 GenericJackson2JsonRedisSerializer 结合自定义的 ObjectMapper，在 Redis 存储时自动添加 type 属性，实现对象的正确序列化与反序列化。

b.AdminController / UserController（用户与管理员接口）

主要功能：用户/管理员注册与登录相关接口
实现基于 JWT 的无状态认证流程，支持管理员与普通用户分离的登录逻辑。

c.GlobalExceptionHandler（全局异常处理）

该文件实现全局异常处理器，用于统一管理 API 错误响应。

核心功能与实现思路：

功能：

拦截并处理各类异常，返回结构化错误信息（JSON 格式），防止系统崩溃，提升 API 健壮性。
关键实现：
- 参数校验失败：
  捕获 MethodArgumentNotValidException 和 ConstraintViolationException，提取字段级错误消息，返回 {字段名: 错误信息}。
- 业务异常：
  处理自定义异常（如 UserTableException、ResourceNotFoundException），返回对应 HTTP 状态码（500/404）及错误描述。
- 文件上传异常：
  捕获 MaxUploadSizeExceededException，返回 400 错误提示文件大小超限。
- 权限控制异常：
  处理 UnauthorizedException，返回 401 未授权状态。
- 统一响应格式：
  返回 Map<String, String>，键为错误字段或 global，值为错误描述，避免敏感信息泄露。

d.PersistentChatMemoryStore（对话记忆持久化）

该组件实现购车咨询会话的对话历史持久化存储。

功能：
为 LLM 购车咨询提供会话级对话记忆管理，确保用户连续对话上下文不丢失。
支持 Redis 缓存 + 数据库双落地方案。

关键实现：

存储结构

Redis 键：chat_memory:sessionId
值：消息 DTO 列表（序列化后）
消息类型：UserMessage 与 AiMessage 交替存储
读取逻辑

优先从 Redis 获取历史消息
Redis 失效时，从数据库加载完整会话记录
向下兼容旧版 Redis 存储结构
写入机制

新消息通过 MessageDTOConverter 转换为 DTO
保存至 Redis 并设置 60 分钟过期时间
清理策略

deleteMessages 方法清除对应 Redis 键，实现会话数据隔离

设计要点：

Redis 提升性能，数据库作为兜底保障
复用现有 ConsultationMapper 与 DTO 转换层
以会话 ID 作为唯一标识，支持多用户并发咨询

e.CarCounselorAgent（AI提示词代理）

该类主要定义 AI 提示词逻辑，为 LLM 提供购车咨询场景的上下文引导与对话模板。

f.AgentConfig（AI代理配置）

该配置类定义 Langchain4j 代理的核心参数，包括模型加载、系统提示初始化、上下文管理等内容，为 AI 购车咨询功能提供底层支撑。

g.MessageDTO（消息传输对象）

MessageDTO 是 LLM 辅助购车系统的核心消息传输对象，封装聊天交互数据。

功能：

支持系统提示、用户输入、AI 响应的多类型统一结构，便于消息存储与上下文维护。

设计与实现思路：

避免直接序列化 Langchain4j 的不可变类，设计轻量级 DTO；
字段包含：type（系统/用户/AI）、text（消息内容）、name（角色标识）、toolName（工具名）、args（工具参数 JSON）；
实现 Serializable 接口以支持 Redis 存储；
作为 MessageDTOConverter 的数据中转格式。

h.MessageDTOConverter（消息转换工具）

该类负责将 Langchain4j 的 ChatMessage 对象与自定义的 MessageDTO 相互转换。

功能与实现：

fromMessage/toMessage：在系统提示、用户输入、AI 回复之间互转；
coerceToDTOList：解析 Redis 返回的 List<Map> 结构，自动恢复为 MessageDTO 列表；
使用空值安全转换（toStringSafe）保障兼容性与稳定性。

i.JWT 无状态认证系统

该系统用于购车辅助服务的 API 安全控制。

核心功能与实现思路：

认证流程

用户登录后生成 JWT；

后续请求需携带 token；

JwtAuthenticationFilter 拦截验证并注入认证上下文。
安全配置

禁用表单登录、CSRF 与 HTTP Basic；

白名单允许登录/注册接口匿名访问；

其他接口需认证访问；

JWT 过滤器优先执行。
认证验证

CustomAuthenticationProvider 根据登录类型（管理员/普通用户）校验；

使用 BCrypt 验证密码；

登录成功生成携带权限的令牌。

关键设计：

令牌自包含认证信息，避免重复校验；
权限通过 auth 字段区分（ADMIN / USER）；
开发环境禁用 CSRF，生产环境需开启。

j.购车辅助服务核心逻辑

核心用户交互流程：

用户认证与会话管理

登录生成 JWT；

创建唯一 sessionId；

所有请求需验证 JWT 与用户 ID。

AI 购车咨询流程

提交用户画像参数（预算、车型、用途等）；

调用 CarCounselorAgent 获取 AI 建议；

将消息与回复保存至数据库；

动态注入用户画像上下文，实现个性化推荐。

会话数据管理

Redis 缓存会话；

数据库备份持久化；

支持多轮对话上下文记忆；
- deleteChat 支持清空指定会话。

系统设计要点

JWT 无状态会话；

用户隔离与安全；

AI 集成 Langchain4j；

分页查询历史记录；

完整流程：登录 → 会话 → 咨询 → 回复 → 持久化 → 历史查看。

三、程序截图说明

智能购车助手项目是一个集前端交互、后端业务逻辑与AI能力于一体的综合系统。在功能实现上，系统通过用户画像处理模块结构化地存储用户偏好，并利用用户输入解析模块中的自然语言处理技术准确理解用户意图；核心的车型推荐引擎则基于多维度评分算法从数据库中筛选出最匹配的车型，并通过对比分析模块和预算规划模块为用户提供客观、全面的购车决策支持。

四、遇到的困难以及解决方式

团队成员	困难描述	解决方法
张宝仁（后端主力）	系统架构设计复杂度超出预期	- 重新梳理模块边界，采用清晰的服务分层架构 - 建立接口规范文档，减少后续修改次数 - 增加技术预研时间，提前验证技术方案可行性
张宝仁（后端主力）	调试时间远超预估	- 增加数据校验层，对AI返回结果进行标准化处理 - 与AI技术员建立实时沟通机制，快速定位问题
曾诗皓（后端 - AI接口）	Prompt工程调试耗时较长	- 建立提示词版本管理，系统记录每次修改效果 - 设计结构化输出模板，约束模型返回格式 - 与前端约定降级方案，确保异常情况下的用户体验
黄俊平（后端 - AI接口）	数据处理与日志管理复杂度高	- 设计统一的数据封装格式 - 建立完整的请求-响应日志链路 - 使用CodeArt的分支管理功能，规范提交记录
王盛明（后端 - DB & 测试）	数据库性能优化需求突显	- 优化数据库索引设计 - 引入缓存机制减轻数据库压力 - 建立性能测试用例，提前发现瓶颈
赵俊强（前端 - UI & PM）	需求变更频繁影响开发进度	- 建立需求变更审批流程 - 采用组件化开发，提高代码复用性 - 加强团队沟通，确保信息同步及时
韩冰晨（前端 - 表单 & 博客）	表单交互复杂度超出预期	- 采用分步表单设计，降低用户填写压力 - 增加实时验证和提示信息 - 优化适配，提升操作便利性
池博洋（前端 - 布局 & 发布）	多环境部署配置复杂	- 统一环境配置管理 - 建立自动化部署流程 - 完善部署文档，减少人为失误

成员	贡献值
张宝仁	22%
曾诗皓	11%
黄俊平	11%
王盛明	13%
赵俊强	18%
韩冰晨	14%
池博洋	11%

五、PSP表格

组员1：张宝仁 (后端主力)

（负责：核心业务逻辑、API 架构设计、功能实现）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	60	60
开发 (Development)
设计 (Design)	120	150
编码 (Coding)	300	420
调试 (Debugging)	120	180
报告 (Reporting)
测试 (Test)	0	0
撰写博客 (Report)	30	60
合计 (Total)	630 (10.5h)	870 (14.5h)

组员2：曾诗皓 (后端 - AI 接口)

（负责：LLM 选型、Prompt 设计、AI 接口编码）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	45	45
开发 (Development)
设计 (Design)	90	120
编码 (Coding)	180	210
调试 (Debugging)	90	120
报告 (Reporting)
测试 (Test)	30	30
撰写博客 (Report)	60	90
合计 (Total)	495 (8.25h)	615 (10.25h)

组员3：黄俊平 (后端 - AI 接口)

（负责：LLM 接口调用、数据处理、CodeArt 日志）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	45	45
开发 (Development)
设计 (Design)	60	90
编码 (Coding)	180	210
调试 (Debugging)	60	90
报告 (Reporting)
测试 (Test)	30	30
撰写博客 (Report)	60	90
合计 (Total)	435 (7.25h)	555 (9.25h)

组员4：王盛明 (后端 - DB & 测试)

（负责：数据库设计、测试用例编写、CodeArt 提交管理）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	60	60
开发 (Development)
设计 (Design)	60	90
编码 (Coding)	120	150
调试 (Debugging)	60	90
报告 (Reporting)
测试 (Test)	90	120
撰写博客 (Report)	30	30
合计 (Total)	420 (7h)	540 (9h)

组员5：赵俊强 (前端 - UI & PM)

（负责：前端页面组件、CSS 样式、分工整理）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	90	120
开发 (Development)
设计 (Design)	60	60
编码 (Coding)	90	120
调试 (Debugging)	30	60
报告 (Reporting)
测试 (Test)	30	30
撰写博客 (Report)	90	120
合计 (Total)	390 (6.5h)	510 (8.5h)

组员6：韩冰晨 (前端 - 表单 & 博客)

（负责：前端咨询表单、PSP 表格收集、博客撰写）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	60	60
开发 (Development)
设计 (Design)	30	30
编码 (Coding)	90	120
调试 (Debugging)	60	90
报告 (Reporting)
测试 (Test)	30	30
撰写博客 (Report)	180	240
合计 (Total)	450 (7.5h)	570 (9.5h)

组员7：池博洋 (前端 - 布局 & 发布)

（负责：前端整体布局、路由、博客最终发布）

Personal Software Process (PSP)	预估耗时 (min)	实际耗时 (min)
规划 (Planning)
需求分析 (Requirement)	30	30
开发 (Development)
设计 (Design)	30	30
编码 (Coding)	120	180
调试 (Debugging)	30	60
报告 (Reporting)
测试 (Test)	60	60
撰写博客 (Report)	90	120
合计 (Total)	360 (6h)	480 (8h)