第二次团队作业:原型设计+概要设计

项目 内容
作业所属课程 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 关键页面截图

image
image
image
image
image
image
528cb8a554de1d633858f1bf5e94cc6d

image

三、概要设计

本章自顶向下分四层展开:总体架构 → 模块划分 → UML 设计 → 数据库设计,与《团队名称_系统设计说明书》(13 章)和《团队名称_数据库设计说明书》(10 章、29 表)两份国标文档一一对应。

3.1 总体架构

架构形态:模块化单体 + 分层架构(API → 应用服务 → 领域 → 基础设施)+ 轻量 DDD + 端口/适配器。业务状态、任务执行状态(agent_jobs)、LLM 上下文三者严格分离。
image

技术栈: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 单机部署。

部署架构图:
图12-1_部署架构图

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-1_模块依赖图

3.3 UML 设计

3.3.1 用例图

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

3.3.2 活动图(业务流程)

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

链路A活动图一_材料上传与候选提取:
图5-1_链路A活动图一_材料上传与候选提取
链路A活动图二_候选确认与差异处理:
图5-2_链路A活动图二_候选确认与差异处理

链路B活动图:
图5-4_链路B活动图

3.3.3 状态机图

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

3.3.4 类图(领域模型)

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

类图1:
图6-2_类图一_用户计划房源材料

类图2:
图6-3_类图二_信息项断言历史差异

类图3:
图6-4_类图三_看房沟通提取条目

类图4:
图6-5_类图四_核对问题比较

3.3.5 时序图(重要算法模块)

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

时序图2:
图6-7_时序图_合同十项核对

3.3.6 协作图

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

image

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:
库图3-1_归属域ER

档案域 ER:
库图3-2_档案域ER

看房域 ER:
库图3-3_看房域ER

沟通与条目域 ER:
库图3-4_沟通与条目域ER

核对域 ER:
库图3-5_核对域ER

比较域 ER:
库图3-6_比较域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)    收藏  举报