这周课题下来的时候说实话有点意外。“2026 SMU week2”——三门课合在一起布置的第二个实训周要求不是交一篇报告就完事而是要跑出一个能用的东西。SMU是我们课程项目的一个统一代号没有任何特指含义第二周轮到我们小组做“数据链路完整”的小型实战。我从这个课题里拆出来的是一个“校园活动签到数据看板”把散落在Excel表、群接龙里的签到记录统一清洗入库通过后端接口聚合统计前端用图表把参与率、院系分布、高峰期一眼呈现出来。这篇内容就记录了我这两天半从零把项目完整跑通的全过程既有代码片段也有选型逻辑和踩坑记录适合刚学完前后端基础、想用一个完整项目串一遍技术栈的人也适合被人工统计签到数据折磨过的活动组织者。1. 课题拆解与完整技术选型1.1 二周目项目到底要解决什么问题这种周级实训项目最怕的不是难而是不知道边界在哪里。课题给了一个很宽的方向用“数据”解决一个校园里的实际问题。我们组最开始列了五六个候选图书馆人流预测、食堂排队时长分析、校园二手交易热度统计……最后敲定做活动签到数据看板是因为它有两个天然优势第一数据就在我们身边每个学院、每个社团都在手动整理签到表真实样本随手就能拿到第二链路足够完整从脏数据清洗到SQL聚合再到图表展示项目的每个环节都能“摸到”不会像预测模型那样花了大量时间在算法上最后展示却只有一张图。我们确定的目标很克制把课程活动里的签到数据和导出Excel统一格式清洗出标准字段然后提供按院系、时间段、活动类型三个维度的统计接口最后在前端展示参与趋势、院系占比、单场到场率等核心指标。不追求大而全核心是把“数据从哪来、如何变干净、怎么算出来、怎样展示”这四步走通。任务拆成三块以后每个人的分工就非常清楚了。一个同学负责收集原始签到文件和字段梳理一个同学负责后端接口和数据库表结构我负责前端看板和联调。我们强制自己遵守一个原则每天的代码必须在当天晚上合并之前都跑得起来每完成一个接口就顺手写一行文档绝不攒到最后一天统一对接不然周日晚上的崩溃几乎是可以预见的。1.2 为什么选这套“轻量全栈”组合技术选型没有追求新潮选的都是能在一周内掌握、出了问题能快速搜索到解决方案的组合。前端用Vite React Recharts后端用FastAPI数据库直接用SQLite整体跑起来只需要本地两条命令没有任何额外的环境依赖。有人问为什么不直接做前后端分离我的回答是正因为是两周阶段性的实训项目前后端分离才有练习价值。如果只是一个单人小工具当然可以后端模板渲染一把梭但那样就练不到接口设计、跨域处理、异步联调这些工作中天天会遇到的东西。具体为什么这么选我对比过几组选项。第一组是FastAPI对比Flask。Flask更老牌资料更多但FastAPI自带OpenAPI交互文档写完接口后在浏览器里就能直接测试这对我们这种需要快速联调的小组太关键了。配合Pydantic做请求体类型校验前端传过来的字段类型不对会直接报422错误比在Flask里手动判空省了很多事。第二组是SQLite对比MySQL。MySQL需要额外安装服务还要处理账号权限而SQLite是一个单文件数据库Python内置库就能驱动项目提交时只需要把db文件一起打包老师都能直接运行。缺点后面会专门讲就是并发写能力很弱但对我们这种学生活动场景完全够用。第三组是React对比Vue。说实话两者都行我们选React只是因为组里已经有同学熟悉学习成本低。Vite比Create React App启动快了不少而且配置文件少几行就搞定代理和路径别名体验好太多。还有一个容易被忽略的选型图表库。我用了Recharts而没用ECharts主要是Recharts的组件化风格和React比较搭改样式不用写大量option配置做基础的折线图、柱状图、饼图完全够用。ECharts在复杂交互上更强大但本次项目里我们用到的图表场景相对基础Recharts的代码量可以少三分之一遇到问题看文档和示例也更容易定位。提示选型时一定要考虑组员的平均水平周级项目里“大家都会用”比“功能最强”重要得多。评审老师看的是完整度和思路不会因为某个技术栈更高级就额外加分。2. 数据清洗最脏但最不能省的一步2.1 原始数据都有哪些“坑”拿到第一批签到数据的时候我整个人都不太好了。三个来源三种格式几乎没有一行是能直接入库的。活动系统导出的CSV字段名是英文字段值是中文群接龙导出的表格只有昵称和接龙时间没有学号还有一份纸质签到的Excel录入表居然把时间写成了“18:23”和“2026/02/24 18:25”混着来。再加上活动当天的连场签到同一批人到场、离场各签一次如果不做去重统计到场率直接就翻倍了。最典型的一个例子学号。系统导出的学号有的显示成“2026000123”有的因为Excel的单元格格式问题变成了“2.026E09”。还有的同学签到的时候直接少写了一位变成“202600012”。这些数据如果直接进数据库后面做“按人统计”的时候同一个人的记录会被拆成三个不同的人整个统计结果就全废了。时间字段的问题也够头疼的。同一个活动里时间格式有“2026-02-24 18:23”、“2026/02/24 18:25”、“2月24日18点30分”三种。Python的datetime解析接口不能直接处理所有格式需要自己做统一映射。如果不处理后面按“时段分布”做统计的时候这些记录要么被丢弃要么被解析成空值前端图表上就会出现大段缺失。2.2 清洗实操pandas三行核心逻辑清洗阶段我直接用pandas处理没有写一堆for循环。pandas做这种事天然合适——它的向量化操作比Python原生循环快一个数量级而且代码量少逻辑清晰。import pandas as pd df pd.read_csv(raw_checkin.csv, dtype{student_id: str}) # 1. 学号补零到10位 df[student_id] df[student_id].str.zfill(10) # 2. 统一时间字段 df[checkin_time] pd.to_datetime( df[checkin_time], formatmixed, errorscoerce ) # 3. 去重同一活动同一人只保留第一次签到 df df.drop_duplicates( subset[student_id, activity_id], keepfirst ) # 4. 删除解析失败的时间行 df df.dropna(subset[checkin_time])第一步的zfill(10)是处理学号前导零丢失的利器。如果学号被存成数字前面的“0”就会消失统一补足到10位之后所有人的编号格式就一致了。第二步用了formatmixedpandas会自动尝试混合格式解析这一步节省了大量手工写正则的时间但前提是脏数据不能太离谱否则还是得老老实实写解析函数。第三步按“学号活动ID”双重维度去重保留最早一条签到记录这样就能剔除连场重复签到的情况。最后一步把无法解析的时间行直接丢掉并在清洗报告里记录下来方便后续追溯。有个细节很多人第一次写会漏掉读取CSV时一定要加上dtype{student_id: str}。如果忽略这一步pandas会按默认类型读入长学号会被当成数字自动丢掉精度后面再补零也救不回来了。这个坑不是我们组踩的是我看别人的代码时发现的但几乎每周实训都有人重复踩一遍。清洗完之后我们组做了一次完整性校验把清洗前后的记录数对比同时随机抽了20条清洗后的数据人工核对字段是否完整。这一步虽然占时间但很有必要尤其是要保证后面统计结果可信数据源得先经得住抽查。2.3 入库前为什么先做清洗而不是入库后这个问题一直有人问能不能先把原始数据全部塞进数据库再用SQL慢慢处理我的观点是可以但完全没有必要而且会很痛苦。清洗放在入库前得到的好处非常直接。第一数据库表结构可以保持干净稳定。如果让原始数据直接入库你会发现同一列里既有“2026-02-24 18:23”又有“2月24日18点30分”建表时对字段类型的判断会被迫降到“字符串”这个最低级别后面做时间聚合时还得在SQL里反复写CAST、SUBSTRING这种兼容逻辑。第二数据量小的时候SQL写起来可能没什么感觉但字段脏到一定程度每条查询都在做隐式转换逻辑多了很难排查。第三清洗逻辑写在哪里决定了它能不能复用。写在Python里每周拿到新数据只要跑一遍脚本就能重新生成干净表而如果清洗逻辑散落在各处SQL查询里换一个需求就全得重写。数据入库的schema我们定得也很简单六列student_id、activity_id、student_name、college、checkin_time、activity_type。其中activity_type是手动补录的用来区分“讲座、文体、志愿”等不同活动类型方便后面按类型筛选。建表DDL放在项目根目录的schema.sql里每次从零搭建环境只需要执行一次就能恢复结构这也算是我们实训中学到的一个好习惯——把环境搭建变成一条命令而不是一堆会话记录。3. 后端接口从建表到聚合统计3.1 先约定接口再写代码进入后端开发之前我们三个人先坐在一张白板前把接口约定写死了。这一步特别关键尤其是有明确分工的团队项目。我们把所有接口的路径、请求参数、返回结构都提前定义好前端可以拿着约定直接写页面后端照着约定实现两边不用反复问“这个字段叫什么”。核心接口一共四个POST /api/checkins提交一条签到记录供手动补录使用GET /api/checkins按条件分页查询明细支持学号、院系筛选GET /api/stats/overview总览指标返回总签到数、总活动数、平均到场率GET /api/stats/trend按时间段或日期聚合的趋势数据支持院系、活动类型筛选GET /api/stats/distribution按院系或活动类型聚合的占比数据返回结构我们统一成{code: 0, message: ok, data: ...}的格式。用code字段区分业务成功和失败而不是只用HTTP状态码因为有些业务错误比如“学号不存在”本来就是预期的HTTP层面返回200也行但前端判断code更直观。字段命名上我们统一用snake_casePython这边天然就是这种风格前端拿到后不做转换直接使用。3.2 FastAPI代码实现表结构和连接逻辑比较简单用的是Python自带的sqlite3没有任何ORM。这个阶段的项目我建议别上SQLAlchemy手写SQL反而更容易理解查出来的是什么数据。import sqlite3 from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel DB_PATH smucheckin.db app FastAPI() app.add_middleware( CORSMiddleware, allow_origins[http://localhost:5173], allow_methods[*], allow_headers[*], ) class CheckinRecord(BaseModel): student_id: str activity_id: str student_name: str college: str checkin_time: str activity_type: str app.post(/api/checkins) def add_checkin(record: CheckinRecord): conn sqlite3.connect(DB_PATH) conn.execute( INSERT INTO checkins (student_id, activity_id, student_name, college, checkin_time, activity_type) VALUES (?, ?, ?, ?, ?, ?), (record.student_id, record.activity_id, record.student_name, record.college, record.checkin_time, record.activity_type), ) conn.commit() conn.close() return {code: 0, message: ok, data: None}注意CORS中间件这个配置我特意放在最显眼的位置是因为它极容易忘。前端开发服务器跑在5173端口后端跑在8000端口两个端口不同浏览器会认为这是一个跨域请求。如果后端不返回允许跨域的响应头前端所有请求都会在浏览器控制台里看到一个红色的CORS报错。后端开发时可以临时把allow_origins设为[*]但上线前最好改成具体的前端地址。还有一点conn.close()一定要写在commit之后。如果连接不关闭SQLite的文件锁一直不释放后面再开连接就可能遇到database is locked。后面会专门讲这个错误。更稳妥的做法是用with上下文管理器但这里为了保持代码直观直接关闭也完全没问题。3.3 统计接口的SQL思路统计接口是整个项目最核心的部分SQL写不好前端再好看也没用。我们的趋势接口需要按钟点维度统计参与人数SQL大概长这样SELECT strftime(%H, checkin_time) AS hour, COUNT(DISTINCT student_id) AS checkin_cnt FROM checkins WHERE college ? GROUP BY strftime(%H, checkin_time) ORDER BY hour;重点是COUNT(DISTINCT student_id)。我们反复强调过同一学生在同一天可能参加多场活动如果直接COUNT(*)人数会被重复计算。前端看趋势图时看的是“不重复参与人数”而不是“签到次数”这两个概念差很多。所有统计指标我们都遵循一个原则按业务口径选择聚合维度不盲目用COUNT(*)。时间聚合用了strftime(%H, checkin_time)提取小时字段。这样一天内的签到高峰一眼就能看出来。如果是按日期聚合就改成strftime(%Y-%m-%d, checkin_time)。SQLite的strftime是内置函数不需要额外扩展比在Python里把时间取出来再分组要省事得多。总览接口里的“平均到场率”计算方式是每场活动的实际签到人数除以应到人数。应到人数来自另一个活动表所以这里涉及两表LEFT JOIN。如果直接按记录表统计没有活动信息就很难算准这也是我们事先约定好“活动表”存在的原因。为了练习我故意把统计拆成了两个接口而不是一个因为按院系筛选的请求和总览请求频率不同分开写缓存策略上也更灵活。注意在这个项目里所有接口我都没有加认证逻辑仅限本机开发演示。如果真实上线的数据里包含个人学号至少需要加一层简单的访问令牌机制数据处理也要遵守最小化原则不要展示完整学号给所有访客。4. 前端看板数据图的正确打开方式4.1 组件结构怎么搭才不乱前端部分我按照“一个页面、四类区块”来组织顶部指标卡、趋势图区、分布图区、底部明细表。组件拆分成五个文件App.jsx页面主体持有筛选条件和统计数据FilterBar.jsx院系、活动类型、时间范围筛选MetricCards.jsx总签到数、总活动数、平均到场率TrendChart.jsx按时段折线图展示参与高峰DistributionChart.jsx按院系柱状图展示占比这个拆分的核心原则是“按数据用途分件”不是按图表类型分件。比如柱状图和饼图都可以叫DistributionChart因为他们依赖同一份分布数据。如果每个图表建一个组件不仅数据请求逻辑会重复而且改一个筛选条件可能会触发多个接口请求。状态管理我没有引入Redux。这个项目的数据流是单向的筛选条件变化重新请求全部数据所有图表基于同一份数据渲染。用React自带的useState和useEffect就完全能搞定引入Redux反而增加概念负担。状态只在App.jsx这一层持有下面的子组件全部无状态只接收props渲染这样调试非常简单数据在哪、从哪里更新扫一眼就知道。4.2 图表选型与数据联动的核心代码图表用Recharts核心代码不复杂import { useState, useEffect } from react; import { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from recharts; function TrendChart({ college }) { const [data, setData] useState([]); useEffect(() { fetch(http://localhost:8000/api/stats/trend?college${college}) .then((res) res.json()) .then((json) setData(json.data)); }, [college]); return ( ResponsiveContainer width100% height{300} LineChart data{data} XAxis dataKeyhour / YAxis allowDecimals{false} / Tooltip / Line typemonotone dataKeycheckin_cnt stroke#3b82f6 / /LineChart /ResponsiveContainer ); }这个组件关键在useEffect的依赖数组[college]。当用户在筛选栏切换院系时college变化组件重新请求数据并刷新图表。没有这个依赖React情绪高涨的优化机制会跳过更新图表永远显示第一次请求的数据。这类bug排查起来最容易让人崩溃因为代码看起来完全没问题但就是不更新。ResponsiveContainer这个组件要重点提一下。Recharts的图表默认宽度是100%但父容器如果高度为0渲染出来的SVG也是0高度图表直接消失。我一开始就是没给容器设置高度结果页面上只有坐标轴字母没有图形排查了好久。正确做法是给ResponsiveContainer指定明确的height甚至父容器也要有固定高度。图表选型的逻辑我简单总结过看趋势用折线图看排名用柱状图看比例用饼图看分布用散点图。本项目里正好三种都用到也算是对可视化基础知识的一次复习。不要迷信花哨图表一个能清晰表达业务含义的柱状图远比一个难以阅读的3D环图有价值。4.3 响应式与前端性能的小细节页面做出来之后我们要求必须能在手机屏幕上正常查看因为评审时很可能是用不同的设备随机打开。Recharts的ResponsiveContainer在这一点帮了大忙图表会自动适配容器宽度。但指标卡部分需要自己处理布局我用了CSS Grid加媒体查询在窄屏时从四列变成两列。性能方面有一个坑图表渲染是很吃CPU的操作如果用户快速切换筛选条件会连续发出好几个请求旧请求还没回来新请求又发出去了。如果接口响应顺序乱了前端可能用旧数据覆盖新数据。这个问题的解决办法是在useEffect里加一个取消标记useEffect(() { let ignore false; fetch(/api/stats/trend?college${college}) .then((res) res.json()) .then((json) { if (!ignore) setData(json.data); }); return () { ignore true; }; }, [college]);这段代码的核心是借助useEffect的清理函数在请求发出后组件卸载或依赖变化时把ignore置为true这样旧请求回来后就不会再执行setData。虽然本项目是本地开发网络延迟低这个问题的出现概率不高但在真实项目中这是必须注意的细节值得养成本能。另外前端请求地址用了完整的http://localhost:8000这个写法在开发和演示时没问题但如果部署到服务器上每次都要改地址非常麻烦。更好的方案是用Vite的代理配置在vite.config.js里加上server.proxy前端直接请求/api路径Vite自动转发到后端端口。这样不仅代码更干净也从根本上绕开了CORS问题。我们实际项目中偷懒直接写了完整地址后来部署时改了几分钟才意识到这个教训分享出来希望后来的人少走弯路。5. 两天踩坑记录问题与排查速查5.1 我遇到的五个典型问题把项目压缩到两天半里完成必然要踩一堆坑。下面这五个问题是我把我们小组的真实情况整理出来的每个都值得单独记录。第一个是CORS跨域问题。表现是前端页面能打开但点击筛选后数据全部为空打开浏览器控制台看到红色的跨域报错。排查方法很简单直接看Network面板如果请求状态是cors error几乎可以确定是后端没配CORS。解决办法就是前面写的在FastAPI应用中添加CORSMiddleware。我个人的经验是这个环节最容易出问题是在团队协作时——前端用的是5173端口后端同学可能自己测试用的不是8000端口端口对不上也会报跨域。第二个是中文乱码。接口返回的中文院系名称在页面上全部变成乱码排查后发现是数据库连接时没有设置UTF-8编码。SQLite数据库本身不强制编码但如果连接时没指定读写中文就可能出问题。解决方式是在连接时执行PRAGMA encoding UTF-8或者在建表时给字段加上COLLATE NOCASE保证中文排序正确。这个坑对我们来说尤其痛因为院系名称全是中文乱码一出现就整页不能看。第三个是日期显示NaN。折线图横坐标显示NaN/NaN/NaN原因是前端直接把后端返回的checkin_time字符串传给了日期组件而组件内部是按Date对象解析的。处理方式是统一在后端把时间字段转换为时间戳或格式化后的字符串前端用new Date()或dayjs再解析一遍。最好前后端约定好时间传递格式比如统一ISO8601格式避免各种缩略写法造成解析失败。第四个是SQLite database is locked。现象是后端进程运行一段时间后某个请求突然报这个错误。原因是SQLite同一时间只允许一个写操作我们后端有手动补录接口如果连续快速提交两条记录第二个写操作就会遇到锁。解决办法有两个一是把数据库文件设为WAL模式PRAGMA journal_modeWAL读写并发能力会强很多二是把写操作串行化比如在接口内加一个应用层的线程锁。这个项目里两种方案一起用了效果很稳。第五个是图表空白但接口有数据。这个我前面已经提过核心就是容器高度为0。排查思路是打开浏览器开发者工具找到图表容器元素看它的实际高度是多少。如果高度为0多半是CSS或ResponsiveContainer配置问题。还有一个冷门原因ResponsiveContainer在初始渲染时没有拿到宽度需要给容器加一个确定的宽度样式或者等待DOM挂载完成后再渲染。5.2 一套可复用的排查顺序这些坑踩多了以后我们总结了一套适合前后端分离项目的排查顺序分享出来供参考。先看Network面板确认请求有没有发出、有没有返回、状态码是多少。这是第一步因为如果请求本身都没发出去后面查什么都是白费。第二步看返回的数据结构是否符合约定这一步能排查80%的字段名不匹配问题。第三步看控制台有没有报错React报错信息通常能直接定位到组件和行号。最后才是查代码逻辑重点看useEffect的依赖数组和状态更新时机。按照这个顺序大部分联调问题都能在5分钟内定位。另外一个习惯也值得保留写接口时随手把一段样例返回数据保存为JSON文件放在前端项目的mock目录下。开发时前端直接用mock数据渲染不依赖后端是否启动联调时再切换为真实接口。这样两边开发完全互不阻塞我们组能两天半完成很大程度上靠这个做法。5.3 两天半项目的时间管理心得最后聊点和时间相关的东西。这个项目一开始我们高估了数据清洗的速度低估了联调的时间。真实时间分布大概是数据清洗和建表用了大半天后端接口一天前端展示大半天联调和修bug用了半天。如果重新来一次我会把联调时间再加长因为不同人写的代码风格差异会带来不少隐性沟通成本比如某个字段前端按驼峰命名后端按蛇形命名这种事只有在联调时才会暴露。问题速查表问题现象可能原因解决方向页面打开空白接口跨域或返回数据结构异常检查Network面板和JSON返回格式中文变乱码数据库连接编码未指定连接时设置UTF-8日期显示NaN前后端时间格式不一致统一ISO8601时间格式图表无图形容器高度为0给ResponsiveContainer设置固定高度database is lockedSQLite并发写冲突开启WAL模式并串行化写操作数据不随筛选更新useEffect依赖数组漏配确认college等参数已加入依赖我个人在这些天实操里体会最深的一点是“先定数据结构再写页面”这句话的分量。我们组几个同学第一天都觉得这是废话但到了联调阶段凡是当初想清楚了字段语义和接口返回结构的代码基本一次通过凡是临场拍脑袋定义的几乎都返工了一遍。数据看板这类项目的成败往往不取决于图表漂不漂亮而取决于数据模型有没有想清楚字段命名是否统一聚合口径是否一致。最后再分享一个小技巧把接口返回的样例数据固定保存在前端项目里开发时前端先跑mock数据后端接口写完后再无缝切换。这个习惯让我在最后半天避开了一场痛苦的联调拉锯战也让我意识到项目代码之外的约定和文档才是团队协作效率的真正杠杆。