diff --git a/docx2md/1_Compact.md b/docx2md/1_Compact.md new file mode 100644 index 0000000..6093c50 --- /dev/null +++ b/docx2md/1_Compact.md @@ -0,0 +1,974 @@ +# 课程编号：A0801260211 + +软件系统设计实训 + +个人报告 + +--- +> 📸 **[指令：请在此处上传图片 001]** +> 文件名: `Image_001.jpeg` +--- + +| | | | | +|------------------|------------------------|--------------|--------------| +| **姓名** | **张臻** | **学号** | **20245738** | +| **班级** | **软件2402** | **指导教师** | **姜琳颖** | +| **实践课程名称** | **软件系统设计实训** | | | +| **开设学期** | **2025-2026 秋季学期** | | | +| **开设时间** | **16-18周** | | | +| **报告日期** | **12.28** | | | + +**东北大学软件学院** + +目录 + +1\. 实训目的 Aim of Project - 1 - + +[2. 预习内容 Preview Content - 1 -](\l) + +[3. 实训内容和实践过程 Project Content and Process - 2 -](\l) + +[3.1 概述Overview - 2 -](\l) + +[3.2 相关技术Relevant Technologies - 2 -](\l) + +[1. 建模与设计工具： - 2 -](\l) + +[2. 架构技术选型： - 2 -](\l) + +[3.3 需求获取Requirement Elicitation - 3 -](\l) + +[1. 用户痛点挖掘与分析： - 3 -](\l) + +[2. 需求转化： - 3 -](\l) + +[3. 业务流程梳理——泳道图设计 - 3 -](\l) + +[3.4 需求分析Requirements Analysis - 5 -](\l) + +[3.4.1 功能分析概览 - 5 -](\l) + +[3.4.2核心用例详述 (Core Use Case Specifications) - 7 -](\l) + +[3.4.3核心对象生命周期分析 - 22 -](\l) + +[3.5 概要设计Architectural Design - 23 -](\l) + +[3.5.1 设计原则与目标 - 23 -](\l) + +[3.5.2 系统总体架构设计 - 24 -](\l) + +[3.5.3 关键技术选型与决策 - 24 -](\l) + +[3.5.4 功能模块与接口设计 - 25 -](\l) + +[3.5.5工程文件组织结构设计 - 27 -](\l) + +[3.6 详细设计Detailed Design - 29 -](\l) + +[3.6.1 详细设计工作概述 - 29 -](\l) + +[3.6.2 模块详细设计与建模 - 29 -](\l) + +[3.6.3关键数据表结构设计 - 33 -](\l) + +[3.6.4 交互原型设计 (UI/UX) - 35 -](\l) + +[4. 实训总结 Summary - 42 -](\l) + +[4.1 项目回顾与工作总结 - 42 -](\l) + +[4.2 遇到的挑战与解决方案 - 42 -](\l) + +[(1) 如何在高并发下实现精准的“每日连胜”计算？ - 42 -](\l) + +[(2) PBL 互评中如何防止“恶意差评”和“刷分”？ - 42 -](\l) + +[(3) 如何让风控系统既安全又不影响用户体验？ - 43 -](\l) + +[4.3 经验教训与感悟 - 43 -](\l) + +[4.4结语 - 44 -](\l) + +[5. 参考资料 References - 45 -](\l) + +# + +# 实训目的 Aim of Project + +本次实训聚焦于软件生命周期的前端阶段——需求分析与系统设计。旨在通过对“智慧课程学习平台”的完整设计过程，深入掌握复杂软件系统的建模方法与架构设计能力。实训的具体目的包括： + +掌握需求工程全流程方法论：通过模拟真实场景，实践从模糊的业务痛点出发，经历需求获取、分析、澄清到撰写标准需求规格说明书 (SRS) 的完整闭环。 + +提升复杂系统架构设计能力：基于领域驱动设计 (DDD) 思想，进行微服务架构的拆分与界限上下文划分，设计高可用、高并发的云原生系统蓝图。 + +强化详细设计与建模技能：熟练运用UML（统一建模语言）绘制类图、时序图、状态图等，能够进行精细化的数据库 Schema 设计与 API 接口定义，为后续开发提供无歧义的“施工图纸”。 + +培养规范化的工程文档素养：严格遵循国家标准或行业规范编写概要设计 (HLD) 与详细设计 (LLD) 文档，确保技术文档的完整性、一致性与可追溯性。 + +# 预习内容 Preview Content + +在项目启动前，我针对系统设计所需的理论知识与工具进行了深入预习，重点掌握了以下内容： + +领域驱动设计 (DDD)：深入研读了DD相关理论，理解了实体(Entity)、值对象(Value Object)、聚合及领域服务的概念，为业务模块的解耦与划分打下基础。 + +UML建模与设计模式：学习了常见设计模式（如策略模式、工厂模式、观察者模式），并熟练掌握了使用PlantUML和ProcessOn绘制标准UML图形的技巧。 + +微服务架构理论：学习Spring Cloud Alibaba生态组件Nacos,Sentinel,Gateway的架构原理与适用场景，以便在架构设计阶段做出正确的技术选型。 + +数据库设计规范：复习了数据库范式理论与反范式优化策略，重点研究了图数据库与时序数据/流数据在教育场景下的数据模型设计。 + +交互设计基础：了解了以用户为中心的设计 原则，学习了Axure/Figma等原型工具的使用，以便输出高质量的UI交互原型。 + +# 实训内容和实践过程 Project Content and Process + +## 3.1 概述Overview + +本次实训项目“智慧课程学习平台”旨在构建一个“以学生个性化学习为中心，教师智能推荐为辅助”的自适应教育生态。**作为核心系统分析师与架构设计人员，我主导了系统的全链路设计**。本系统的核心设计理念在于：**利用知识图谱与AI算法为学生生成个性化学习路径，同时通过多维能力画像赋能教师，使其能精准地进行个性化干预与资源推荐**。 工作重点在于将模糊的教育痛点转化为精确的工程模型，通过领域驱动设计方法划分微服务边界，并输出高保真的详细设计文档。具体工作如下： + +1. 需求工程：主导**用户访谈**，梳理业务流程。 + +2. 架构设计：负责M01至M05**所有模块**的技术架构决策与逻辑设计。 + +3. 详细设计：**主导**进行**核心模块的类结构设计**、**数据库建模、API接口定义及UI原型设计。** + +## 3.2 相关技术Relevant Technologies + +1. 建模与设计工具： + + 1. PlantUML / Draw.io：用于绘制用例图、类图、时序图、活动图及部署架构图。 + + 2. Figma / Axure：用于制作高保真用户界面 (UI) 原型与交互逻辑演示。 + + 3. MySQL Workbench / Neo4j Browser：用于设计关系型数据库E-R图与知识图谱数据模型。 + +2. 架构技术选型： + + 1. 微服务架构：设计基于Spring Cloud Alibaba的分布式架构，利用其服务治理能力应对理论上的高并发场景。 + + 2. 流计算架构：规划引入Apache Flink处理xAPI实时流数据，设计了“存算分离”的数据流转路径。 + + 3. 图计算技术：选用Neo4j作为知识图谱的存储方案，利用其图算法优势支持自适应路径规划。 + +## 3.3 需求获取Requirement Elicitation + +在需求获取阶段，我作为组长主导了从“用户痛点”到“技术需求”的转化过程。我通过场景分析法梳理PBL教学与系统安全两大核心领域的业务逻辑，并且，并承担了以下关键工作： + +1. 用户痛点挖掘与分析： + + 1. 场景模拟： + + 1. 针对“学生”角色（缺乏个性化）： 识别出传统教学“千人一面”的痛点。基础不同的学生被迫按同一线性路径学习，导致“学霸吃不饱，学渣吃不消”。学生急需基于自身能力画像的个性化学习路径。 + + 2. 针对“教师”角色（缺乏干预手段）： 识别出教师缺乏数据支撑，无法进行针对性辅导的痛点。教师需要系统自动识别“高阻断知识点”和“风险学生”，以便进行个性化资源推荐与干预。 + + 3. 针对“教务管理”角色： 识别出账号共享难管控的安全隐患，以及PBL项目中普遍存在的“搭便车”与“评分不公”痛点。针对PBL中普遍存在的“搭便车”与“评分不公”痛点，我通过调研实际教学场景，梳理出基于客观证据的评价需求。 + + 4. 针对教育平台面临的账号倒卖与异地代课风险，我组织了安全需求评审，确立了主动防御机制。 + +2. 需求转化： + + 1. 将“个性化学习”诉求转化为 FR-ADAPT-01 （自适应路径规划）需求，决定设计基于知识图谱的动态导航功能。确定引入M01自适应引擎与 M04 游戏化服务。 + + 2. 将“账号安全”诉求转化为 NF-SEC-01 （异地登录风控） 非功能需求，定义了“IP跳变触发MFA”的业务规则。 + + 3. 将模糊的“公平评价”转化为“多源数据交叉验证”需求。针对PBL项目“搭便车”现象，确立了M02 协作评价服务中的“Git 贡献度分析”与“方差仲裁”机制。 + + 4. 需求转化：将“系统安全”细化为“身份真实性校验”与“环境异常感知”两个维度。 + +3. 根据教研员反馈，定义了“课程健康度 (CHI）”指标，设计 M03 智慧教研智脑 以实现教学内容的自动诊断。 + +4. 业务流程梳理——泳道图设计 + +为了明确各子系统在需求执行中的职责边界，我绘制了“PBL协作评价全链路数据流泳道图”。该图详细描述了从代码提交触发 Webhook，到仲裁引擎计算方差，再到信誉分更新的完整闭环。 + +--- +> 📸 **[指令：请在此处上传图片 002]** +> 文件名: `Image_002.png` +--- + +图 1 协作评价全链路数据流泳道图 + +图1的设计详细规划了代码提交与互评打分两条数据流在仲裁引擎中的汇聚逻辑。 + +## 3.4 需求分析Requirements Analysis + +### 3.4.1 功能分析概览 + +在需求分析阶段，本人作为组长负责**统一认证、游戏化激励、风险教研、社交路由四大核心子系**统的逻辑建模。本阶段工作的重点是将业务需求转化为严谨的系统功能规格，明确数据流转规则与业务判断逻辑。 + +根据业务拆解，系统以“学生能力画像（涵盖认知、勤奋、协作、影响力、代码质量、创新性六大维度）”为数据基座，支撑起个性化推荐与教师干预两大核心业务。根据业务拆解，本人负责的功能模块清单如下（共计**26**个用例）： + +表 1 功能模块清单 + +| | | | | +|--------------|--------------|-----------------------------------------------------------------------------------------------|--------------------------------------| +| **子系统** | **模块名称** | **包含核心用例(UseCases)** | **核心逻辑点** | +| 统一认证 | 身份与安全 | 统一身份登录、SSO/社交登录、风险检测、MFA二次验证、会话心跳续期、角色切换、监控大屏 | 身份校验、多设备互踢、异常登录识别 | +| **游戏化** | 激励引擎 | **每日连胜检查**、火焰特效、积分补签、多维画像 | 连续性算法、积分扣减规则、画像合成 | +| **风险教研** | 质量监控 | **触发红色预警**、人工干预、课程健康度监控、教学事故工单、智能归因、资源热更新、A/B测试验证 | 行为数据聚合、阈值判定、版本对比逻辑 | +| **社交路由** | 互助匹配 | 注册在线状态、发起悬赏、智能路由匹配、消息推送、建立会话、评价与影响力结算、PBL互评、争议仲裁 | 匹配算法、加权打分、信誉分计算 | + +以下为我负责整体用例图： + +--- +> 📸 **[指令：请在此处上传图片 003]** +> 文件名: `Image_003.png` +--- + +图 2 整体用例情况 + +图2涵盖了我负责的**六大核心模块：用户中心、课程管理、学习中心、作业考试、互动社区、后台管理**。 + +## 3.4.2核心用例详述 (Core Use Case Specifications) + +为了确保系统逻辑的严密性，本报告选取其中**7个**逻辑最为复杂的核心用例进行详细规约说明。为了清晰地界定各子系统的功能边界及参与者权限，本人绘制了如下分模块用例图。图中明确了学生、教师及系统后台在不同业务场景下的交互范围。”以下为这7个核心用例的部分整体用例图： + +--- +> 📸 **[指令：请在此处上传图片 004]** +> 文件名: `Image_004.png` +--- + +图 3 部分用例整体用例图 + +图3涵盖了风险教研子系统、社交路由子系统、统一认证子系统、游戏化激励子系统的核心用例的用例情况。 + +1. **\[认证核心\]** 统一身份登录 (UC-AUTH-01) + +本用例是系统的安全门户，其核心逻辑不仅仅在于校验账号密码，更在于构建“事件驱动”的登录流程。分析中明确了登录过程必须包含“风险前置校验”环节，即在生成令牌前先判断环境安全；同时，登录成功被定义为一个全局触发事件，该事件将作为信号源，自动激活下游的“每日连胜计算”和“在线状态注册”模块，从而实现子系统间的逻辑解耦。 + +表 2 UC-AUTH-01 + +
项目内容描述
用例名称统一身份登录
用例编号UC-AUTH-01
主要参与者学生、教师、管理员、认证服务
前置条件用户已注册账号；网络连接正常。
后置条件客户端获取有效令牌(Token)；系统建立会话白名单；发布“用户已登录”事件。
基本事件流

1.用户在登录页输入账号和密码。

2.前端对密码进行加密预处理并发送请求。

3.系统验证凭证正确性（比对数据库中的加密密文）。

4.系统调用 UC-AUTH-03 （风险检测）评估当前登录环境。

5.若无风险，系统生成身份令牌（包含用户ID、角色、有效期）。

6.系统将令牌存入会话存储，并强制踢出超限设备（如限制单用户 3 设备）。

7.系统向消息中心发布“用户已登录”事件（含 IP、时间戳）。

8.系统返回令牌，前端跳转至仪表盘。

扩展事件流

若风险检测判定为高危（如异地登录）：

1.系统中断标准流程，转入 UC-AUTH-04 (MFA 二次验证）。

2.验证通过后，继续执行步骤 5。

若密码连续错误超过 5 次：

1.系统锁定该账号 15 分钟。

2.返回“账号已冻结”提示。

特殊需求登录接口响应需包含next_action字段，指示前端是否需要进行 MFA 或强制改密。
非功能需求关联安全性 NF-SEC-01（密码传输加密）；性能 NF-PER-02（登录响应 < 500ms）。
+ +--- +> 📸 **[指令：请在此处上传图片 005]** +> 文件名: `Image_005.png` +--- + +图 4 UC-AUTH-01 + +2. **\[风控核心\] 风险检测 (UC-AUTH-03)** + +本用例旨在建立一套基于规则的动态风控模型。分析中定义了系统如何通过对比“当前环境”与“历史画像”来识别异常。核心难点在于定义具体的判断规则：一是地理位置规则，通过计算移动速度（距离/时间差）来识别不可能的物理移动；二是设备指纹规则，通过识别浏览器特征来判断是否为陌生设备。该逻辑确保了系统能在无人工干预的情况下自动拦截可疑访问。 + +表 3 UC-AUTH-03 + +
项目内容描述
用例名称风险检测
用例编号UC-AUTH-03
主要参与者认证服务 （系统后台）
前置条件用户凭证已校验通过，但尚未签发 Token。
后置条件返回风险等级（低/中/高）及具体风险标签。
基本事件流

1.系统提取当前请求的 IP 地址，解析地理位置。

2.系统提取浏览器指纹（User-Agent + Canvas特征）。

3.系统查询缓存中该用户最近一次登录的 IP 和设备信息。

4.规则匹配：

－计算地理位置距离：若距离 > 100km且时间差 < 1h，标记为异地。

－比对设备指纹：若为全新设备，标记为新设备。

5.返回风险评估结果。

扩展事件流

若 IP 在黑名单库中：

直接返回“High Risk - Blocked”，阻断登录。

特殊需求IP 库需定期更新；指纹计算需在前端完成并加密传输。
非功能需求关联性能 NF-PER-03（风控计算延迟 < 100ms）。
+ +--- +> 📸 **[指令：请在此处上传图片 006]** +> 文件名: `Image_006.png` +--- + +图 5 UC-AUTH-03 + +3. **3.\[**逻辑核心\] 每日连胜检查 (UC-GAME-01) + +分析重点： 本用例的核心在于设计高效的连续性判定算法。分析中摒弃了传统的“查询所有历史记录”的方式，而是采用“只看昨天”的逻辑：即通过检查“昨天是否已签到”来决定今日是“连胜+1”还是“重置为1”。此外，分析中特别强调了时间维度的连续性处理，要求算法必须能够正确处理跨月（如1月31日到2月1日）和跨年（12月31日到1月1日）的特殊场景，保证激励机制的准确性。 + +表 4 UC-GAME-01 + +
项目内容描述
用例名称每日连胜检查
用例编号UC-GAME-01
主要参与者学生、激励引擎
前置条件监听到系统发布的“用户已登录”事件。
后置条件用户连胜天数更新，触发奖励发放。
基本事件流

1.激励引擎消费登录事件。

2.计算当前日期在年份中的索引 (Day of Year)。

3.读取用户的历史签到记录状态。

4.检查昨日状态： 判断“昨天”是否已签到。

5.连胜逻辑：

- 若昨日已签到：执行连胜计数 +1。

- 若昨日未签到：重置连胜计数为 1。

6.将“今日”的状态标记为已签到。

7.若连胜天数达到里程碑（如 3, 7, 30天），触发 UC-GAME-05 （勋章结算）。

扩展事件流

今日已登录过（重复事件）：

检测到今日状态已为签到，直接忽略，不执行计算。

特殊需求必须处理跨年场景的连胜计算（如1月1日需检查12月31日）。
非功能需求关联性能 NF-PER-05（事件处理吞吐量 > 5000TPS）。
+ +--- +> 📸 **[指令：请在此处上传图片 007]** +> 文件名: `Image_007.png` +--- + +图 6 UC-GAME-01 + +4. **\[监控模块核心\]** 触发红色预警 (UC-RISK-01) + +本用例定义了系统对学生学习状态的自动化诊断与**教师复制干预**逻辑。分析重点在于如何将离散的学习行为数据聚合为可度量的风险指标。设计采用了多维度阈值判定机制：一方面关注“活跃度”（是否长期缺勤），另一方面关注“掌握度”（做题正确率趋势）。该逻辑实现了从“事后诸葛亮”到“事前预警”的转变，确保教师能在学生挂科前收到通知并介入干预。 + +表 5 UC-RISK-01 + +
项目内容描述
用例名称触发红色预警
用例编号UC-RISK-01
主要参与者风险教研引擎
前置条件实时计算作业正在运行，持续消费学习行为流。
后置条件生成预警记录，推送到教师端待办列表。并为教师生成个性化干预建议（推荐习题/微课）。
基本事件流

1.数据聚合：引擎按用户维度聚合最近 7 天的行为数据。

2.规则判定：

－活跃度检测：连续 7 天无登录记录。

－掌握度检测：模型预测当前知识点掌握概率 < 60%。

3.若满足上述任一条件，系统标记该学生为“高危 (Red Risk)”。

4.写入预警记录表，记录触发原因代码。

5.通过消息通道向该生的辅导员/教师发送实时通知。并结合AI助教分析，向教师推送针对该学生的个性化补救资源建议（如推荐特定章节的强化训练），供教师一键推送。

扩展事件流

数据不足（冷启动）：

若学生为新生且行为数据稀疏，不触发预警，标记为“观察期”。

特殊需求预警算法需支持“防抖动”，避免同一天内重复报警。
非功能需求关联实时性NF-RTM-01（从行为发生到预警触发延迟 < 5分钟）。
+ +--- +> 📸 **[指令：请在此处上传图片 008]** +> 文件名: `Image_008.png` +--- + +5. 图 7 UC-RISK-01 + +6. **\[验证核心\]** 执行 A/B 测试验证 (UC-RISK-07) + +本用例描述了教学资源迭代的科学验证闭环。分析中引入了互联网产品常用的 A/B 测试思想，定义了如何通过流量分流和数据对比来客观评价新旧版本资源的优劣。核心逻辑在于“控制变量法”：确保在同一时间段内，不同组别的学生分别使用不同版本的资源，并通过对比“健康度分数 (CHI)”这一量化指标来决定是否进行全量发布，从而避免盲目更新导致的教学质量下降。 + +表 6 UC-RISK-07 + +
用例名称执行 A/B 测试验证
用例编号UC-RISK-07
主要参与者风险教研引擎
前置条件资源存在 v1.0 (旧) 和 v1.1 (新) 两个版本。
后置条件确定新版本是否胜出，并执行全量发布或回滚。
基本事件流

1.系统配置流量分配策略：10%学生访问 v1.1，90% 访问 v1.0。

2.持续运行 48 小时，分别收集两组的 CHI (健康度) 数据。

3.效果对比：

- 若 v1.1 的 CHI 显著高于 v1.0（提升 > 5%）：判定胜出。

- 否则：判定失败。

4.胜出：系统自动将流量切换为 100% v1.1。

5.失败：系统自动回滚至 v1.0，并通知教师“迭代无效”。

扩展事件流

样本量不足：

若不足以产生统计显著性，延长测试时间或扩大流量比例至 30%。

特殊需求同一学生在测试期间必须始终看到同一个版本（会话粘滞）。
非功能需求关联可测试性 NF-TST-01（支持灰度路由）。
+ +--- +> 📸 **[指令：请在此处上传图片 009]** +> 文件名: `Image_009.png` +--- + +图 8 UC-RISK-07 + +7. \[算法核心\] 智能路由匹配 (UC-SOC-03) + +本用例是社交子系统的核心，旨在解决“谁来回答问题”的资源分配难题。分析中借鉴了网约车派单模式，设计了一套多因子加权匹配算法。系统不再是随机分配，而是综合考量了候选人的“能力”（知识点掌握度）、“意愿”（历史响应速度）和“信誉”（影响力分数）。通过加权公式计算匹配分，确保求助请求能被最合适、最快响应的“学霸”接单，从而提高互助成功率。 + +表 7 UC-SOC-03 + +
项目内容描述
用例名称智能路由匹配
用例编号UC-SOC-03
主要参与者路由引擎
前置条件收到求助请求；在线用户池不为空。
后置条件锁定最佳候选人列表。
基本事件流

1.筛选候选人：

－在线：在在线用户池中。

－能力：已点亮该知识点节点。

－角色：排除求助者自己。

2.计算匹配分 (Score)：

Score =影响力 * 0.5 + 响应速度 * 0.3 + 知识掌握度 * 0.2。

3.按 Score 降序排列，生成候选队列。

4.将请求发送给队列首位的候选人。

扩展事件流

无合格候选人在线：

1.将请求转入异步论坛发帖模式。

2.通知求助者“暂无学霸在线，已转论坛”。

特殊需求避免路由给刚刚拒绝过求助的用户。
非功能需求关联效率 NF-EFF-01（匹配计算耗时 < 500ms）。
+ +--- +> 📸 **[指令：请在此处上传图片 010]** +> 文件名: `Image_010.png` +--- + +图 9 UC-SOC-03 + +8. **\[闭环核心\]** 评价与影响力结算 (UC-SOC-06) + +本用例构建了社交互助的价值闭环。分析重点在于如何通过积分和信誉机制来激励用户持续参与互助。逻辑设计上包含两层结算：一是显性收益（积分转移），完成即时奖励；二是隐性收益（影响力提升），通过累积信誉来提升用户在未来匹配中的权重。同时，分析中加入了防作弊逻辑，通过检测频繁互评行为来维护评价体系的公平性。 + +表 8 UC-SOC-06 + +
项目内容描述
用例名称评价与影响力结算
用例编号UC-SOC-06
主要参与者学生 (求助者)、路由引擎
前置条件互助会话结束。
后置条件积分转移，影响力分更新。
基本事件流

1.求助者对解答质量进行评分（1-5星）和标签（如“耐心”“大牛”）。

2.结算：解冻积分，转入互助者账户。

3.若评分为 5 星，额外奖励系统积分。

4.更新画像：

- 重新计算互助者的影响力 (Influence)。

- Influence = 旧值 + (评分 * 权重)。

5.若影响力升级，触发勋章颁发。

扩展事件流

求助者恶意差评（如1星无理由）：

互助者可申诉，进入UC-SOC-08 (争议仲裁)流程。

特殊需求评分需去除“互刷”嫌疑（如同两人频繁互评）。
非功能需求关联公平性 NF-FAI-01。
+ +--- +> 📸 **[指令：请在此处上传图片 011]** +> 文件名: `Image_011.png` +--- + +## 图 10 UC-SOC-06 + +## 3.4.3核心对象生命周期分析 + +在社交路由子系统中，“互助求助单”是业务流转的核心载体。为了确保业务逻辑的严密性，本人对其全生命周期的状态流转进行了建模（见图11），明确定义了从创建、匹配、进行中到结算的完整状态变迁逻辑。 + +--- +> 📸 **[指令：请在此处上传图片 012]** +> 文件名: `Image_012.png` +--- + +图 11 互助求助单状态机图 + +1. **初始阶段：发起与匹配** + +流程始于学生发起求助请求，系统进入**\[待匹配\]**状态。 + +1. 内部处理：在**\[待匹配\]**状态内部，系统会进行“轮询下一位候选人”的循环操作，不断寻找合适的接单者。 + +2. 分支路径： + + 1. 锁定候选人：如果找到合适的人选，系统将该候选人锁定，状态流转至**\[待响应\]**。 + + 2. 求助者取消：如果求助者在匹配过程中主动取消，状态直接流转至**\[已取消\]**，流程结束。 + + 3. 无人接单：如果长时间无人接单导致超时，状态流转至\[论坛模式\]（可能意味着转为帖子留言形式），流程结束。 + + + +2. **握手阶段：候选人响应** + +当系统进入**\[待响应\]**状态后，取决于被锁定候选人的操作： + +1. 接受：候选人确认接单，状态流转至**\[进行中\]**，辅导正式开始。 + +2. 拒绝或超时：如果候选人拒绝接单或者响应超时，状态回退至 \[待匹配\]，系统将重新开始轮询寻找下一位候选人。 + + + +3. **进行阶段：辅导会话** + +在**\[进行中\]**状态下，双方进行沟通或辅导。 + +1. 会话结束：当辅导结束时，状态流转至**\[待结算\]**。 + + + +4. 结算与仲裁阶段 + +在**\[待结算\]**状态下，系统等待双方的处理结果： + +1. 正常流程：双方完成评分，状态流转至**\[已完成\]**，流程结束。 + +2. 异常流程（仲裁）：如果出现“恶意差评”，状态流转至\[仲裁中\]。 + +3. 助教裁决：在仲裁状态下，经由助教介入裁决后，状态最终也会流转至**\[已完成\]**，流程结束。 + +## 3.5 概要设计Architectural Design + +对概要设计过程中本人承担的主要工作内容进行介绍； + +### 3.5.1 设计原则与目标 + +本系统的概要设计严格遵循“以业务价值为导向，以技术架构为基石”的原则。在设计过程中，我们确立了以下核心设计思想，以确保系统能够支撑“双螺旋自进化生态”的复杂业务需求： + +1. **领域驱动设计 (DDD)**：将系统严格划分为自适应学习、智慧教研、协作评价、社交互动、统一认证五个界限上下文。各模块间通过领域事件交互，严禁跨库查询，确保高内聚、低耦合。 + +2. **事件驱动架构 (EDA)**：核心业务逻辑异步化。例如，“学生登录”不直接调用各子系统，而是发布事件，由下游服务订阅消费，以此提升系统的扩展性和吞吐量。 + +3. **存算分离与多模态存储**：针对不同类型的数据特征采用最适配的存储方案（如关系型数据用 MySQL，图数据用 Neo4j，热数据用 Redis），打破单一数据库的性能瓶颈。 + +## 3.5.2 系统总体架构设计 + +本系统基于云原生 (Cloud Native) 理念构建，逻辑架构呈现清晰的“漏斗型”数据价值链，自下而上划分为四层： + +1. **接入与边缘层**：负责流量清洗、TLS 卸载及身份鉴权，作为系统的安全防线。 + +2. **业务服务层**：由一组无状态微服务组成（如PBL服务、社交服务），负责具体的业务编排。 + +3. **数据与智能中枢**：分为处理毫秒级任务的“热路径”（Redis/流计算）和处理离线训练任务的“冷路径”（大数据分析）。 + +4. **基础设施层**：提供持久化存储及算力资源支持。 + +## 3.5.3 关键技术选型与决策 + +为了满足高并发、低延迟及复杂关系查询的需求，本系统进行了如下关键技术选型： + +表 9 关键技术选型与决策 + +| | | | +|----------------|----------------------|---------------------------------------------------------------------------------------------------| +| **组件类别** | **选型方案** | **选型决策理由** | +| **服务网关** | Spring Cloud Gateway | 集成 Sentinel 实现毫秒级限流，作为零信任架构的边界，支持动态路由以配合 A/B 测试。 | +| **核心数据库** | MySQL 8.0 | 存储用户、订单、评分等强事务数据。选用 8.0 版本利用其 JSON 特性优化非结构化数据存储。 | +| **缓存/状态** | Redis Cluster | 存储全校学生的 Bitmap（每日连胜）和 Hash（实时画像），Cluster 模式支持自动分片，满足高并发读写。 | +| **图数据库** | Neo4j | 存储课程知识图谱。利用其免索引邻接特性，在多跳查询（如查找前驱知识点）场景下比SQL快2～3个数量级。 | +| **消息队列** | Apache Kafka | 用于xAPI行为流的削峰填谷，解耦上游业务与下游计算，保障高吞吐量。 | +| **流计算** | Apache Flink | 用于实时计算 CHI 指数和迷茫状态，确保乱序数据下的计算准确性。 | + +## 3.5.4 功能模块与接口设计 + +根据需求分析，系统被拆解为M01-M05五大核心模块。以下针对本人重点关注的教研、社交、认证模块进行接口设计说明。 + +**3.5.4.1 \[M03\] 智慧教研智脑模块** + +本模块负责实时监控课程资产健康度 (CHI) 并管理资源热更新。 + +关键接口定义： + +表 10 获取课程资产健康度接口 + +| | | +|----------|-------------------------------------------------------------------------| +| 接口名称 | 获取课程资产健康度 | +| 接口地址 | GET /api/v1/research/dashboard/health/{courseId} | +| 功能描述 | 聚合查询课程的实时 CHI 指数、趋势以及 Top N 问题节点列表。 | +| 请求参数 | courseId(路径参数): 课程唯一标识。 | +| 返回数据 | { "currentChiScore": 85.5, "trend": "DOWN", "unhealthyNodes": \[...\] } | + +表 11 发布资源热更新接口 + +| | | +|----------|----------------------------------------------------------------------------------| +| 接口名称 | 发布资源热更新 | +| 接口地址 | POST /api/v1/research/resources/publish | +| 功能描述 | 针对有问题的知识点发布新版资源，支持灰度发布策略。 | +| 请求参数 | ticketId(工单ID),newResourceUrl(新资源地址),grayScale(灰度比例 0-100)。 | +| 返回数据 | { "versionId": "v1.2", "publishStatus": "GRAY\_RELEASE", "monitorJobId": "..." } | + +**3.5.4.2 \[M04\] 游戏化与社交服务模块** + +本模块利用Redis原子操作实现连胜计算，并基于影响力分值实现实时路由匹配。 + +关键接口定义： + +表 12 **获取个人游戏化档案接口** + +| | | +|--------------|--------------------------------------------------------------------------------------| +| **接口名称** | **获取个人游戏化档案** | +| 接口地址 | GET /api/v1/social/gamification/me | +| 功能描述 | 读取 Redis 热数据，获取用户当前的连胜天数、勋章及积分状态。 | +| 返回数据 | { "uid": "1001", "streak": { "days": 5 }, "badges": \["勤奋勋章"\], "points": 1200 } | + +表 13 即时互助匹配接口 + +| | | +|----------|----------------------------------------------------------------------------| +| 接口名称 | 即时互助匹配 | +| 接口地址 | POST /api/v1/social/match/request | +| 功能描述 | 发起求助请求，系统在后台基于算法匹配最合适的互助对象。 | +| 请求参数 | knowledgeNodeId(知识点ID),bounty(悬赏积分),problemDesc(问题描述)。 | +| 返回数据 | { "requestId": "REQ\_001", "status": "MATCHING", "estimatedWaitTime": 15 } | + +**3.5.4.3 \[M05\] 统一认证与风控模块** + +本模块是系统的安全基座，内置风控引擎识别异常行为。 + +关键接口定义： + +表 14 统一登录接口 + +| | | +|----------|--------------------------------------------------------------| +| 接口名称 | 统一登录 (含风控) | +| 接口地址 | POST /api/v1/auth/login | +| 功能描述 | 校验账号密码，并同步进行设备指纹与异地登录检测。 | +| 请求参数 | username,password(加密),deviceFingerprint(设备指纹)。 | +| 返回数据 | { "status": "SUCCESS", "token": "eyJhbG...", "user": {...} } | + +表 15 MFA二次验证接口 + +| | | +|----------|----------------------------------------------------------| +| 接口名称 | MFA 二次验证 | +| 接口地址 | POST /api/v1/auth/mfa/verify | +| 功能描述 | 当登录触发风控（如异地登录）时，提交验证码进行二次核验。 | +| 请求参数 | tempToken(临时令牌),code(验证码),type(SMS/TOTP)。 | +| 返回数据 | { "status": "VERIFIED", "finalToken": "..." } | + +## 3.5.5工程文件组织结构设计 + +本项目采用Monorepo单体仓库结构管理微服务，结合Maven Modules进行构建。这种结构有利于统一依赖管理、代码规范以及CI/CD流程的标准化。 + +smart-course-platform/ + +├── docs/ 项目全量文档(SRS, SD, API) + +├── frontend/ 前端工程 + +│ ├── web-student/ 学生端(Vue3 + TS) + +│ └── web-admin/ 教研/管理后台(React + AntD) + +├── backend/ 后端微服务工程Spring Cloud + +│ ├── pom.xml 父工程依赖管理 + +│ ├── scp-gateway/ \[Infrastructure\] API 网关 + +│ ├── scp-auth/ \[M05\] 认证中心 + +│ ├── scp-adaptive/ \[M01\] 自适应学习引擎 + +│ ├── scp-pbl/ \[M02\] PBL 评价服务 + +│ ├── scp-social/ \[M04\] 社交服务 + +│ └── scp-common/ 公共模块 (Utils, DTOs) + +├── data-engine/ 大数据与 AI 工程 + +│ ├── flink-jobs/ Flink 实时计算任务 + +│ └── ai-services/ AI 推理服务 (Python) + +└── deploy/ 基础设施与部署 + +├── k8s/ Kubernetes Helm Charts + +└── docker/ Dockerfile 定义 + +## 3.6 详细设计Detailed Design + +## 3.6.1 详细设计工作概述 + +在详细设计阶段，本人主要承担了**自适应学习引擎(M01)、协作评价服务 (M02) 以及 统一认证与风控(M05)三大核心模块**的详细设计工作。工作内容涵盖了模块内部的类结构设计、对象交互时序逻辑定义、数据库Schema设计以及前端交互原型的构建。 + +本阶段的设计目标是将概要设计中的逻辑架构转化为可直接编码的物理模型，明确每个类的方法签名、属性定义及异常处理机制。 + +## 3.6.2 模块详细设计与建模 + +**3.6.2.1 \[M01\] 自适应学习引擎详细设计** + +本模块是系统的核心“大脑”，负责基于知识图谱和DKT模型动态规划学习路径。 + +1. 交互逻辑设计(Sequence Diagram) + + 场景描述：当学生进入课程学习页面时，前端会发起获取当前最佳学习路径的请求。系统首先会对用户的会话状态进行校验，确认其合法性。随后，PathPlanningService 作为一个编排者，会并行发起两个关键调用： + + 首先，它向 Redis 缓存查询用户当前的“游标位置”（即上次学到的知识点 ID），并基于此 ID 向知识图谱服务请求该节点的后继拓扑结构，获取一组潜在的“候选学习节点”。 + + 紧接着，为了判断学生是否真正掌握了这些候选节点，服务会将用户的历史答题序列和候选节点 ID 打包，发送给DKT推理客户端 (DKTInferenceClient)。该客户端会调用部署在 TensorFlow Serving 上的深度学习模型，预测学生对每个候选节点的掌握概率。 + + 最后，PathPlanningService依据策略模式对返回的概率进行判定：若某节点的掌握概率低于阈值（如0.8），系统将其状态标记为REMEDY（需补救），并自动插入一段**个性化推荐的微课视频**作为前置任务；若高于阈值，则标记为UNLOCKED（已解锁）。最终，这一整套包含状态标记的个性化路径树被组装成PathVO对象返回给前端进行渲染。 + +--- +> 📸 **[指令：请在此处上传图片 013]** +> 文件名: `Image_013.png` +--- + +图 12 **自适应学习引擎详细设计**时序图 + +2. 核心类设计 + + 1. PathPlanningService:核心业务服务类。 + + **职责：**负责路径生成的全流程编排，实现了策略模式以支持不同的推荐算法（如“激进型”或“稳健型”）。 + + **核心方法：**generatePath(String courseId, String userId)—— 该方法内部包含了异常熔断逻辑，当 AI 服务超时时，会自动降级为基于规则的推荐策略。 + + 2. DKTInferenceClient:AI 服务适配器类。 + + **职责：**封装与 AI 推理服务的 HTTP 通信细节，处理张量数据的序列化与反序列化。 + + **核心方法：**predict(String userId, List<String> nodeIds)—— 返回一个 Map，键为知识点 ID，值为 0.0-1.0 之间的掌握概率。 + +## 3.6.2.2 \[M02\] 协作评价(PBL)服务详细设计 + +本模块负责处理非标化作业的评价，核心在于 Git 贡献度分析与互评仲裁。 + +1. 交互逻辑设计(Sequence Diagram) + + 场景描述：在PBL项目互评阶段，学生提交对同组其他成员代码作业的评分及评语。请求到达后端后，ReviewService 首先将原始评价数据持久化到数据库，确保数据不丢失。 + + 随后，为了保证评分的公正性，系统立即触发 仲裁服务 (ArbitrationService)的介入。该服务会拉取针对该作业的所有历史评分记录，并执行方差计算算法。 + + 系统设定了一个动态阈值（例如方差>15.0），一旦计算结果超过该阈值，说明评分存在极大的两极分化（即存在争议）。此时，系统会执行一系列连锁反应：首先将该作业的最终成绩标记为“冻结”状态；其次，在 arbitration\_tasks 表中生成一条待处理的仲裁工单；最后，通过消息队列发布 ArbitrationTriggered 事件，实时通知教研端的助教介入人工复核。若方差在正常范围内，系统则按照加权平均公式自动计算最终得分并发布。 + +--- +> 📸 **[指令：请在此处上传图片 014]** +> 文件名: `Image_014.png` +--- + +图 13 协作评价(PBL)服务详细设计时序图 + +2.核心类设计 (Class Design) + +1. ContributionAnalysisService:代码贡献度分析服务。 + +职责：监听GitLab Webhook事件，解析 Commit 日志，基于代码行数增删量和提交频率计算“个人贡献因子”。 + +核心方法：calculateFactor(Long projectId, Long userId)—— 该方法包含防作弊逻辑，会自动降权那些在 DDL 前一小时突击提交的大量代码。 + +2. ArbitrationService:争议仲裁引擎。 + +职责：负责评分数据的统计分析，识别恶意差评或刷分行为。 + +核心方法：checkControversy(Long submissionId)—— 计算评分方差，返回布尔值指示是否触发仲裁。 + +## 3.6.2.3 \[M05\] 统一认证与风控详细设计 + +本模块是系统的安全基座，集成SSO、RBAC与动态风控。 + +1. 交互逻辑设计 (Sequence Diagram) + + 场景描述： 用户在前端输入账号密码点击登录后，请求首先经过 API 网关的限流清洗，到达 AuthController。在验证账号密码正确性之前，系统会先启动 风控引擎 (RiskControlEngine) 进行环境评估。 + + 风控引擎首先从数据库中读取该用户上一次成功登录的快照信息（包含 IP、时间、设备指纹）。然后，它调用 GeoIPService 计算本次登录 IP 与上次登录 IP 之间的物理距离，并结合时间差计算“移动速度”。 + + 如果计算出的移动速度超过了物理极限（例如 800km/h，即“超音速移动”），或者设备指纹完全陌生，风控引擎将返回 NEED\_MFA 状态。 + + 此时，认证服务不会颁发正式的 JWT 令牌，而是返回一个临时的、权限受限的 TempToken，并向前端抛出 403 状态码，指示客户端弹出 MFA 二次验证窗口（如短信验证码或 TOTP）。只有当用户通过了二次验证，系统才会颁发正式的访问令牌。 + +--- +> 📸 **[指令：请在此处上传图片 015]** +> 文件名: `Image_015.png` +--- + +图 14 统一认证与风控详细设计时序图 + +2.核心类设计(Class Design) + +1. RiskControlEngine:风险控制核心引擎。 + +职责：聚合多种风险因子（地理位置、设备指纹、登录频率），计算综合风险分值。 + +核心方法：assessRisk(AuthContext ctx)——内部实现了规则链模式，依次执行各项检查，一旦命中黑名单直接阻断。 + +2. GeoIPService:地理位置服务。 + +职责：将IP地址解析为经纬度坐标，并计算两点间的球面距离（Haversine公式）。 + +## 3.6.3关键数据表结构设计 + +为了支撑上述复杂的业务逻辑，本人设计了以下关键数据表，详细定义了字段类型、约束及设计意图： + +--- +> 📸 **[指令：请在此处上传图片 016]** +> 文件名: `Image_016.png` +--- + +图 15 ER图 + +以下为对该关键数据表的详细解释与描述： + +1. 学情画像表(learner\_profiles) + +该表用于存储学生的多维能力数据，是自适应推荐和教师干预的基础。 + +1. user\_id(BIGINT, PK/FK):关联用户主表，作为主键，确保一对一关系。 + +2. capability\_radar (JSON, NN):核心字段，存储认知能力、勤奋度、协作能力、影响力、代码质量、创新性 六大维度的量化数据。该数据是系统进行个性化路径推荐和教师进行干预决策的根本依据。 + +3. influence\_score (INT, Default 0):社交影响力分，用于互助匹配时的权重计算。 + +4. current\_streak (INT, Default 0):当前连胜天数，用于游戏化激励计算。 + +5. reputation\_score (DECIMAL(5,2), Default 100.00):评阅信誉分，用于 PBL 互评时的加权计算。 + + + +2. PBL提交记录表 (submissions) + +该表记录学生在项目式学习中的作业提交及评价状态。 + +1. submission\_id (BIGINT, PK):唯一标识。 + +2. project\_id (BIGINT, FK):关联的项目ID。 + +3. submitter\_id (BIGINT, FK):提交者ID。 + +4. contribution\_factor (DECIMAL(3,2)):个人贡献因子（0.0-1.0），由 Git 分析服务自动计算填入。 + +5. final\_score (DECIMAL(5,2)):最终加权得分，该字段在仲裁期间会被锁定。 + +6. is\_frozen (BOOLEAN, Default 0):冻结标记，当触发仲裁时置为 1，防止成绩被意外发布。 + + + +3. 仲裁任务表 (arbitration\_tasks) + +该表用于管理由系统自动触发的争议评分处理任务。 + +1. task\_id (BIGINT, PK):任务唯一标识。 + +2. submission\_id (BIGINT, FK):关联的争议作业 ID。 + +3. variance\_val (DECIMAL(5,2), NN):触发仲裁时的方差值，用于后续审计分析争议程度。 + +4. status (VARCHAR(20), NN):任务状态（PENDING-待处理, RESOLVED-已解决, IGNORED-已忽略）。 + +5. create\_time (DATETIME):任务创建时间，用于 SLA 超时监控。 + + + +4. 系统审计日志表 (audit\_logs) + +该表用于记录所有敏感操作，满足安全合规性要求。 + +1. log\_id (BIGINT, PK):日志流水号。 + +2. operator\_id (BIGINT, FK):操作人 ID（可能是管理员，也可能是系统自动任务）。 + +3. action\_type (VARCHAR(50),NN):操作类型枚举（如 LOGIN\_RISK, UPDATE\_SCORE, BAN\_USER）。 + +4. target\_id (VARCHAR(64)):被操作对象的ID（如被封禁的用户ID）。 + +5. ip\_address (VARCHAR(45), NN):操作源IP，支持IPv6。 + +6. details (JSON):存储操作前后的数据快照，便于回滚和追溯。 + +## 3.6.4 交互原型设计 (UI/UX) + +基于“沉浸式学习”与“数据可视化驱动”的设计理念，本人设计了以下核心界面原型，并对其交互细节进行了深度定义： + +#### UI-01 统一身份认证页 + +视觉风格：页面背景采用深蓝色的动态粒子网格效果，寓意“数据连接”。登录框位于屏幕中央，采用半透明磨砂玻璃（Glassmorphism）质感，提升科技感。 + +交互细节： + +1. 输入反馈：当用户输入密码时，若长度不足 8 位，输入框边框会实时变红并显示提示，无需点击提交即可获得反馈。 + +2. MFA阻断：当后端返回“异地登录”风险时，屏幕背景会平滑变暗（Dimmed），中央弹出一个模态对话框，提示“检测到异常环境，请输入手机尾号 8899 收到的验证码”。验证码输入框支持自动聚焦下一位（Auto-tab），提升输入体验。 + +3. 加载状态：点击登录按钮后，按钮文字变为“认证中...”，并显示旋转的 Loading Spinner，防止用户重复点击。 + +--- +> 📸 **[指令：请在此处上传图片 017]** +> 文件名: `Image_017.png` +--- + +图 16 统一身份认证页-登录台 + +--- +> 📸 **[指令：请在此处上传图片 018]** +> 文件名: `Image_018.png` +--- + +图 17 统一身份认证页-MFA安全验证 + +#### UI-02 学生沉浸式工作台 + +视觉风格：这是一个聚合了学生核心数据的 Dashboard。顶部导航栏右侧展示用户的头像、积分余额以及一个动态燃烧的火焰图标（代表连胜天数）。 + +交互细节： + +1. 雷达图动画：页面左侧的能力画像”雷达图在加载时，个性化推荐的“大脑”。直观展示学生在认知、勤奋、协作等六大维度的强弱项。会从中心点向外扩散展开（Scale-up动画），数据点之间会有连线动画，增强视觉冲击力。 + +2. 连胜激励：当鼠标悬停在顶部的火焰图标上时，火焰燃烧动画会加速，并弹出一个 Tooltip 提示：“再坚持学习 3 天，即可获得‘持之以恒’勋章”，利用微交互增强用户的成就感。 + +3. 任务完成：右侧的待办任务列表支持直接勾选。当用户点击 Checkbox 完成任务时，该任务项会产生“中间划线 + 透明度降低 + 向右滑动消失”的组合动画，同时顶部的积分数字会产生滚动增加的特效（Ticker Effect）。 + +--- +> 📸 **[指令：请在此处上传图片 019]** +> 文件名: `Image_019.png` +--- + +图 18 学生工作台 + +#### UI-06 智慧教研监控大屏 + +视觉风格：专为教师设计的数据可视化大屏。核心区域是一个巨大的仪表盘，显示当前的CHI (课程健康度)分数。 + +交互细节： + +1. 仪表盘入场：页面加载时，仪表盘的指针会从 0 刻度缓慢旋转至当前分值（如 58 分），背景色会根据分值从绿色渐变为红色（预警状态），直观传达紧迫感。 + +2. 下钻分析：左侧列出了“高阻断知识点 Top5”。当教师点击某一行（如“动态规划”）时，该行会向下展开（Accordion效果），显示由LLM生成的归因报告。报告文字不是一次性显示，而是采用“打字机效果”逐行输出，模拟AI正在实时分析的过程，提升可读性和科技感。 + +个性化干预学生信息： + +--- +> 📸 **[指令：请在此处上传图片 020]** +> 文件名: `Image_020.png` +--- + +图 19 智慧教研监控大屏 + +--- +> 📸 **[指令：请在此处上传图片 021]** +> 文件名: `Image_021.png` +--- + +图 20 学情预警与干预中心 + +#### UI-07 社交互助呼叫弹窗 + +视觉风格：模仿网约车呼叫界面的设计。弹窗中央是一个雷达扫描动画，背景有波纹扩散效果。 + +交互细节： + +1. 匹配过程：在匹配过程中，雷达扫描线持续转动，文字提示“正在为您寻找最匹配的学霸...”。 + +2. 成功反馈：一旦匹配成功，弹窗会瞬间翻转（Flip 3D 动画），背面显示对方的头像、昵称及擅长标签（如“算法大神”）。 + +3. 倒计时机制：“进入协作”按钮上会显示 15 秒倒计时。若倒计时结束用户仍未操作，弹窗会自动关闭并取消匹配，防止无效占用资源。 + +4. AI 诊断模块：支持代码段的实时语法检测，并给出高置信度（如 99.8%）的诊断报告。底部设有“一键修复并运行”的显著按钮，强调高效解决基础逻辑错误。 + +5. Peer 互助模块：明确展示匹配逻辑（如：系统筛选“算法能力 Top 10%”且当前“在线空闲”的同学），增加用户信任感。显示呼叫者与被呼叫者的匹配度（如 98%）及技能标签（如“技能互补”），并标注预计等待时间。 + +6. 激励与资源机制：呼叫需消耗一定积分（如 5 积分），顶部实时显示用户的“贡献分”与“社区活跃度”，鼓励用户通过帮助他人获取积分。提供“预约时间”与“立即呼叫”两个入口，灵活处理非即时性的深度交流需求。 + +--- +> 📸 **[指令：请在此处上传图片 022]** +> 文件名: `Image_022.png` +--- + +图 21 社交互助呼叫弹窗-呼叫中 + +--- +> 📸 **[指令：请在此处上传图片 023]** +> 文件名: `Image_023.png` +--- + +图 22 社交互助呼叫弹窗-匹配成功 + +--- +> 📸 **[指令：请在此处上传图片 024]** +> 文件名: `Image_024.png` +--- + +图 23 混合智能互助中心 + +#### UI-08 教师教学工作台 + +视觉风格：该界面采用“信息聚合”布局，旨在让教师一眼掌握班级整体学情。整体色调以清爽的白色和浅灰色为主，辅以不同颜色的状态标签（绿色-正常，红色-预警，黄色-待处理），确保信息层级分明，减少视觉干扰。 + +交互细节： + +1. 核心指标卡片：顶部横向排列四个关键指标卡（活跃学生数、待批改作业、班级平均分、学业预警数）。当鼠标悬停在“学业预警数”卡片上时，卡片会有轻微的上浮阴影效果（Elevation），并显示具体的预警类型分布（如：缺勤3人，成绩下滑5人）。 + +2. 图表联动筛选：页面左侧展示“期中考试成绩分布”柱状图。当教师点击图表中代表“<60分”的红色柱体时，系统会自动触发筛选逻辑，右侧的学生名单列表会立即刷新，仅展示该分数段的学生信息，方便教师进行针对性辅导。 + +3. 快捷操作栏：在每个风险学生的列表项右侧，提供了一组隐藏的快捷操作按钮（推送个性化任务、发送邮件、预约面谈）。只有当鼠标悬停在该行时，这些按钮才会显现（Hover Reveal），既保持了界面的整洁，又保证了操作的便捷性。教师可点击“推送个性化任务”，系统会自动根据该生的薄弱点推荐相关微课或习题，教师确认后即可一键发送。 + +4. 红点导航：左侧导航栏中的“作业批改”选项旁会实时显示红点数字徽标（Badge），提示当前有多少份新提交的作业等待批阅，点击后红点自动消除。 + +--- +> 📸 **[指令：请在此处上传图片 025]** +> 文件名: `Image_025.png` +--- + +图 24 教师教学工作台 + +#### UI-09 系统管理员控制台 + +视觉风格：作为系统的“驾驶舱”，该界面采用深色模式（Dark Mode）设计，背景为深灰蓝，数据图表采用高亮荧光色（青色、紫色），营造出极强的科技感和监控感，适合长时间挂在大屏上显示。 + +交互细节： + +1. 实时流量监控：页面中部的折线图展示HTTP与WebSocket的实时流量趋势。该图表采用WebSocket推送数据，每5秒自动向左平移更新一次（Real-time Streaming），无需管理员手动刷新页面，线条采用平滑曲线（Spline）绘制，视觉体验流畅。 + +2. 服务健康脉冲：页面右侧列表展示各微服务（Auth Service, Course Service, AI Node）的健康状态。状态指示灯带有“呼吸灯”效果——绿色代表服务健康，呼吸节奏平稳；红色代表服务故障或高延迟，呼吸节奏急促闪烁，利用动态视觉强力吸引管理员注意。 + +3. 审计日志透视：底部展示敏感操作审计日志。点击某一条日志（如“修改成绩”），会从右侧滑出一个抽屉面板（Drawer），展示该操作前后的数据快照对比（Diff View），变更字段会以高亮背景色标出，方便管理员快速追溯问题。 + +4. 一键熔断：在每个服务卡片的右上角提供了一个带警示色的“熔断”开关。点击开关时，会弹出一个需要二次确认的模态框（输入管理员密码），防止误操作导致服务停摆。 + +--- +> 📸 **[指令：请在此处上传图片 026]** +> 文件名: `Image_026.png` +--- + +图 25 系统管理员控制台 + +### 实训总结 Summary + +## 4.1 项目回顾与工作总结 + +本次实训中，我深度参与了“智慧课程学习平台”的全生命周期设计，重点承担了需求分析、概要设计以及详细设计的核心工作。 + +在需求分析阶段，我跳出了传统的“增删改查”思维，负责了统一认证、游戏化激励、风险教研、社交路由四大核心子系统的逻辑建模。我通过绘制用例图和活动图，清晰定义了系统如何利用事件驱动机制将“学生登录”这一简单动作转化为触发全系统联动的信号源。 + +在设计阶段，我主导了自适应学习引擎 (M01) 和 协作评价服务 (M02)以及登录认证(M05)的详细设计。面对“如何实时计算每日连胜”和“如何公正处理互评争议”等业务难题，我没有停留在概念层面，而是深入到了数据结构和算法的设计——利用Redis Bitmap设计了千万级用户的高效签到统计，利用方差分析算法构建了自动化的评分仲裁机制。这些工作让我深刻体会到，优秀的软件设计不仅仅是画图，更是对业务逻辑的精准抽象和对技术边界的合理把控。 + +## 4.2 遇到的挑战与解决方案 + +在项目推进过程中，我遇到了多个棘手的技术与逻辑挑战，这些问题的解决过程也是我成长最快的时刻： + +1. 如何在高并发下实现精准的“每日连胜”计算？ + +问题描述：最初设计时，我打算在数据库中存储每一条签到记录，然后通过 SQLCOUNT查询连胜天数。但在详细设计复盘时发现，当用户量达到百万级时，这种全表扫描的方式会导致数据库崩溃，且无法处理跨年、跨月的复杂日期逻辑。 + +解决方案：我查阅了大量关于高并发签到系统的设计资料，最终决定引入位图技术。我将每个用户的签到状态映射为一个二进制位（0/1），一年的签到记录仅需 365 bit（约46字节）。在逻辑上，我设计了“只看昨天”的算法——仅需判断昨天的位值是否为 1，即可决定今天是“连胜+1”还是“重置为1”。这不仅将存储空间压缩了上千倍，更将查询复杂度降低到了*O*(1)。 + +2. PBL 互评中如何防止“恶意差评”和“刷分”？ + +问题描述：协作评价模块的核心痛点在于人性。如果完全依赖学生互评，很容易出现“好朋友互刷高分”或“因私怨恶意打低分”的情况，导致系统失去公信力。 + +解决方案：我引入了“统计学仲裁”与“信誉加权”双重机制。首先，在详细设计中，我定义了ArbitrationService，利用方差公式实时监控评分波动，一旦某份作业的评分方差超过阈值（如 15.0），系统自动冻结成绩并触发人工介入，从机制上拦截了恶意差评。其次，我设计了“影响力模型”，高信誉用户的评分权重更高，而有过违规记录的用户权重降低，从而构建了一个良币驱逐劣币的生态闭环。 + +3. 如何让风控系统既安全又不影响用户体验？ + +问题描述：在设计统一认证模块时，我面临一个两难选择：如果风控太严（如每次登录都有验证码），用户体验极差；如果太松，又无法防范异地盗号。 + +解决方案：我采用了“无感风控”的设计思路。在RiskControlEngine中，我设计了基于 GeoIP 的“速度检测算法”。系统会在后台静默计算用户两次登录之间的物理移动速度，只有当速度超过物理极限（如 800km/h）时，才会触发 MFA 二次验证。这种设计在保障安全的同时，最大程度地减少了对正常用户的打扰，实现了安全与体验的平衡。 + +## 4.3 经验教训与感悟 + +架构设计必须“以终为始”。实训初期，我曾试图在需求分析阶段就确定所有的技术细节，结果导致文档反复修改。后来我意识到，需求分析的重点是“做什么”（业务边界），而概要设计才是“怎么做”（技术选型）。这种关注点分离的思维方式，让我后续的设计工作变得井井有条。 + +文档是工程师的第二语言。以前写代码时，我总觉得文档是累赘。但这次实训让我明白，一份清晰的时序图或状态机图，能胜过千言万语的解释。特别是在设计复杂的“仲裁流程”时，正是通过绘制状态流转图，我才发现了“仲裁中”到“已完成”之间缺失了“结果通知”这一环节，从而避免了逻辑漏洞。 + +技术的价值在于解决业务问题。在设计“自适应路径”时，我最初沉迷于复杂的AI模型，忽略了系统的高可用性。后来在老师指导下，我增加了“熔断降级”逻辑——当 AI 服务超时，自动切换为规则推荐。这让我深刻领悟到：技术的先进性固然重要，但系统的稳定性与业务的连续性才是工程设计的底线。 + +## 4.4结语 + +本次实训不仅是一次技术的演练，更是一次工程思维的洗礼。我学会了如何从宏观架构俯瞰系统，如何在微观细节中打磨逻辑，更学会了如何在权衡取舍中做出最优的设计决策。这些宝贵的经验将成为我未来职业生涯中坚实的基石，指引我设计出更加优秀、健壮的软件系统。 + +* +* + +### 参考资料 References + +1. \[美\] Roger S. Pressman, Bruce R. Maxim. 软件工程：实践者的研究方法(原书第8版) \[M\]. 郑人杰, 等译. 北京: 机械工业出版社, 2016 + +2. \[美\] Eric Evans. 领域驱动设计：软件核心复杂性应对之道 \[M\]. 赵俐, 等译. 北京: 人民邮电出版社, 2016. + +3. \[美\] Grady Booch, James Rumbaugh, Ivar Jacobson. 统一建模语言用户指南(第2版) \[M\]. 邵维忠, 等译. 北京: 人民邮电出版社, 2006. + +4. \[美\] Chris Richardson. 微服务架构设计模式 \[M\]. 喻勇, 译. 北京: 机械工业出版社, 2019. + +5. \[美\] Josiah L. Carlson. Redis实战 \[M\]. 黄健宏, 译. 北京: 人民邮电出版社, 2015. + +6. Piech C, Bassen J, Huang J, et al. Deep Knowledge Tracing \[J\]. Advances in Neural Information Processing Systems, 2015, 28: 505-513. + +7. \[美\] Fabian Hueske, Vasiliki Kalavri. Flink基础教程 \[M\]. 崔星灿, 译. 北京: 人民邮电出版社, 2019. + +8. 方志朋. 深入理解Spring Cloud与微服务构建 \[M\]. 北京: 人民邮电出版社, 2019. + +9. \[美\] Ian Robinson, Jim Webber, Emil Eifrem. 图数据库 \[M\]. 刘涛, 译. 北京: 人民邮电出版社, 2016. + +10. GB/T 8567-2006, 计算机软件文档编制规范 \[S\]. 北京: 中国标准出版社, 2006. diff --git a/docx2md/1_Images_Ordered/Image_002.png b/docx2md/1_Images_Ordered/Image_002.png new file mode 100644 index 0000000..6faf9c5 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_002.png differ diff --git a/docx2md/1_Images_Ordered/Image_003.png b/docx2md/1_Images_Ordered/Image_003.png new file mode 100644 index 0000000..8809fba Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_003.png differ diff --git a/docx2md/1_Images_Ordered/Image_004.png b/docx2md/1_Images_Ordered/Image_004.png new file mode 100644 index 0000000..1afc391 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_004.png differ diff --git a/docx2md/1_Images_Ordered/Image_005.png b/docx2md/1_Images_Ordered/Image_005.png new file mode 100644 index 0000000..d40c9ee Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_005.png differ diff --git a/docx2md/1_Images_Ordered/Image_006.png b/docx2md/1_Images_Ordered/Image_006.png new file mode 100644 index 0000000..7235b73 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_006.png differ diff --git a/docx2md/1_Images_Ordered/Image_007.png b/docx2md/1_Images_Ordered/Image_007.png new file mode 100644 index 0000000..638a7d4 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_007.png differ diff --git a/docx2md/1_Images_Ordered/Image_008.png b/docx2md/1_Images_Ordered/Image_008.png new file mode 100644 index 0000000..638a7d4 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_008.png differ diff --git a/docx2md/1_Images_Ordered/Image_009.png b/docx2md/1_Images_Ordered/Image_009.png new file mode 100644 index 0000000..e6d7e50 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_009.png differ diff --git a/docx2md/1_Images_Ordered/Image_010.png b/docx2md/1_Images_Ordered/Image_010.png new file mode 100644 index 0000000..975a248 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_010.png differ diff --git a/docx2md/1_Images_Ordered/Image_011.png b/docx2md/1_Images_Ordered/Image_011.png new file mode 100644 index 0000000..3a515aa Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_011.png differ diff --git a/docx2md/1_Images_Ordered/Image_012.png b/docx2md/1_Images_Ordered/Image_012.png new file mode 100644 index 0000000..1a31fc0 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_012.png differ diff --git a/docx2md/1_Images_Ordered/Image_013.png b/docx2md/1_Images_Ordered/Image_013.png new file mode 100644 index 0000000..a9804e8 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_013.png differ diff --git a/docx2md/1_Images_Ordered/Image_014.png b/docx2md/1_Images_Ordered/Image_014.png new file mode 100644 index 0000000..533464a Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_014.png differ diff --git a/docx2md/1_Images_Ordered/Image_015.png b/docx2md/1_Images_Ordered/Image_015.png new file mode 100644 index 0000000..3c420fb Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_015.png differ diff --git a/docx2md/1_Images_Ordered/Image_016.png b/docx2md/1_Images_Ordered/Image_016.png new file mode 100644 index 0000000..2ad9017 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_016.png differ diff --git a/docx2md/1_Images_Ordered/Image_017.png b/docx2md/1_Images_Ordered/Image_017.png new file mode 100644 index 0000000..233da06 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_017.png differ diff --git a/docx2md/1_Images_Ordered/Image_018.png b/docx2md/1_Images_Ordered/Image_018.png new file mode 100644 index 0000000..04afc12 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_018.png differ diff --git a/docx2md/1_Images_Ordered/Image_019.png b/docx2md/1_Images_Ordered/Image_019.png new file mode 100644 index 0000000..e18d5d4 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_019.png differ diff --git a/docx2md/1_Images_Ordered/Image_020.png b/docx2md/1_Images_Ordered/Image_020.png new file mode 100644 index 0000000..5be6b12 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_020.png differ diff --git a/docx2md/1_Images_Ordered/Image_021.png b/docx2md/1_Images_Ordered/Image_021.png new file mode 100644 index 0000000..44ecd84 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_021.png differ diff --git a/docx2md/1_Images_Ordered/Image_022.png b/docx2md/1_Images_Ordered/Image_022.png new file mode 100644 index 0000000..4a54f2e Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_022.png differ diff --git a/docx2md/1_Images_Ordered/Image_023.png b/docx2md/1_Images_Ordered/Image_023.png new file mode 100644 index 0000000..1f85260 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_023.png differ diff --git a/docx2md/1_Images_Ordered/Image_024.png b/docx2md/1_Images_Ordered/Image_024.png new file mode 100644 index 0000000..509a155 Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_024.png differ diff --git a/docx2md/1_Images_Ordered/Image_025.png b/docx2md/1_Images_Ordered/Image_025.png new file mode 100644 index 0000000..30f161c Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_025.png differ diff --git a/docx2md/1_Images_Ordered/Image_026.png b/docx2md/1_Images_Ordered/Image_026.png new file mode 100644 index 0000000..5e95d0b Binary files /dev/null and b/docx2md/1_Images_Ordered/Image_026.png differ diff --git a/docx2md/AI友好型.py b/docx2md/AI友好型.py new file mode 100644 index 0000000..0d88e1c --- /dev/null +++ b/docx2md/AI友好型.py @@ -0,0 +1,120 @@ +import subprocess +import os +import re +import shutil +import urllib.parse # 用于处理文件名中的 %20 空格 +from pathlib import Path + +def convert_final_clean(docx_file): + # --- 配置区域 --- + path_obj = Path(docx_file) + base_name = path_obj.stem + output_md = f"{base_name}_Compact.md" + + # 临时文件夹 (乱序，脚本运行完会删除) + temp_media_folder = f"{base_name}_temp_media" + # 最终文件夹 (有序，这是你要的) + final_images_folder = f"{base_name}_Images_Ordered" + # ---------------- + + print(f"🔄 正在启动 Pandoc 转换...") + + # 1. Pandoc 转换 (提取原始图片) + cmd = ["pandoc", docx_file, "-o", output_md, + "--to=gfm", + "--standalone", + f"--extract-media={temp_media_folder}", # 提取到临时目录 + "--wrap=none"] + + try: + subprocess.run(cmd, check=True, capture_output=True) + except Exception as e: + print(f"❌ Pandoc 转换失败: {e}") + return + + # 准备最终文件夹 + if os.path.exists(final_images_folder): + shutil.rmtree(final_images_folder) # 如果旧的存在，先清空 + os.makedirs(final_images_folder) + + with open(output_md, 'r', encoding='utf-8') as f: + content = f.read() + + print(f"🔄 正在整理图片并重命名...") + + # 2. 图片清洗与重命名逻辑 + img_count = 0 + + def img_replacer(m): + nonlocal img_count + + # 获取图片路径 (兼容 Markdown ![]() 和 HTML ) + # group(2) 是 Markdown 路径，group(4) 是 HTML src 路径 + raw_path = m.group(2) or m.group(4) or "" + + if not raw_path: return m.group(0) + + # 解码路径 (比如把 "media/image%201.png" 转为 "media/image 1.png") + original_path = urllib.parse.unquote(raw_path) + + # 修正 Windows 反斜杠问题 + original_path = original_path.replace("\\", "/") + + # 构造新文件名 (Image_001.png) + ext = os.path.splitext(original_path)[1] + if not ext: ext = ".png" # 防止无后缀 + new_filename = f"Image_{img_count+1:03d}{ext}" # 序号从 001 开始 + + # 执行文件复制 + # 注意：Pandoc 提取的路径通常是 "folder/media/image.png" + # 我们需要找到这个文件在磁盘上的真实位置 + src_full_path = os.path.join(os.getcwd(), original_path) + dest_full_path = os.path.join(final_images_folder, new_filename) + + if os.path.exists(src_full_path): + shutil.copy2(src_full_path, dest_full_path) + img_count += 1 # 只有文件存在且复制成功，计数器才+1 + + # 生成 AI 上传指令 (Markdown) + return ( + f"\n\n---\n" + f"> 📸 **[指令：请在此处上传图片 {img_count:03d}]**\n" + f"> 文件名: `{new_filename}`\n" + f"---\n\n" + ) + else: + # 如果找不到原图，保留原样或提示错误 + print(f"⚠️ 警告: 找不到图片文件 {src_full_path}") + return m.group(0) + + # 正则：同时匹配 Markdown图片 和 HTML图片 + pattern = r'(!\[.*?\]\((.*?)\))|(]+src=["\'](.*?)["\'][^>]*>)' + content = re.sub(pattern, img_replacer, content, flags=re.IGNORECASE) + + # 3. 表格与文本清洗 + content = re.sub(r' +', ' ', content) # 压缩空格 + content = re.sub(r'\{width=.*?\}', '', content) # 去除 pandoc 尺寸标记 + content = re.sub(r'\n{3,}', '\n\n', content) # 去除过多空行 + + # 4. 保存 Markdown + with open(output_md, 'w', encoding='utf-8') as f: + f.write(content) + + # 5. 【关键步骤】删除那个乱七八糟的临时文件夹 + if os.path.exists(temp_media_folder): + try: + shutil.rmtree(temp_media_folder) + print(f"🗑️ 已删除临时文件夹: {temp_media_folder}") + except: + pass + + print(f"\n" + "="*50) + print(f"✅ 处理完成！") + print(f"📂 请务必打开这个文件夹找图片: 【 {final_images_folder} 】") + print(f"📄 Markdown 文件: {output_md}") + print(f"🔢 共处理图片: {img_count} 张") + print(f"="*50) + +if __name__ == "__main__": + # 请确保这里的文件名是你真实的 docx 文件名 + convert_final_clean("1.docx") \ No newline at end of file diff --git a/docx2md/docx2md.py b/docx2md/docx2md.py index 98fa590..22fdc51 100644 --- a/docx2md/docx2md.py +++ b/docx2md/docx2md.py @@ -100,4 +100,4 @@ def convert_compact_mode(docx_file): print("="*60) if __name__ == "__main__": - convert_compact_mode("详细设计说明书（最终版）.docx") \ No newline at end of file + convert_compact_mode("1.docx") \ No newline at end of file