linzelong/G41_TAPD_BUG_SYNC

Fork 0

zelong 6e51a505bd 'phase3'

2025-12-17 15:50:12 +08:00

20 KiB

Raw Blame History

Debug阶段自动开单工具 - 开发路线

一、项目概述

本项目旨在实现一个自动化工具，从腾讯智能表格读取bug信息，自动在TAPD创建bug单，实现表格到TAPD的单向同步。

二、开发说明

2.1 access_token管理策略

第五阶段前： 所有需要access_token的操作，由开发者手动获取token并传入程序
第五阶段： 实现access_token的自动获取与缓存机制
第五阶段后： 程序自动管理access_token的获取、缓存和刷新

2.2 日志记录策略

所有api调用记录都要写入log文件夹下的api_log.json
第八阶段前： 使用简单的print输出关键信息
第八阶段： 实现完整的日志记录系统

2.3 API频率限制

TAPD:默认频率为60req/1min
智能表格：见智能表格接口文档

三、字段映射关系

智能表格列名	TAPD Bug字段	字段类型	说明
标题	title	string	必填，同步为TAPD标题
详细描述	description	string	必填
优先级	priority_label	string	必填，单选
严重程度	severity	string	必填，单选
处理人	current_owner	string	必填
验证人	confirmer	string	必填
发现版本	version_report	string	必填
模块	module	string	必填
开单状态	-	-	工具回写，✅成功 / ❌失败
TAPD单号	-	-	工具回写，可点击跳转
bug状态	-	-	工具回写，同步TAPD当前状态

字段说明：

priority_label：推荐使用的优先级字段（兼容自定义优先级）
severity 可选值：fatal(致命)、serious(严重)、normal(一般)、prompt(提示)、advice(建议)
必填字段共8个，需在第一阶段校验

四、开发阶段规划

前期准备：API测试工具开发

目标： 创建测试脚本，熟悉智能表格API，为后续开发做准备

任务清单：

创建API测试脚本（api_test.py）
实现获取access_token功能
- 手动输入corpid和corpsecret
- 调用企业微信API获取access_token
- 将token保存到变量中供后续使用
实现新建文档功能
- 调用创建智能表格接口
- 传入必要参数（doc_name、doc_type等）
实现重命名文档功能
- 调用重命名文档接口
- 传入docid和新名称
实现删除文档功能
- 调用删除文档接口
- 传入docid
实现执行记录功能
- 记录每次API调用的请求内容
- 记录请求发起时间
- 记录返回结果
- 将所有记录保存到JSON文件（api_test_log.json）
实现简单的命令行交互
- 选择要执行的操作
- 输入必要参数
- 显示执行结果

验收标准：

能成功获取access_token
能成功创建智能表格文档
能成功重命名文档
能成功删除文档
所有API调用都有完整的记录保存到JSON文件
JSON文件格式清晰，包含请求和响应的完整信息
脚本有基本的错误处理

技术要点：

使用requests库调用企业微信API
JSON文件的读写操作
时间戳的格式化
基本的命令行交互

JSON记录格式示例：

{
  "records": [
    {
      "operation": "get_access_token",
      "timestamp": "2025-12-15 10:30:00",
      "request": {
        "url": "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
        "params": {
          "corpid": "xxx",
          "corpsecret": "***"
        }
      },
      "response": {
        "errcode": 0,
        "errmsg": "ok",
        "access_token": "xxx",
        "expires_in": 7200
      }
    }
  ]
}

潜在问题记录：

access_token的有效期管理（本阶段暂不处理，手动重新获取即可）
API调用失败时的重试机制（本阶段暂不实现）

第一阶段：基础框架搭建与数据读取

阶段1.1：建立基础框架

目标： 搭建项目基础结构，实现配置管理

任务清单：

创建项目目录结构
实现ini配置文件读取模块
- 配置项：workspace_id（TAPD项目ID）
- 配置项：docid（智能表格文档ID）
实现命令行参数解析
- 接收access_token参数
- 接收其他必要参数
实现基本的错误处理
- 配置文件不存在
- 配置项缺失
- access_token未提供

验收标准：

能成功读取ini配置文件中的所有配置项
能通过命令行参数接收access_token
配置缺失时有清晰的错误提示
使用print输出关键信息

技术要点：

使用configparser读取ini文件
使用argparse解析命令行参数
基本的异常处理

潜在问题记录：

配置文件路径的处理（相对路径 vs 绝对路径）

阶段1.2：实现智能表格数据读取与校验

目标： 扫描智能表格，获取"开单状态"为空的行，并校验必填项

任务清单：

实现智能表格API调用模块
- 接收命令行传入的access_token
- 获取子表信息（get_sheet接口）
- 获取字段信息（get_fields接口）
- 查询记录（get_records接口）
实现字段ID映射
- 根据字段标题获取字段ID
- 建立字段名称到字段ID的映射关系
实现数据过滤逻辑
- 筛选"开单状态"字段为空的记录
- 使用filter_spec参数实现服务端过滤
实现必填项校验
- 校验8个必填字段是否为空
- 记录校验失败的行和具体缺失字段
输出扫描结果
- 使用print打印待开单的记录数量
- 使用print打印校验通过和失败的记录详情

验收标准：

能成功连接智能表格并获取子表信息
能正确获取所有字段的ID和名称
能准确筛选出"开单状态"为空的记录
能正确校验所有必填字段
校验失败时能明确指出缺失的字段
使用print输出关键信息
异常情况（如网络错误、字段不存在）有明确的错误提示

技术要点：

使用企业微信文档API的smartsheet相关接口
使用filter_spec实现条件查询（OPERATOR_IS_EMPTY）
字段类型判断：文本、单选、人员等
数据结构设计：记录对象的表示方式

潜在问题记录：

字段值的合法性校验（如优先级、严重程度的可选值）暂不实现，后续优化
人员字段的userid格式校验暂不实现
大量数据的分页处理（limit和offset参数）

第二阶段：TAPD API集成与开单功能

目标： 根据获取到的需要开单的行，调用TAPD API创建bug单

任务清单：

实现TAPD API认证模块
- 从环境变量读取TAPD_API_USER和TAPD_API_KEY
- 实现Basic Auth认证
实现字段映射转换
- 将智能表格字段值转换为TAPD API参数
- 处理人员字段的userid映射
- 处理单选字段的值映射
实现TAPD创建bug接口调用
- 构造请求参数
- 调用POST /bugs接口
- 解析返回结果
实现错误处理
- API调用失败重试机制（最多3次）
- 记录失败原因
批量处理逻辑
- 逐条创建bug单
- 记录成功和失败的数量

验收标准：

能成功从环境变量读取TAPD认证信息
能正确将智能表格数据转换为TAPD API参数
能成功调用TAPD API创建bug单
创建成功后能获取到bug ID
~~API调用失败时有重试机制~~
所有操作都有详细的日志记录
能处理TAPD API返回的各种错误码

技术要点：

使用requests库的auth参数实现Basic Auth
TAPD API的workspace_id参数必填
返回结果中的Bug.id即为TAPD单号
错误码处理：认证失败、参数错误、权限不足等

潜在问题记录：

TAPD API的频率限制需要注意
字段值的格式转换（如日期格式）
人员字段的userid在TAPD和企业微信中不一致，需要确认映射关系

第三阶段：回写结果到智能表格

目标： 将开单结果回写到智能表格，更新"开单状态"、"TAPD单号"、"bug状态"字段

任务清单：

实现智能表格更新记录接口
- 调用update_records接口
- 构造更新参数
实现开单成功的回写逻辑
- 更新"开单状态"为✅
- 更新"TAPD单号"为可点击的链接
- 更新"bug状态"为TAPD当前状态
实现开单失败的回写逻辑
- 更新"开单状态"为❌
- 记录失败原因（可选，后续优化）
实现批量回写
- 收集所有需要更新的记录
- 批量调用更新接口
实现回写失败的处理
- 记录回写失败的记录
- 重试机制

验收标准：

开单成功后能正确回写✅到"开单状态"字段
能正确回写TAPD单号，并生成可点击的链接
能正确回写bug状态
开单失败后能正确回写❌到"开单状态"字段
回写失败时有重试机制
所有操作都有详细的日志记录

技术要点：

智能表格的链接字段格式：CellUrlValue类型
批量更新时注意API的请求限制
字段类型：文本、链接

潜在问题记录：

回写失败时是否需要回滚TAPD的bug单（暂不实现）
链接字段的格式需要确认
bug状态的同步频率（需求文档建议15分钟一次）

第四阶段：定时任务与服务化

目标： 将工具部署为服务，实现定时扫描和状态同步

任务清单：

实现定时任务调度
- 使用schedule库或APScheduler
- 配置开单扫描频率（默认5分钟）
- 配置状态同步频率（默认15分钟）
实现bug状态同步功能
- 查询已开单的记录
- 调用TAPD API获取bug最新状态
- 更新智能表格的"bug状态"字段
实现服务启动和停止
- 命令行参数解析
- 优雅退出机制
实现配置文件扩展
- 添加轮询频率配置
- 添加状态同步频率配置
完善日志和监控
- 添加运行统计信息
- 添加性能监控

验收标准：

服务能正常启动和停止
能按配置的频率执行开单扫描
能按配置的频率执行状态同步
状态同步功能正常工作
服务异常时能自动恢复
有完善的运行日志和统计信息

技术要点：

定时任务的线程安全
信号处理（SIGINT、SIGTERM）
异常捕获和恢复
配置热加载（可选）

潜在问题记录：

长时间运行的内存泄漏问题
access_token过期的自动刷新
并发执行的冲突处理

第五阶段：access_token自动获取与缓存

目标： 实现access_token的自动获取与缓存机制，不再需要手动传入token

任务清单：

实现企业微信认证模块
- 从环境变量读取corpid和corpsecret
- 调用企业微信API获取access_token
- 处理认证失败的情况
设计token缓存结构
- 存储token值
- 存储过期时间
- 存储获取时间
实现token缓存逻辑
- 首次获取时缓存
- 使用前检查是否过期
- 过期前自动刷新（建议提前5分钟）
实现持久化存储（可选）
- 使用文件存储token
- 服务重启后能恢复token
实现token失效处理
- 检测token失效（API返回42001错误码）
- 自动重新获取
重构现有代码
- 保留命令行传入access_token的逻辑，如无传入则自动调用缓存的token
- 所有API调用自动使用缓存的token

验收标准：

能从环境变量读取corpid和corpsecret
能自动获取access_token
token能正确缓存和复用
token过期前能自动刷新
token失效时能自动重新获取
不再需要手动传入access_token
减少了获取token的API调用次数
环境变量未设置时有清晰的错误提示

技术要点：

token有效期为7200秒（2小时）
建议在过期前5分钟刷新
使用os.environ读取环境变量
线程安全的缓存实现
异常处理：网络错误、认证失败等

潜在问题记录：

多实例部署时的token共享问题
时钟不同步导致的过期判断错误
环境变量的安全性问题

第六阶段：企业微信推送功能

目标： 实现开单失败时的企业微信推送通知

任务清单：

实现企业微信消息推送API
- 调用发送应用消息接口
- 构造消息内容
实现推送对象配置
- 配置接收推送的人员列表
- 支持按部门推送
实现推送内容设计
- 失败原因
- 失败的记录信息
- 智能表格链接
实现推送频率控制
- 避免频繁推送
- 合并相同类型的错误
实现推送失败处理
- 记录推送失败的日志
- 重试机制

验收标准：

开单失败时能正确推送消息
推送内容清晰明确
推送对象配置灵活
推送频率合理
推送失败有日志记录

技术要点：

企业微信消息推送API
消息格式：文本、markdown等
推送对象：userid、部门ID
频率控制：时间窗口、消息合并

潜在问题记录：

推送频率限制
消息长度限制
用户未关注应用时的处理

第七阶段：字段合法性校验与优化

目标： 完善字段值的合法性校验，提高数据质量

任务清单：

实现优先级字段校验
- 获取TAPD项目的优先级配置
- 校验智能表格中的值是否合法
实现严重程度字段校验
- 校验可选值：fatal、serious、normal、prompt、advice
实现人员字段校验
- 校验userid格式
- 校验用户是否存在
实现模块字段校验
- 获取TAPD项目的模块配置
- 校验模块是否存在
实现版本字段校验
- 获取TAPD项目的版本配置
- 校验版本是否存在
完善错误提示
- 明确指出不合法的字段和原因
- 提供修正建议

验收标准：

能正确校验所有字段的合法性
不合法的值有明确的错误提示
校验失败时不创建TAPD单
校验结果能回写到智能表格（可选）

技术要点：

TAPD API：获取字段配置接口
智能表格：单选字段的option_id
数据缓存：避免频繁查询配置
错误信息的友好展示

潜在问题记录：

TAPD配置变更时的同步问题
自定义字段的校验规则

第八阶段：日志系统与性能优化

目标： 实现完整的日志记录系统，优化系统性能，添加监控和告警

任务清单：

实现日志记录模块
- 使用Python logging模块
- 日志级别：DEBUG、INFO、WARNING、ERROR
- 日志输出：控制台 + 文件
- 日志轮转：按日期或大小分割
重构现有代码
- 将所有print语句替换为日志记录
- 添加详细的日志信息
- 统一日志格式
实现批量处理优化
- 批量创建TAPD bug
- 批量更新智能表格
实现并发处理
- 使用线程池或协程
- 控制并发数量
实现性能监控
- 记录每次扫描的耗时
- 记录API调用的耗时
- 记录成功率
实现告警机制
- 失败率过高时告警
- 服务异常时告警
实现数据统计
- 每日开单数量
- 失败原因统计
- 性能趋势分析

验收标准：

日志模块能正常输出到控制台和文件
日志格式统一，信息完整
日志文件能自动轮转
所有关键操作都有日志记录
批量处理性能提升明显
并发处理稳定可靠
有完善的性能监控数据
异常情况能及时告警
有详细的统计报表

技术要点：

logging模块的配置和使用
RotatingFileHandler或TimedRotatingFileHandler
线程池：concurrent.futures.ThreadPoolExecutor
协程：asyncio、aiohttp
监控：Prometheus、Grafana（可选）
告警：企业微信、邮件等

潜在问题记录：

并发时的API频率限制
数据一致性问题
监控数据的存储和查询
日志文件的磁盘占用

五、技术栈

编程语言： Python 3.8+
核心库：
- requests：HTTP请求
- configparser：配置文件解析
- argparse：命令行参数解析
- json：JSON文件处理
- datetime：时间处理
- logging：日志记录（第八阶段）
- schedule/APScheduler：定时任务（第四阶段）
API：
- 企业微信文档API
- TAPD Open API

六、配置文件示例

config.ini

[TAPD]
workspace_id = 10158231

[SmartSheet]
docid = your_doc_id

[Schedule]
# 第四阶段添加
scan_interval = 5
sync_interval = 15

环境变量（第五阶段开始使用）

# 企业微信（第五阶段）
WEWORK_CORPID=your_corpid
WEWORK_CORPSECRET=your_corpsecret

# TAPD（第二阶段）
TAPD_API_USER=your_api_user
TAPD_API_PASSWORD=your_api_password

七、目录结构（建议）

autoTAPD/
├── config/
│   └── config.ini          # 配置文件
├── src/
│   ├── __init__.py
│   ├── api_test.py         # 前期准备：API测试工具
│   ├── config.py           # 配置管理
│   ├── wework_api.py       # 企业微信API（第五阶段完善）
│   ├── smartsheet.py       # 智能表格操作
│   ├── tapd_api.py         # TAPD API
│   ├── validator.py        # 数据校验
│   ├── mapper.py           # 字段映射
│   ├── token_cache.py      # token缓存（第五阶段）
│   ├── scheduler.py        # 定时任务（第四阶段）
│   ├── logger.py           # 日志模块（第八阶段）
│   └── main.py             # 主程序
├── logs/                   # 日志目录（第八阶段）
│   └── api_test_log.json   # API测试记录
├── tests/                  # 测试代码
├── requirements.txt        # 依赖包
└── README.md              # 项目说明

八、开发原则

小步走原则： 每个阶段完成一个独立功能，验收通过后再进入下一阶段
先实现后优化： 前期以完成功能为主，不过度设计，后期再优化性能和潜在问题
异常处理： 所有外部调用都要有异常处理，关键操作需要重试机制
配置驱动： 尽量通过配置文件控制行为，避免硬编码
代码复用： 相同逻辑封装为函数或类，避免重复代码
阶段性验收： 每个阶段完成后必须通过验收标准才能进入下一阶段

九、注意事项

API频率限制： 注意企业微信和TAPD的API调用频率限制
数据安全： 敏感信息（如token、密码）不要硬编码，使用环境变量
错误恢复： 服务异常时要能自动恢复，不影响后续执行
向后兼容： 配置文件和数据结构的变更要考虑向后兼容
文档更新： 每个阶段完成后更新相关文档
access_token管理： 第五阶段前手动传入，第五阶段后自动管理
日志策略： 第八阶段前使用print，第八阶段后使用logging模块

十、阶段依赖关系

前期准备（API测试工具）
    ↓
第一阶段（基础框架 + 数据读取）
    ↓
第二阶段（TAPD开单）
    ↓
第三阶段（回写结果）
    ↓
第四阶段（定时任务）
    ↓
第五阶段（access_token自动化）
    ↓
第六阶段（企业微信推送）
    ↓
第七阶段（字段合法性校验）
    ↓
第八阶段（日志系统 + 性能优化）

十一、后续优化方向

支持多个智能表格和TAPD项目
支持自定义字段映射配置
支持webhook触发（实时开单）
支持双向同步（TAPD更新同步到智能表格）
提供Web管理界面
支持数据统计和报表
支持更多的字段类型和复杂映射规则

20 KiB Raw Blame History Unescape Escape

Debug阶段自动开单工具 - 开发路线

一、项目概述

二、开发说明

2.1 access_token管理策略

2.2 日志记录策略

2.3 API频率限制

三、字段映射关系

四、开发阶段规划

前期准备：API测试工具开发

第一阶段：基础框架搭建与数据读取

阶段1.1：建立基础框架

阶段1.2：实现智能表格数据读取与校验

第二阶段：TAPD API集成与开单功能

第三阶段：回写结果到智能表格

第四阶段：定时任务与服务化

第五阶段：access_token自动获取与缓存

第六阶段：企业微信推送功能

第七阶段：字段合法性校验与优化

第八阶段：日志系统与性能优化

五、技术栈

六、配置文件示例

config.ini

环境变量（第五阶段开始使用）

七、目录结构（建议）

八、开发原则

九、注意事项

十、阶段依赖关系

十一、后续优化方向

20 KiB

Raw Blame History