业务与功能介绍
### 核心业务
- **员工与部门管理**:增删改查、Excel 批量导入导出、部门层级。
- **请假登记**:按假期类型登记起止日期,自动按工作日计算请假天数;支持修改、销假。
- **工作日口径**:默认排除周末,节假日管理中**标记为补班日的周六日强制计入工作日**(1.1.0),登记与修改共用同一计算入口,前端预估天数也调用后端接口,保证口径统一。
- **假期额度与档位**:每种假期可配置档位规则(按工龄分档,如公休 `[1-10年]=5天 / [11-20年]=10天 / [21年以上]=15天`),工作年限采用**虚年制**(`当前年份 - 入职年份 + 1`),系统启动时自动幂等重算存量剩余天数快照。
- **考勤统计与导出**:月度统计、请假明细,导出双 Sheet Excel(假期明细 + 考勤统计),列序与格式有回归测试保护。
- **登录认证**:JWT 会话、注册/改密、角色控制。
### 桌面端特性(Tauri 壳)
- **系统托盘常驻**:关闭窗口默认收进托盘不退出;单实例检测,二次启动激活已有窗口;开机自启动。
- **托盘白屏修复(1.1.5)**:窗口长时隐藏后恢复时,同步 WebView2 控制器可见性(`SetIsVisible` + `NotifyParentWindowPositionChanged`),show/resize/focus 三路唤醒兜底,根治"点托盘还原后一片白"的微软 WebView2 已知问题。
- **自动备份**:数据库迁移前自动备份,支持按计划自动备份与手动备份,失败留痕。
- **诊断日志**:panic 落盘、日志按 256KB 轮转,托盘进程抗杀看门狗(MCP 子进程目击复活机制)。
- **腾讯文档同步**:干部请假登记自动写入腾讯在线表格台账(A-I 九列,剩余天数/假期类型与导出口径一致),同步失败不阻塞登记。
### MCP 智能助手
通过 MCP(stdio / HTTP 双通道)暴露考勤工具,AI 助手可用自然语言操作:
- 登记请假:"登记——张三,工休,家中有事,5月19日至22日"
- 销假:"销假——张三,工休,5月19日至22日"
- 查询 / 统计:"查询——张三的请假记录"、"统计——5月考勤"
MCP 子进程由主进程拉起并捆绑回收,带 30 秒存活监护与自动重新拉起。
### 模块与技术栈对应
| 目录 | 职责 | 技术栈 |
|---|---|---|
| `frontend/` | 单页前端:登录、工作台、员工、部门、假期类型、请假记录、工作日计算、设置 8 个视图 | Vue 3 + Vite + Tailwind + Pinia |
| `desktop-rust/src/routes/` | REST API 层(认证、员工、部门、假期、请假、统计、考勤、同步配置) | Axum + serde |
| `desktop-rust/src/business/` | 纯业务规则:工作日天数、档位与剩余天数、虚年制工龄 | 纯 Rust(含单元测试) |
| `desktop-rust/src/db.rs` | SQLite 打开、迁移(迁移前自动备份)、存量快照回填 | rusqlite(bundled) |
| `desktop-rust/src/desktop/` | 桌面壳:托盘、窗口事件、单实例、自启动、备份调度、诊断、MCP 子进程监护 | Tauri 2 + windows-sys |
| `desktop-rust/src/mcp/` | MCP 服务端实现(stdio / HTTP 两形态,同一工具集) | rmcp |
| `desktop-rust/src/tencent_docs.rs` | 腾讯文档 Sheet MCP 直连(token 配置、WAF 兜底重传) | reqwest + base64 |
| `backend/`、`mcp-server/` | 历史 Node 实现(迁移对照与数据回溯参考,非当前运行形态) | Express + better-sqlite3 / MCP SDK |
### 实现过程简述
1. **Node 原型**:Express 后端 + Vue 前端跑通全部业务,验证产品形态。
2. **桌面化迁移**:评估 Electron 与 Tauri 后选择 Tauri 2(单文件、体积小、内存低),将后端整体用 Rust 重写(Axum + rusqlite),前端原样嵌入 WebView2。
3. **单进程融合**:后端服务并入桌面进程,消除"后端 exe + 桌面壳"双进程部署;MCP 保留子进程形态以便独立接入。
4. **硬化迭代**(1.0.x → 1.1.x):panic 落盘、迁移前备份、看门狗复活、单实例、托盘白屏三路唤醒等稳定性修复;每项修复配套全量测试(`cargo test`)与生产级实测(白屏场景按"还原态 + 90 秒挂起"复测)。
5. **口径统一**:导出 Excel、界面显示、腾讯文档同步三处链路共用同一格式化实现(如 `mmdd-mmdd(X天)`、公休显示为"年休"),杜绝口径漂移。