2026秋软工实践 鹦伟达——项目原型设计+概要设计
2026秋软工实践 鹦伟达——项目原型设计+概要设计
| 项目 | 内容 |
|---|---|
| 作业所属课程 | 202601 软件工程与软件工程实践 |
| 作业要求 | 团队作业-第二次：项目原型设计+概要设计 |
| 作业的目标 | 完成 OfferPilot 的交互原型、系统概要设计与数据库设计，明确后续开发计划和成员分工，展示本次团队协作记录。 |
| 团队名称 | 鹦伟达 |
| 团队成员学号-名字 | 组长：102401608-魏之皓；组员：162404103-蔡信坡、102401312-刘谦益、102401318-陈常群、042402115-张锦昊、102401215-李义东、102401137-佘博海、102401310-庄凯堃、102401609-王智钦、162404109-杜玉鹤、102401135-何慧渊 |
一、原型设计
原型基于 Figma Design 制作。学生端以校内推免资格自查为主要示例，展示建项、条件核对、计划确认和材料准备；后台展示来源与规则、领域智能体（Agent）运行状态及异常信息。两端分别提供交互演示入口：
配图采用 Page 1 的基础页面，交互以 Page 2 演示为准。确认、拒绝、重试和导出等状态通过预设画面呈现，可编辑 Word 文档（DOCX）的生成属于后续实现内容。图中的学校、学生资料、通知与统计数字均为演示数据。
1.1 按个人事项组织工作区
事项工作台集中列出个人事项。进入事项后，用户通过顶部标签切换概览、来源与条件、阶段与任务、材料写作台、Agent 待处理和归档记录，处理过程始终保留当前事项的上下文。
概览突出显示信息缺口、任务进度与关键节点。推免示例中，专业排名尚未确认，页面提示补充排名信息；用户可从这里进入补录页面，也可查看 Agent 已整理的计划及待确认事项。
1.2 来源核对、计划确认与材料审阅
来源与条件页面并列显示通知版本、适用范围和个人条件，使每条自查结果能够对应到具体依据。候选计划经用户审阅确认后转为正式任务，任务保留截止日期、来源及前置条件。
设计将“官方必需、官方建议、自主可选、待核实”作为任务性质，与执行状态分别记录。当前推免演示主要展示官方必需任务。任务的建议准备时间与官方截止日期分开标注；前置条件不足时，后续任务显示受阻原因。
材料写作台将缺项诊断、原段落与建议段落放在同一视图，并标明引用的事实与材料要求。示例中的项目经历只写了“参与”，尚未说明具体职责，因此 Agent 先追问本人承担的工作，再据此修改表述。修改以候选稿呈现，由用户逐项接受或拒绝。
1.3 Agent 交互与异常恢复
用户通过统一入口发起检索、规则分析、计划或材料处理。材料起草演示中，Agent 根据当前事项的要求和获准使用的个人事实整理草稿，遇到职责、成果等信息缺失时向用户追问。补充并确认后，草稿进入材料审阅页面。联系导师、报名及正式提交由用户在官方渠道完成。
Agent 待处理页集中列出信息缺失、计划待确认、来源冲突和解析超时等事项，分别提供补充信息、审阅计划、对照来源或重试入口。异常恢复演示从已保留的检查点继续，并展示恢复后的任务状态。
1.4 后台管理与视觉规范
后台管理原型包含运行概览、知识与规则、Agent 任务三个页面，侧重运行监测、来源追溯与异常定位。来源列表展示版本、处理状态与记录入口，任务列表展示执行进度和耗时，异常详情显示失败步骤与原因。
界面以紫色标识主要操作，用浅灰紫背景与白色卡片区分内容层级。左侧导航标识当前工作区，顶部标签标识当前功能。来源与条件、原稿与建议采用对照布局；完成、待确认、受阻和失败等状态同时使用文字与颜色表达。
1.5 在线演示路线
| 流程 | 在 Page 2 中的操作路线 |
|---|---|
| 新建事项 | 学生端工作台 → 新建工作区 → 填入示例 → 创建 → 进入新事项。 |
| 条件自查 | 事项概览 → 补充排名信息 → 本人确认 → 查看排名计算与四态结果。 |
| 候选计划 | Agent 待处理 → 审阅计划 → 确认并加入任务；暂不采用分支保留原有任务。 |
| 材料与 Agent | 材料写作台 → 与 Agent 对话 → 个人陈述 → 发送预设请求 → 补充并确认职责 → 审阅修改 → 模拟导出与归档。 |
| 异常恢复 | Agent 待处理 → 解析超时的“重试” → 演示恢复成功 → 返回列表。 |
| 后台维护 | 后台运行概览 → 知识与规则 → Agent 任务 → AG-1048 查看异常。 |
二、系统概要与统一建模语言（UML）设计
设计图及后文中的缩写约定如下：
| 缩写或标识 | 含义 |
|---|---|
| UML | Unified Modeling Language，统一建模语言。 |
| ER | Entity–Relationship，实体-联系模型。 |
| API | Application Programming Interface，应用程序接口。 |
| B/S | Browser/Server，浏览器/服务器架构。 |
| DOCX | 基于 Office Open XML 的 Word 文档格式。 |
| Portable Document Format，可移植文档格式。 | |
| GB/T | 推荐性国家标准的代号。 |
| JSON、JSONB | JSON 为 JavaScript Object Notation；JSONB 为 PostgreSQL 的二进制 JSON 数据类型。 |
| PK、FK、UK | Primary Key（主键）、Foreign Key（外键）、Unique Key（唯一键）。 |
| UC、P0、P1 | UC 为 Use Case（用例）编号；P0 表示首版范围，P1 表示后续增强范围。 |
| opId | Operation ID，标识同次写入操作的唯一编号。 |
| PR | Pull Request，拉取请求，用于提交和评审仓库变更。 |
系统按 B/S 架构设计，划分为表现层、应用服务层、智能体层、来源与证据层、数据与支撑层。前端通过业务服务访问个人工作区，业务服务负责身份、权限、状态和版本约束。Agent 编排器按需调用检索、解析、校验及材料处理工具；来源与证据层保存可追溯依据，数据与支撑层承担业务数据、文件和运行记录的存储。
首版设计覆盖推免模板与一个竞赛试点，优先实现按需检索、条件自查、计划确认、材料准备与个人归档。定期巡检、条款级新旧对比和完整影响分析列入 P1，原型中的通知变化页面展示相应交互。
系统与数据库设计说明书均参考 GB/T 8567—2006《计算机软件文档编制规范》。系统设计由总体架构展开到部件、接口与运行逻辑，数据库设计由概念模型展开到关系模式、字段与约束。
模型、程序和用户各自承担不同职责：模型提取信息、生成候选结果并解释依据；程序完成明确条件的计算，以及权限、版本、日期和状态校验；用户确认个人事实、计划与材料。向外部模型传输个人信息时，另行取得本次传输同意。要求和结论保留来源快照及原文定位，信息不足或存在歧义的条目进入待补充、待核对状态。
UML 视图分别描述系统边界、静态结构和动态行为：
| UML 视图 | 在设计中的用途 |
|---|---|
| 用例图 | 展示用户、官方来源/办理系统与系统边界，覆盖事项建立、来源核对、自查、计划、材料和归档等用例。 |
| 活动图 | 描述来源提取、四态判断、缺口处理与计划确认等业务过程。 |
| 类图 | 描述用户工作区、事项、来源快照、要求评估、计划任务、个人事实、授权、材料版本等结构及关系。 |
| 时序图 | 展示来源处理、计划确认写入、材料改写与导出等关键交互。 |
| 协作图 | 以对象链接和编号消息展示计划确认过程中的对象协作顺序。 |
2.1 用例与系统结构
用例图以学生用户和官方来源/办理系统为外部参与者，覆盖建项、来源核对、条件自查、计划确认、材料准备及归档。Agent 编排属于系统内部实现。UC06 的完整变化分析列入 P1。
类图以事项 Matter 为核心，关联阶段、要求、评估、候选计划和任务。事项引用模板版本并保存适用范围，任务保存依赖与完成证据。评估结论统一为“按现有信息符合、按现有信息不符合、待补充信息、待用户核对”，其中缺少个人事实和规则存疑分别进入后两种状态。
2.2 业务活动与关键交互
活动图按条目处理规则判断：缺少个人数据时暂停该条判断并提示补充；规则存疑时补充检索，仍无法确定的交用户核对。其他条目可以继续处理，结果连同依据进入候选计划。
计划生成由 Agent 与程序配合完成。Agent 检索通知、提取要求并生成候选计划，程序校验引用、任务依赖和日期。用户确认具体版本后，业务服务复查权限及输入版本，再以唯一操作标识写入正式任务；重复确认返回同次结果。
材料处理分别检查本次模型传输同意和文件访问权限，候选稿连同差异、修改理由保存。用户审阅后，导出工具检查关键字段、材料要求和版本，再生成 DOCX 副本。存在未确认关键字段时，导出规则仅允许在权限有效的前提下生成带“未定稿”标记的副本。
协作图用编号消息展示计划确认中的对象协作。Agent 读取获准事实与规则并提交候选；用户确认后，计划服务调用授权守卫和校验器，检查访问权限、输入版本及计划约束，再写入任务并记录审计事件。
完整用例图、类图、时序图和对象协作图见系统设计说明书及其 Markdown 图源。
三、数据库设计
数据库设计以 PostgreSQL 16 为目标数据库，将 32 张表组织在 core、ops、kb 三个模式中，覆盖事项、来源、规则、计划、个人资料和材料等数据域。设计文档进一步定义主外键关系、状态约束、索引及删除策略。
ER 图从工作区与事项、来源与证据、个人资料、材料与归档四个视角展示主要关系。来源快照、事实和材料保留历史版本；证据记录来源、快照、原文定位与获取时间，使既有评估可以追溯到当时使用的依据。
3.1 分域 ER 图
工作区与用户一一对应，一个工作区容纳多个事项。事项引用具体模板版本，再展开对应阶段；模板更新后，既有事项仍保留原版本引用。
来源通过快照保存版本，要求关联快照，评估关联要求。证据记录原文位置；无法读取的页面或附件另存为来源缺口，供后续补充或核对。
个人材料和事实归当前用户所有。材料通过具体版本及引用记录与事项关联；事实使用授权和外部模型传输同意分别管理，撤回后停止对应范围内的后续使用。
模型传输同意由 core.model_transfer_consent 记录，包含用户、服务商、字段范围、用途和同意状态。
事项材料与版本、候选计划与任务分别关联。提交证据与官方结果分别建模，官方结果关联对应证据，因此材料导出、本人登记提交和收到官方结果可以保持各自状态。
3.2 关系模型与对象映射
主要关系模式节选如下，完整字段、类型与约束见数据库设计说明书：
| 关系模式 | 主键 | 关键关联或约束 |
|---|---|---|
workspace(id, owner_id) |
id |
owner_id 引用用户且唯一，保证每人一个工作区。 |
matter(id, workspace_id, template_version_id, scope_attrs) |
id |
引用工作区与模板版本，范围属性随事项保存。 |
snapshot(id, source_id, version_no, fetched_at) |
id |
引用来源，source_id + version_no 唯一。 |
requirement(id, matter_id, snapshot_id, field_key) |
id |
要求同时绑定事项与来源快照。 |
evaluation(id, requirement_id, conclusion, rule_version, fact_version) |
id |
评估绑定要求和规则/事实版本，结论限制为四态。 |
task(id, matter_id, plan_id, status) |
id |
任务属于具体事项，plan_id 用于关联来源候选计划；确认写入由业务事务控制。 |
material_version(id, material_id, version_no, diff, accepted_patches) |
id |
记录材料版本、差异和接受记录。 |
对象关系映射根据实体身份、版本和生命周期确定。事项等实体直接映射到表，模板拆分为模板与模板版本，规则包拆分为规则包与规则；阶段定义、要求骨架及材料差异使用 JSONB 保存。审阅、检索和工具执行事件合并到审计日志，类型差异由模板与事项的 scope_attrs 字段承载。
| 实体类 | 库表 | 映射要点 |
|---|---|---|
Matter |
core.matter |
通用属性使用列，类型差异进入 scope_attrs，归档信息合并到事项。 |
Template |
core.template、core.template_version |
身份与版本分开，既有事项继续引用原版本。 |
Source、Snapshot |
ops.source、ops.snapshot |
稳定来源与内容版本分开保存。 |
Fact、FactGrant |
core.fact、core.fact_grant |
事实保留版本，使用授权按对象与用途记录。 |
PersonalDocument、DocumentVersion |
core.personal_document、core.document_version |
材料身份与文件版本分开，引用指向具体版本。 |
Material、MaterialVersion |
core.material、core.material_version |
保存事项材料、候选版本与修改接受记录。 |
3.3 领域知识与执行数据的管理
公开来源、快照、结构化要求和版本化规则组成领域依据。用户交互保存为事项决策、计划确认、材料修改接受记录和授权记录；检索及工具执行在审计日志中记录操作对象、时间、结果与失败原因。设计中将快照正文、原始文件和导出文件置于对象存储，数据库保存对象键、摘要、版本与关联信息。
完整 ER 图、32 张表的关系模式、实体类与数据库表映射，以及字段、约束和索引定义见数据库设计说明书 V2.0。
四、开发计划与团队协作
4.1 预期开发计划
开发计划覆盖 11 月 9 日至 12 月 6 日，共四周。表内里程碑为预期开发目标，课程提交日期以课程通知为准。
| 周次 | 日期 | 阶段目标与主要工作 | 里程碑/产出 |
|---|---|---|---|
| 第 1 周 | 11 月 9 日至 15 日 | 完成本次作业交付，确认试点、字段和接口；搭建页面、业务服务与数据库，跑通本人事项创建、官方来源处理和结果留存。 | 11 月 9 日提交博客、原型和设计文档；11 月 11 日确认业务与接口；11 月 15 日跑通首条真实来源链路。 |
| 第 2 周 | 11 月 16 日至 22 日 | 完成推免与竞赛两类流程、自查与候选计划确认；联调材料导入、修改审阅、导出和 Agent 失败恢复。 | 11 月 20 日双场景计划流程连通；11 月 22 日材料流程连通。 |
| 第 3 周 | 11 月 23 日至 29 日 | 补齐提交前检查、归档和关键异常流程；11 月 25 日冻结首版范围，集中评测、修复并完成可交付版本。 | 11 月 25 日首版功能冻结；11 月 29 日形成可交付版本。 |
| 第 4 周 | 11 月 30 日至 12 月 6 日 | 开展小范围试用，修复操作阻塞；完成干净环境启动、回归、演示和交付文件检查，预留发布修复时间。 | 12 月 2 日完成最终交付检查；12 月 3 日至 6 日作为修复与补交缓冲。 |
4.2 预期开发分工
| 学号与姓名 | 角色 | 负责内容 |
|---|---|---|
| 102401608 魏之皓 | 项目经理、产品验收 | 维护范围和业务边界，安排任务与里程碑，制定验收标准并组织试用。 |
| 102401312 刘谦益 | 界面、原型与交互 | 完成 Figma 原型、页面状态、导航与视觉规范，并核对前端还原。 |
| 102401318 陈常群 | 前端：事项与计划 | 实现事项入口、来源与条件、自查、候选计划、任务依赖和归档页面。 |
| 042402115 张锦昊 | 前端：Agent 与材料 | 实现 Agent 交互、任务进度、材料版本、差异审阅和导出下载。 |
| 102401137 佘博海 | 后端：账号、事项与任务 | 实现身份校验、个人事项、候选计划、任务依赖、权限与状态约束。 |
| 102401215 李义东 | 后端：资料、文件与导出 | 实现个人事实、文件版本、授权、DOCX 导入导出和归档关联。 |
| 102401609 王智钦 | Agent：检索与计划 | 实现官方来源检索、要求提取、计划编排、工具调用和运行检查点。 |
| 102401310 庄凯堃 | Agent：材料处理 | 实现材料诊断、局部改写、事实一致性检查、授权与失败恢复。 |
| 162404109 杜玉鹤 | 领域规则与效果评估 | 整理推免和竞赛规则、来源样本、模板配置及评测用例。 |
| 102401135 何慧渊 | 需求流程与自动化检查 | 维护流程和状态约束，编写双场景检查用例并跟踪缺陷复测。 |
| 162404103 蔡信坡 | 来源引用模块与博客 | 负责来源元数据与引用字段校验，整理原文定位与引用清单；汇总团队博客及设计资料。 |
4.3 本次协作记录
本次设计资料通过 GitHub PR 分模块提交，主要记录如下：
| 记录 | 协作产出 |
|---|---|
| PR #4、PR #16 | 提交并修订需求流程说明。 |
| PR #3、PR #11、PR #17 | 整理领域规则依据，修订个人数据边界与使用授权规则。 |
| PR #5、PR #14 | 提交 Agent 集成设计，补充授权和撤回处理。 |
| PR #6、PR #15 | 提交并更新系统设计说明书。 |
| PR #7、PR #13 | 提交并更新数据库设计资料。 |
| PR #12、PR #19 | 提交原型截图与展示说明，补充 Page 2 的交互路线和状态说明。 |
| PR #18 | 提交 Markdown 本地资源检查脚本及使用说明 |
| PR #20 | Mortal810 提交 Page 2 前端审查报告、问题与复核清单及浏览器复测截图，记录新建事项、计划确认、材料审阅和通知更新等流程的检查结果。 |
浙公网安备 33010602011771号