2026秋软工实践outfit合伙人——项目原型设计+概要设计

作业所属课程	H202601软件工程与软件工程实践
作业要求
作业的目标	本次作业目标：围绕"衣柜满、没衣服穿"的真实痛点，完成只盘活已有衣物、不做导购带货的对话式穿搭推理智能体的原型设计与工程蓝图。在171份问卷确定的需求优先级和色彩、版型、体型、面料、场景礼仪五类领域知识驱动的规则引擎与偏好加权双层推理基础上，交付原型设计、概要设计、UML设计与数据库设计四部分成果，明确系统边界、模块结构、交互流程与数据模型，确保设计可落地、可验收，为后续核心功能的真实、完整、可运行实现提供依据
团队名称	OUTFIT合伙人
团队成员学号-名字	赖彦然-102402106、谢慧彬-102402114、松格拉-102402112、吴佳仪-102402113、李青容-102402111、陈薇薇-102402109、姜思源-102402110、张润-102402115、刘翠华-102402105、阿合加依娜尔-102402108、王凯凤-052403108、王恩嘉-072401214、林诗怡-052402111

一、 项目介绍

项目背景

市面上的衣橱类应用多聚焦图像识别与服饰导购，缺少以"盘活用户已有衣物"为核心的工具。171 份问卷（有效 167 份）印证了这一缺口：50.9% 的人"衣柜很满却觉得没衣服穿"，45.5% 承认平时只穿那几件，39.5% 自评不会搭配；而 89.8% 每天决策不超过 5 分钟——痛点不是慢，而是结果不满意。供给端同样错位：65.3% 靠小红书等内容平台"看别人的穿搭"，仅 6.6% 用过衣橱类 App，电商推荐则天然偏向"买新的"。需求真实、供给缺位，是本项目的立足点。

项目目标

做一个以用户已有衣橱为唯一候选池的穿搭推理 Agent：结合天气、场合、体型等客观约束，从自己的衣服里推出 3 套可解释、可改写、可采纳的搭配，并通过反馈持续学习偏好，最终提升衣橱单品利用率、减少无效购买。验收不看"出方案有多快"，而看：3 套中至少 1 套被采纳、平均改写轮次、采纳后"喜欢"占比、单次推荐覆盖的单品数，以及用户能否复述"为什么选这套"。

核心功能

1. 数字衣橱：下拉标签录入 + Excel 批量导入，照片仅本地预览、不上传。
2. 情境输入：天气 API（温度、降雨）+ 场合标签 + 自然语言提需求。
3. 两层推理：客观硬规则（体型、场合、天气）先筛，再用临时偏好与长期偏好排序，输出 3 套差异化方案，每套附色彩、比例、面料、场合四条依据。
4. 对话改写：单品级替换（"把长裤换成半身裙"）与排除项叠加（"不要黑色"）。
5. 购前评估：新品与现有衣橱的适配单品数、重复度，不提供购买链接。
6. 反馈学习：喜欢 / 一般 / 不喜欢三档，权重按时间衰减。

二、原型设计

1.交互说明

本节说明原型的页面组织关系与关键交互行为：用户做了什么、系统如何响应、界面如何变化。

1.1 页面地图

登录 / 注册
└─ 今日推荐（首页）
├─ 电子衣橱
│ ├─ 新增衣物
│ ├─ 编辑衣物
│ ├─ 修改衣物状态
│ ├─ 删除衣物
│ └─ 清空衣橱
├─ AI 对话（本期未实现，界面占位）
├─ 购前评估 ──→ 历史评估
├─ 历史记录 ──→ 对话记录 / 评估记录
└─ 个人资料与偏好
├─ 编辑资料
└─ 重置偏好
导航规则：左侧栏常驻，点击即切换内容区，当前项高亮；二级页面（新增、编辑、评估结果）以右侧内容区替换的方式呈现，返回后回到上一级并保留筛选条件。

1.2 全局交互约定

• 反馈：所有写操作完成后在底部弹出轻提示（如“已保存”“已删除”），约 2.6 秒自动消失，不打断操作。
• 二次确认：删除衣物、清空衣橱、重置偏好三项为破坏性操作，执行前必须弹出确认框，默认焦点在“取消”。
• 空状态：无数据时显示插画 + 一句引导 + 一个主按钮（如“去添加第一件衣物”），不显示空白区域。
• 表单校验：必填项标 *；输入框失焦时即时校验，提交时整体再校验一次；校验未通过时按钮不响应并给出具体原因。
• 防重复提交：请求或计算过程中按钮置灰并显示加载态，完成前不可再次点击。
• 数据持久化：原型以本地存储模拟后端，刷新页面后衣物、偏好、历史记录均保留。

1.3 关键流程的交互时序

流程一：首次使用
打开原型 → 登录/注册 → 完善资料（体型、风格、场合偏好）→ 进入电子衣橱 → 逐件新增衣物（或批量导入）→ 回到今日推荐 → 系统结合天气与场合生成 3 套方案。
流程二：采纳一次推荐
查看 3 套方案 → 阅读每套的四条依据 → 不满意则点「换一批」，或用对话改写替换单品 → 选定一套 → 点「喜欢」并记录“今天穿了” → 偏好权重更新。
流程三：购前评估
进入购前评估 → 上传/填写新品信息 → 点「开始评估」→ 右侧给出可搭配单品数与重复度 → 结果存入历史评估 → 之后可在历史记录中回看。

1.4 交互设计依据

• 录入采用下拉标签而非拍照识别：48.5% 的用户担心录入麻烦，58.7% 接受标签式录入。
• 一次输出 3 套而非 1 套：43.1% 的用户担心推荐不准，把选择权交还用户可降低不信任。
• 每套方案附四条依据：14.4% 的用户抱怨“不知道 AI 为什么这样搭”，可解释性用于建立信任。
• 破坏性操作均二次确认：衣橱数据是用户的主要沉没成本，误删的代价高于多点一次的代价。

2.原型展示

2.1 各页面截图

01-登录注册

02-注册

03-个人资料与偏好

04-编辑资料

05-重置偏好

06-新增衣物

07-编辑衣物

08-修改衣物状态

09-品类筛选

10-颜色季节场合筛选

11-删除衣物

12-清空衣橱

13-今日推荐首页

14-对话记录

15-购前评估

16-购前评估历史

17-AI对话未实现

2.2在线链接

https://admirable-piroshki-2dcf08.netlify.app/

三、概要设计

1. 总体设计

1.1 功能结构

系统围绕对话式穿搭推理 Agent 分为七个模块，每个模块的具体功能如下：
用户管理：注册登录、资料与体型、偏好管理；衣橱管理：衣物增删改查、Excel 批量导入、图片上传、标签枚举；对话推荐：会话管理、搭配推荐、多轮调整、单品改良、反事实对比；知识问答：知识库检索、流式问答；天气服务：实时天气、降级兜底；反馈学习：提交反馈、偏好重算、反馈撤销；购前评估：可搭配分析、重复度计算、购买建议。
其中对话推荐为主链路，衣橱管理提供候选衣物，天气服务与知识问答提供环境约束和知识依据，反馈学习承担偏好闭环。

1.2 业务流程

注册登录并完善资料与体型 → 录入衣物（手工或 Excel 批量导入）→ 创建会话 → 确定天气与场合 → 信息不足时澄清补充 → 生成搭配方案 → 满意则提交反馈，不满则多轮调整后重新生成 → 反馈更新长期偏好 → 可选购前评估 → 历史回看。

1.3 系统架构

系统自下而上分四层：用户交互层（HTML/CSS/JavaScript）、API 接口层（FastAPI，负责鉴权、参数校验与业务调度）、Agent 推理与业务处理层（规则引擎、组合枚举、多维评分、知识检索、单品画像、Jaccard 重复度分析）、数据存储与外部服务层（SQLite、JSON 规则、Markdown 知识库、本地图片、Open-Meteo 与智谱 API）。

1.4 关键技术决策

系统以规则引擎作为推荐的推理主体，大模型只承担意图理解与文案生成。这样设计的原因是：规则可校验、可解释、可离线，模型不可用时推荐链路仍能完整运行。推荐链路为“组合枚举 → 硬规则过滤 → 多维评分 → 差异化筛选”：先用体型、季节、暖度、场合等硬规则剔除不可穿组合，再在合规集合内按偏好打分，最后控制品类与风格分歧，输出最多 3 套。知识检索采用 BM25 双通道检索并以 RRF 融合排名，取前 5 个片段；购前评估用 Jaccard 相似度衡量新品与衣橱单品的重复程度，按 0.7 / 0.5 两档划分重复等级。

2. UML 设计

2.1 用例图

参与者为注册用户。Excel 批量导入、上传衣物图片以「extend」扩展“管理衣物”，多轮调整与单品改良以「extend」扩展“获取搭配推荐”。

2.2 活动图：对话生成搭配

消息进入后端先做意图识别，分知识问答、约束调整、推荐三类。问答走知识库检索，无模型密钥时降级展示原文片段；约束调整只更新会话约束；推荐分支校验信息完整性与额度后，依次执行枚举、硬过滤、排除已展示方案、打分排序、差异化取前三、生成理由并持久化快照。

2.3 类图

ORM 实体位于 app/db.py，对应七张表；Agent 部分含推荐引擎、知识索引、规则仓库、单品画像与大模型客户端。推荐引擎依赖规则仓库取规则，调用单品画像，检索结果交由模型客户端生成回复。

2.4 时序图：搭配生成主流程

前端 POST /chat/{id}/message → 对话路由识别意图 → 按需解析天气 → 读取衣物与画像 → 调用推荐引擎加载规则并完成枚举、过滤、打分、差异化 → 生成理由点 → 返回 Top3 → 持久化快照并扣减额度 → 组织回复。模型不可用时该步走模板文案。

2.5 协作图：对象交互

协作图给出推荐过程中 15 条消息的次序：前端提交 → 路由分发 → 读衣物与画像 → 调推荐引擎 → 取规则 → 计算 → 按需检索知识库 → 生成文案 → 写快照 → 统一响应。

3. 领域 Agent 设计

3.1 与系统的集成方式

Agent 以推理层形式嵌在接口层之后，不接管鉴权、存储与规则。对话路由负责意图识别与编排，把一次请求拆成取天气、读衣物、调规则、生成理由、组织回复，再逐步调用推荐引擎、知识库与模型客户端。需要说明：对话模块本阶段不作为已交付能力，大模型调用仅完成封装，实际调用未验证。

3.2 领域知识与工具的作用

规则库 JSON 承载过滤、评分与体型规则，直接参与计算，保证方案下限；领域知识 Markdown 作为语料经 BM25 检索，为回答提供出处。工具调用负责限定候选池、提供天气约束、完成规则校验与重复度计算，使结果可追溯。

3.3 知识检索的时序

路由识别为 knowledge → 知识库检索 → 原词与同义词双通道 BM25 打分 → RRF 融合取 Top5 → 返回带来源的片段 → 有密钥且调用成功时结合上下文生成回答，否则降级整理原文片段 → 保存问答消息。

4. 数据库设计

4.1 ER 图

共七张表：用户、衣物单品、会话、消息、搭配方案、反馈记录、购前评估。用户与衣物、会话、反馈、评估均为一对多；会话与消息、方案为一对多。

4.2 关系数据模型

表名	主要字段	主键	外键
users	user_id、nickname、username、password_hash、body_shape、city、gender、styles、pref_color、pref_style、pref_comfort、pref_occasion、pref_fabric、created_at	user_id	—
clothing_items	item_id、user_id、name、category、sub_category、color、color_brightness、season、fit_snug、fit_silhouette、fabric、style、occasion、warmth_level、formality_level、image_url、tags	item_id	user_id → users
chat_sessions	session_id、user_id、status、occasion、weather_temp、constraints、remaining_count	session_id	user_id → users
chat_messages	message_id、session_id、role、action、content、payload	message_id	session_id → chat_sessions
outfit_records	outfit_id、user_id、session_id、items、score、reason_points	outfit_id	user_id → users、session_id → chat_sessions
feedback_records	record_id、user_id、session_id、outfit_id、rating、evidence	record_id	user_id、session_id、outfit_id
purchase_evaluations	evaluation_id、user_id、target_item、result	evaluation_id	user_id → users

设计说明：方案的单品组合与理由以 JSON 存于 outfit_records，因为方案是一次性快照、整体读取，不做联表；衣物属性逐列存储，因为过滤与打分需要按列比较。

4.3 对象关系映射

实体类	对应表	关系
User	users	1 : N ClothingItem、ChatSession、FeedbackRecord、PurchaseEvaluation
ClothingItem	clothing_items	N : 1 User
ChatSession	chat_sessions	N : 1 User；1 : N ChatMessage、OutfitRecord
ChatMessage	chat_messages	N : 1 ChatSession
OutfitRecord	outfit_records	N : 1 User、ChatSession
FeedbackRecord	feedback_records	N : 1 User、ChatSession、OutfitRecord
PurchaseEvaluation	purchase_evaluations	N : 1 User

推荐引擎、知识索引、规则仓库、单品画像、模型客户端属运行期对象，不映射数据表。

4.4 数据的存储与管理方式

领域知识以 JSON 规则库与 Markdown 知识库两种形态随代码版本管理，前者供规则引擎加载，后者供 BM25 建索引。

交互记录存于 chat_sessions 与 chat_messages，保存场合、天气、约束、剩余额度与逐轮消息；feedback_records 保存评级与增量证据，撤销时写 undone 标记并触发偏好重算。

任务结果存于 outfit_records 与 purchase_evaluations，方案存组合、得分与理由点，评估存新品属性与结论，均支持历史回看。

图片上传后保存至服务端 data/uploads/，通过 /uploads/ 访问，目前未按用户身份做访问鉴权，属已知限制。

四、后端设计展示

本节不再重复第 3 节的图示，仅补充接口设计与运行说明

1.接口设计

后端共 34 个端点，按业务模块划分，统一前缀 /api/v1。除注册、登录、账号检查、天气与健康检查外，其余接口均需在请求头携带 Authorization: Bearer <token>；统一响应结构为 {code, msg, data}，业务成功 code=0，令牌无效或过期返回 401，越权访问返回 403。

模块	前缀	端点数	主要能力
用户	/user	9	注册、登录、资料与体型、偏好查询与重置、数据清空
衣物	/clothing	9	增删改查、标签枚举、导入模板、Excel 批量导入、整柜清空
天气	/weather	1	按城市查询实时天气
对话	/chat	6	创建会话、发送消息、流式问答、会话列表与详情、结束会话
反馈	/feedback	4	提交反馈并重算偏好、查询影响、撤销、历史查询
购前评估	/purchase	3	新品评估、历史查询、删除记录
上传	/upload	2	图片上传、上传并识别属性

核心接口示例：

方法	路径	功能	鉴权
POST	/api/v1/user/register	注册，返回令牌与用户信息	免鉴权
POST	/api/v1/user/login	登录，返回令牌与统计	免鉴权
GET	/api/v1/clothing	分页查询衣橱，支持品类筛选	需要
POST	/api/v1/clothing	新增衣物	需要
POST	/api/v1/clothing/import	Excel 批量导入	需要
GET	/api/v1/weather?city=	查询指定城市天气	免鉴权
POST	/api/v1/feedback	提交反馈并重算偏好	需要
POST	/api/v1/feedback/{record_id}/undo	撤销一条反馈	需要
POST	/api/v1/purchase/evaluate	新品购前评估	需要
POST	/api/v1/chat/{session_id}/message	发送消息，后端统一意图分流	需要

说明：对话模块 6 个端点属目标设计，完整多轮机制待确认、大模型未接入，当前以静态原型演示；上传识别接口的视觉模型段未启用，走本地启发式。完整端点与参数见附录《接口清单表》。

2.运行环境

项目	内容
语言	Python 3.10 及以上
Web 框架	FastAPI + Uvicorn（默认端口 8300）
ORM / 校验	SQLAlchemy / Pydantic
数据库	SQLite，默认位于用户主目录 .wardrobe
检索	jieba 分词 + rank-bm25，同义词扩展 + RRF 融合
前端	单文件 HTML + 原生 JavaScript，由 FastAPI 静态挂载
外部依赖	Open-Meteo 天气接口；智谱 GLM 为可选

启动方式：uvicorn app.main:app --port 8300。应用在启动时依次完成规则库加载、数据库建表与知识库索引构建，随后一个进程同时提供页面、接口与图片访问；密钥通过 .env 注入，不写入代码。

3.已知限制

• 大模型调用层已封装但未接入实际密钥，问答以检索片段原文展示、推荐以模板文案回复；
• 多轮对话机制待确认，对话模块 6 个端点属设计态，界面由静态原型承载；
• 图片保存至服务端 data/uploads/ 并以 /uploads/ 直接访问，未按用户身份鉴权；
• 视觉识别模型未启用，图片属性走本地主色与文件名启发式。

附加文件