开始界面
图 1　开始界面：发光标题、飘动箭头、玩法卡片、实时演示棋盘与音效开关

AIGC标识 棋理学伴——项目原型设计+概要设计

2026秋软工实践 棋理学伴——项目原型设计+概要设计

项 内容
作业所属课程 2026 秋软件工程实践（福州大学 202601SofwareEngineering）
作业要求 团队作业-第二次：原型设计 + 概要设计
作业的目标 把第一次作业确定的需求落成可演示的高保真原型，并从架构、UML、数据库三个层面完成概要设计；同时给出可执行的开发计划与团队分工。
团队名称 棋理学伴团队
团队成员学号-名字 182400143 张宇天、102401418 王宇航、102401421 丁政伟、292400336 吴涵彬、112401430 王龙滨、112401341 吴佳辉、102401404 孟维涛、102402117 蔡以恒、102401414 许书凯

目录

  1. 本次要解决的问题
  2. 原型设计（40%）
  3. 概要设计（40%）
  4. UML 设计
  5. 数据库设计
  6. 智能体与软件系统的集成
  7. 后端设计展示
  8. 团队协作记录（20%）
  9. 链接与文档

1. 本次要解决的问题

第一次作业里我们把「棋理学伴」的目标写清楚了：面向象棋初学者的短局面战术学习助手，用户先独立落子，再依据规则证据与分级讲解理解这一步为什么成立。

这一次要回答三个更具体的问题：

  • 界面怎么长：用户从选一道题到看懂一步，屏幕上有哪些信息、按什么顺序出现、哪些操作会被拒绝。
  • 系统怎么搭：前端、服务、领域规则、引擎、模型各自负责什么，边界在哪里，谁信任谁。
  • 数据怎么存：题目、棋理、学习记录、讲解会话、调用日志分别落在哪张表，怎么保证匿名与可迁移。

下面按原型、概要设计、UML、数据库、协作记录的顺序展开。

2. 原型设计（40%）

2.1 工具与设计原则

  • 原型工具：墨刀（Modao）制作可点击高保真原型；本地同时维护一套可离线打开的 HTML 原型（prototype.html），逐屏截图直接进入本文档与说明书。
  • 画布尺寸：用户端 390 × 844（手机），后台管理 1280 × 800（桌面）。
  • 配色：沿用项目标志的深绿 #234b40、米色 #d8c597、朱红 #b54c3d、米白 #f7f2e7，不使用棋类 App 常见的木纹写实风。
  • 三条交互原则：
    1. 先做后讲：先让用户独立落子，提示与讲解按需展开，不默认给出答案；
    2. 判定可见：通过 / 未达标 / 非法三态必须明确，非法走法直接拒绝并说明原因；
    3. AI 不越权：模型只组织语言，棋盘与回放只采用本地核验过的线路，调用状态在页面上可见。

2.2 用户端原型（10 屏）

编号 屏幕 核心内容 关键交互与规则
P01 首页 / 题库 今日进度、分类/主题筛选、题目列表 只按分类与主题筛选；完成标记区分「独立完成」与「提示后完成」
P02 训练页 棋盘、本题目标、提示入口 点击己方棋子 → 点击目标格；非法走法被拒，合法未达标给区别提示
P03 判定反馈 三态说明与具体原因 非法：规则/帅将安全；未达标：合法但没到目标；通过：记录证据
P04 三级提示 观察方向 → 路径 → 示例着法 逐级解锁；第 3 级展示示例走法，用了提示就不再计为独立完成
P05 本地解法回放 步骤列表、走前/走后、摆谱入口 回放只读，不修改答题棋盘与成绩；线路来自本地核验
P06 AI 逐步讲解 分步讲解、E1–E4 证据、一致性提醒 用户主动调用；结构失败明确报错；引用不一致保留原文并标黄
P07 错题本 错题列表、错误次数、状态标签 只标记状态不删除；提示后完成与独立完成分开统计
P08 图片识谱 选图 → 四角校正 → 校对 图片在浏览器内压缩；必须人工核对后才进入分析
P09 规则知识库 7 条棋理条目 条目带来源与适用范围，不覆盖长将长捉等比赛裁定
P10 设置 口令、记录导入导出、API Key Key 只在页面内存；模型调用失败不自动重试，避免重复计费

P01

P01 首页：题库筛选与进度；完成标记区分「独立完成」与「提示后完成」。
P02

P02

P02 训练页：棋盘 + 本题目标 + 提示/讲解入口，先独立落子。

P04

P04 三级提示：观察方向 → 路径 → 示例走法，逐级解锁。

P06

P06 AI 逐步讲解：分步讲解 + 四条规则证据 + 一致性提醒（advisory）。

2.3 后台管理原型（3 屏）

编号 屏幕 核心内容 说明
A01 题库管理 题目列表、筛选、上架/草稿、难度与目标 服务端化后由维护者使用，当前为规划功能
A02 知识条目维护 7 条棋理编辑、关联题目、来源与状态 知识条目与题目多对多，可预览后发布
A03 调用监控 调用量、成功率、结构失败、延迟、token 对应 t_model_call_log，支持导出与按路由筛选

A01

A01 题库管理：题目上下架与审核状态；当前代码中尚无后台，属于服务端化规划。

2.4 界面里的「领域 Agent」

在 P02 → P04 → P06 三个屏幕里，智能体不是一个独立的聊天框，而是嵌在学习闭环中：

  • 输入是结构化证据：用户着法、FEN、E1–E4 规则证据、引擎候选着法与评分；
  • 输出是分步解释：目的 → 对方应对 → 结果 → 其他选择，每一步都能在棋盘上定位；
  • 越权保护：模型正文里临时提出的着法不会进入回放；引用与证据不一致时只加提醒；
  • 失败可见：调用中、成功、带提醒成功、失败四种状态都在页面顶部与讲解区显示，失败不假装成功。

3. 概要设计（40%）

3.1 分层架构

fig-layer-arch

图 1 五层架构：L1 表示层、L2 接口层、L3 应用服务层、L4 领域层、L5 基础设施层。

层 职责 主要组成
L1 表示层 棋盘与交互、提示与讲解呈现、回放与摆谱、识图四角校正、本地记录 public/*（原生 JS，无框架）
L2 接口层 静态资源、HTTP API、口令、Origin/Host 校验、限流 server.js
L3 应用服务层 编排一次业务用例：判定、提示、讲解、导入、评测 src/training.js、coach*.js、import-analysis.js 等
L4 领域层 规则判定、短杀搜索、证据生成、题库与棋理 vendor/xiangqi.js（MIT）、endgame-search.js、knowledge.js 等
L5 基础设施层 Pikafish 子进程、DeepSeek HTTP、请求闸门、IndexedDB 适配 engine.js、model-client.js、learning-store.js

三条信任边界：① 前端不可信——服务端重新计算局面与历史；② 后端不存密钥——API Key 只在页面内存，经服务端转发；③ 引擎可降级——引擎不可用时保留规则核验与证据。

3.2 功能模块结构

fig-module-tree

图 2 功能模块树：M01–M11 已实现，M12 后台内容管理为规划模块。

模块表（详见说明书 2.4 节）：

模块 名称 已实现 关键文件
M01 题库与选题 是 puzzles.js、curriculum.js
M02 走法与目标判定 是 training.js、vendor/xiangqi.js
M03 三级提示与规则证据 是 training.js、knowledge.js
M04 本地解法回放与摆谱 是 walkthrough.js、walkthrough-view.js
M05 AI 逐步讲解 是 coach.js、coach-prompt.js、coach-validation.js
M06 图片识谱导入 是 position-vision.js、vision-*.js
M07 残局多步训练 是 endgame-training.js、endgame-search.js
M08 错题本与学习记录 是 learning-store.js
M09 规则知识库 是 knowledge.js
M10 对照评测 是（机制） teaching-analysis.js
M11 安全、限流与模型代理 是 server.js、model-request.js
M12 后台内容管理 规划 服务端化后新增

3.3 运行逻辑

一次训练会话：选题 → 独立落子 → 服务端重算 → 三态判定 →（按需）提示/本地解法/AI 讲解 → 记录状态 → 错题重练。详见第 4 节活动图与时序图。

4. UML 设计

4.1 用例图

fig-usecase

图 3 用例图：学习者 8 个用例、维护者 3 个用例；DeepSeek 与 Pikafish 是外部系统参与者。

4.2 活动图

fig-activity-learn

图 4 学习闭环活动图：三态判定 + 提示/解法/讲解三条辅助路径。

fig-activity-coach

图 5 AI 逐步讲解活动图：结构校验失败即报错；引用不一致保留原文并提醒。

4.3 类图

fig-class

图 6 领域类图（概念模型）。实现以模块 + 函数组织，类图表达领域概念，不表示同名源码类。

4.4 时序图

fig-seq-attempt

图 7 走子判定时序图：浏览器只上传着法与局面，服务端重新核验。

fig-seq-coach

图 8 AI 逐步讲解时序图：引擎候选 → 四段式提示词 → DeepSeek → 结构与引用校验 → 渲染。

4.5 协作图

fig-collab

图 9 协作图：对象之间的消息编号与时序图对应。

4.6 部署图

fig-deploy

图 10 部署图：浏览器 ↔ Node.js 服务端 ↔ Pikafish 子进程 / DeepSeek 云。

5. 数据库设计

5.1 ER 图

fig-er

图 11 数据库 ER 图（12 张表）。当前单机版使用 IndexedDB，本设计为服务端化方案。

5.2 关系模型与表清单

# 表 用途
1 t_puzzle 题目主表：题面、FEN、目标、标准着法、教案
2 t_hint 三级提示（puzzle_id, level）
3 t_puzzle_solution 多解清单
4 t_knowledge 7 条棋理
5 t_puzzle_knowledge 题目—棋理多对多
6 t_learning_record 学习记录（scope_id + puzzle_id 唯一）
7 t_attempt_log 作答流水
8 t_coach_session AI 讲解会话
9 t_coach_output 讲解原始输出与校验问题
10 t_engine_analysis 引擎分析缓存
11 t_model_call_log 模型调用日志
12 t_admin_user 后台管理员

5.3 ORM 映射（摘录）

实体类 表 主键 关键字段映射
Puzzle t_puzzle id canonical → canonical_uci；maxRedMoves → max_red_moves
Hint t_hint (puzzle_id, level) 组合主键
KnowledgeEntry t_knowledge id sourceLabel → source_label
LearningRecord t_learning_record (scope_id, puzzle_id) lastSeen → last_seen
AttemptLog t_attempt_log id move → move_uci
CoachSession t_coach_session id warnings → warning_count
EngineAnalysis t_engine_analysis id pv → pv_json

5.4 数据的存储与管理

  • 领域知识：题库、提示、棋理属于只读配置类数据，按版本发布、审核后上架；前端不需要写权限。
  • 用户交互记录：当前存浏览器 IndexedDB（qili-learning-v2 的 records / meta），只存学习字段，不存 Key、模型原文与 token；服务端化后用 scope_id + puzzle_id 做幂等同步，保留匿名性。
  • 任务执行结果：讲解会话保留状态、校验结论与 token 统计；t_coach_output 存原始 JSON 供复核与评测，按保留策略定期归档。

6. 智能体与软件系统的集成

领域 Agent 在系统中承担「解释者」而不是「判定者」：

环节 谁做 输入 输出
规则判定 程序 FEN、着法、历史 合法/非法、将军、目标完成
证据生成 程序 局面与着法 E1–E4 证据、对手应对数
引擎参考 Pikafish 当前局面 候选着法与评分、可重放线路
提示编排 程序 题目、证据、候选 四段式提示词
讲解与校验 模型 + 程序 提示词 分步讲解；结构/引用校验结果

集成方式：server.js 代理模型请求，Key 只在页面内存；模型输出经 coach-validation.js 校验后才渲染；模型正文中的着法不会进入回放线路。失败时页面明确报错，不自动重试、不自动展示本地答案。

7. 后端设计展示

  • 接口清单：/api/health、/api/puzzles、/api/knowledge、/api/attempt、/api/hint、/api/lesson、/api/engine、/api/coach、/api/compare、/api/model/test、/api/import/*、/api/study/analyze。
  • 安全措施：项目口令（timingSafeEqual）、Origin/Host 校验、请求体大小限制、12 次/分（分析 30 次/分）限流、CSP、全站不使用 innerHTML。
  • 成本控制：模型调用由用户主动触发，单次 120 s 超时，失败不自动重试；引擎每次独立进程、单线程、64 MiB 哈希。

详见《系统设计说明书》第 3、4、6 章与《数据库设计说明书》第 4、5 章。

8. 团队协作记录（20%）

8.1 开发计划

周次 日期 里程碑 主要产出 验收方式
W1 10/19–11/15 M1 设计定稿 两份说明书、13 屏原型通过评审 对照作业要求逐条检查
W2 11/16–11/22 M2 训练闭环增强 多解提示优化、错题本重练、回归测试 自动测试 + 20 题可解性
W3 11/23–11/29 M3 智能体质量 讲解对照样本、校验规则细化 同条件对照 + 人工点评
W4 11/30–12/06 M4 识图与导入 四角校正体验、识别失败兜底 真实图片样例回归
W5 12/07–12/13 M5 服务端化预研 数据库落地、接口改造、限流 迁移脚本 + 接口测试
W6 12/14–12/20 M6 验收与发布 验收测试、部署、演示材料 验收清单全通过

8.2 角色与分工（具体到人）

学号 姓名 角色 负责的详细开发部分
182400143 张宇天 队长 / PM 计划与里程碑、设计评审、答辩统筹、需求变更
102401414 许书凯 需求与用户研究 原型任务流程梳理、验收口径、用户走查与访谈
102401421 丁政伟 领域知识 题库与棋理内容、教案核对、后台内容管理需求
292400336 吴涵彬 规则与算法 合法判定、多解枚举、短杀搜索、类图/时序图对应模块
112401430 王龙滨 前端交互 墨刀原型、交互说明、棋盘与回放实现
112401341 吴佳辉 后端与安全 分层架构、接口设计、限流与口令、部署图
102401404 孟维涛 AI 集成 提示编排、结构校验、智能体集成方式与对照评测
102402117 蔡以恒 测试与验收 验收用例、自动测试、质量门禁
102401418 王宇航 视觉与文档 UI 视觉、说明书排版、博客与图示

8.3 协作过程

  • 需求评审：以第一次作业的需求为准，逐条核对原型是否覆盖 F01–F08；未覆盖项进入待办。
  • 设计评审：架构图、类图、ER 图三张图先评审再定稿，避免后期返工。
  • 工具：飞书多维表格管理任务与里程碑；GitHub 团队仓库管理文档与代码；每周例会只讲进展、阻塞、能否当场演示。
  • 协作记录方式：例会纪要 + 原型走查截图 + 仓库提交记录（每个成员均有 commit）。

9. 链接与文档

项目 链接
GitHub 团队仓库 【待替换：https://github.com/团队/仓库】
原型在线展示（墨刀） 【待替换：墨刀分享链接】
《棋理学伴_系统设计说明书.pdf》 https://wwbxl.lanzouw.com/iam494f8svuh
《棋理学伴_数据库设计说明书.pdf》 https://wwbxl.lanzouw.com/iN7nQ4f8svqd

附：缩写表

缩写 含义
FEN Forsyth–Edwards Notation，象棋局面记谱串
UCI Universal Chess Interface，走法坐标串（如 a1a7）
NNUE 高效可增量更新的神经网络评估函数
API Application Programming Interface，应用程序接口
ER Entity-Relationship，实体—联系模型
ORM Object-Relational Mapping，对象关系映射
DAO Data Access Object，数据访问对象
PM Project Manager，项目经理
GB/T 8567 《计算机软件文档编制规范》

团队：棋理学伴团队｜文档：第二次作业（原型设计 + 概要设计）｜2026-11-09

posted @ 2026-11-09 00:49  Bari  阅读(6)  评论(0)    收藏  举报
悬停被挡的箭头
图 2　悬停被挡：红色路径 + 阻挡者橙色框
悬停可飞出的箭头
图 3　悬停可飞出：绿色路径延伸到棋盘外