第二次团队作业

脉语团队第二次团队作业——原型设计+概要设计

项目 内容
作业所属课程 广东工业大学 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 持续咨询 单物品对话、历史消息、重新开始 按用户+物品隔离;失败保留问题可重试

01-图 1 前台公告板原型

02-图 2 前台 AI 匹配结果原型

2.3 后台管理原型

后台管理按“运营后台(V1.1)”完成设计,用于真实试点后的内容与纠纷处理;本阶段只做界面、交互与规则设计,编码在后续迭代中实现。

表 2 后台原型页面

编号 页面 主要内容 关键规则
A1 运营登录 管理员账号、密码 与普通用户分离;生产强制 HTTPS
A2 数据概览 用户、物品、请求、AI 调用、失败率、演示数据量 只读;不展示联系方式明文
A3 用户管理 搜索、禁用、重置密码、违规记录 禁用即时生效;操作写审计日志
A4 物品管理 搜索、下架、恢复、演示标记、删除 下架需填原因;删除保留软删除记录
A5 请求仲裁 双方说明、通过/拒绝、强制归还 需双人复核;联系方式仍只对双方可见
A6 内容审核 关键词命中、举报队列、聊天抽样 只处理公开文本,不默认读取私密特征
A7 演示数据与备份 重新种子、清理演示数据、触发/下载备份 备份不含密钥;操作写审计日志

03-图 3 后台数据概览原型

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。

04-图 4 系统分层架构

05-图 5 功能模块图

模块编号为 M01~M13:M01 认证与会话、M02 物品发布与管理、M03 公告板检索、M04 AI 线索匹配、M05 认领与线索、M06 核验与归还、M07 持续咨询、M08 元数据与健康检查、M09 后台管理(设计)、M10 备份与恢复、M11 演示数据与隔离、M12 部署与运行、M13 测试与验收。

3.2 用例图

参与者为浏览者、注册用户(丢失者/拾物者)和管理员(设计)。核心用例包括浏览与搜索、查看详情、注册/登录、发布线索、AI 匹配、提交认领、核验归还、持续咨询、后台管理;发布包含上传照片,提交认领包含登录,核验归还包含查看联系方式。

06-图 6 系统用例图

3.3 活动图

发布与匹配:填写表单 → 校验 → 保存物品 → 可选照片重编码 → 发起匹配 → 候选池(≤150)→ 规则初筛(前 12)→ AI 精排或规则回退 → 白名单/分数/新鲜度校验 → 展示候选。

认领与核验:提交说明 → 权限/状态/演示范围/重复校验 → 待核验 → 发布者核对 → 通过或拒绝;通过时请求、物品与其他请求在同一事务内更新,联系方式解锁。

07-图 7 活动图:发布线索与 AI 匹配

08-图 8 活动图:认领、核验与归还

3.4 类图

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

09-图 9 领域类与服务类

3.5 时序图

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

10-图 10 时序图:AI 匹配候选

11-图 11 时序图:认领、核验与联系方式解锁

3.6 协作图

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

12-图 12 协作图:认领核验中的对象协作

3.7 状态机

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

13-图 13 状态机:物品与认领请求

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。

14-图 14 核心实体 ER 图(Chen)

15-图 15 关系数据模型

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 图、前台/后台原型、博客与协作记录

过程记录方式:

  1. 每周一次线上同步,确认本周目标、阻塞与下周计划;
  2. 文档与原型改动先在仓库中提交,再在周计划表中更新状态;
  3. 设计文档与图表源文件(.puml、.dot、.svg)一并入库,便于复查;
  4. 原型先出 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
posted @ 2026-11-22 23:54  forest132  阅读(6)  评论(0)    收藏  举报