所有文章

工程案例分析：将粗糙的高校PDF课表重构为具备论坛与推送功能的PWA生态系统

pwacase-studyfastapireactarchitecturereverse-engineeringparsing

工程案例分析：将粗糙的高校PDF课表重构为PWA生态系统

在高等教育信息化建设中，学生的日常数字化体验往往受制于保守的传统IT基础设施。在新西伯利亚国立大学高等信息学院（VKI NSU），最核心的教学运营数据——课表，多年来一直以人工排版、非结构化的多页PDF文档形式发布。

本文将从工程视角深入复盘该服务的独立研发历程：从攻克数据提取（Data Extraction）与逆向工程（Reverse Engineering）难题，到设计基于FastAPI的高吞吐后端、React PWA离线客户端以及集成的学生社区。

1. 业务痛点与架构背景

从产品与交互体验角度分析，原有的数据分发链路存在严重的可用性缺陷：

  • 缺乏机器可读的API：官方教务系统不提供任何公开的JSON/REST接口。
  • 极高的访问摩擦（Friction）：学生每天需要下载数兆的PDF文件，在移动端频繁缩放，在密集的单元格中检索本班级代号。
  • 零响应时效性：当发生临时调课、更换教师或教室变更时，用户无法实时获知变更。

项目目标非常明确：构建一个自主、高可用、全栈式服务，自动提取清洗上游原始文档，生成强类型API，并秒级触达移动端与桌面端用户。

2. 数据工程：逆向工程与自研PDF启发式解析管线

从PDF中提取表格结构是计算机视觉与文本解析中的经典难题，因为PDF标准本质上只存储坐标绘图指令与字形，缺乏行、列和表格等语义信息。

遗留开源方案的局限性

在初期预研中曾尝试引入现有的开源解析方案（如 DedMaxTech 的 VkiHub 项目）。然而，随着学院教务处对课表版式的又一次调整，第三方方案因规则脆弱性彻底失效：

  1. 边界框偏移（Bounding Box Shift）：列基准线的细微偏移导致相邻班级的数据交叉污染。
  2. 动态合并单元格（Merged Cells）：跨子班级、合班大课、单双周排课的合并单元格破坏了确定性网格矩阵。
  3. 异构文本格式：教师姓名的随意缩写（Иванов И.И.、Иванов И. И）、校区代号与各种附加标记混杂。

事实证明，在缺乏对底层规则完全掌控的情况下，任何上游微调都会导致整个数据管线发生级联崩溃（Cascade Failures）。

从零研发Core解析引擎

在重构后的后端架构（services/parser.py）中，彻底移除了外部脆弱依赖，完全采用自主研发的算法管线：

[ 官方PDF文件 ] 
       │
       ▼ (Camelot Lattice/Stream Extraction)
[ 原始二维矩阵 ] 
       │
       ▼ (find_header_row & 正则匹配)
[ 动态表头边界识别 ] 
       │
       ▼ (启发式单元格解构 & 实体提取)
[ 强类型JSON载荷 ] 
       │
       ▼ (构建倒排索引)
[ 索引：班级 / 教师 / 教室 ]

核心解析引擎的关键设计决策：

  • 动态表头定位（find_header_row）：算法通过严格的班级代号正则（^[А-ЯA-Z]\d{4}[а-яa-z]{1,2}\d$）扫描矩阵前若干行，自动界定文档元数据与课表数据的动态分界线。
  • 启发式单元格解构（parse_cell）：分层提取算法逐项解析文本块：
    • 提取教师姓名并标准化缩写格式：extract_teacher。
    • 识别教室编号与校区建筑：extract_room。
    • 课型分类标识（isLecture、isPractice、isExam、isConsultation、isCanceled）。
    • 词法去重与噪声过滤（remove_duplicate_words）。
def parse_cell(self, text: str):
    if not text or not text.strip():
        return None

    text = self.clean_text(text)
    teacher = self.extract_teacher(text)
    classroom = self.extract_room(text)
    isLecture = 'лекци' in text.lower() or 'диста' in text.lower()
    lesson_text = self.extract_subject(text)
    lesson = self.normalize_lesson(self.remove_duplicate_words(lesson_text))

    if not lesson:
        return None

    formatted_lesson = (lesson[0].upper() + lesson[1:]) if lesson.lower() == lesson else lesson
    if classroom:
        formatted_lesson = formatted_lesson.replace(classroom, '')

    isIssusing = ((not teacher or not classroom) and (not isLecture or (isLecture and 'нет' in text.lower()))) or 'выставле' in text.lower()

    return {
        'line': self.remove_duplicate_words(text) if isIssusing else text,
        'lesson': formatted_lesson,
        'teacher': teacher,
        'classroom': classroom,
        'isLecture': isLecture,
        'isPractice': 'практик' in text.lower(),
        'isExam': 'экзам' in text.lower(),
        'isIssusing': isIssusing,
        'isConsultation': 'консул' in text.lower(),
        'isCanceled': 'отмен' in text.lower()
    }
  • 倒排索引构建（Inverted Index）：在内存中实时生成次级数据投影——按教师维度的课表（/schedule/teachers）和按教室维度的课表（/schedule/classrooms），使得查询任意时间段的空闲教室的时间复杂度降至 O(1)。

3. 系统全栈架构与技术栈选型

系统严格遵循关注点分离原则，针对首屏交互时间（TTI）与移动端低功耗进行了深度优化。

系统层级 技术栈 架构职责
Backend Core Python 3.12, FastAPI, Tortoise ORM 异步请求路由、定时轮询Worker、事务一致性管理
Database PostgreSQL 用户资料、Session会话、论坛讨论帖与Push订阅信息存储
Frontend App React 19, TypeScript, Vite 响应式SPA单页应用、客户端路由与状态管理
PWA & Offline Service Workers, Web App Manifest 静态资产预缓存、桌面/主屏幕安装、离线运行能力
Styling & UI 模块化 SCSS, 自研Design System 高性能轻量组件库，杜绝冗余第三方UI库的包体积开销
Push Gateway Web Push Protocol, VAPID, pywebpush 操作系统层级的后台课表变更即时推送

4. 产品演进：学生社区论坛的诞生

最初项目定位于单功能工具（Schedule Viewer）。然而在与UI设计师的深度协作中，我们发现了将每日高频工具流量转化为社区生态的产品机遇。

UGC子系统设计（User Generated Content）

论坛子系统注重极低的交互阻力：

  • 安全与权限隔离：Session Token无感鉴权、用户角色划分与内容审查机制。
  • 分层内容架构：分类版块、标签筛选、嵌套回复树及点赞反馈机制。
  • 移动端交互优化：自适应发帖对话框、乐观UI更新（Optimistic Updates）与丝滑微动画。

5. 核心平台能力

目前平台已成为服务学院师生的综合数字化助手：

  1. 实时教室占用查询： 借助倒排教室索引，学生可一键查询当前无课的自习与研讨空间。

  2. 事件驱动的Push通知： 后台调度Worker（services/request.py）定期轮询教务网站，在检测到目标班级课表变更时即刻向订阅设备推送通知。

  3. 离线优先的PWA能力： 依托Service Worker强缓存策略，即便在地下实验室等弱网或无网络环境下依然秒开可用。

  4. 内置学生交流论坛： 提供学术资料共享、组队开发、课程交流的一站式校园沟通空间。

6. 技术沉淀与总结

平台的持续演进带来了宝贵的工程经验：

  • 上游容灾（Resilience）：针对学院官网偶发的网络中断，实现了上一次有效版本数据的降级回退缓存（Fallback Caching）。
  • 掌控核心资产：彻底剥离脆弱的第三方库依赖、自主实现启发式解析，使解析异常率趋近于零。

总结

该项目验证了一个工程师与一位设计师的高效协作模式：通过扎实的技术实现、完全自主的代码掌控以及对用户真实痛点的敏锐洞察，在单个暑期内将一份粗糙的PDF课表成功打造为高黏性的校园级应用。