4.5 增加特色：实现一个有价值的特色功能¶

核心业务稳定后，再为项目增加一个“记得住”的亮点¶

特色功能不是技术展示，而是让用户少一步、快一点、看得更清楚

添加一个与业务无关的聊天窗口，不会自动让项目更有价值。真正的特色功能，应该针对项目中的具体问题，利用已有数据或适合的技术，带来能够观察和验证的改进。

本节只选择一个特色功能。它可以是统计图表、智能搜索、提醒、图片处理，也可以是 AI 问答或推荐。重点不是技术复杂，而是与业务有关、能够演示、失败可处理。

本节学习目标

从真实用户问题出发选择一个范围可控的特色功能，说明它的输入、处理、输出和价值，完成实现与效果验证，并处理外部服务失败、密钥和隐私等实际问题。

🎯 本节完成后，你要交付¶

成果	要求
特色功能说明	说明目标用户、真实问题、使用场景和预期价值
可运行特色功能	能够在项目业务页面中实际使用，不是独立演示代码
效果验证记录	使用固定案例检查正常、失败和边界结果
失败与降级方案	功能不可用时有明确提示，核心业务仍然能够运行
安全说明	不泄露 API Key，不上传不必要的隐私数据
Git 提交记录	特色功能与无关修改分开，改动能够解释和回退

特色功能属于项目加分项或进阶任务。核心业务闭环尚未完成，或者仍有严重数据和权限问题时，应先返回上一节修复基础功能。

🚦 第一步：先判断是否适合进入特色开发¶

开始前检查：

项目能够稳定启动；
登录和主要权限正常；
核心业务能够从开始连续完成到结束；
业务失败和越权操作得到正确处理；
不需要手工修改数据库推进流程；
当前没有阻断演示的严重问题；
剩余时间足够完成实现和测试。

如果其中多项没有完成，暂停特色功能。先完成一个小而完整、可以运行的系统，比留下一个基础流程不通的“智能项目”更有价值。

💡 第二步：从用户问题选择一个特色方向¶

不要先问“可以用什么新技术”，而要先问：

用户在完成核心业务时，还有什么重复、困难、低效或不清楚的地方？

常见方向¶

方向	适合解决的问题	示例
数据统计与图表	数据很多，管理者难以看出变化	报修类型和处理时长统计
智能筛选与搜索	普通查询难以快速找到目标	按关键词、状态和时间组合搜索
提醒与预警	用户容易忘记或错过重要节点	借阅到期、预约临近、库存不足提醒
文件或图片处理	业务需要上传和查看材料	报修图片压缩、商品图片预览
排序或简单推荐	用户选择很多，不知道优先看什么	热门活动、相关图书、服务推荐
内容辅助生成	用户需要反复填写相似文字	根据表单生成规范描述草稿
知识问答	用户需要查询固定业务知识	校园办事流程或课程资料问答
地图、语音、识别	业务确实依赖位置或媒体信息	报修地点标注、图片文字识别

不合适的特色功能¶

与项目主流程没有关系的通用聊天；
只换颜色、动画或背景图；
只展示一张写死的数据图；
复制第三方演示页面，未连接项目数据；
为了显得高级而加入多个中间件；
需要大量新知识，课程周期内无法验证；
外部服务失败后整个项目不能使用。

📋 第三步：填写特色功能任务卡¶

开始编码前，先把特色功能压缩成一个可以验收的小任务。

项目	内容
功能名称	【填写】
目标用户	【填写】
当前问题	【用户现在有什么困难】
使用场景	【在核心流程哪一步使用】
输入	【用户输入或项目数据】
处理	【统计、搜索、规则或外部服务】
输出	【页面展示或业务结果】
价值	【怎样更快、更准或更清楚】
最小范围	【本次只做什么】
明确不做	【本次不扩展什么】
失败结果	【怎样提示或降级】
验证方法	【用哪些固定案例判断】

示例：报修统计看板¶

目标用户：后勤管理员
当前问题：只能逐条查看报修，难以判断高发问题
输入：现有报修类型、状态、提交时间和完成时间
处理：按类型和月份统计数量，计算已完成比例
输出：统计卡片和两张简单图表
价值：帮助管理员发现高发报修类型和积压情况
最小范围：只提供查询和展示，不做复杂预测
失败结果：查询失败时显示提示，不影响报修办理

能用简单方案解决，就先用简单方案

统计 SQL、业务规则或关键词搜索能够完成的功能，不必强行调用大模型。特色来自解决问题的效果，不来自技术名称。

🧭 第四步：把特色功能接入现有业务¶

特色功能应出现在用户真正需要的位置。

核心业务页面
→ 用户提供输入或选择数据
→ 后端读取当前项目数据
→ 特色处理模块
→ 返回结果
→ 页面展示并允许用户继续业务

复用已有工程能力¶

使用已有登录身份和角色权限；
使用已有统一请求与响应；
使用已有 Service 和数据访问方式；
使用已有页面布局、加载和错误组件；
使用已有日志和异常处理；
使用环境配置保存外部服务参数。

不要为一个特色功能重新创建第二套登录、请求封装、异常格式或数据库连接。

保持模块边界¶

内容	建议位置
页面与用户交互	现有前端页面或独立特色页面
接口	当前业务模块或明确的特色接口
业务规则	Service
统计查询	Mapper/DAO
外部服务调用	独立客户端或服务封装
API Key 和地址	环境变量或本地配置

第一版只完成最短路径。例如统计功能先完成一个查询和一张图，AI 功能先完成一种输入和一种可靠输出。

🔌 第五步：正确处理第三方或 AI 服务¶

如果特色功能完全使用本地数据和代码，可以跳到第六步。

外部调用要集中封装¶

不要在 Controller、Servlet 或页面中到处直接调用第三方接口。建议通过一个独立服务完成：

业务接口
→ 特色功能 Service
→ 第三方服务客户端
→ 外部 API

这样更容易统一处理：

API 地址和模型名称；
API Key；
超时；
返回格式；
错误日志；
重试或降级；
后续替换服务。

密钥不能写入代码¶

错误做法：

1	`apiKey = "真实密钥"`

正确做法：

本地开发使用环境变量或不提交的配置文件；
仓库只提供 .env.example 或配置示例；
README 说明需要配置什么，不写真实值；
提交前搜索是否误写密钥；
密钥泄露后立即在服务平台撤销和重新生成。

只发送完成任务所需的数据¶

不要把完整用户表、密码、手机号、身份证号、聊天记录或其他无关数据发送到外部服务。能使用匿名编号、脱敏内容或局部文本时，不发送原始敏感信息。

外部服务失败时怎么办¶

失败情况	建议处理
超时	结束等待并提示稍后重试
API Key 无效	服务端记录原因，页面不显示密钥细节
调用额度用尽	提示功能暂不可用，保留基础操作
返回格式异常	校验结果，使用默认或人工处理
服务完全不可用	隐藏或禁用特色入口，不阻断核心流程

不要无限重试

外部服务持续失败时，重复调用会增加等待和费用。课程项目只需设计清楚的超时、有限重试或直接降级方案。

🤖 第六步：AI 功能要允许不确定和人工确认¶

如果选择大模型问答、内容生成、推荐或识别，不能把模型输出直接当作绝对正确的业务结论。

明确输入和输出¶

输入：用户提供什么、系统补充什么
处理：使用什么提示词或知识来源
输出：返回文本、分类、推荐还是结构化数据
使用：结果仅供参考，还是会影响业务状态

风险不同，处理方式不同¶

AI 输出用途	建议
生成描述草稿	用户确认后再保存
推荐内容	说明推荐依据，允许用户忽略
查询知识	显示资料来源，无法确认时明确提示
自动分类	允许人工修改分类结果
修改业务状态	不直接自动执行，由后端规则或人工确认

记录可复现信息¶

至少记录：

使用的服务或模型；
提示词模板；
输入数据来源；
主要参数；
输出格式；
测试案例和失败案例；
人工确认方式。

不要求保存用户的全部原始隐私输入，也不要在日志中记录 API Key。

🧪 第七步：用固定案例验证特色效果¶

特色功能“能够返回结果”不等于“有价值”。需要准备固定案例进行比较。

最低测试集合¶

一个典型正常输入；
一个空值或信息不足输入；
一个边界或容易出错的输入；
一个无权限操作；
一个外部服务失败或降级场景；
一个能够说明业务价值的对比。

效果验证表¶

场景	输入或初始数据	预期结果	实际结果	是否有帮助	结论
正常使用	【填写】	【填写】	【填写】	是 / 否	通过 / 未通过
信息不足	【填写】	提示补充或返回空结果	【填写】	是 / 否	通过 / 未通过
边界情况	【填写】	【填写】	【填写】	是 / 否	通过 / 未通过
无权限	【填写】	拒绝访问	【填写】	—	通过 / 未通过
服务失败	【填写】	明确提示并降级	【填写】	—	通过 / 未通过

价值可以简单衡量¶

原来需要查看 20 条记录，现在一张统计图可以看出重点；
原来需要填写完整描述，现在生成草稿后只需修改；
原来需要多个条件逐个尝试，现在能够组合搜索；
原来只能等待发现问题，现在能够提前提醒；
原来结果没有来源，现在能够定位到相关资料。

不要虚构准确率、用户数量或节省时间。没有真实测量时，使用测试案例和操作对比说明效果。

🖥️ 第八步：处理页面状态和用户反馈¶

特色页面至少处理：

首次进入时的说明；
输入为空；
加载或生成中；
成功结果；
没有结果；
服务失败；
无权限；
重新尝试；
返回核心业务。

对于可能等待较久的外部服务：

点击后禁用重复提交；
显示正在处理；
设置合理超时；
失败后允许重新尝试；
不让页面一直处于无反馈状态。

特色功能应帮助用户继续完成业务，而不是把用户带到一个孤立、无法返回的演示页面。

🤝 第九步：让 AI 辅助实现而不是扩大范围¶

可以先让 AI 评估最小方案：

请先阅读 AGENTS.md、需求分析说明书、系统设计说明书，
以及当前已经完成的核心业务代码和测试记录。

我准备增加一个特色功能：
- 功能名称：
- 目标用户：
- 当前问题：
- 使用场景：
- 输入：
- 预期输出：
- 明确不做：

请先不要修改代码，完成：
1. 检查它是否与核心业务直接相关；
2. 给出一个最小可运行方案；
3. 列出可复用的现有模块和公共能力；
4. 说明需要修改的页面、接口、服务和数据；
5. 识别外部服务、密钥、隐私和失败风险；
6. 给出正常、边界、无权限和降级测试；
7. 标出需要人工确认的问题。

不要增加第二个特色功能，不要重构无关模块。

确认后分步实施：

现在只完成特色功能的第 1 个可验证步骤：【填写】。

要求：
- 不影响原有核心流程；
- 复用已有登录、请求和异常处理；
- 不在代码中写入真实密钥；
- 失败时返回明确结果；
- 完成后运行相关验证并说明实际结果。

如果 AI 建议增加向量数据库、消息队列、微服务或多个新框架，先问清楚它们解决什么当前问题。没有必要依据时，选择更简单的方案。

👀 第十步：审查、回归和提交¶

特色功能完成后检查：

是否解决任务卡中的真实问题；
是否出现在合适的业务页面；
是否只实现一个清楚的小范围；
是否复用现有工程结构；
是否具有后端登录和权限检查；
是否泄露密钥、密码或隐私数据；
是否处理空值、超时和服务失败；
AI 输出是否允许人工确认；
外部服务不可用时核心流程是否仍然正常；
测试结果是否来自真实运行；
README 或特色说明是否与代码一致。

回归核心业务¶

重新执行上一节的核心流程。至少确认：

登录正常
→ 核心流程正常
→ 特色功能正常
→ 关闭或模拟特色服务失败
→ 核心流程仍然正常

提交建议¶

1
2
3

feat(feature): add 【特色功能名称】
test(feature): cover normal and fallback cases
docs(feature): record configuration and evaluation

提交前检查：

1 2	`git status git diff`

重点确认 .env、真实配置、测试隐私数据和日志没有进入提交。

✅ 本节验收清单¶

📝 总结¶

特色来自业务价值：先说明用户问题，再选择技术。
只做一个小亮点：范围清楚、能够完成、能够演示。
简单方案同样有价值：统计、搜索和提醒不比 AI 功能低级。
外部服务必须可失败：保护密钥和隐私，准备明确降级。
特色不能破坏基础项目：核心业务在任何情况下都应继续可用。