linzelong/G41_TAPD_BUG_SYNC

Fork 0

zelong 3aeb65233d 'phase7'

2025-12-24 19:41:56 +08:00

26 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分钟一次）

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

目标： 实现access_token的自动获取与缓存机制，不再需要手动传入token，该模块应该与其他功能独立

任务清单：

实现企业微信认证模块
- 从环境变量读取CORPID和CORPSECRET
- 调用企业微信API获取access_token
- 处理认证失败的情况
设计token缓存文件结构
- 在项目根目录创建token缓存文件（token_cache.json）
- 存储token值
- 存储获取时间（时间戳）
实现token缓存逻辑
- 首次获取时写入缓存文件
- 每次使用前从文件读取并检查是否过期（当前时间 - 获取时间 >= 7200秒）
- 过期则重新获取并更新缓存文件
实现token失效处理
- 检测token失效（API返回42001错误码）
- 自动重新获取并更新缓存
重构现有代码
- 保留命令行传入access_token的逻辑，如无传入则自动从缓存获取
- 所有API调用自动使用缓存的token
- 修改wework_api.py，添加token管理功能

验收标准：

能从环境变量读取corpid和corpsecret
能自动获取access_token并写入缓存文件
token能正确从文件读取和复用
token过期时能自动重新获取
token失效时（API返回42001）能自动重新获取
不再需要手动传入access_token（命令行参数可选）
减少了获取token的API调用次数
环境变量未设置时有清晰的错误提示
缓存文件格式清晰易读

*修复了开单状态不为空的记录也被读取的问题：filter_spec的conjunction应该为CONJUNCTION_AND而不是and

技术要点：

token有效期为7200秒（2小时）
使用时间戳判断过期（time.time()）
使用os.environ读取环境变量
JSON文件的读写操作
异常处理：网络错误、认证失败、文件读写错误等

缓存文件格式示例：

{
  "access_token": "xxx",
  "fetch_time": 1702800000
}

潜在问题记录：

多实例部署时的token文件竞争问题（本阶段暂不处理）
时钟不同步导致的过期判断错误
环境变量的安全性问题
缓存文件的权限问题

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

目标： 实现定时任务调度，让工具能够自动定期执行开单扫描

阶段5.1：重构main.py核心逻辑

任务清单：

重构main.py，提取核心逻辑
- 将main()函数的核心逻辑提取为run_once()函数
- run_once()接收配置对象和access_token作为参数
- run_once()返回执行结果字典（包含成功/失败数量等统计信息）
- 移除run_once()中的sys.exit()调用，改为返回状态码
保持main()函数的单次执行功能
- main()函数继续支持命令行参数解析
- main()调用run_once()并根据返回值调用sys.exit()
- 确保原有的单次执行模式不受影响

验收标准：

run_once()函数能被独立调用
run_once()返回包含执行统计的字典
原有的python main.py单次执行模式正常工作
异常处理正确，不会导致调用方崩溃

技术要点：

函数重构和职责分离
返回值设计（包含成功数、失败数、开单数等）
异常处理策略（捕获但不退出）

阶段5.2：扩展配置文件

任务清单：

修改config.ini
- 添加[Schedule]配置节
- 添加scan_interval配置项（默认5分钟）
修改config.py
- 添加get_schedule_config()方法
- 读取scan_interval配置
- 提供默认值（5分钟）
- 添加配置验证（必须为正整数）

验收标准：

config.ini包含[Schedule]配置节
ConfigManager能正确读取scan_interval
配置缺失时使用默认值5分钟
配置值非法时有清晰的错误提示

技术要点：

configparser的配置节读取
配置验证和默认值处理

阶段5.3：创建调度器模块

任务清单：

创建scheduler.py
- 使用schedule库实现定时任务
- 创建AutoTAPDScheduler类
- 实现job()方法：调用main.run_once()执行一次开单流程
- 实现start()方法：启动调度器，立即执行一次，然后按间隔执行
- 实现异常捕获：单次执行失败不影响后续执行
集成TokenManager
- 调度器启动时初始化TokenManager
- 每次执行前调用get_token()获取有效token
- 处理token获取失败的情况
集成ConfigManager
- 调度器启动时读取配置
- 根据scan_interval配置调度频率
- 传递配置给run_once()函数

验收标准：

能通过python src/scheduler.py启动调度器
启动后立即执行一次开单流程
按配置的频率（默认5分钟）自动执行
单次执行失败后能继续下次执行
每次执行后显示简单的统计信息

技术要点：

schedule库的基本使用：schedule.every(n).minutes.do(job)
立即执行：启动时手动调用一次job()
异常捕获：在job()方法中使用try-except
循环执行：while循环 + schedule.run_pending()

阶段5.4：实现优雅退出与统计

任务清单：

实现信号处理
- 捕获SIGINT信号（Ctrl+C）
- 捕获SIGTERM信号（系统关闭）
- 设置退出标志，等待当前任务完成后退出
实现执行统计
- 记录服务启动时间
- 记录总执行次数
- 记录成功次数和失败次数
- 记录总开单数量
- 记录最后一次执行时间
- 显示下次执行时间
实现统计信息输出
- 每次执行后显示本次统计（扫描X条，成功Y条，失败Z条）
- 退出时显示完整的运行统计
添加命令行参数
- 支持--config参数指定配置文件路径
- 支持--verbose参数显示详细信息

验收标准：

Ctrl+C能优雅退出（不强制中断）
退出前显示完整的运行统计
每次执行后显示本次执行的统计信息
显示下次执行时间
支持命令行参数配置

技术要点：

signal.signal()注册信号处理函数
使用标志位控制循环退出
datetime模块处理时间统计
schedule.idle_seconds()获取下次执行时间

阶段5.5：完善错误处理和日志输出

任务清单：

完善异常处理
- 区分不同类型的异常（配置错误、网络错误、API错误等）
- 针对不同异常类型输出不同的提示信息
- 记录异常发生的时间和详情
优化输出格式
- 统一输出格式（使用分隔线、对齐等）
- 添加时间戳到每次执行的输出
- 区分不同级别的信息（INFO、WARNING、ERROR）
添加启动检查
- 启动时检查配置文件是否存在
- 启动时检查环境变量是否设置
- 启动时测试token获取是否正常
- 启动时测试一次完整流程

验收标准：

不同类型的错误有清晰的提示信息
输出格式统一、易读
每次执行都有时间戳
启动时进行必要的检查，及早发现配置问题

技术要点：

异常类型判断和分类处理
字符串格式化和对齐
datetime.now()获取当前时间

整体验收标准：

服务能正常启动和停止
启动后立即执行一次，然后按配置的频率执行
能按配置的频率（默认5分钟）执行开单扫描
每次执行都调用main.py的核心逻辑
服务异常时能自动恢复（捕获异常后继续下次执行）
有清晰的执行统计信息（每次执行 + 总体统计）
Ctrl+C能优雅退出
支持命令行参数配置

技术要点：

schedule库的基本使用
信号处理（signal模块）
异常捕获和恢复
循环执行的设计
函数重构和职责分离

潜在问题记录：

长时间运行的内存泄漏问题（后续监控）
并发执行的冲突处理（如果上次执行未完成）- 当前通过同步执行避免
配置热更新功能（暂不实现，记录为后续优化方向）
日志文件的磁盘占用（第九阶段实现日志轮转）

第六阶段：bug状态同步功能

目标： 实现定期同步TAPD的bug状态到智能表格

任务清单：

实现状态同步功能模块
- 查询智能表格中已开单的记录（"开单状态"为✅且"TAPD单号"不为空）
- 过滤掉状态为"完成"或"取消"的记录
- 调用TAPD API获取bug最新状态
- 对比状态是否变化
实现状态回写逻辑
- 只有状态发生变化时才更新智能表格
- 批量更新智能表格的"bug状态"字段
集成到定时任务
- 在scheduler.py中添加状态同步任务
- 配置状态同步频率（默认15分钟）
实现配置文件扩展
- 在config.ini中添加状态同步频率配置
完善错误处理
- TAPD API调用失败的处理
- 智能表格更新失败的处理

验收标准：

能正确查询已开单的记录
能正确过滤"完成"和"取消"状态的记录
能成功调用TAPD API获取bug状态
状态变化时能正确回写到智能表格
状态未变化时不进行更新（减少API调用）
能按配置的频率执行状态同步
有清晰的同步统计信息（检查X条，更新Y条）

技术要点：

TAPD获取bug详情API
状态对比逻辑
批量更新优化
定时任务的多任务调度

潜在问题记录：

大量bug的状态查询性能问题
TAPD API频率限制
状态映射的准确性

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

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

实现方式：使用企微自带的消息推送功能。

假设webhook是：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa 以下是用curl工具往群组推送文本消息的示例（注意要将url替换成你的消息推送webhook地址，content必须是utf8编码）：

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693axxx6-7aoc-4bc4-97a0-0ec2sifa5aaa'
-H 'Content-Type: application/json'
-d ' { "msgtype": "text", "text": { "content": "hello world" } }'

任务清单：

配置文件新增webhook地址
实现开单失败时调用推送功能
实现推送内容设计
- 失败原因
- 失败的记录信息
- 智能表格链接
实现推送频率控制
- 避免频繁推送
- 合并相同类型的错误
实现推送失败处理
- 记录推送失败的日志
- 重试机制

验收标准：

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

技术要点：

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

潜在问题记录：

推送频率限制
消息长度限制

第八阶段：测试

目标： 进行边界测试等，防止出现意外情况导致服务出错

任务清单： 1.

验收标准：

技术要点：

潜在问题记录：

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

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

任务清单：

实现日志记录模块
- 使用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           # 字段映射
│   ├── scheduler.py        # 定时任务（第五阶段）
│   ├── sync_status.py      # bug状态同步（第六阶段）
│   ├── logger.py           # 日志模块（第九阶段）
│   └── main.py             # 主程序
├── logs/                   # 日志目录（第九阶段）
│   ├── api_log.json        # API调用记录
│   └── api_test_log.json   # API测试记录
├── tests/                  # 测试代码
├── token_cache.json        # token缓存文件（第四阶段）
├── requirements.txt        # 依赖包
└── README.md              # 项目说明

八、开发原则

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

九、注意事项

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

十、阶段依赖关系

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

十一、后续优化方向

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

26 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自动获取与缓存

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

阶段5.1：重构main.py核心逻辑

阶段5.2：扩展配置文件

阶段5.3：创建调度器模块

阶段5.4：实现优雅退出与统计

阶段5.5：完善错误处理和日志输出

第六阶段：bug状态同步功能

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

第八阶段：测试

潜在问题记录：

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

五、技术栈

六、配置文件示例

config.ini

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

七、目录结构（建议）

八、开发原则

九、注意事项

十、阶段依赖关系

十一、后续优化方向

26 KiB

Raw Blame History