第二次团队作业:原型设计+概要设计
| 项目 | 内容 |
|---|---|
| 作业所属课程 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS?filter=homework |
| 作业要求 | https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16784 |
| 作业的目标 | 在第一次作业的基础上进入设计阶段:① 使用墨刀完成前台与后台管理原型,并给出在线预览链接;② 按国标规范撰写《系统设计说明书》与《数据库设计说明书》,用 UML(用例图、活动图、状态机图、类图、时序图、协作图)完成概要设计,用 ER 图、关系数据模型与 ORM 映射完成数据库设计;③ 制定到周的开发计划与人到人的分工安排,为后续编码实现打好基础 |
| 团队名称 | 我思故我队 |
| 团队成员学号-名字 | 汪琳-3224004195、陈沐兰-3224004191、蔡小宇-3224004190 |
| 项目名称 | RentMate |
一、项目背景回顾
RentMate 是面向租房者、以 Agent 为核心辅助能力的租房全流程信息管理与决策辅助系统,服务于用户「已获得候选房源之后」的过程:把房源介绍、聊天记录、看房观察、合同文本等多来源信息集中管理,形成可追溯的房源档案,支持看房记录、多房源比较、沟通承诺审核与签约前固定十项合同核对。
二、原型设计
2.1 工具与总体范围
原型使用 墨刀(Modao) 制作,覆盖前台 20 页 + 后台管理 5 页,共 25 页。页面清单与阶段五《模块接口与数据交互设计说明》§8.1 的页面编号一一对应,每个页面都标注了对应的 API 端点与数据需求,做到「原型与真实接口同构」,后续开发时页面可以直接对照实现。
2.2 前台页面清单(20 页)
| 页面 | 核心交互 | |
|---|---|---|
| 1 | 登录/注册 | 登录、注册开关(演示账号模式) |
| 2 | 个人空间(计划列表) | 多计划管理 |
| 3 | 计划详情 | 计划信息、房源入口 |
| 4 | 需求编辑 | 硬性条件/偏好区分、增删改、暂搁 |
| 5 | 房源列表 | 轻量创建、疑似重复提示 |
| 6 | 房源详情(Tab 容器) | 档案/材料/看房/沟通分区入口 |
| 7 | 材料列表+上传 | 上传、解析状态(parsed/parse_failed)、失败手动录入 |
| 8 | 候选确认 | 逐条确认/修改/排除,来源追溯徽标 |
| 9 | 差异处理 | 未决差异四选一裁决(维持/采用/多条件/存疑) |
| 10 | 信息历史 | 只追加的时间线 |
| 11 | 看房列表+发起 | 生成可编辑清单 |
| 12 | 看房记录(移动优先) | 现场文字/图片记录,观察整理三选一处置 |
| 13 | 沟通列表+新建 | 手动补记电话/线下沟通 |
| 14 | 沟通详情(条目处置) | 承诺条目五档处置(入档/建问题/关联问题/仅保留/忽略) |
| 15 | 问题列表+详情 | 三态问题(跟踪/已解决/关闭未解决)、依据关联 |
| 16 | 比较方案配置 | 默认维度增删与排序 |
| 17 | 比较结果 | 桌面矩阵 / 移动卡片,缺失不判不符合 |
| 18 | 合同核对发起 | 上传合同 + Idempotency-Key |
| 19 | 十项核对逐项 | 逐项摘录对照、接受/修改/忽略、缺项显式标记 |
| 20 | 任务中心 | Agent 任务轮询与状态提示 |
2.3 后台管理页面清单(5 页)
后台面向管理员角色,定位是运营/运维后台而非业务后台(RentMate 本身是单用户私有空间工具):
| 页面 | 说明 | |
|---|---|---|
| 1 | 概览 | 用户数、任务量等聚合指标 |
| 2 | 用户管理 | 账号状态管理 |
| 3 | 演示数据重置 | 一键重置虚构演示数据(不触碰真实数据) |
| 4 | Agent 任务监控 | 任务状态、失败原因、重试情况 |
| 5 | 审计日志 | 只追加的操作审计查询 |
后台只展示聚合指标与任务元数据,不展示用户材料内容,与系统的隐私边界一致。
2.4 原型中的三个设计亮点
① 来源追溯抽屉。 档案中每条确认信息都带来源徽标,点开统一呈现「断言 → 摘录 → 原文」的追溯链。这是产品差异化(多来源证据链)在界面上的核心表达,25 页里所有涉及确认的页面共用这一个组件。
② 候选确认工作流。 Agent 提取结果永远先进入「候选区」,用户逐条处置后才进入档案;出现来源冲突时进入差异处理页做四选一裁决,且每条信息项同时最多一个未决差异。原型完整表达了这条规则,而不是把 AI 结果直接展示成事实。
③ 任务中心轮询。 所有 Agent 能力(材料提取、观察整理、承诺提取、十项摘录、比较摘要)都是异步任务,前端统一用任务中心展示「排队中/执行中/成功/失败/需手动处理」,失败时保留原件并开放手动录入——模型不可用时系统依然可用。
2.5 关键页面截图








三、概要设计
本章自顶向下分四层展开:总体架构 → 模块划分 → UML 设计 → 数据库设计,与《团队名称_系统设计说明书》(13 章)和《团队名称_数据库设计说明书》(10 章、29 表)两份国标文档一一对应。
3.1 总体架构
架构形态:模块化单体 + 分层架构(API → 应用服务 → 领域 → 基础设施)+ 轻量 DDD + 端口/适配器。业务状态、任务执行状态(agent_jobs)、LLM 上下文三者严格分离。

技术栈:Vue 3 + TypeScript + Element Plus | Python 3.12 + FastAPI + SQLAlchemy 2.0 + Alembic | PostgreSQL 16/17 | Pydantic AI v2(结构化输出,无工具调用)| agent_jobs 表 + 独立 Worker(FOR UPDATE SKIP LOCKED)| Docker Compose + Caddy 单机部署。
部署架构图:

Agent 任务的可靠性设计:建任务幂等(enqueue_key)、来源证据幂等(dedupe_key)、同轮去重(content_hash)、5 分钟租约 + 退避重试(30/60s,总执行 3 次)、业务写入与任务成功同事务。
3.2 功能模块划分
系统划分为 12 个业务模块 + 1 个 shared 支撑模块,每个模块拥有自己的数据表,跨模块只允许调用公开应用服务,禁止访问对方 ORM。
| 模块 | 核心职责 |
|---|---|
| identity | 注册/登录/会话/角色 |
| planning | 计划与需求管理 |
| property | 房源识别与四态 |
| archive | 材料、信息项状态机、来源断言、差异开合(核心模块) |
| viewing | 看房清单/记录/观察 |
| communication | 沟通原文版本化 |
| extraction | 提取条目五档处置、来源证据校验 |
| verification | 十项核对任务与逐项处置 |
| issue | 问题三态跟踪 |
| comparison | 比较方案/维度/不可变快照/过期/摘要 |
| agent | LlmPort 适配、任务租约/重试/幂等 |
| admin | 演示数据重置、任务监控 |

3.3 UML 设计
3.3.1 用例图
参与者为租房用户(主)与管理员(后台运维);Agent/Worker 是系统内部机制,不作为参与者。11 个顶层用例,其中「查看来源追溯」是候选确认、看房整理、沟通处置、合同核对四个用例的包含用例。

3.3.2 活动图(业务流程)
链路 A 拆为两段:材料上传与候选提取(含解析失败手动录入分支)、候选确认与差异处理(四选一裁决);链路 B 表达沟通→承诺条目→五档处置→十项核对。
链路A活动图一_材料上传与候选提取:

链路A活动图二_候选确认与差异处理:

链路B活动图:

3.3.3 状态机图
信息项确认状态机(待确认→已确认→待复核→已排除,差异状态由未决差异记录派生):

3.3.4 类图(领域模型)
23 个领域对象按四个子域拆分表达:① 用户/计划/房源/材料;② 信息项/来源断言/历史/差异;③ 看房/沟通/提取条目;④ 核对/问题/比较。核心结构是「一个信息项拥有多条来源断言,断言携带来源载体(材料/沟通版本/看房观察/手动)与原文摘录」。
类图1:

类图2:

类图3:

类图4:

3.3.5 时序图(重要算法模块)
选取两个最核心的模块:① 材料提取与确认入档(含 Worker 领取、LLM 结构化输出、L1 校验、同事务落库、独立确认事务);② 合同十项核对(十项同事务初始化、单次结构化输出、逐项处置)。
时序图1:

时序图2:

3.3.6 协作图
协作图与时序图1表达同一消息序列,从对象协作视角展示「前端 → API → 档案服务 → Worker → Agent 网关 → 数据库」之间的消息传递:

3.4 数据库设计
3.4.1 总体设计
PostgreSQL,29 张业务表按 10 个模块归属,四批 Alembic 迁移与开发闭环对齐。通用约定:UUID 主键、timestamptz(UTC)、金额 numeric(14,4)、状态用 varchar+CHECK(不用原生 enum,便于迁移)、不使用全局 CASCADE、JSONB 仅用于不可变快照与任务载荷。
3.4.2 ER 图(六个业务域)
归属域 ER:

档案域 ER:

看房域 ER:

沟通与条目域 ER:

核对域 ER:

比较域 ER:

3.4.3 关系数据模型要点
完整 29 张表的字段、约束、索引见《数据库设计说明书》§4(数据字典)。这里列几个最有代表性的设计决策:
- 来源陈述(source_assertions):来源载体四选一 CHECK(材料/沟通版本/看房观察/手动),dedupe_key 全局唯一实现跨任务证据幂等;断言内容列不可 UPDATE(列级权限),保证证据不可篡改;
- 信息项(information_items):当前展示值与最后确认基线分离(三组互斥列),确认状态 CHECK 与基线联动(待确认必有基线为空、已确认必有基线);基线断言用复合外键保证必属同一信息项;
- 差异记录(difference_records):部分唯一约束 UNIQUE(item_id) WHERE status='open' 保证每条信息项最多一个未决差异;
- 比较结果(comparison_results):快照 JSONB 不可变(列级权限只允许更新过期标记),重跑生成新记录不覆盖旧结果;
- 材料删除采用墓碑模式:同事务完成入队清理任务→置墓碑→清内容→解链→断言置 deleted,物理文件由 Worker 提交后删除;
- 追加表不可变:信息历史、沟通版本、问题日志、比较摘要等表对运行期角色只授予 SELECT/INSERT。
3.4.4 ORM 映射(对象关系映射)
领域对象与数据表的映射总表(完整版见说明书 §5):
| 领域对象 | 数据表 | 映射方式 |
|---|---|---|
| User / RentalPlan / Requirement / Property | users / rental_plans / requirements / properties | 1:1 |
| Material / MaterialLink | materials / material_links | 1:1 / 1:N |
| InformationItem | information_items | 1:1(多条件为兄弟行 + group_id) |
| SourceAssertion | source_assertions | 1:N |
| ViewingRecord / ViewingObservation | viewing_records(checklist 合并 JSONB)/ viewing_observations | 合并 / 1:N |
| CommunicationRecord / Version | communication_records / communication_versions | 1:1 / 1:N(只追加) |
| ExtractedClaim | extracted_claims | 1:1(分诊条目) |
| VerificationTask / Item | verification_tasks / verification_items | 1:1 / 1:10 |
| Issue / IssueLog / IssueLink | issues / issue_logs / issue_links | 1:1 / 1:N / 多态引用 |
| ComparisonPlan / Dimension / Result / Summary | comparison_plans / ... dimensions / ... _results / ... _summaries | 1:1 / 1:N / 1:N / 1:N |
| ComparisonPlanProperty(关联表) | comparison_plan_properties | M:N 关联 |
| AgentJob(技术对象) | agent_jobs | 1:1 |
ORM 组织:每模块独立 models.py,共享 base.py 统一命名约定(uq_/ck_/ix_/fk_ 前缀);合并不建表的对象(ViewingChecklist、ItemCondition、MaterialVersion 等)及理由见说明书 §5.2。
3.5 规范性说明
- 两份说明书均设术语与缩写表(系统 §1.4、数据库 §1.4),所有缩写(L1–L5、INV-x、D-xx、S1–S9 等)首次出现前已定义;
- 全部 20 张图统一使用 Mermaid/PlantUML 渲染,图号、图题、正文引用一一对应(图表清单见说明书 §13.1);
- 描述采用「总体 → 模块 → 类/表」的分层形式,细节随层次深入而具体。
四、团队协作记录
4.1 预期开发计划(W1–W4,里程碑 M1–M4)
与《开发启动计划与任务分解》(W1–W4、任务 C0–C10、里程碑 M1–M4)一致,下表为周粒度摘要。
| 周次 | 阶段目标 | 关键任务 | 里程碑产出 |
|---|---|---|---|
| W1 | 基础设施与核心域 | 项目脚手架、Docker Compose 环境、迁移 0001(核心域 8 表)、迁移 0002(档案域 7 表)、模型服务商兼容验证(连通/结构化输出/超时限流/长中文)、认证与私有空间 | M1:核心域可运行,注册登录可用 |
| W2 | 档案与条目域 | 迁移 0003(看房/沟通/条目)、0004(核对/比较域);材料上传与解析;extract_material 任务链路;候选确认与差异处理 | M2:链路 A 后端贯通 |
| W3 | 双链路联调与原型 | 链路 B(沟通→承诺→十项核对)、比较生成与摘要;任务中心;前台页面按原型实现(墨刀链接本周对外);前后端联调 | M3:两条链路端到端可演示 |
| W4 | 后台、验收与部署 | 后台 5 页、演示数据种子与重置、部署上线(域名/HTTPS/备份)、验收场景一至八走查、缺陷修复 | M4:验收演示就绪,文档定稿 |
4.2 分工安排
| 成员 | 技术定位 | 负责范围 |
|---|---|---|
| 汪琳 | 后端核心 / 数据库 / 部署 | 数据库设计与迁移、核心域与档案域后端、部署运维 |
| 陈沐兰 | 前端开发 / 轻量后端 | 全部前台页面、公共组件、记录类模块后端 |
| 蔡小宇 | Agent 工程 / 测试集成 | 大模型链路、核对与后台模块、测试与质量 |
4.3 本次协作分工
| 成员 | 角色 | 负责内容 |
|---|---|---|
| 汪琳 | 技术负责人 | 《系统设计说明书》《数据库设计说明书》两份文档撰写;20 张 UML 图与 ER 图设计与渲染;29 张表的数据库设计与 ORM 映射;后续编码阶段承担核心实现 |
| 陈沐兰 | 前端 | 墨刀原型 25 页搭建与关键页截图;博客撰写;交付物链接、云盘、仓库整理 |
| 蔡小宇 | 测试与集成 | 原型交互走查与验收场景测试;协作记录收集;W1-W4 计划与里程碑跟踪、两份 PDF 定稿检查、博客终审 |
五、交付物清单与链接
| 交付物 | 链接 |
|---|---|
| 团队名称_系统设计说明书.pdf(36 页,14 图) | https://wwbct.lanzouu.com/iQsLD4h0vimd |
| 团队名称_数据库设计说明书.pdf(34 页,29 表,6 ER) | https://wwbct.lanzouu.com/ilhlR4h0vifg |
| 墨刀原型在线预览 | https://modao.cc/proto/H7r5fQ8ItowzjsDQ2Jck/sharing?view_mode=read_only&screen=llmVbhgpaQ51h7H2r |
| GitHub 团队仓库链接 | https://github.com/Stella-0203/RentMate |
posted on 2026-11-22 23:26 Stella_0218 阅读(6) 评论(0) 收藏 举报
浙公网安备 33010602011771号