2026秋软工实践 妈妈夸我说的队——项目原型设计+概要设计

一、原型设计

1.1 工具与四条设计约束

家长端、儿童端、桌面端个人中心和后台管理端均使用 Figma 展示页面布局、交互路径与状态反馈。

设计上定了四条硬约束，后面每个界面都要满足：

1. 移动端优先：以 375px 宽为基准，主要操作落在拇指区，不出现横向滚动。
2. AI 输出可见、可停、可改：推荐理由、问题、回答都要有出处或状态，家长能跳过、能改字、能中断。
3. 儿童模式是减法：只保留大按钮、图画、语音和选项，不出现长表单、自由输入框和管理入口。
4. 失败态当正常态设计：模型超时、识别失败、内容撤回都有明确文案和下一步，而不是转圈。

视觉上不追求花哨：后台深绿侧栏 + 米色底 + 卡片式列表，状态统一用标签区分；用户端按手机阅读场景放大字号与点击区域，儿童模式进一步收成按钮、图画、语音三样东西。

1.2 任务链与页面结构

页面没有按功能清单平铺，而是按家长真正会走的一遍组织：选书 → 共读 → 互动 → 记录。

图1　用户端页面流转与后台入口。橙色表示智能体参与的界面，绿色表示主流程。

几个具体决定：首页不做信息流，只回答"今天读什么、上次读到哪"；详情页把"为什么推荐"放在开始按钮上方，家长看完理由再决定；共读页把翻页和提问分开，翻页是确定动作，提问是可跳过动作；小结页只陈述事实（时长、互动次数、停留页），不出现"注意力不集中"这类评价。

移动端 Figma 原型包含首页、绘本馆、绘本详情、亲子共读、智能互动、原创故事、阅读小结和儿童模式。儿童自主阅读模式只保留受授权的绘本、朗读和简化操作；原创绘本页面展示生成与审核状态，不代表内容已发布。具体跳转与状态以文末原型链接为准。

图2　移动端 Figma 图片总览。展示首页、绘本馆、绘本详情、亲子共读、智能互动和阅读小结等画板。

1.3 桌面端个人中心

拉取请求（PR）#23 提交了 1440×900 的桌面端个人中心 Figma 原型，PR #24 将说明统一收录到 prototype/figma/personal-center-desktop/README.md。顶部沿用站点导航，左侧六项功能导航，右侧以卡片呈现当前模块；当前项用深绿色高亮。六页分别是个人中心首页、个人资料、儿童档案、我的书架、成长记录和阅读计划。首页的“查看全部”“查看计划”“切换孩子”进入对应模块；儿童档案的新增、编辑、删除有确认反馈；资料保存、头像更换、书架收藏和计划编辑提供反馈状态；阅读趋势可切换周/月，计划日历可切换月份。昵称、书架数量、阅读时长等均为原型演示数据，不代表后端已有数据。完整页面与交互见文末的桌面端原型。

图3　桌面端 Figma 图片总览。展示桌面端首页、绘本共读、个人中心及资料、书架和阅读计划等页面。

1.4 领域 Agent（领域智能体）的三种交互界面

智能体如果只做成右下角的聊天窗，家长看到的永远是"我问它答"，看不到它凭什么这样答。所以原型把它的工作过程放进页面结构，落在三个界面上。

推荐理由卡（选书阶段）。 以《小狐狸的雨伞》为例，主角是小狐狸，符合孩子对动物故事的兴趣。全书共 6 页，适合 3～4 岁幼儿。故事围绕下雨、撑伞和妈妈的陪伴展开，可以引导孩子观察天气、表达情绪和理解家人的关心。

推荐理由下方的“依据”区展示知识引用的交互样式。原型可用适龄的 KN-AGE-001 演示，如邀请孩子说出故事中的主要人物和情节。该条目目前是草稿（DRAFT），仅用于原型示例。正式检索只使用已审核且有效的知识版本。

互动问题卡（共读阶段）。 在关键情节页从底部浮起，一次只问一个问题，句式控制在一句话以内，三个动作是"孩子答了""没听懂""跳过"。点"没听懂"不重复原问题，而是换得更具体："看看小松鼠的脸，它的嘴巴是向上还是向下的？"点"跳过"本次不再追问，但事件照样入库，不调用模型。

语音问答浮层（孩子提问）。 孩子按住说话，松开转写，转写文本先给家长看，可以改字或重录，确认后才请求回答，文字出现的同时播放语音。整个浮层只有"重录""确认""播放/暂停"三个按钮。

三种界面共用一条链路：界面收集上下文 → 后端校验权限与状态 → 智能体检索知识并生成 → 安全校验 → 落库返回。界面只展示服务端已保存的结果，不在前端"先显示再补救"。

1.5 后台管理端 Figma 原型

后台 Figma 插件在 PR #21 入库，设计范围是工作台、绘本管理、版本审核、领域知识库、接口与权限五页。页面采用侧栏导航、顶部当前模块标题和右侧卡片/列表内容区：工作台汇总待处理事项；绘本管理维护本体、版本和素材；版本审核进入逐项核对与确认；知识库显示分类、适龄、版本及状态；接口与权限页解释不同角色的可操作范围。以上为已提交的原型设计，并非运行中的后台服务。

后台交互按“草稿编辑 → 提交审核 → 管理员核对版权、适龄、页面和安全项 → 通过或驳回”设计。只有有审核权限的内容管理员可作审核决定；普通家长与儿童端不能进入管理界面。实现时由服务端校验身份并记录 reviewed_by_id、reviewed_at，客户端展示状态不能直接决定发布。知识修订新增版本，历史引用保留原版本。接口与权限页展示的是设计边界，不代表相应接口已实现。

数据状态需与演示区分：当前种子数据中的 21 个绘本版本和 20 条领域知识均为 DRAFT（草稿），不是待审核、已通过或已发布。工作台若显示待审数字，仅属于原型演示数据，不能作为数据库现状。草稿需要补齐素材与审核记录后，才可能按设计流程进入后续状态。

后台与移动端共用一个 Figma 文件，文末的后台入口定位到节点 32:6729。

图4　后台管理端 Figma 图片总览。展示工作台、绘本管理、版本审核、领域知识库、接口与权限五个画板。

1.6 主要原型交互规则与异常处理

原型评审最容易走过场的地方，是大家点几个按钮就说"可以"。这次把关键规则固化成表，开发按表实现，测试按表验收。

选书时家长在首页看到推荐，进入详情核对适龄与推荐理由，再选择共读；共读时翻页由用户控制，智能体在关键页提供可跳过的问题；语音提问须先由家长核对转写；结束后进入阅读小结和成长记录。原型可演示这些页面和反馈状态，数据库写入、语音识别与合成、知识检索和安全校验属于后续实现与验收范围。

二、概要设计

依据与成熟度。需求规格说明书 v0.2 仍标注待团队评审；系统设计说明书 v1.1、数据库设计说明书 v1.1、接口契约 v0.4、知识库 v2.5 及 PR #22 的设计变更记录是本次核对的仓库依据。已合并的设计稿、契约和原型属于已提交成果；架构、接口、审核流程与异常恢复属于开发方案；DCL-005～DCL-008 等冲突仍待决策。本文不把设计约定写成已上线功能，也不改动正式设计基线。接口口径以 v0.4 契约和公共术语表为准，物理表结构以数据库设计说明书 v1.1 为准；若原型演示状态与种子数据冲突，以种子现状说明数据，以设计文档说明预期流程。

2.1 架构：一个部署单元，六个组件

决策 D1｜首版只做一个后端部署单元，不拆微服务。

• 依据：要保证公网可演示，服务拆得越细，联调和部署成本越高；组件边界用接口约束住，将来要拆时有地方下手。
• 代价：单进程意味着并发上限受限于 SQLite 写锁与单机资源，扩容只能靠换更强的机器，不能靠加副本。

图5　系统组件与依赖图。来源为系统设计说明书 图 4-1。

六个组件各管一段：AuthService 管会话与授权，业务服务管档案、绘本、会话、小结，ReadingAgent 负责生成，KnowledgeService 负责检索，VoiceService 管自动语音识别（ASR）与文本转语音（TTS），Repository 统一处理权限、并发与事务；安全校验器作为横切能力内嵌在智能体与内容侧，不单列部署单元。

技术选型按同一逻辑收敛：

2.2 功能模块划分

12 个模块分四组：账号与内容（M1 账号档案、M2 绘本内容、M10 内容管理）、阅读主链（M3 推荐、M4 共读朗读、M5 互动引导、M6 语音问答、M7 记录小结）、生成与儿童（M8 原创与分支、M9 儿童模式）、横切（M11 安全异常、M12 部署运维）。

图6　功能思维导图。来源为需求规格说明书 2.6 节。

模块之间只允许三种关系：调用（M5 调 M6 的转写结果）、依赖数据（M3 读 M2 的版本）、事件通知（M4 翻页产生事件供 M7 汇总）。不允许跨层直连——M9 儿童模式不能直接读库，必须经业务服务校验授权。

2.3 运行逻辑

图7　阅读业务数据流。来源为系统设计说明书 图 4-2。

一次共读在系统里这样走：开始前校验档案归属与绘本可读性，不通过直接返回原因，不产生无效会话；阅读循环由"会话有效、未超时、内容可用"三个条件守卫，任何一条不成立就退出并按真实原因保存终态；结束时把终态、事实、小结和可重放的原响应放进同一个事务。

图8　阅读主流程活动图。来源为系统设计说明书 图 5-3。

活动图描述人的操作顺序，状态机描述会话本身能处在哪些状态、怎样迁移。

图9　阅读会话状态图。来源为系统设计说明书 图 6-1。

CREATED → IN_PROGRESS → FINISHED 是正常路径，INTERRUPTED 是异常出口；状态只前进不回退，两个终态都不可再变——这直接决定了小结能不能生成、历史能不能复读。

2.4 UML 设计

UML 不追求画全，而是让每张图回答一个问题。完整图表（含分支、续写、占位、生成校验四张时序图与服务类图）在仓库 docs/design/diagrams/，本文放主干五张，状态图见 2.3 节。

用例图：谁能做什么。 两个建模决定：幼儿不是独立账号，而是"受家长授权"的参与者约束，所以接口权限模型都围绕"家长账号 + 儿童授权"展开；"选择已审核分支"是独立用例，以扩展关系挂在亲子共读和儿童模式上——分支只在到达决策节点时发生，两种模式的审核要求也不同。

图10　阅读用户用例图。来源为系统设计说明书 图 3-1。

类图：职责怎么分。

决策 D2｜绘本与绘本版本拆成两个类。

• 依据：家长读的是某个具体版本，不是"这本书"；授权、事件、小结都挂在版本上，换版本不会污染历史记录。
• 代价：列表页、推荐页都要多一层"取当前生效版本"的解析，查询比单表复杂。

图11　核心领域类图。来源为系统设计说明书 图 5-1。

服务侧对应分成会话、分支、知识、安全、语音与仓储六类职责，彼此只通过方法调用，不共享内部状态。

时序图：把并发和失败画出来。 智能体任务时序里有两个 alt 分支：没取得执行权就直接返回原响应或"处理中"，取得执行权才允许调模型；提交阶段再复核授权与 revision，状态变了就回滚并返回 409。同一个请求键重放两次，家长看到的仍是同一个结果。

图12　阅读智能体任务时序。来源为系统设计说明书 图 5-5。

语音链路设计了三级降级：ASR 失败转重录或文字；模型超时返回预置的安全回答；TTS 失败只显示文字。任何一级失败都不会让家长卡在转圈上。

图13　语音问答与文字回退时序。来源为系统设计说明书 图 5-7。

协作图：对象怎么连。 阅读页面把反馈交给会话服务，会话服务取上下文交给智能体，智能体查知识、调模型、过校验，最后交回会话服务落库。链路里没有"智能体直接找数据库"这条边——所有数据访问都必须经过 Repository 的权限校验。

图14　动态引导协作图。来源为系统设计说明书 图 5-8。

2.5 领域 Agent 与系统的集成

决策 D3｜智能体是业务后端的一个受控能力，不是系统入口；首版不拆多智能体。

• 依据：三类任务（提问、引导、生成故事）边界清楚，工作流固定，拆多智能体会让调度和评测同时变复杂。
• 代价：任务类型要扩展时，需要在 Agent 内部重构工作流，而不是新增一个"专家"。

集成位置。 业务服务完成鉴权、会话校验和事件落库之后，才把上下文交给 ReadingAgent；前端不直接调模型，密钥只在服务端环境变量里。智能体拿到的是快照而不是数据库连接：当前绘本版本、页码、前后页摘要、档案年龄段、最近的互动记录。

领域知识。 20 条知识分年龄发展、引导方法、安全规则三类，每条带来源、引用定位、适用年龄和任务标签。检索先按 ageBand 初筛（只用该年龄段与全龄知识，不跨龄借用），再按主题与标签过滤，最后按相关度取有限片段；未审核内容永远不进检索。

工具调用。 只有四个面：知识检索取带来源的片段，模型网关生成问题与回答，语音服务做 ASR/TTS，仓储负责事件与执行权。失败时分别退化为规则话术、预设问题、文字回答与回滚。

任务流程。 三条固定工作流，都是"读上下文 → 取知识 → 生成 → 校验 → 展示"的固定形状，不让模型自由发挥：

• 提问：读页面 → 判年龄 → 取情节要素 → 选问题类型 → 生成一句问题 → 校验是否扣住当前页。
• 引导：读反馈（理解 / 未理解）→ 取上一条问题 → 换策略（更具体或更进阶）→ 生成 → 校验。
• 生成故事：读参数 → 取结构模板 → 生成 4～6 页 → 结构校验（有开头、有结局、页数合规）→ 安全检查 → 存草稿。

证据与评测。 每次生成都在 event_evidence 里记下实际用到的知识版本与排序，家长问"你凭什么这么问"时能查到依据。评测采用对照设计：同一基础模型、同样输入，比较通用模型与注入领域知识、页面上下文和规则的知芽智能体；维度是年龄适宜性、情节一致性、引导合理性、知识依据、安全性、原创与分支连贯性，每项 0～2 分，至少两人独立打分。我们不预设"提升 XX%"的结论，首轮结果在 MS3 之后产出。

2.6 接口与一致性

前后端约定固定成 32 个接口（API-001～API-032），分认证、档案、绘本、推荐、会话、语音、原创、内容管理与健康检查九组，写清方法、路径、权限与错误码。贯穿全契约的是三条约束：

• 认证与会话：Cookie 使用 Secure / HttpOnly / SameSite=Lax，写操作校验跨站请求伪造（CSRF）令牌；进入儿童模式时在同一事务里吊销家长会话、签发儿童授权并绑定可用版本。
• 并发：会话带 revision，每次交互原子递增；旧值提交返回 409，由前端刷新到服务端状态，而不是静默覆盖。
• 幂等：同一 client_request_id 只有一次执行权，重放返回原响应。

错误码分工：400/422 请求不合法，401 未登录，403/404 越权或不存在（对外不区分，避免探测），409 状态冲突，503 依赖不可用。前端对每一类都有对应界面状态。

2.7 部署与后端设计展示

图15　软件独立部署图。来源为系统设计说明书 图 8-1。

首版是单机：Nginx 终止 TLS 并托管前端静态资源，反向代理到 FastAPI，SQLite 落在持久化卷上，模型与语音服务出网调用。

图的清晰度做了三件事：统一 PlantUML + Graphviz 渲染、220 DPI、中文字体统一；每张图保留 .puml、.png、.svg 三种格式；连线人工核对，避免线穿框与箭头指错对象。

三、数据库设计

3.1 留痕原则

绘本平台的价值不在"存了书"，而在可追溯。第一原则是留痕：绘本有版本，授权落到版本，互动记证据，任务留执行权。

四条落地规则：一切以版本为准，修订产生新行而非覆盖；儿童授权精确到版本 ID，不按年龄段放宽；对外 ID 用 JSON 正整数（1～9007199254740991），避开 JS 精度问题；状态显式化，DRAFT / PENDING_REVIEW / PUBLISHED / APPROVED_PRIVATE / RETIRED / WITHDRAWN 都是库里的值，不靠"有没有某个字段"推断。

3.2 实体联系（ER）图：三条线

图16　账号、儿童授权与请求执行。来源为数据库设计说明书 图 4-1。

第一张解决"谁能访问什么"：账号一对多会话，家长会话可签发儿童授权，授权再通过白名单表落到具体版本；执行权表挂在账号与会话上，承担幂等。

图17　绘本本体、版本与阅读记录。来源为数据库设计说明书 图 4-2。

第二张是业务主干：绘本本体到版本，再到页面与分支；阅读会话绑定档案与版本，互动事件记录每次操作，小结与会话一对一。

图18　事件与实际引用的知识版本。来源为数据库设计说明书 图 4-3。

第三张是证据链：互动事件与知识条目通过引用表多对多关联，带顺序号。知识改版后，历史事件仍指向当时实际使用的那一版。

3.3 关系数据模型

核心关系模式节选，PK（Primary Key）为主键、FK（Foreign Key）为外键、UK（Unique Key）为唯一键，省略号表示博客未展开的字段；完整类型、默认值与索引见数据字典。

accounts(id[PK], role, ...)
auth_sessions(id[PK], account_id[FK], revoked_at, ...)
child_profiles(id[PK], guardian_id[FK], ...)
child_grants(id[PK], profile_id[FK], issued_by_session_id[UK], expires_at, revoked_at)
child_grant_books(grant_id[PK,FK], version_id[PK,FK])
storybooks(id[PK], source_type, owner_guardian_id[FK], ...)
story_versions(id[PK], storybook_id[FK] + version_no[UK], status, ...)
story_pages(version_id[PK,FK], page_no[PK], default_next_page_number, ...)
reading_sessions(id[PK], profile_id[FK], version_id[FK], revision, visited_pages_json, ...)
interaction_events(id[PK], session_id[FK], version_id[FK], request_key, page_no, event_type, ...)
reading_reports(session_id[PK,FK], status, summary, ...)
knowledge_items(id[PK], item_key + version_no[UK], status, source_title, ...)
event_evidence(event_id[PK,FK], knowledge_item_id[PK,FK], rank_no)
request_executions(id[PK], owner_account_id[FK], scope_type, scope_id, client_request_id)

四条硬约束决定了这些表为什么长这样：(storybook_id, version_no) 唯一，同一本书版本号不重复；(version_id, page_no) 作复合主键，页码在版本内唯一且稳定；(session_id, request_key) 唯一，同一请求键只落一条事件；(owner_account_id, scope_type, scope_id, client_request_id) 唯一，保证幂等执行权。

3.4 实体类与库表的映射

映射规则很朴素：实体类就是表，值对象落到列。Account→accounts、ChildProfile→child_profiles、Storybook→storybooks、StoryVersion→story_versions、StoryPage→story_pages、ReadingSession→reading_sessions、InteractionEvent→interaction_events、ReadingReport→reading_reports、KnowledgeItem→knowledge_items，一行对一行。

例外只有一个：ChildGrant 一个对象映射两张表（授权头 + 版本白名单），因为授权必须能精确到版本集合。其余细节（字段类型、可空性、默认值）见数据库设计说明书第 4 章。

3.5 领域知识、交互记录与任务结果怎么存

决策 D4｜模型调用先占位、后生成、再提交。

• 依据：模型调用是慢操作，不能占着数据库写锁等它；先写执行权再调模型，重放时能直接返回原响应。
• 代价：多了一张执行权表和一个"处理中"状态，前端要能区分"生成中"和"失败"。

领域知识：版本化 + 证据链。 修订走 PATCH，插入新行、分配新版本号，旧行转 RETIRED；检索只读 APPROVED；被引用过的事实永久留在引用表里。这样既能迭代知识，又不会让历史记录跟着变。

用户交互：只存事实，不存原始录音。 每次翻页、提问、回答、跳过、分支选择都落一条事件，带页码、请求键和输入输出文本。原始音频默认不长期保存，只保留转写并经家长确认的文本。

任务执行：三段式。 占位写执行权表，生成在事务外完成，提交时复核授权与 revision；失败回滚，重放返回原响应。结束阅读时，终态、事实记录、PENDING 小结和可重放的原响应在同一事务内完成。

异常恢复：启动时收尾。 单工作进程启动时，把遗留的 PENDING 小结条件更新为 FAILED，保留事实摘要、活动数组置空，不重新调用模型。重启不会重复计费，也不会让家长看到一个永远"生成中"的页面。

四、团队协作记录

4.1 协作方式

团队通过飞书多维表格管理任务与里程碑，通过 GitHub 拉取请求协作提交原型、设计文档和交接材料。设计变更与冲突处理记录在仓库的设计变更日志中。

4.2 本次可追溯协作记录

4.3 预期开发计划（八步，截止 2026-11-28）

开发计划从 11 月 10 日开始，分八步推进，11 月 28 日完成验收材料与答辩演练。

4.4 分工安排

本阶段（G01～G06）的预期分工是：需求基线由黄锦培牵头、全员补充，知识与绘本样例由张楠负责，原型与展示材料由张陈雨菲、吴怡霏、卢志勇负责，业务数据与 API 由姚华俊牵头，智能体与外部服务由陈烨婷牵头、张智文与林鑫协作，测试与领域对比方案由刘俊延牵头。

五、作业总结

用一句话概括这次作业：我们把“想做成什么样”写成了“别人可以检查的设计”。本次又将移动端、桌面端个人中心和后台管理端的 Figma 原型、设计变更记录，与已有 UML、数据库模型和接口契约互相核对。原型展示交互，设计说明预期行为；开发和验收仍需按计划推进。

• 术语统一。绘本、版本、会话、小结在两份设计说明书、接口契约和术语表中应保持同义，字段与接口才能对应。
• 版本留痕。绘本本体与版本、知识条目与版本分离，使授权、事件和历史证据指向确定版本；代价是查询和状态校验更复杂。
• 原型与设计互相校对。未理解、跳过、生成失败等页面反馈，应在后续实现的接口和数据状态中找到落点。种子目前仍是草稿，发布与审核尚需实际执行。

让阅读成为陪伴，让成长自然发生。

六、成果入口