从零构建轻量级企业考勤订饭系统：Node.js + SQLite 全栈实战复盘

在中小企业的日常管理中，考勤和午餐统计往往是一件琐碎但必须处理好的小事。市面上的SaaS软件要么功能过于臃肿，要么价格昂贵；而纯手工的Excel记录又容易出错且难以协同。
C:\myApp\attendance-enterprise
本文将详细复盘如何使用Node.js + SQLite + 原生前端技术，从零开始构建一个轻量、实用且具备高度定制化（如客饭统计、多Sheet导出、日历设置）的考勤系统。

一、 背景 (Background)

最初的需求很明确：一个Web端的应用程序，能够管理员工信息，记录每日上下班时间，统计订饭人数（含客饭），并支持周视图录入和Excel月度报表导出。

但在开发过程中，我们遇到了几个典型的业务挑战：

1. 数据准确性：如何避免考勤和订饭数据在联合查询时出现“笛卡尔积”导致的统计翻倍？
2. 交互体验：HR习惯按周批量补录，如何提供直观的“周矩阵”视图，并自动高亮周末和节假日？
3. 时区陷阱：如何确保周视图中的日期在不同浏览器中永远显示正确，不会因为UTC时差导致“周日变周六”？

二、 目标 (Goal)

我们将构建一个包含以下核心模块的单页应用（SPA风格）：

1. Dashboard：实时概览出勤率、订饭总数、下个假期提示。
2. 每日考勤：支持开关式打卡，实时计算“员工餐+客饭”总数。
3. 周考勤录入：矩阵式表格，支持批量勾选，自动识别并高亮（粉色）周末与节假日。
4. 报表统计：支持自定义日期范围，导出包含“汇总”与“明细”双Sheet的Excel文件。
5. 系统设置：员工管理，以及可视化日历形式的节假日配置。

三、 方法 (Method)

为了保证部署简单（无需安装MySQL等大型数据库）且开发迅速，我们选用了以下技术栈：

• Runtime: Node.js
• Web Framework: Express.js
• Database: SQLite3 (文件型数据库，零配置，极易迁移)
• Excel Engine:node-xlsx
• Frontend: 原生 HTML5 + CSS3 + Vanilla JavaScript (无构建工具，修改即生效)

四、 过程 (Process)

1. 数据库设计与迭代

最初的设计较为简单，但在处理“客饭”和“节假日”时进行了迭代：

• users: 基础员工表。
• attendance: 记录clock_in,clock_out。
• meals: 记录员工个人的订饭状态。
• holidays: 存储节假日日期。
• daily_extras(新增): 专门用于存储每日手动的“客饭/额外份数”，与员工个人数据解耦。

2. 攻克统计报表的“笛卡尔积”难题

在早期版本中，我们尝试直接LEFT JOIN考勤表和订饭表，结果发现如果某人同一天有多条记录（异常数据），统计结果会成倍增加。
解决方案：采用子查询 (Subqueries)。

/* 优化后的 SQL 逻辑 */SELECTu.id,u.name,(SELECTCOUNT(*)FROMattendance aWHEREa.user_id=u.id...ANDa.clock_inISNOTNULL)asdays_worked,(SELECTCOUNT(*)FROMmeals mWHEREm.user_id=u.id...ANDm.taken=1)asmeals_countFROMusers u

这样确保了考勤和订饭的计数互不干扰，绝对准确。

3. 周视图：日期偏差与视觉优化

这是前端逻辑最复杂的模块。

• 时区问题：直接使用date.toISOString()会导致在中国时区（UTC+8）的周日早上被转换为前一天的日期。
  • 修正：放弃 UTC 方法，使用本地时间拼接YYYY-MM-DD字符串。
• 视觉反馈：HR 需要一眼看出哪些天是休息日。
  • 逻辑：视觉优先级 = 今天(蓝) > 节假日(粉) = 周末(粉) > 工作日(白)。我们在后端返回holidays数组，前端weekly.js在渲染每一列时进行比对匹配。

4. 导出功能的深度定制

单一的汇总表无法满足财务核对需求。我们利用node-xlsx构建了多 Sheet 输出：

• Sheet 1 汇总：姓名、部门、总天数、总饭数。
• Sheet 2 明细：日期、姓名、打卡时间、是否订饭。

5. 设置页面的交互升级

最初的节假日设置是枯燥的列表。为了提升体验，我们手写了一个JS 日历组件：

• 支持月份切换。
• 点击日期即可“增加/删除”节假日。
• 日历格子与周视图保持一致的视觉语言（休息日显示粉红背景）。

五、 结果 (Result)

经过数次迭代，系统达到了生产可用标准：

1. 首页 (Dashboard)：清晰展示今日核心指标。
2. 每日操作：加入了“客饭”输入框，系统会自动计算员工勾选数 + 手动输入数 = 总订饭数，数据实时入库。
3. 周考勤：界面直观，周六日及设定的“春节”等假期背景自动变粉，防止误操作。
4. Excel 报表：一键导出标准格式文件，不仅有统计数据，还有每日明细供查账。