艳yyz先交代一下背景，这个项目不是凭空拍脑袋想出来的。当时部门主管最头疼的事情是：每周大家写的周报水分太大，项目进度全靠问、考核评分全靠感觉。他想上一套系统，能把每个人的任务、工时、成果量摆到台面上，让项目进度和员工产出有据可查。项目最终落地成果是一套 Spring Boot 工作量统计管理系统，带完整源码和文档，能覆盖任务下发、工作量填报、审批、统计报表几个核心环节。
如果你正准备做 Spring Boot 练手项目，或者公司内部缺一个轻量级的任务/工时管理工具，这篇文章的建模思路、实现细节和踩坑记录应该能帮你省不少时间。这套系统本身不复杂，但里面涉及的表结构设计、权限控制、报表统计、事务处理，几乎把 Java 后端日常开发的典型问题都碰了一遍，读完你可以直接照着拆分复用到自己的项目里。
1. 项目背景与需求拆解
1.1 工作量统计到底在解决什么痛点
先说个普遍现象：很多团队在考核工作量时，最终依据是员工的日报或周报。可日报周报的自由度太高，有人写三百字像写了三千字，有人干了重要的事只留下一行“修复Bug”。真正做管理的人拿到这些文本，根本没法量化，更没法跨部门对比。所以做这个系统之前，我先梳理了三个必须解决的痛点：
- 任务来源不透明，谁在什么时候接了哪个任务、做到什么程度，没有统一记录；
- 工作量缺乏原子数据，工作成果和工时对不上，后期统计全靠Excel手工拼；
- 审批和反馈链路断裂，上报内容到底认不认、修改意见是什么，缺少线上线下一致的状态记录。
因此这个系统不是简单做一个“记工时”的工具。它的核心目标是把任务派发、执行反馈、主管审核、汇总统计串成一个完整的业务闭环。管理端能随时看出谁的工作量异常偏高或偏低，项目负责人能依据实时数据调整排期，员工也能通过系统提交内容让“干过的活”不被埋没。
1.2 核心业务流程与功能模块划分
整个系统围绕一条主线展开：管理员创建人员与权限，项目负责人下发任务，执行人接收任务后按周期填报工作量和工时，主管逐条审核，审核通过的数据进入统计报表。有的团队还需要把“任务类型”和“项目名称”维度也纳入统计，方便看出人力成本都花在了哪些项目上。
我在落地时把功能拆成六个核心模块：
| 模块 | 核心职责 | 主要角色 |
|---|---|---|
| 登录认证 | 用户登录、Token签发与校验 | 所有用户 |
| 用户权限 | 用户/角色/菜单管理，控制菜单和数据权限 | 系统管理员 |
| 任务管理 | 任务的创建、下发、变更、状态跟踪 | 项目负责人、执行人 |
| 工作量填报 | 按日期/周期填写工作内容、工时、成果描述 | 普通员工 |
| 审批管理 | 主管对填报内容进行通过/驳回操作 | 主管、部门负责人 |
| 统计报表 | 按人员、任务、部门、时间维度汇总工作量 | 管理层、项目负责人 |
这套模块划分从实际复盘来看是合理的。任务管理管的是“源头”，工作量填报管的是“过程数据”，审批是“质量闸门”，统计报表是“最终出口”。四个环节缺一个，系统就又会退回 Excel 手工维护的状态。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术方案选型与架构设计
2.1 为什么选 Spring Boot 这套组合
选型时我基本没犹豫，后端直接用 Spring Boot 2.7.18。之所以定在 2.7.x 而不是 3.x，主要考虑到两个现实因素：一是很多公司生产环境 JDK 还停留在 8，Spring Boot 3 强制要求 JDK 17 起步，升上去麻烦；二是网上资料和问题排查经验最多、最稳的还是 2.7.x 这个版本段，遇到坑能更快找到解决方案。
持久层我用 MyBatis-Plus 而不是原生 MyBatis。原因很简单：简单的单表 CRUD 可以直接用 BaseMapper 内置方法，不用写大量重复 XML；统计报表这类复杂场景又能自由写 SQL，灵活度不会被框架绑死。数据库选 MySQL 8.0，因为 MySQL 8.0 对窗口函数、公用表表达式的支持更完善，做同比环比之类的报表要比 5.7 顺手很多。认证这块用 JWT + 自定义拦截器的方式，不引入 Spring Security。工作量统计系统大多是企业内网或中小团队使用，权限模型相对简单，Spring Security 那套过滤器链配置成本对这种体量来说有点重了。
前端部分用的是 Vue 2 + Element-UI，和前端同事配合时也是按前后端分离的模式联调。后端只提供 RESTful 接口，前端通过 Nginx 转发请求。这层决策给后续二次开发留了很大的便利，比如以后想换一套前端框架，后端接口完全不需要动。
2.2 数据库设计：一张“统计友好”的表结构
这个项目里我踩的最大的坑，其实不是代码，而是表结构设计。最开始我按照“人员、任务、填报记录”三张表做，结果到了报表阶段发现一个简单的按人出勤统计都要 join 四五张表，SQL 写起来痛苦，查询还慢。后来调整思路，把所有面向统计的冗余字段直接落到业务表上。
核心表我最终收敛成这六张：
| 表名 | 核心字段 | 用途说明 |
|---|---|---|
| sys_user | id, dept_id, username, password, real_name, status | 用户基础信息，status 控制是否可登录 |
| sys_role | id, role_name, role_code | 角色，编码字段用来写权限判断逻辑 |
| sys_user_role | user_id, role_id | 用户与角色关联表 |
| operate_task | id, task_no, task_name, project_name, publisher_id, assignee_id, priority, status, expect_end_date | 任务主表，assignee_id 表示当前处理人 |
| workload_record | id, record_date, user_id, task_id, work_content, work_hours, task_type, status, audit_user_id, audit_time | 工作量填报记录，一条记录对应当天某个任务的工作小结 |
| sys_dict_data | dict_type, dict_label, dict_value | 用于维护任务类型、优先级等下拉项 |
几个容易忽略的设计点补充一下：workload_record 里我故意冗余了 task_id 和 project_name，而不是通过任务表去关联项目。因为工作量统计最频繁的查询条件就是“某个人某段时间干了哪些任务、工作量是多少”，只有把关键过滤字段直接冗余到记录表，才能避免每次统计都做大规模连表。同时 workload_record 增加了 status 字段，PENDING 代表待审核、APPROVED 代表已通过、REJECTED 代表已驳回。审批表单独建关联表当然能记录操作历史，但初期需求只关心“最终审批结果”，直接用字段记录状态最省事。
还有一个细节：所有表的 create_time、update_time 我用 MyBatis-Plus 的自动填充功能统一维护，实体类上标 @TableField(fill = FieldFill.INSERT) 和 @TableField(fill = FieldFill.INSERT_UPDATE)，然后在 MetaObjectHandler 里统一处理。这样代码里不会散落一堆 new Date()，保存时的创建时间也一定一致。
2.3 后端分层与代码结构规划
工作量大统计系统的后端沿用经典的三层结构，但在 package 组织上做了一些规范化设计。我的目录结构大概长这样：
text复制com.example.workload
├── annotation // 自定义注解，如 @RequirePermission
├── aspect // 切面，如操作日志记录
├── config // 全局配置，拦截器注册、跨域配置、MyBatis-Plus配置
├── controller // 接口层
├── service // service 接口
│ └── impl // service 实现
├── mapper // MyBatis-Plus Mapper 接口
├── entity // 数据库实体类
├── dto // 接收前端参数的传输对象
├── vo // 返回给前端的视图对象
├── common // 统一返回结果、异常处理、常量类
└── utils // JWT工具、日期工具等
Controller 层里只做参数接收、简单校验和结果封装，业务判断全部下沉到 Service。举一个典型的反例：有的项目在 Controller 里直接调用 Mapper 做数据更新，一旦后续增加审批逻辑，还得去 Controller 层到处找改，维护成本高到离谱。工作流类业务尤其不能这么写，一个工作量填报记录的保存和审核操作涉及多条数据的状态变更，必须放在 Service 方法里统一配合事务使用。
3. 核心业务功能落地实现
3.1 基于 JWT 的登录认证与权限控制
登录模块实现的是标准 JWT 流程：用户提交用户名密码，后端先用 BCrypt 比对库里的密码哈希，比对通过后生成一个 Token，Token 里只放 userId、userName、roleCode 这三个核心信息，有效期设置为 24 小时。密码加密必须用 BCrypt 而不是 MD5，哪怕项目只是内网使用，也不能让明文密码直接落库，这是安全底线。
Token 校验我用一个 HandlerInterceptor 实现。前端在每个请求的请求头里带 Authorization: Bearer xxx，后端写一个 AuthInterceptor 拦截所有 /api/** 请求，在 preHandle 方法里解析 Token，解析成功就把用户信息放进 ThreadLocal，方便后续 Controller 直接拿到当前登录人。preHandle 里我额外做了一层角色判断，用自定义注解 @RequirePermission 标记接口需要的角色码，例如 @RequirePermission("admin")，再配合拦截器里的反射解析完成权限控制。为什么不用 Spring Security？答案是团队当时的实际需要是“菜单级按钮级权限够用就行”，RBAC 模型加注解足够支撑，引入 Security 反而增加学习成本。
这里有个容易踩的坑：ThreadLocal 用完不清理会导致内存泄漏，甚至出现用户A的请求读到用户B信息的串号问题。我在 afterCompletion 里必须执行 UserContext.clear()。另外 Token 过期问题，实际使用时前端往往在 401 后跳回登录页，但如果用户在填写一长串工作内容时才过期，体验会非常糟糕。后面我加了一个简单的处理：当 Token 剩余有效期不足 30 分钟时，后端通过响应头返回一个 refreshToken 标记，前端静默重新登录替换本地 Token，用户无感续期。
3.2 任务下发与人责绑定
任务模块的工作逻辑看起来简单，做起来有几个细节需要处理。项目负责人创建一个任务后，并不是直接就生效。我设计的状态流是：待处理 -> 执行中 -> 已完成 -> 已归档。任务创建后先落在“待处理”状态，执行人可以在个人工作台看到并“确认接收”，确认之后任务才进入“执行中”。只有执行人确认过的任务，才能填报工作量。这个设计是为了避免管理者单方面下发任务但执行人根本不知道——很多协同工具只是把任务挂在列表里，实际没有绑定到人的执行意愿上。
任务实体里的 assignee_id 字段在设计时是唯一处理人。后来遇到多人协作任务时，发现这个模型不够用。处理方式是新增一个 operate_task_member 关联表，任务主表保留负责人 assignee_id，完整的参与人列表放到任务成员表里。这样既能查到“这个任务谁负责”，也能统计“哪些人其实参与了某个任务”。如果需要给多人协作场景打分，可以按成员表中每个参与人员分别生成填报入口。
任务列表的查询需要支持多条件组合筛选，包括状态、优先级、项目名称、负责人等。用 MyBatis-Plus 的 LambdaQueryWrapper 动态拼接 where 条件最合适，不需要为每种组合写一个 XML SQL。但需要注意：如果筛选条件里有 task_no 模糊查询，而 task_no 又建了唯一索引，那一定要在 SQL 里做前缀匹配，否则用不到索引，数据量大后查询速度会明显下降。
3.3 工作量填报与审批的状态流转
工作量填报是这个系统最核心的数据来源，所以我在设计字段时一点不敢马虎。workload_record 表里除了基础的人员、工时、内容字段外，还包含了 record_date 和 task_type。record_date 是工作发生的日期，task_type 是任务类别，比如“需求开发”“Bug修复”“会议沟通”。这两列在项目管理中经常用来做交叉分析，比如“这个月花了多少时间在修Bug”、“哪个人投入需求开发的比重大”。
填报页面流程是这样：用户先选择任务，再选择日期，填写工作内容和工时，提交后数据状态为 PENDING。这里最关键的约束是同一用户、同一任务、同一天只能有一条有效填报记录，否则统计会出现重复数据。我除了在代码里查询前先做存在性判断之外，还在数据库层面加了唯一索引：
sql复制ALTER TABLE workload_record
ADD UNIQUE KEY uk_user_task_date (user_id, task_id, record_date, status_flag);
等等，这里有个问题：如果状态从 PENDING 变成 REJECTED 后用户需要重新提交，唯一索引会限制插入。所以我实际并没有把 status_flag 放进唯一索引，而是设计成：驳回的记录逻辑删除，重新提交时生成新记录，通过一个 parent_id 指向被驳回的原记录。这个方案保证了数据的可追溯，也避免了唯一索引失效。
审批逻辑用状态机来理解最清晰。主管点击“通过”，后端代码执行一个条件更新：只允许状态是 PENDING 的记录被改成 APPROVED。SQL 大概是：
sql复制UPDATE workload_record
SET status = 'APPROVED',
audit_user_id = #{auditUserId},
audit_time = NOW(),
audit_remark = #{auditRemark}
WHERE id = #{recordId}
AND status = 'PENDING'
这样写有个天然的好处，两个主管同时审批同一条记录时，只有一个 update 会成功，另一个影响行数为 0，再根据影响行数提示“记录已被处理”。不需要额外加锁，也不用 Redis 分布式锁，代码简单且不会出并发问题。
3.4 工作台：让三类角色各看各的界面
系统登录后根据角色不同跳转到不同的工作台。普通员工看到的是“我的任务”和“我的填报”，能按日期快速填写今天的工作量，也能看到自己哪些填报被驳回以及驳回原因。主管端看到的是“部门任务”和“待审批列表”，可以把待审核的记录列表按提交人和日期排序，逐条审核。管理员端则多出用户管理、角色配置和全局统计。
填报页面有个体验优化的点特别值得一提：用户经常忘记前几天干了什么。我就在填报页默认展示了最近的待确认任务列表，并附上任务名称和截止时间作为提示。这项改动上线后，漏填率明显下降。
统计报表默认布局是“按人看整体贡献”：每人当月填报总次数、总工时、已完成任务数、驳回次数。再加两个维度：按项目统计工时占比、按任务类型统计工时分布。这三张报表刚好回答管理层日常最爱问的三个问题：谁干得多？活都花在哪个项目上？时间都去哪了？
4. 统计报表与数据可视化实现
4.1 核心统计SQL的设计思路
报表功能我没有依赖第三方 BI 工具，直接用后端 SQL 聚合后把结果返回给前端渲染图表。最基础的“个人工作量汇总”查询大致长这样：
sql复制SELECT
u.real_name,
COUNT(DISTINCT wr.task_id) AS task_count,
ROUND(SUM(wr.work_hours), 2) AS total_hours,
COUNT(wr.id) AS record_count,
SUM(CASE WHEN wr.status = 'REJECTED' THEN 1 ELSE 0 END) AS rejected_count
FROM workload_record wr
LEFT JOIN sys_user u ON wr.user_id = u.id
WHERE wr.record_date >= #{startDate}
AND wr.record_date < #{endDate}
GROUP BY u.id, u.real_name
ORDER BY total_hours DESC
这里日期过滤条件我采用了大于等于开始日期、小于结束日期的方式，而不是 BETWEEN AND。用 BETWEEN 在 MySQL 中如果 record_date 是 datetime 类型，很容易把最后一天凌晨的数据漏掉，或者因精度问题导致月底数据被划到下个月。和“时间范围”相关的问题都是这样解决最稳妥，这也是后来排查几天统计数据对不上的关键经验。
按周汇总时还涉及一个常见的业务规则：一周从周一开始还是从周日开始。不同团队的定义可能不同，这个不能拍脑袋写死在SQL里，我单独做了一个配置项，由管理员在系统设置里选，统计时用 Java 端算好每一周的起止日期，再传入 SQL 作为过滤条件。
4.2 报表查询慢的优化路径
报表上线一段时间后，workload_record 表的数据量涨到几十万行，按用户维度统计的接口开始出现明显延迟。第一次优化直接对 (user_id, record_date) 和 (task_id, record_date) 两个组合加了联合索引。加了之后发现效果没有想象中明显，用 EXPLAIN 一下才知道，问题出在统计时经常做 LEFT JOIN sys_task 取项目名称。于是我在 workload_record 表里直接冗余 project_name 字段，避免关联任务表。
后续又做了一次更大的优化：把高频汇总结果落地到 workload_report_summary 汇总表。每天晚上由定时任务把前一天的填报数据按“用户+日期+任务类型”维度预先聚合，报表查询只查汇总表。刚开始数据量小，所有统计走实时计算完全没问题；一旦数据量大起来，这种“有人查就算一遍”的做法会白白浪费数据库资源。汇总表方案很土，但真的很有效，让报表接口的响应时间从三秒降到了三百毫秒以内。
5. 后端开发中的典型坑与排查记录
5.1 事务失效：工作量填报保存了一半
系统实现时最严重的一个线上Bug：填报工作量保存接口，用户在本地测试时发现能成功插入到 workload_record，但操作日志表里没有记录。查了下日志，服务方法里抛了异常但数据却插进去了。原因很经典：我在一个私有方法里加的 @Transactional，Spring 事务是基于代理实现的，私有方法不走代理，事务注解自然失效。另外还有一处是在同一个类中通过 this 调用另一个带事务方法，同样失效。
修正方案就是事务方法必须走 public 修饰的入口，且通过注入自身代理或者拆到另一个 Service，让外部调用者触发事务切面。再一个教训是代码里不能用 try-catch 吞掉异常后只打印日志不放回，这样也会导致事务感知不到异常而提交成功。现在我的习惯是：在事务方法内部不自己 catch 异常，统一由 Service 层往外抛，Controller 层通过全局异常处理器捕获并转换返回结果。
5.2 审批并发：两个人同时点击通过
这个坑是测试同事发现的。测试环境里用两个浏览器分别登录同一个主管账号，同时点击同一条填报记录的“通过”按钮，最后发现这条记录状态变成了 APPROVED，但后端日志显示有两个成功的更新操作。原因是我最开始实现审批时先查一次状态，判断是 PENDING 再执行 UPDATE，这属于典型的 check-then-act 竞态条件。两个并发请求同时查到了 PENDING，然后都能进入更新分支。
解决办法就是前文提到的条件 UPDATE，把状态判断并入 update 的 where 条件，通过 update 返回的影响行数判断是否有人抢先操作。这种操作方式在库存扣减、金额变动、审批这类并发敏感的操作中通用，建议大家都养成这个习惯：能用一个原子条件更新实现，就不要先 SELECT 再 UPDATE。
5.3 跨天任务导致统计偏差
有个现象是员工在周一上午填写上周五的工作量时，系统默认把 record_date 设置为当天，导致数据被统计到下一周。这是填报页默认值的锅。修复方式是在填报工作量时默认取“任务最近活跃日期”，而不是系统当前日期。用户可以通过日期控件修改，但如果任务压根是新建的，就默认选择今天。
统计侧的另一个经验是，所有跨周/跨月/跨年的统计代码，都不要用 Java 里的 WEEK_OF_YEAR 去算周，不同地区对一周起始日的定义不一样，很容易出现在 12 月底和 1 月初出现 53 周、第 1 周等边界问题。我的方案是写一个统一 DateRangeUtil，传入日期返回所在的周一和周日，所有模块都用同一个日期工具方法，避免口径不统一。
5.4 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 登录接口报401，但密码明明正确 | 用户状态是禁用 | 查看 sys_user.status 状态 |
| 填报保存时报唯一键冲突 | 同一用户同一任务同一天已有记录 | 先查后插，并用唯一索引兜底 |
| 统计数字和Excel核对总对不上 | 时区或日期边界问题 | 统一切换到 Asia/Shanghai 时区，日期条件用 >= start AND < end |
| 上报列表页面很慢 | 列表查询条件没走索引 | EXPLAIN 看执行计划，给 user_id/record_date 建联合索引 |
| 前端上传工作量列表Token失效 | token 过期时间过短 | 改为剩余30分钟内自动续期 |
| 审批通过后列表仍显示待审核 | 前端页面缓存 | 清一下页面缓存或检查接口请求是否有CDN缓存 |
6. 源码部署与二次开发要点
6.1 本地环境要求与启动步骤
项目源码要顺利跑起来，建议严格按照下面的清单核对环境，特别是数据库脚本导入顺序不要乱：
- JDK 1.8 及以上
- Maven 3.6 以上
- MySQL 5.7 / 8.0
- Redis 5.0 以上（如果开启了缓存功能，部分功能依赖 Redis）
- IDEA 或 Eclipse
把源码导入 IDE 后，先执行工程根目录下 doc 文件夹里的 schema.sql 和 data.sql，前者是建表语句，后者是初始数据，包括管理员账号、角色和基础字典。然后修改 application.yml 里数据源和 Redis 配置：
yaml复制server:
port: 8080
spring:
datasource:
url: jdbc:mysql://localhost:3306/workload_system?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
data:
redis:
host: localhost
port: 6379
mybatis-plus:
mapper-locations: classpath*:mapper/**/*.xml
configuration:
map-underscore-to-camel-case: true
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
启动类和普通 Spring Boot 工程一致，直接运行 WorkloadApplication main 方法。前端工程在 frontend 目录下，先 npm install，然后 npm run dev 本地启动，默认端口一般是 9528。需要留意的是前端里 src/config/index.js 里的后端接口地址和 Nginx 转发规则要对应起来。
文档包里自带了一份配置说明和使用手册，内容包括接口文档、数据库表结构说明、页面操作指引。数据库脚本里内置的初始密码建议登录后立即修改。
6.2 源码二次开发建议与扩展方向
这个系统后续的扩展空间主要是三个方向：对接公司现有账户体系、引入自定义表单、增加更复杂的工作流审批。源码层面需要改动的地方我认为都还比较清晰：如果要对接企业微信或钉钉，只需要在 AuthInterceptor 之前增加一个 OAuth 登录入口，登录成功后生成与系统内部 user_id 关联的 token，现有 JWT 解析逻辑不需要动。
如果想把“任务派发”延展成项目的 WBS 分解模式，可以考虑引入工作流引擎类似 Flowable，但这里我必须提醒一句：工作量统计系统的业务核心是数据和审批，不是流程流转，不要一上来就上重工作流引擎，先用状态机字段就能解决 80% 的流程场景。
还有个小建议，如果公司内部想把这套源码作为新手学习素材，最值得看的代码不是 Controller 层的 CRUD，而是 workload_record 的唯一索引设计、审批流程状态机处理方式和统计 SQL 的日期边界写法。这三处是区分一个项目是否有工程经验的关键点。我见过太多学习项目里把状态判断写在前端，后端接口任何人都能直接调，这是非常危险的。把数据完整性和权限校验放在后端，是任何管理系统开发的基本功。
这套系统做下来，我最大的体会是：工作量统计从来不是技术难题，而是管理口径的抽象难题。技术方案再华丽，如果业务上说不清“什么算工作量、以谁的数据为准、审核不过怎么处理”，系统做出来也只会是数字搬运工。开发之前一定要和业务方对齐这几个关键口径，再动手画表结构，代码实现反而是水到渠成的事。源码包已经整理好，里面附带数据库脚本和完整文档，拿到手按步骤启动，大概半小时能跑通全流程。