工时无忧系统 V4.7 — TAPD 工时填报

概述

一键式 TAPD 工时填报工具，将「逐天手动填写」升级为「选择周期 → 配置任务 → 一键提交」的批量工作流。

版本记录

• 4.7（2026-07-05）：修复重试时重复提交已成功工时；新增提交锁、超时待核验状态、TAPD 业务响应校验、代理输入校验与路径白名单；增加前端、代理和 HTTP 回归检查。
• 4.6.1（2026-06-22）：初始 SkillHub 发布版。

⚠️ 重要：这是一个本地 HTML 文件应用，不是托管网站，也不是 CLI 命令行工具。每次使用时需要：
1. 打开 tapd-timesheet-v4.html（浏览器直接打开或用 HTTP 服务器托管）
2. 确保 tapd_proxy.py 代理服务器在后台运行（用于提交/删除工时到 TAPD API）

快速上手：一个完整示例

> 场景：今天是周一，你需要填报上个月的工时。

Step 1 — 启动代理（终端）

cd assets/
python3 tapd_proxy.py
# 看到 "✅ TAPD 代理服务已启动: http://127.0.0.1:8899"

Step 2 — 打开页面
浏览器打开 tapd-timesheet-v4.html

Step 3 — 配置令牌
- 点击右上角头像「邵」→ 令牌配置
- 填入 TAPD 个人访问令牌（Bearer Token）
- 修改姓名为你的名字 → 保存

Step 4 — 选择周期
- 在「工时周期」卡片中，点击「上月」快捷按钮
- 日历自动显示上个月所有工作日
- 检查并取消选中请假/放假的日子

Step 5 — 保存周期
- 点击「保存周期」按钮
- 状态栏显示「● 已保存」

Step 6 — 配置任务
- 在「任务管理」卡片中，输入任务ID（19位数字）
- 填写工作内容「前端页面开发」
- 精力%保持100

Step 7 — 保存任务
- 点击「保存」→ 条形图自动展示

Step 8 — 生成预览 & 提交
- 点击「生成预览」→ 弹窗显示每日工时明细
- 确认无误 → 点击「提交到 TAPD」
- 进度弹窗逐条展示 → 完成

界面元素对应关系

文件结构

assets/

• tapd-timesheet-v4.html — 单文件前端应用（HTML + CSS + JS）
• tapd_proxy.py — Python 本地代理服务器（转发 TAPD API 请求，解决 CORS）
• TAPD工时填报系统_PRD.md — 产品需求文档

核心功能

边界 & 限制

本系统能做什么

• ✅ 批量填报「任务」类型工时到 TAPD
• ✅ 按工作日自动排除周末和法定假日
• ✅ 多人任务精力%分配 + 工时计算
• ✅ 提交后历史记录查看 + 作废（删除 TAPD 记录）

本系统不能做什么

• ❌ 不支持多人协作 — 单用户本地工具，不支持共享配置或多人同时使用
• ❌ 不支持非任务实体 — 仅支持 entity_type: 'task'，不支持需求/缺陷等类型
• ❌ 不支持修改已提交记录 — TAPD 不支持直接修改，只能「作废 → 重新提交」
• ❌ 不自动拉取 TAPD 已有工时 — 仅单向写入，不提供 TAPD 侧已填工时的双向同步
• ❌ 不自动更新节假日 — 内置2024-2027国务院放假安排，过期需手动更新代码中的 holidays 数据
• ❌ 依赖本地代理 — 必须运行 tapd_proxy.py 才能提交/删除工时
• ❌ 不支持移动端 — 未适配移动端布局，主力场景为桌面浏览器

常见问题 & 反模式（FAQ）

Q1: 如何撤销/作废已提交的工时？

A: 右上角头像 → 历史记录 → 勾选要作废的记录 → 点击「批量作废」。系统会调用 TAPD API 真实删除工时记录（POST /proxy/timesheets_delete.json），本地标记为「已作废」。

Q2: TAPD Token 在哪里获取？401 错误怎么办？

A: TAPD 右上角头像 → 我的设置 → 个人访问令牌 → 创建。注意：
- 复制完整的 Token 字符串
- 本系统使用 Bearer 认证方式，无需加前缀
- 如果 Token 泄露，请及时在 TAPD 中撤销
- 401 错误通常表示 Token 无效或已过期

Q3: 提交失败，提示 "The access token provided is invalid"？

A: 依次排查：
1. Token 是否复制完整（开头是否有空格）
2. Token 是否在 TAPD 后台已被撤销
3. 代理服务器 tapd_proxy.py 是否正常运行（查看终端日志）
4. 检查浏览器控制台 Console 日志，查看具体请求/响应

Q4: 提示 "workspace_id 不匹配"？

A: 系统从 19 位任务 ID 中自动提取中间 8 位作为 workspace_id。请确保：
- 任务 ID 为 19 位纯数字
- 该任务属于你当前配置的 TAPD 项目

Q5: 提交时提示 "网络错误，请检查代理服务器是否运行"？

A: 确保 tapd_proxy.py 已在终端启动，且端口 8899 未被占用。可以尝试：

curl http://127.0.0.1:8899/proxy/timesheets.json -X POST -H "Content-Type: application/json" -d '{}'

如果返回结果而非连接失败，则代理运行正常。

Q6: 保存任务时提示 "精力合计需=100%"？

A: 确保所有任务的精力%加起来等于 100。添加新任务后，系统会自动计算剩余精力给第一个任务。常见的错误是新增了任务但没填精力值。

Q7: 提示 "以下日期没有任务覆盖"？

A: 每个任务都有独立的「日期范围」。如果某天没有任务覆盖该日期，系统会拦截保存。解决方案：
- 手动调整任务的开始/结束日期，确保覆盖周期内的每一天
- 如果想精简单个任务覆盖整个周期，无需修改（默认继承周期范围）

Q8: 修改了周期日期，为什么任务日期没变？

A: 保存周期时，系统会自动刷新所有任务的日期范围为当前周期的工作日起止日。如果修改后发现任务日期不一致，请重新「保存周期」触发刷新。

Q9: 提交成功了但 TAPD 页面没看到数据？

A: 通常原因：
- Token 权限不足（该用户不是项目的成员）
- workspace_id 提取错误（检查任务 ID 是否 19 位）
- 提交到了错误的项目（检查 workspace_id 对应的项目）

Q10: 如何删除代理服务器日志？

A: 终端输出在屏幕中，Ctrl+C 停止服务后重新启动即可。代理没有写日志文件。

技术细节

• 代理服务器：http://127.0.0.1:8899，转发 POST /timesheets.json 到 api.tapd.cn
• 删除工时：POST /proxy/timesheets_delete.json（内部 _method=delete）
• 认证方式：Bearer Token（TAPD 个人访问令牌）
• 前端缓存：预览结果缓存至 S.sheetsValid，避免重复计算
• 数据持久化：localStorage（令牌、人员、历史记录）
• 节假日数据：内置 2024-2027 国务院放假安排，动态获取会降级回本地数据

质量检查

修改前端提交逻辑或 Python 代理后，必须运行：

sh tests/run_checks.sh

检查内容包括：Python 语法、TAPD 成功/业务失败/超时分类、响应 ID 解析、前端 JavaScript 语法、仅重试明确失败项、防重复提交和结果待核验状态。

常见错误码对照