从零构建内部任务与工时追踪系统：立项、选型到踩坑复盘

001项目总结终于能写出来了。这个代号001的项目，实际是我接手团队内部第一个完整从立项、开发、测试、上线走完全流程的工具型项目。说“完整”其实有点心虚，因为中间踩的坑比预想的多得多，光是有记录的反复排查就占掉了三分之一的开发时间。但也正因为踩过这些坑，我觉得这个项目总结值得认真写一写。

这个项目本身不复杂，目标是做一个内部用的任务与工时追踪小系统，用来替代我们团队一直在用的共享表格。一开始的需求清单长得吓人：任务看板、甘特图、消息提醒、移动端适配、周报自动生成……后来真正做进去才发现，很多功能只是“看起来重要”。如果你正在带一个小团队，或者准备从零做一个内部工具，这篇文章可以供你参考：它覆盖了立项、选型、开发、踩坑、上线、复盘这条完整链路，也写清楚了很多环节背后的取舍逻辑。

1. 立项起点：001项目到底要解决什么问题

1.1 项目背景与核心痛点

我们这个项目启动的导火索很朴素：团队一直用共享表格记录每个人的任务和工时，每个月月底做统计的时候，问题集中爆发。表格里同一个人的名字能有三四种写法，任务状态标的乱七八糟，有人填了工时却没写对应任务，有人写了任务描述但忘了填时长。负责整理的人每个月都要花大半天在清洗数据上，还经常被同事质疑统计结果不准。

痛点其实就一句话：登记和统计两条链路都完全依赖人工，缺少约束和反馈机制。表格不能强制必填项，不能限制枚举值，也不能自动提醒“你这个任务还没填工时”。所以我们决定做一个轻量的内部系统，目标非常具体：让每个成员每天花不到一分钟完成登记，月底统计时点一个按钮就能得到准确结果。

这个目标听起来平淡，但它决定了后面所有设计的方向。我们不需要一个复杂的项目管理工具，我们需要的是一个“数据入口规范、统计口径统一、权限边界清晰”的记录系统。

1.2 需求取舍与验收标准

立项讨论时，团队提了一堆功能，第一版清单大概有十多项。后来我们用了两个维度做减法：使用频率高不高？没有它会不会导致现有流程跑不下去？

最终砍到只剩四个核心模块：

• 任务登记与状态流转（待处理、进行中、已完成、已取消）
• 工时记录（按任务、按日期追加记录）
• 统计报表（按成员、按任务、按月汇总）
• 基础权限控制（普通成员和管理员的查看范围区分）

甘特图是第一刀砍掉的。不是因为不需要，而是因为团队现在根本没有人和精力去维护计划日期，先把执行真实情况记录下来才是基础。移动端适配也砍了，内部团队成员都用电脑办公，先做桌面端足够。

验收标准我们当时写得很朴素，却直接决定了测试方案：

• 本月最后一个工作日以前，系统能生成上月整月的工时统计报表；
• 报表数据与成员实际填报工时完全一致；
• 普通成员只能查看自己的任务和工时，管理员可以查看全部；
• 整个统计流程不需要人工复制粘贴或修改数据。

1.3 里程碑安排

因为是内部项目，我们按周分任务，没有做很重的项目管理流程。实际排期如下：

阶段	时间	工作内容
需求梳理	第1周	访谈团队日常登记习惯，确定功能清单与验收标准
原型设计	第2-3周	画页面草图、确定数据模型、设计接口草案
开发实现	第4-6周	前后端并行开发，核心接口先联调
测试修复	第7周	内部试用、Bug修复、补测试用例
灰度上线	第8周	组长先试用，再放开全员

现在回头看，这个排期最大的问题是我低估了测试修复的耗时，第7周实际上是连轴转的一周，每天都能收到新问题。后面我会专门讲其中的典型坑。想提醒的是：内部项目如果时间排得太满，灰度期就很容易变成另一个开发期，一定要留缓冲。

2. 技术方案选型与整体设计

2.1 选型思路

技术选型这件事，内部工具和对外产品有本质不同。对外产品要考虑团队长期演进、招聘成本、流量体量；内部工具就一个原则：团队里维护的人最少、上手最快、最容易排查问题的方案就是好方案。

我们最终选定的组合是：

• 服务端：轻量的 Python 服务框架，逻辑简单，生态成熟；
• 前端：Vue 加现成的组件库，开发速度快；
• 数据库：PostgreSQL，因为报表统计涉及聚合查询，PostgreSQL 的日期函数和窗口函数写起来很顺手；
• 部署：Docker Compose 跑在团队一台小主机上，配置简单，也能隔离环境差异。

这个组合没有什么炫技成分。团队维护者一共三个人，Python 和 Vue 大家都有基础，Docker Compose 也是现成的实践。如果用过于复杂的微服务架构或消息队列，对这个项目就是纯负担。

2.2 数据模型设计

数据模型是整个项目最值得花时间的地方。我见过太多项目在界面上折腾了半天，最后卡在表结构上重新改。我们第一版的数据表设计分成三张核心表和一个扩展表。

用户表，主要字段：

• id
• 姓名
• 角色（普通成员 / 管理员）
• 所属组
• 状态（启用 / 停用）

任务表，主要字段：

• id
• 标题
• 描述
• 指派人
• 状态（待处理 / 进行中 / 已完成 / 已取消）
• 优先级
• 截止日期
• 创建人
• 创建时间
• 更新时间

工时记录表，是这个项目最核心的表：

• id
• 任务id
• 用户id
• 记录日期
• 工时分钟数
• 备注
• 创建时间

最初我们差点把工时记录直接塞进任务表，每一行任务带一个“工时”字段。后来提前推演了一下统计场景才改过来：如果业务上需要统计某个成员某个月在某个任务上投入了多少时间，把工时间内嵌任务表会非常难查。拆成独立的工时记录表后，每次填写都是插入一行新记录，统计时按用户、任务、月份做分组聚合就可以，语义非常清晰。

这算一个很基础的设计决策，但它在后来避免了好几次“改表”的灾难。

2.3 服务端接口与权限设计

接口设计遵循了最简单直接的方式：按资源划分接口，写操作统一走事务。

文档里我们定义了下面几组接口：

• 任务接口：创建任务、更新任务状态、修改任务字段、查询任务列表
• 工时接口：添加工时记录、查询我的工时记录
• 报表接口：按月生成成员工时汇总、按任务汇总工时
• 用户接口：登录、获取当前用户信息、管理员管理成员

权限上只分两个层级。普通成员登录后只能访问“自己的任务”和“自己的工时”，管理员可以查看全部数据，并在报表页面按成员筛选。权限校验在接口层做统一拦截，前端菜单也会根据角色隐藏入口，但真正的控制完全以后端为准。

这个统一拦截看起来很简单，实际非常重要。很多内部系统管不住权限，就是因为觉得“页面隐藏了就行”，但接口一旦被人猜到并直接访问，数据就裸奔了。我们专门写了一个小的依赖函数，所有需要登录态的接口直接调用，从源头堵住漏配的可能。

2.4 前端页面结构

前端一共三个主页面，没有多余导航。

任务看板页：按状态分列展示任务卡片，支持拖拽变更状态。这个页面最耗精力的是拖拽后的排序权重问题，如果不维护一个 order 字段，卡片拖到中间位置就会乱跳回末尾。我们后来在任务表里加了一个 sort_order，拖拽完成后一次性批量提交所有卡片的新顺序。

工时记录页：默认展示当天的任务列表，旁边加上“记录半小时”“记录一小时”的快捷按钮；另外提供一个补录入口，允许选择过去七天内的日期进行补填。这个补录场景是真实需求，周五忘记填的人很普遍。

统计报表页：默认显示当月统计表，支持切换月份，管理员可以按成员筛选。表格每一行是一个成员对一个任务的合计工时，最后一行是总计。

3. 开发落地：核心功能实现的过程与要点

3.1 任务状态流转的实现细节

任务状态看起来只是四个枚举值，但边界条件必须提前定清楚，否则就是无数个隐藏Bug的来源。

我们定义的流转规则是：

• 待处理 → 进行中
• 进行中 → 已完成
• 进行中 → 待处理
• 已完成 → 进行中（表示重新打开）
• 待处理 → 已取消
• 已取消 → 待处理

这里有一个关键约束：已完成的任务不能直接变成已取消，已取消的任务也不能直接变成已完成。原因很简单，如果允许任意跳转，月底统计报表里就会出现状态矛盾的数据，比如同一个任务既“已完成”又“已取消”。所以后端在更新状态时不是简单赋值，而是先判断当前状态和目标的组合是否在允许的流转集合里。

前端卡片拖拽也是调用同一个接口，接口返回业务码提示“不允许的流转关系”，卡片会自动回弹原位置。这个小细节能避免用户误操作以后对着列表困惑。

3.2 工时记录模块：补录与防覆盖

工时记录模块的核心操作是“插入而非更新”。我们设计了一个很明确的约束：同一个人、同一个任务、同一天可以多次记录工时，每次都是新增一行，而不是覆盖之前的值。

为什么这么设计？因为实际使用场景里，一个人在某个任务上投入的时间本来就可能是分段的。上午做了两小时，下午又做了一小时，如果只允许一条记录，就需要用户反复修改“总工时”，很容易改错。拆成多条记录后，每一次提交都保留独立的时间戳和备注，统计时再聚合，账目最清楚。

这是我个人在这个项目里最认可的一个决定。它避免了并发覆盖问题，也给后续统计留了更细的粒度。

3.3 统计报表的SQL与聚合逻辑

报表模块写起来并不复杂，但特别容易在细节上出错。月度统计的核心SQL长这样（以PostgreSQL为例）：

SELECT u.name AS user_name, t.title AS task_title, SUM(r.minutes) / 60.0 AS hours, COUNT(r.id) AS record_count FROM work_records r JOIN users u ON r.user_id = u.id JOIN tasks t ON r.task_id = t.id WHERE r.record_date >= DATE_TRUNC('month', CURRENT_DATE) AND r.record_date < DATE_TRUNC('month', CURRENT_DATE) + INTERVAL '1 month' GROUP BY u.name, t.title ORDER BY u.name, hours DESC;

这里有两个容易踩的坑，我先说给可能照着写的朋友。

第一个坑：时间范围判断。如果直接用日期字段做等值匹配，月末最后一天的数据极可能漏掉，因为跨月的边界条件很多人写不好。我习惯用“大于等于月初且小于下月初”这种左闭右开区间，能避开当天零点附近的数据边界问题。

第二个坑：工时单位。我们一开始让用户按“小时”填，前端可以输入0.5、0.25这类小数，数据库字段用的浮点数。结果累计之后出现了0.699999999这种数字，报表显示非常难看。后来改成分钟整数存储，前端展示时才转成小时，彻底解决了精度问题。

3.4 写操作的事务与统一返回结构

内部工具虽然并发量不大，但写操作的事务保护不能省。所有新增任务、更新状态、添加工时记录，后端都在一个事务上下文中执行，任何一个步骤失败就整体回滚。

接口返回结构也做了统一，格式固定为：

{ "code": 0, "message": "success", "data": {} }

错误时 code 返回对应业务码，message 给出人能看懂的原因。前端拿到 code 不为0时统一弹出提示，不会因为某次请求失败导致页面白屏或数据丢失。这个小约定让前后端联调快了很多，不需要各自猜返回格式。

4. 踩坑记录：三个最有代表性的问题排查链路

4.1 并发写入导致工时记录被覆盖

上线后第一周，我们收到反馈：两个同事几乎同时给同一个任务补录当天工时，后保存的那个把前一个的记录覆盖了。

我排查这个问题花了一个下午。第一反应是并发锁问题，但看数据库锁日志没有异常。接着我打开后端日志，发现一个关键现象：每次保存前端提交过来的不是一个“新增记录”动作，而是一个“完整对象保存”动作。后端的处理逻辑带了UPDATE语义，它先按“用户+任务+日期”查找已有记录，找到就直接更新，没找到才插入。

而前端为了省事，把单条记录当成了“可编辑的表格行”。也就是说，用户在页面上看到之前有人填过，就以为可以改，改完提交后系统不是新增，而是把同条件下原记录整体覆盖掉。

解决方案分两层。数据层：禁止在这个场景下做UPSERT，工时记录只允许INSERT，后端如果收到带id的保存请求就直接拒绝。统计层：增加了一条数据校验规则，每天每个任务每个成员最多只能有一条“系统自动生成”的初始记录，如果出现多条，说明需要人工关注。

这个问题教育了我一个原则：写代码前先想清楚“你的接口是幂等更新还是新增事件”，数据类型定错了，后面所有排查都会被带偏。

4.2 月中报表和月底对不上

第二个坑更隐蔽。月中我们截图发的统计报表，数字和月底最终报表差了0.5小时。大家一开始互相怀疑有人补录没通知，后来查下来发现是典型的浮点误差累积。

我们最初的工时字段是“小时”，数据库类型是浮点数。用户在页面上填0.5，计算之后变成0.50；填0.1，二进制存储会变成0.10000000000000001。单条记录误差微乎其微，但一个成员一个月积累几十条记录，舍入误差就可能在末位显示成0.9999或1.00001，报表格式化后视觉上对不上。

另外还有一个重复统计问题。状态变成“已完成”后，成员又“重新打开”并补录了工时，这时候如果报表逻辑简单地按月、按任务分组求和，就会把前后两段重复算进去。我们后来加了明显的历史记录标识，只统计“非已取消”且“最新状态”对应的有效记录。

这个坑让我以后形成了一个习惯：凡是跟金额、工时、库存相关的字段，一律用整数最小单位（分钟、分、克等）存储，永远不在数据库里存带小数的“展示单位”。

4.3 开发机正常但服务器部署失败

开发阶段一切正常，docker-compose 在本地一拉就跑。结果部署到团队那台小主机上，第一件事就翻车：中文乱码、数据库连接超时、静态文件加载不出来，三个问题同时冒出来。

排查顺序很重要，我当时是这样一步步缩小的：

• 第一步：看后端主日志，发现数据库连接报错，提示字符集不匹配；
• 第二步：用命令行工具直接连数据库，执行查询正常，但查看数据库默认编码发现不是UTF8；
• 第三步：对比本地和服务器环境，发现docker-compose.yml里数据库服务少了字符集环境变量，本地因为镜像缓存默认值碰巧正常，服务器上的基础镜像版本不同，默认字符集就暴露了问题；
• 第四步：再检查代码里的路径配置，发现有个模块读取配置文件时用了写死的本机绝对路径，容器里当然找不到这个路径，导致整个服务启动了一半就挂了。

最后我们把所有环境相关配置全部改成从环境变量读取，并通过部署脚本统一注入；docker-compose文件里显式设置字符集和时区；启动流程加了健康检查，前端页面能正常返回后才标记服务可用。

这类“换台机器就坏”的问题，根因大概率是环境配置不是显式依赖。内部项目更要养成习惯：写死路径和默认值看似省事，后面排查就是浪费时间。

5. 测试、灰度上线与运维保障

5.1 测试用例设计与自动化程度

内部项目没有条件做完整自动化测试，但至少把核心链路的手工测试用例做到了可重复执行。我们整理了一张测试矩阵，每次发版前按表跑一遍：

用例编号	场景	操作步骤	预期结果
TC01	任务创建	新建任务并指定负责人和截止日期	任务出现在看板的待处理列
TC02	状态流转	将待处理任务拖到进行中	状态更新且看板卡片位置变化
TC03	非法流转	将已完成任务直接拖到已取消	系统拒绝并提示流转规则
TC04	工时登记	对某任务添加30分钟记录	统计报表该任务总工时增加30分钟
TC05	跨天补录	补录3天前的工时记录	补录成功且月度统计中包含该数据
TC06	权限隔离	普通成员修改他人任务	接口返回无权限错误
TC07	报表导出	生成上月统计表格	数据与明细记录逐条核对一致

这个表看着简单，实际价值非常大。团队后来新增功能时，都靠它做回归，避免“改好一个功能弄挂一个旧功能”的尴尬。

5.2 灰度上线方案与回滚计划

因为用户全是内部成员，灰度发布不需要搞很重的规则，但节奏必须有。

我们的方案分三步：

• 第一步：只开放给三位组长试用，每天收集反馈，重点关注统计报表数据是否准确；
• 第二步：一周后开放给全团队，但只用来登记新任务，不要求历史数据一次性迁移；
• 第三步：跑完一个完整的月底结算周期后，确认报表数据和人工统计一致，再宣布系统正式启用。

灰度期间如果发现严重问题，我们已准备好回滚：服务上一版本的镜像还在Docker仓库里，直接切换回旧容器即可。因为数据全部存在PostgreSQL里，回滚不会丢数据，最多是页面功能回到旧体验。

这里值得强调的是，内部小系统也要保留回滚能力。不要觉得就几个人用，出了问题现场改就行。真到月底统计当天出了错，你会发现“快”比“完美”重要得多。

5.3 监控与备份的落地

内部工具我们没上复杂的监控系统，只做了三件最基础的事：

• 每天早上检查服务端口是否正常响应；
• 数据库每天凌晨3点做一次全量备份，保留30天，备份文件放在另一块磁盘；
• 接口错误日志按天滚动，保留14天，方便出问题时回溯。

备份命令很简单，用的就是PostgreSQL自带的备份工具，定时任务写好之后不用人管。有一次真的派上了用场：某个晚上我们改脚本误删了一张配置表，第二天早上发现后直接从备份恢复到凌晨状态，只丢失了当晚添加的少量临时配置，影响可控。

很多内部项目死就死在“觉得不用备份”，一旦出了问题，之前所有补救手段都不存在。备份占用的磁盘可能就几个GB，但它是系统信任感的底线。

5.4 用户反馈的主动收集

上线不等于结束，这是这个项目给我最深的体会之一。用户反馈不会自动跑来找你，尤其是内部工具，很多人遇到小问题宁愿忍着也不提。

我们在前两周做了几件事：每天下午在团队群里发一条消息，问“今天系统有没有让你觉得卡壳的地方”；每周约两位成员做一次五分钟的短访谈，带他们实际操作一遍最常用的流程，观察哪些动作犹豫了、哪些按钮找不到。

用这种方法，我们发现了一个被人忽视的小问题：工时记录页面的“补录入口”藏得太深，很多用户以为只能记录当天。改成一个更显眼的按钮后，补录使用率立刻上升，月底数据少填的问题明显减少。

6. 项目复盘与后续演进建议

6.1 复盘会上我们总结的几条经验

项目正式稳定运行后的第二周，我们开了一次复盘会。没有走形式，就是对着开发记录一条条过，最终沉淀下来几条自己认账的经验：

• 需求范围要严格，先做最小可用版本。甘特图和移动端如果第一版就做，上线时间至少要拖一个月；
• 测试时间不能砍。第7周几乎每天都在修复中度过的苦，源头是开发期把接口自测压缩得太少；
• 数据模型比界面更重要。工时记录表独立设计和分钟整数存储，这两个决定让后面所有统计都轻松了；
• 日志要早打。很多问题复盘时才想起来，如果当时有详细的请求日志，定位时间至少减半。

6.2 沉淀下来的可复用资产

项目带给团队的不止一个工具，还有一批可以复用的资产：需求文档模板、接口返回规范、测试用例矩阵、Docker部署脚本、月度报表的SQL片段。这些东西现在都放在团队的知识库里，后续再做内部工具可以直接引用。

尤其值得说的是接口返回规范。它本来是这个项目里随口定的约定，后来成了我们内部所有小工具的默认标准。新成员接手时不需要重新理解接口格式，沟通成本降了不少。

6.3 下一步的功能规划与优先级

001项目稳定之后，我们列了下一个版本的候选需求，按使用频率重新排了优先级：

• 周报自动汇总（每周五下午定时推送，直接替代手动整理）
• 任务超期提醒（超过截止日期自动标注红色）
• 移动端简单查看（只读模式，方便不在工位时确认状态）
• 更自由的自定义标签（按成员需要打上“会议”“沟通”“编码”等分类）

这里我想提醒的是，规划后续功能时不要迷信“技术难度”，要看团队实际使用习惯。我们一开始觉得移动端重要，但调研下来大家最烦的是每周手动写周报，所以把周报自动汇总排到了第一。

6.4 写给后续接项目的人

最后说点实在话。如果让我重新做一遍001项目，我会在立项当天就把数据模型画出来，把测试用例写出来。这两件事做在前面，后面能少加班两周。数据模型决定了系统能长多大，测试用例决定了你能不能放心改代码。

内部工具项目不会像对外产品那样光鲜，但它的价值恰恰在于贴身解决真实问题。只要团队成员每天愿意打开页面登记，说明它真的做到了“好用”。001项目就是这样一个起点，它不复杂，但它把流程走全了，把坑踩明白了，这就很值得。