第二次团队作业
脉语团队第二次团队作业——原型设计+概要设计
| 项目 | 内容 |
|---|---|
| 作业所属课程 | 广东工业大学 2024 级计算机科学与技术 5、6 班课程主页 |
| 作业要求 | 第二次团队作业:原型设计 + 概要设计 |
| 作业的目标 | 在第一次作业的选题与需求分析基础上,完成前台与后台原型设计、系统概要设计(UML、ER、关系模型、ORM 映射)以及两份国标结构的设计说明书,并把设计、原型和协作过程整理成可检查的团队交付物 |
| 团队名称 | 脉语团队 |
| 团队成员学号-名字 | 3124004197-蔡志冲;3124004213-林华杰 |
| 项目名称 | 寻回 · 校园失物找回助手 |
| 软件形式 | Web 网站 |
| 文档版本 | V1.0(2026-11-22) |
本次作业的重点是把“寻回”从需求推进到可评审的设计:用原型说明界面与交互,用概要设计说明架构、模块、流程和数据。本阶段交付两份设计说明书、前台与后台原型、UML/ER 图、数据库设计与协作记录;编码实现安排在评审通过后的迭代中。文中“设计(V1.1)”指本期完成设计、尚未进入实现。
一、作业目标与本项目对应关系
| 作业要求 | 本项目交付 |
|---|---|
| 前台应用原型 + 后台管理原型,交互、文本、规则说明,UI 美观 | 前台 11 屏 + 后台 7 屏,HTML 可点击原型 + 墨刀在线原型 + 逐屏说明 |
| 概要设计:架构、功能模块、运行逻辑 | 五层架构、13 个模块、24 个接口、关键流程 |
| UML:用例图、活动图、类图、时序图、协作图 | 用例图 1 张、活动图 2 张、类图 1 张、时序图 3 张、协作图 1 张、状态机 1 张、部署图 1 张 |
| 数据库:ER 图、关系模型、ORM 映射 | Chen ER、IE ER、关系模式、ORM 映射,配套数据字典 |
| 两份国标结构 PDF | 《脉语团队_系统设计说明书》《脉语团队_数据库设计说明书》 |
| 协作记录:周计划、分工、过程、GitHub 贡献 | 周计划表、分工表、提交记录、里程碑 |
| 在线原型链接、仓库链接、文档链接 | 见文末“链接汇总” |
二、原型设计(40%)
2.1 原型工具与在线链接
原型使用墨刀搭建(在线预览链接见下方)。为了让页面在墨刀中可快速复刻,团队先完成了一套同风格的高保真 HTML 原型,作为切图与交互标注的来源;墨刀中的页面顺序、热区、弹窗与规则说明均按这套原型 1:1 搭建。
- 在线原型:寻回 · 校园失物找回助手-分享
- HTML 原型入口:
prototype/index.html(随仓库提交,可直接浏览器打开) - 原型截图:
prototype/screenshots/(前台 11 张、后台 7 张,1440px 宽)
说明:本项目是纯软件 Web 应用,不涉及硬件原型,因此没有硬件连接图或硬件照片。
2.2 前台应用原型
前台覆盖“浏览 → 发布 → 匹配 → 认领 → 核验 → 咨询”的完整链路。
表 1 前台原型页面
| 编号 | 页面 / 状态 | 主要内容 | 关键交互与规则 |
|---|---|---|---|
| F1 | 公告板首页 | 介绍区、统计、搜索、类型标签、类别/状态筛选、日期范围、演示记录开关、物品网格、分页 | 搜索与筛选可组合;无结果显示空状态;加载中显示“正在读取公告板” |
| F2 | 筛选结果 | 关键词 + 类别 + 状态 + 日期后的结果 | 旧请求不得覆盖新结果;页码越界自动回到最后一页 |
| F3 | 物品详情(访客) | 公开描述、照片、发布者昵称、状态、认领入口 | 不展示私密特征与联系方式;已归还可读不可操作 |
| F4 | 物品详情(发布者) | 私密核验特征、AI 匹配、编辑、归还、删除 | 仅发布者可见;已归还不能编辑;有待核验请求不能删除 |
| F5 | 发布 / 编辑 | 类型、名称、类别、日期、地点、描述、私密特征、照片 | 日期不晚于今天;照片 JPG/PNG/WebP、≤5 MiB;错误保留内容 |
| F6 | AI 匹配结果 | 候选卡片、相关度、理由、建议核对的问题 | 只从后端候选选;AI 失败显示“关键词候选线索”;分数不是归属概率 |
| F7 | 提交认领 | 核验说明输入、提交 | ≥8 字;不能认领自己的物品;提交后进入“我的请求” |
| F8 | 我的请求 | 收到的请求 / 我的请求、状态、处理说明、联系方式 | 待核验可通过/拒绝/撤回;通过后才显示联系方式 |
| F9 | 登录 / 注册 | 账号、密码、昵称、联系方式 | 演示账号提示;错误原因可读 |
| F10 | 个人资料 | 昵称、联系方式、修改密码 | 改密使其他会话失效;演示账号资料固定 |
| F11 | 持续咨询 | 单物品对话、历史消息、重新开始 | 按用户+物品隔离;失败保留问题可重试 |


2.3 后台管理原型
后台管理按“运营后台(V1.1)”完成设计,用于真实试点后的内容与纠纷处理;本阶段只做界面、交互与规则设计,编码在后续迭代中实现。
表 2 后台原型页面
| 编号 | 页面 | 主要内容 | 关键规则 |
|---|---|---|---|
| A1 | 运营登录 | 管理员账号、密码 | 与普通用户分离;生产强制 HTTPS |
| A2 | 数据概览 | 用户、物品、请求、AI 调用、失败率、演示数据量 | 只读;不展示联系方式明文 |
| A3 | 用户管理 | 搜索、禁用、重置密码、违规记录 | 禁用即时生效;操作写审计日志 |
| A4 | 物品管理 | 搜索、下架、恢复、演示标记、删除 | 下架需填原因;删除保留软删除记录 |
| A5 | 请求仲裁 | 双方说明、通过/拒绝、强制归还 | 需双人复核;联系方式仍只对双方可见 |
| A6 | 内容审核 | 关键词命中、举报队列、聊天抽样 | 只处理公开文本,不默认读取私密特征 |
| A7 | 演示数据与备份 | 重新种子、清理演示数据、触发/下载备份 | 备份不含密钥;操作写审计日志 |

2.4 三个重点交互
(1)AI 匹配不是“全库丢给模型”。
前端只展示后端返回的候选;后端先取最多 150 条有效记录,用类别、地点、日期和文字规则筛到 12 条,再交给 DeepSeek 排序。模型返回的 ID 必须在这 12 条里,分数截断到 0~100,最多返回 8 条。AI 不可用时,页面标题变成“关键词候选线索”,并明确说明 method=rules。相关度不是物主概率,页面不提供“AI 确认归属”的按钮。
(2)认领要经过核验,联系方式后置。
申请者提交不少于 8 字的说明;发布者看到说明与请求版本,只有发布者能通过或拒绝;通过时在同一事务内把物品置为已归还、其他待处理请求结束,并对双方解锁联系方式。审批带 expected_updated_at,说明被改过后旧页面提交会被拒绝,必须刷新再核验。
(3)后台与前台使用同一套状态语义。
后台的“请求仲裁”不新造状态,仍使用 pending / accepted / rejected 与 resolution;演示数据与真实数据在匹配、认领、后台列表中都按 is_demo 隔离。这样前台看到的“已归还”“已结束”与后台处理结果一致。
2.5 原型中的规则清单
- 日期不得晚于校园时区(默认 Asia/Shanghai)的今天;
- 账号 3~24、密码 8~128、昵称 1~32、联系方式 2~100;
- 标题 2~80、描述 5~2000、地点 2~100、私密特征 ≤500;
- 认领说明 ≥8 字;同一用户对同一物品最多一条请求;
- 照片 ≤5 MiB,仅 JPG/PNG/WebP,≤1500 万像素,服务端重编码去 EXIF;
- 公开列表与详情不返回
contact与verification_hint; - 演示账号只能处理演示记录,真实账号只能处理真实记录;
- AI 失败必须明确降级,不得把规则结果说成 AI 成功。
三、概要设计(40%)
完整内容见《脉语团队_系统设计说明书》与《脉语团队_数据库设计说明书》,本节给出关键图与说明。
3.1 分层架构与模块划分
系统分为表现层、接口层、业务层、数据层和外部服务层。表现层是 Vue 3 单页应用;接口层是 FastAPI 的 24 个 REST 接口;业务层包含认证会话、物品、检索、匹配、认领核验、咨询和后台设计;数据层是 SQLite(WAL)与本地图片;外部服务是 DeepSeek。


模块编号为 M01~M13:M01 认证与会话、M02 物品发布与管理、M03 公告板检索、M04 AI 线索匹配、M05 认领与线索、M06 核验与归还、M07 持续咨询、M08 元数据与健康检查、M09 后台管理(设计)、M10 备份与恢复、M11 演示数据与隔离、M12 部署与运行、M13 测试与验收。
3.2 用例图
参与者为浏览者、注册用户(丢失者/拾物者)和管理员(设计)。核心用例包括浏览与搜索、查看详情、注册/登录、发布线索、AI 匹配、提交认领、核验归还、持续咨询、后台管理;发布包含上传照片,提交认领包含登录,核验归还包含查看联系方式。

3.3 活动图
发布与匹配:填写表单 → 校验 → 保存物品 → 可选照片重编码 → 发起匹配 → 候选池(≤150)→ 规则初筛(前 12)→ AI 精排或规则回退 → 白名单/分数/新鲜度校验 → 展示候选。
认领与核验:提交说明 → 权限/状态/演示范围/重复校验 → 待核验 → 发布者核对 → 通过或拒绝;通过时请求、物品与其他请求在同一事务内更新,联系方式解锁。


3.4 类图
领域实体为 User、Session、Item、Claim、ChatMessage,服务类为 AuthService、ItemService、MatchService、ClaimService、ChatService。项目没有使用 ORM 框架,实体类与表通过 sqlite3.Row、字典投影和显式 JOIN 映射;public_item() 只投影公开字段。

3.5 时序图
- AI 匹配:浏览器 → 匹配接口 → 候选查询 → 规则打分 → DeepSeek → 白名单/新鲜度校验 → 候选;
- 认领核验:申请者提交 → 接口校验 → 数据库写入 → 发布者读取 → 审批事务 → 双方联系方式;
- 持续咨询:浏览器 → 咨询接口 → 串行锁 → 读取公开物品与最近 20 轮 → DeepSeek → 成功才写入。


3.6 协作图
协作图展示认领核验中申请者浏览器、认领接口、数据库与发布者浏览器的对象协作:1 提交请求、1.1 写入 pending、1.2 返回 claim_id;2 发布者审批、2.1 更新 accepted/returned、2.2 返回 ok;3 申请者刷新请求、3.1 查询、3.2 仅在 accepted 时返回联系方式。

3.7 状态机
物品只有“寻找中”和“已归还”;请求有“待核验”“已通过”“已结束”,结束原因单独存在 resolution(withdrawn/rejected/returned/accepted/ended),不能用备注文字伪造。

3.8 数据库设计
数据库为 SQLite(WAL),5 张表:users、sessions、items、claims、chat_messages。关键约束包括:users.username 唯一、claims(item_id, claimant_id) 唯一、items.kind/status 与 claims.status 的 CHECK 约束、外键开启、物品软删除、演示标记 is_demo。


ORM 映射采用轻量方式:sqlite3.Row → dict → 业务函数;实体属性与表字段一一对应,关联查询用显式 JOIN,不引入懒加载与级联。完整字段映射、索引与 DDL 见《数据库设计说明书》。
3.9 关键设计取舍
| 取舍 | 选择 | 原因 | 代价 |
|---|---|---|---|
| 前端 | Vue 3 本地文件,无构建 | 便于评审与演示 | 模板集中在 index.html |
| 数据库 | SQLite + WAL | 单校试点、零依赖、备份简单 | 写并发与多实例有限 |
| 进程 | 单 Uvicorn worker | 内存锁、AI 并发限制、限流生效 | 横向扩展需外置 |
| AI | 只做排序与咨询 | 避免模型承担归属判断的错误成本 | 依赖网络与账户 |
| 联系方式 | 核验通过后解锁 | 降低骚扰与隐私泄露 | 交接前双方无法直接联系 |
| 演示数据 | is_demo 双端隔离 |
防止真实说明进入共享演示账号 | 演示与真实不能混合匹配 |
四、团队协作记录(20%)
4.1 按周设计计划与里程碑
| 周次 | 日期 | 主要工作 | 里程碑 / 产出 | 状态 |
|---|---|---|---|---|
| W1 | 2026-10-26 ~ 11-01 | 选题、场景梳理、需求假设、角色与流程 | 选题与需求初稿 | 已完成 |
| W2 | 2026-11-02 ~ 11-08 | 原型草图、信息架构、核心业务流程 | 前台页面清单与低保真原型 | 已完成 |
| W3 | 2026-11-09 ~ 11-15 | 前台高保真、交互规则、接口草案 | 前台 11 屏与接口清单 | 已完成 |
| W4 | 2026-11-16 ~ 11-22 | 后台原型、UML/ER、数据库设计、两份说明书 | 设计说明书 V1.0、前后台原型 18 屏 | 已完成 |
| W5 | 2026-11-23 ~ 11-29 | 设计评审、图表与文档修订、答辩准备 | 评审记录、修订版设计文档 | 进行中 |
| W6 | 2026-11-30 ~ 12-06 | 编码、联调、测试与部署准备 | 可运行版本与测试报告 | 计划 |
| W7 | 2026-12-07 ~ 12-13 | 试点、验收、答辩材料 | 演示环境与答辩脚本 | 计划 |
4.2 分工安排
| 成员 | 角色 | 负责内容 | 本次作业产出 |
|---|---|---|---|
| 蔡志冲(3124004197) | 后端、AI、部署(设计) | 接口设计、SQLite 数据与权限设计、DeepSeek 匹配与咨询方案、Docker/备份方案 | 系统设计说明书第 2~4、6~7 章;数据库设计说明书第 4~5、7 章;接口与安全评审 |
| 林华杰(3124004213) | 前端、需求、原型 | 公告板与发布交互设计、认领核验页面、需求整理、原型走查、博客维护 | 系统设计说明书第 1、3.1、5、8 章;数据库设计说明书第 2~3、6 章;前台/后台原型、博客与协作记录 |
分工是职责安排,覆盖本阶段的原型、设计文档与评审;编码阶段按同一分工继续推进。
4.3 协作过程记录
团队以 GitHub 仓库为主要协作载体:文档、图表、原型与设计源文件都进入同一仓库;每次改动通过提交记录留痕,周计划与里程碑在本文与仓库文档中同步。
可核对的提交记录(截至 2026-11-22):
| 时间 | 提交 | 内容 |
|---|---|---|
| 2026-11-08 | 9f1df68 |
初始化仓库 |
| 2026-11-08 | 25965fc |
课程作业基础结构 |
| 2026-11-09 | 172fddb |
项目基础结构与需求文档 |
| 本次作业 | 设计交付 | 两份设计说明书、UML/ER 图、前台/后台原型、博客与协作记录 |
过程记录方式:
- 每周一次线上同步,确认本周目标、阻塞与下周计划;
- 文档与原型改动先在仓库中提交,再在周计划表中更新状态;
- 设计文档与图表源文件(
.puml、.dot、.svg)一并入库,便于复查; - 原型先出 HTML 高保真版本,再按同一页面顺序在墨刀中搭建,保证原型与后续实现使用同一套页面和交互规则。
说明:团队合照与线下讨论照片待补充;本文不使用演示数据或原型走查结果冒充真实用户调研。
4.4 GitHub 贡献
- 仓库地址:https://github.com/it-cc/3124004197
- 项目基础与早期提交:蔡志冲(it-cc);
- 本次设计文档、原型与博客:林华杰(Lin-huaj);
- 提交后可在仓库
Insights → Contributors查看两人贡献记录。
五、验证与边界
本阶段验证
- 原型 18 屏逐屏走查:入口、返回、弹窗关闭与主流程跳转;
- 两份 PDF 的目录、页码、图表编号、数据字典与 DDL 一致性检查;
- UML 图与数据库设计字段逐项对照;
- 原型页面与接口规则、页面说明逐屏对照;
- 1440 / 1024 / 768 / 390 / 320px 下检查 HTML 原型无横向溢出。
不能宣称的
- 没有真实用户访谈、问卷或团队合照;
- 本次为设计阶段,没有公网部署,也没有可对外访问的运行地址;静态原型与墨刀演示不等于已上线;
- 没有 AI 准确率评测集,不报告准确率;
- 后台管理为 V1.1 设计,编码在后续迭代中实现;
- 演示数据是虚构线索,不是真实找回案例。
六、链接汇总
| 内容 | 链接 |
|---|---|
| GitHub 团队仓库 | https://github.com/it-cc/3124004197 |
| 系统设计说明书 PDF | 百度网盘 https://pan.baidu.com/s/1RTTYXU2Swjb1eorWDj7sbA?pwd=4smh 提取码: 4smh |
| 数据库设计说明书 PDF | https://pan.baidu.com/s/1tDt7Uzy67r4kJHToUlRJRg?pwd=xtps 提取码: xtps |
| 设计文档索引 | 见仓库 docs/assignment2/README.md |
| 原型在线预览(墨刀) | 寻回 · 校园失物找回助手-分享 |
| HTML 原型入口 | 见仓库 prototype/index.html |
| 原型截图 | 见仓库 prototype/screenshots/ |
墨刀原型为公开只读分享;如链接打不开,请用无痕窗口重试,或直接打开仓库里的
prototype/index.html离线原型。
附:图表与文档清单
| 编号 | 内容 | 位置 |
|---|---|---|
| 图 1 | 前台公告板原型 | prototype/screenshots/front-board.png |
| 图 2 | 前台 AI 匹配原型 | prototype/screenshots/front-matches.png |
| 图 3 | 后台数据概览原型 | prototype/screenshots/admin-dashboard.png |
| 图 4 | 系统分层架构 | docs/assignment2/figures/fig-01-architecture.png |
| 图 5 | 功能模块图 | docs/assignment2/figures/fig-02-modules.png |
| 图 6 | 系统用例图 | docs/assignment2/figures/fig-03-usecase.png |
| 图 7 | 活动图:发布与匹配 | docs/assignment2/figures/fig-04-activity-publish-match.png |
| 图 8 | 活动图:认领与归还 | docs/assignment2/figures/fig-05-activity-claim-return.png |
| 图 9 | 领域类与服务类 | docs/assignment2/figures/fig-06-class.png |
| 图 10 | 时序图:AI 匹配 | docs/assignment2/figures/fig-07-seq-match.png |
| 图 11 | 时序图:认领核验 | docs/assignment2/figures/fig-08-seq-claim.png |
| 图 12 | 协作图:认领核验 | docs/assignment2/figures/fig-10-comm-claim.png |
| 图 13 | 状态机 | docs/assignment2/figures/fig-11-state.png |
| 图 14 | Chen ER 图 | docs/assignment2/figures/fig-13-er-chen.png |
| 图 15 | 关系数据模型 | docs/assignment2/figures/fig-15-relational.png |
| 文档 | 系统设计说明书 | docs/assignment2/脉语团队_系统设计说明书.pdf |
| 文档 | 数据库设计说明书 | docs/assignment2/脉语团队_数据库设计说明书.pdf |

浙公网安备 33010602011771号