Extreme Programming

Yuangz. 2025-12-12 02:32:19

Extreme Programming

项目	内容
课程名称	EE308FZ
团队名称	两只羊
团队成员	832301122 杨媛真 832301121 杨越
作业要求	实现具备收藏、多联系方式、Excel导入导出功能的通讯录管理系统，进行团队协作开发，撰写技术博客
作业目标	掌握极限编程协作流程，实践Git团队开发，提升前端工程能力，完成完整项目开发周期
GitHub仓库地址	`https://github.com/Yuanzhen-Yang-832301122/832301121_832301122_address_book`

1. 任务描述

本次极限编程作业要求开发一个功能完整的通讯录管理系统。核心需求包括：实现联系人收藏功能、支持多种联系方式、提供Excel格式的导入导出能力。项目需以团队形式完成，体现极限编程的协作理念，包括频繁的代码提交、持续的沟通以及共同对代码质量负责。

项目开发过程需通过Git进行版本控制，并在GitHub上维护清晰的提交历史以展示协作过程。最终需撰写技术博客，详细记录开发过程、功能实现思路、团队协作经验以及项目总结。

2. 功能展示

2.1 收藏联系人功能 (核心功能)

系统提供了完善的联系人收藏机制。每个联系人卡片右上角设有星形图标按钮，用户点击即可在收藏与取消收藏状态间切换。被收藏的联系人具有醒目的视觉标识，包括黄色边框和背景高亮，方便用户快速识别。系统还设有独立的"收藏联系人"展示区域，集中显示所有被收藏的联系人。

2.2 多联系方式支持 (核心功能)

系统支持为每个联系人存储多种联系方式。除了基本的姓名外，系统提供了电话、电子邮箱、详细地址和社交媒体账号等多个信息字段。这些字段均为可选填项，用户可根据实际需要灵活填写。

在联系人展示界面，系统会智能地仅显示已填写的联系方式，避免空白字段造成的界面混乱。

2.3 Excel导入与导出功能 (核心功能)

系统实现了完整的Excel文件导入导出能力，方便用户进行数据迁移和备份。

导出功能：用户点击"导出为Excel"按钮，即可一键将所有联系人导出为结构化的通讯录_日期.xlsx文件。文件包含"姓名"、"电话"、"邮箱"、"地址"、"社交媒体"、"是否收藏"等完整表头。

导入功能：用户点击"导入Excel文件"，选择按模板格式填写的Excel文件，系统即可批量添加联系人。导入时，系统会基于姓名和电话进行智能去重，并提供导入结果反馈。

2.4 搜索与筛选功能 (附加功能)

实时搜索：在顶部搜索框输入关键词时，系统即时对联系人列表进行过滤。搜索范围涵盖所有信息字段（姓名、电话、邮箱、地址、社交媒体）。

高级筛选：提供了多条件组合筛选。用户可按"仅收藏"、"未收藏"筛选收藏状态，也可按"有电话"、"有邮箱"筛选联系方式类型。

2.5 数据统计展示

系统首页集成了直观的数据统计面板，实时显示通讯录的关键统计数据，包括：总联系人数量、收藏联系人数量、有电话/邮箱的联系人数量。

2.6 测试功能 (开发辅助)

系统提供了便捷的测试工具，便于演示和功能验证：

添加示例数据：一键添加预设的示例联系人
测试所有功能：自动执行完整的操作流程测试
清空所有数据：快速重置系统状态

3. GitHub代码与提交记录

3.1 代码仓库与文件结构

项目全部源代码已托管至GitHub平台。

仓库地址：https://github.com/Yuanzhen-Yang-832301122/832301121_832301122_address_book
主要文件:
- index.html：系统主界面，包含所有HTML结构。
- style.css：所有样式设计，实现响应式布局与视觉特效。
- script.js：核心业务逻辑，包括数据管理、搜索筛选、联系人操作等。
- excel-export.js：Excel导入导出功能实现，使用SheetJS库。

3.2 提交记录与协作证明

团队在开发过程中遵守极限编程的持续集成实践，保持了高频率的代码提交。累计完成6次主要提交，两位成员的提交次数均达到了每人3次。

4. 功能实现思路说明

4.1 收藏联系人功能

实现思路：

数据模型：在每个联系人对象中增加一个布尔类型的bookmarked属性来标记收藏状态。
状态切换：为每个联系人卡片的收藏按钮绑定onclick事件。点击时，通过联系人ID找到对应的联系人对象，切换其bookmarked属性值。
视觉反馈：通过JavaScript动态修改按钮的样式（添加/移除bookmarked类名）和联系人卡片的边框/背景色，提供即时反馈。
数据持久化：状态变更后，立即将整个联系人数组更新到localStorage，确保数据不丢失。
独立展示：在渲染联系人列表时，先筛选出所有bookmarked为true的联系人，专门渲染在"收藏联系人"区域。

4.2 多联系方式支持

实现思路：

灵活的数据结构：联系人对象设计为包含多个可选字段：{id, name, phone, email, address, social, bookmarked, createdAt}。
表单设计：在添加/编辑表单中，为每种联系方式提供独立的输入框。通过HTML5的输入类型（如type="tel", type="email"）提供基础验证和移动端优化。
智能显示：在渲染联系人详情时，遍历对象的所有属性，使用条件渲染技术，仅当属性值不为空字符串时，才创建对应的DOM元素进行显示。

4.3 Excel导入与导出功能

实现思路：

模块分离：将Excel相关功能独立到excel-export.js文件中，保持代码结构清晰，便于维护。
技术选型：采用成熟稳定的第三方库 SheetJS (xlsx) 来处理Excel文件的读写。
导出功能：
- 将内存中的联系人数组（JavaScript对象数组）使用XLSX.utils.aoa_to_sheet()方法转换为工作表。
- 创建新的工作簿，将工作表加入，最后使用XLSX.writeFile()方法生成并下载.xlsx文件。
导入功能：
- 监听文件输入框的change事件，获取用户上传的Excel文件。
- 使用FileReader API读取文件为二进制数据。
- 使用XLSX.read()方法解析数据，再通过XLSX.utils.sheet_to_json()转换为JavaScript对象数组。
- 对新数组进行遍历验证（确保姓名字段不为空），并与现有数据进行去重比对（基于姓名和电话），最后合并到主联系人数组并保存。
用户体验：提供模板下载、导入成功/失败提示、文件格式验证等完整流程。

4.4 搜索与筛选功能

实现思路：

实时搜索：
- 监听搜索输入框的input事件，实现边输入边搜索的即时反馈。
- 获取输入值，转换为小写后，遍历联系人数组。
- 对每个联系人的所有字符串类型字段（name, phone, email, address, social）使用includes()方法进行模糊匹配。
- 将匹配成功的联系人存入新数组，并用此新数组重新渲染列表。
高级筛选：
- 为每个筛选条件创建对应的<select>下拉菜单。
- 监听下拉菜单的change事件，收集所有被选中的条件。
- 在每次筛选时，对联系人数组应用多个过滤函数（如contact.bookmarked === true, contact.phone !== null），最终得到符合所有选中条件的联系人列表。
性能优化：使用防抖技术优化搜索性能，避免频繁的重渲染。

4.5 数据统计功能

实现思路：

统计本质上是数组的归约操作。在updateStats()函数中计算：

const total = contacts.length;
const bookmarked = contacts.filter(c => c.bookmarked).length;
const withPhone = contacts.filter(c => c.phone).length;
const withEmail = contacts.filter(c => c.email).length;

将这些计算逻辑封装在一个函数中，在每次联系人数组发生变更（增、删、改、导入）后调用，并更新DOM中统计面板的数字。
使用CSS Grid布局实现统计卡片的响应式排列。

4.6 消息提示系统

实现思路：

动态创建：通过JavaScript动态创建消息提示DOM元素，避免HTML中固定结构的限制。
四种类型：实现成功（绿色）、信息（蓝色）、警告（橙色）、错误（红色）四种消息类型，对应不同场景。
动画效果：使用CSS动画实现消息的滑入滑出效果，提升用户体验。
自动管理：消息显示3秒后自动淡出，同时支持手动关闭。
位置固定：始终显示在屏幕右上角，不干扰主要操作区域。

5. PSP表格

5.1 832301122 杨媛真 - PSP表格

PSP阶段	计划时间 (h)	实际时间 (h)	差值 (h)	完成情况说明
计划与设计	3.0	3.5	+0.5	完成界面原型与交互流程设计
开发环境搭建	1.0	1.0	0.0	配置开发环境、Git、代码编辑器
界面实现(HTML/CSS)	6.0	7.0	+1.0	创建HTML页面结构，优化响应式CSS样式
搜索与筛选功能开发	4.0	4.5	+0.5	实现实时搜索与复合筛选功能
测试功能开发	2.0	2.5	+0.5	添加示例数据功能和测试工具
文档与博客撰写	2.0	2.5	+0.5	撰写项目报告，整理开发文档
总计	18.0	21.0	+3.0	时间主要用于界面细节优化与响应式设计

5.2 832301121 杨越 - PSP表格

PSP阶段	计划时间 (h)	实际时间 (h)	差值 (h)	完成情况说明
计划与设计	2.0	1.5	-0.5	分析功能需求，设计数据模型
核心逻辑开发(JS)	6.0	6.5	+0.5	实现联系人增删改查、收藏功能
Excel功能开发	5.0	6.0	+1.0	集成SheetJS库，实现导入导出功能
功能集成与测试	3.0	2.5	-0.5	测试业务逻辑，修复异常问题
最终优化	2.0	1.5	-0.5	完善Excel验证，进行代码优化
总计	18.0	18.0	0.0	各项任务基本按计划完成

6. 团队成员分工与贡献度评估

6.1 分工详情

团队成员基于技术专长和项目需求进行了明确分工：

832301122 杨媛真：前端界面与交互

整体页面结构设计与HTML代码实现。
CSS样式系统开发与响应式布局适配。
搜索、筛选功能的交互逻辑与用户界面实现。
数据统计面板的设计与实现。
消息提示系统的UI实现。
项目技术文档与博客的撰写与整理。

832301121 杨越：核心逻辑与数据处理

联系人数据模型设计与JavaScript实现。
联系人增删改查、收藏等核心业务逻辑开发。
浏览器**本地存储(LocalStorage)**持久化方案实现。
Excel文件导入导出功能的完整开发（基于SheetJS）。
测试功能模块的开发与实现。
系统模块整合与核心代码维护。

6.2 贡献度评估

贡献度评估基于代码提交数量与质量、实现功能的复杂度与完整性、解决问题的重要性、以及文档工作等多个维度进行综合考量。

经过团队共同评议，两位成员均深度参与项目全流程，在各自负责的领域完成了核心工作，贡献相当。

总体贡献度：100%
832301122 杨媛真贡献度：50%
832301121 杨越贡献度：50%

7. 合作中遇到的困难及解决方案

7.1 代码合并冲突

问题：在并行开发script.js文件时，两人同时修改了同一区域（如联系人数组的初始化逻辑），导致Git合并时产生冲突。

解决方案：

预防：在开始开发一个可能被共同修改的模块前，先进行沟通，或通过Git分支进行隔离开发。
解决：当冲突发生时，使用GitHub Desktop或VSCode内置的对比工具，仔细分析冲突内容。双方通过在线会议共同Review冲突代码，协商决定保留哪个版本，或融合两者优点产生一个新版本。这个过程虽然耗时，但加深了彼此对代码的理解。

7.2 Excel导入的数据验证与去重

问题：用户导入的Excel文件数据格式可能不标准，或包含大量重复条目，直接合并会导致数据混乱。

解决方案：

提供模板：在导入界面提供标准Excel模板下载，引导用户规范数据格式。
前端验证：在解析Excel数据后，对每个条目的必填字段（如姓名）进行非空校验，对电话、邮箱格式进行正则表达式校验。
智能去重：定义重复规则（如"姓名相同且电话相同"视为同一人）。在导入时，将新数据与现有localStorage中的数据遍历比对，过滤掉重复项，并给出提示（如"成功导入X条，跳过Y条重复数据"）。

7.3 响应式布局下的组件适配

问题：在移动设备小屏幕上，原本为桌面设计的联系人卡片布局会出现错乱，筛选按钮区域拥挤。

解决方案：

使用CSS媒体查询：针对最大宽度为768px和480px的屏幕设置断点。
布局调整：在小屏幕下，将联系人卡片从水平排列改为垂直堆叠；将筛选区域的按钮改为下拉菜单或可折叠面板。
弹性布局：使用Flexbox和CSS Grid实现弹性布局，确保元素在不同屏幕下都能合理排列。
测试：使用浏览器开发者工具的"设备仿真"功能，反复测试不同尺寸下的显示效果，直至布局合理。

7.4 状态同步与页面刷新

问题：开发初期，在快速连续执行"添加联系人"和"修改收藏状态"操作后，偶尔出现界面显示与localStorage中数据不一致的情况。
解决方案：

状态集中管理：重构代码，确保所有对核心数据（联系人数组）的修改，都必须通过少数几个"原子操作"函数（如addContact(), toggleBookmark()）进行。
单一数据流：在这些原子函数中，遵循"更新内存数据 -> 保存到localStorage -> 重新渲染UI"的固定顺序。这确保了数据变化的源头唯一，流向清晰。
引入防抖：对频繁触发的事件（如搜索框的input事件）加入防抖(debounce)机制，减少不必要的重复渲染，提升性能。
事件委托：使用事件委托技术处理联系人卡片上的操作，避免为每个卡片单独绑定事件，提升性能。

8. 项目总结

本项目成功完成了通讯录管理系统的开发，实现了作业要求的全部三项核心功能（收藏、多联系方式、Excel导入导出）以及附加的搜索筛选功能、数据统计、测试工具等。系统界面简洁直观，操作流畅，数据持久化可靠。

8.1 目标达成情况

功能实现：100%完成既定需求，所有功能均经过测试，运行稳定。
团队协作：通过Git进行有效的版本控制和协作，提交记录清晰，符合极限编程提倡的"持续集成"实践。
技术实践：综合运用了现代Web前端技术（HTML5, CSS3, ES6+ JavaScript），并成功集成了第三方库（SheetJS）解决特定问题。
代码质量：采用模块化设计，代码结构清晰，注释完整，便于维护和扩展。