linzelong/G41_TAPD_BUG_SYNC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

'remove-useless-md'

Browse Source
This commit is contained in:
zelong 2025-12-25 15:14:03 +08:00
parent 31162e96bc
commit e958f73af0
3 changed files with 2 additions and 887 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
config/config.ini
View File

@ -14,6 +14,6 @@ docid = dcRybSHojZR9-b5ePgDp33yr29bQy6BtQiVJ-nSGUM-ot6FSpq-TGW9jEn_f7ORLcFWRj9zv
[Schedule]
# 开单扫描频率（分钟）
scan_interval = 1
scan_interval = 60
# bug状态同步频率（分钟）
sync_interval = 1
sync_interval = 60

830
开发路线.md
View File

@ -1,830 +0,0 @@
# 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，为后续开发做准备
**任务清单：**
1. 创建API测试脚本（api_test.py）
2. 实现获取access_token功能
- 手动输入corpid和corpsecret
- 调用企业微信API获取access_token
- 将token保存到变量中供后续使用
3. 实现新建文档功能
- 调用创建智能表格接口
- 传入必要参数（doc_name、doc_type等）
4. 实现重命名文档功能
- 调用重命名文档接口
- 传入docid和新名称
5. 实现删除文档功能
- 调用删除文档接口
- 传入docid
6. 实现执行记录功能
- 记录每次API调用的请求内容
- 记录请求发起时间
- 记录返回结果
- 将所有记录保存到JSON文件（api_test_log.json）
7. 实现简单的命令行交互
- 选择要执行的操作
- 输入必要参数
- 显示执行结果
**验收标准：**
- [x] 能成功获取access_token
- [x] 能成功创建智能表格文档
- [x] 能成功重命名文档
- [x] 能成功删除文档
- [x] 所有API调用都有完整的记录保存到JSON文件
- [x] JSON文件格式清晰，包含请求和响应的完整信息
- [x] 脚本有基本的错误处理
**技术要点：**
- 使用requests库调用企业微信API
- JSON文件的读写操作
- 时间戳的格式化
- 基本的命令行交互
**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：建立基础框架
**目标：** 搭建项目基础结构，实现配置管理
**任务清单：**
1. 创建项目目录结构
2. 实现ini配置文件读取模块
- 配置项：workspace_id（TAPD项目ID）
- 配置项：docid（智能表格文档ID）
3. 实现命令行参数解析
- 接收access_token参数
- 接收其他必要参数
4. 实现基本的错误处理
- 配置文件不存在
- 配置项缺失
- access_token未提供
**验收标准：**
- [x] 能成功读取ini配置文件中的所有配置项
- [x] 能通过命令行参数接收access_token
- [x] 配置缺失时有清晰的错误提示
- [x] 使用print输出关键信息
**技术要点：**
- 使用configparser读取ini文件
- 使用argparse解析命令行参数
- 基本的异常处理
**潜在问题记录：**
- 配置文件路径的处理（相对路径 vs 绝对路径）
---
#### 阶段1.2：实现智能表格数据读取与校验
**目标：** 扫描智能表格，获取"开单状态"为空的行，并校验必填项
**任务清单：**
1. 实现智能表格API调用模块
- 接收命令行传入的access_token
- 获取子表信息（get_sheet接口）
- 获取字段信息（get_fields接口）
- 查询记录（get_records接口）
2. 实现字段ID映射
- 根据字段标题获取字段ID
- 建立字段名称到字段ID的映射关系
3. 实现数据过滤逻辑
- 筛选"开单状态"字段为空的记录
- 使用filter_spec参数实现服务端过滤
4. 实现必填项校验
- 校验8个必填字段是否为空
- 记录校验失败的行和具体缺失字段
5. 输出扫描结果
- 使用print打印待开单的记录数量
- 使用print打印校验通过和失败的记录详情
**验收标准：**
- [x] 能成功连接智能表格并获取子表信息
- [x] 能正确获取所有字段的ID和名称
- [x] 能准确筛选出"开单状态"为空的记录
- [x] 能正确校验所有必填字段
- [x] 校验失败时能明确指出缺失的字段
- [x] 使用print输出关键信息
- [x] 异常情况（如网络错误、字段不存在）有明确的错误提示
**技术要点：**
- 使用企业微信文档API的smartsheet相关接口
- 使用filter_spec实现条件查询（OPERATOR_IS_EMPTY）
- 字段类型判断：文本、单选、人员等
- 数据结构设计：记录对象的表示方式
**潜在问题记录：**
- 字段值的合法性校验（如优先级、严重程度的可选值）暂不实现，后续优化
- 人员字段的userid格式校验暂不实现
- 大量数据的分页处理（limit和offset参数）
---
### 第二阶段：TAPD API集成与开单功能
**目标：** 根据获取到的需要开单的行，调用TAPD API创建bug单
**任务清单：**
1. 实现TAPD API认证模块
- 从环境变量读取TAPD_API_USER和TAPD_API_KEY
- 实现Basic Auth认证
2. 实现字段映射转换
- 将智能表格字段值转换为TAPD API参数
- 处理人员字段的userid映射
- 处理单选字段的值映射
3. 实现TAPD创建bug接口调用
- 构造请求参数
- 调用POST /bugs接口
- 解析返回结果
4. 实现错误处理
- API调用失败重试机制（最多3次）
- 记录失败原因
5. 批量处理逻辑
- 逐条创建bug单
- 记录成功和失败的数量
**验收标准：**
- [x] 能成功从环境变量读取TAPD认证信息
- [x] 能正确将智能表格数据转换为TAPD API参数
- [x] 能成功调用TAPD API创建bug单
- [x] 创建成功后能获取到bug ID
- [ ] ~~API调用失败时有重试机制~~
- [ ] 所有操作都有详细的日志记录
- [ ] 能处理TAPD API返回的各种错误码
**技术要点：**
- 使用requests库的auth参数实现Basic Auth
- TAPD API的workspace_id参数必填
- 返回结果中的Bug.id即为TAPD单号
- 错误码处理：认证失败、参数错误、权限不足等
**潜在问题记录：**
- TAPD API的频率限制需要注意
- 字段值的格式转换（如日期格式）
- **人员字段的userid在TAPD和企业微信中不一致，需要确认映射关系**
---
### 第三阶段：回写结果到智能表格
**目标：** 将开单结果回写到智能表格，更新"开单状态"、"TAPD单号"、"bug状态"字段
**任务清单：**
1. 实现智能表格更新记录接口
- 调用update_records接口
- 构造更新参数
2. 实现开单成功的回写逻辑
- 更新"开单状态"为✅
- 更新"TAPD单号"为可点击的链接
- 更新"bug状态"为TAPD当前状态
3. 实现开单失败的回写逻辑
- 更新"开单状态"为❌
- 记录失败原因（可选，后续优化）
4. 实现批量回写
- 收集所有需要更新的记录
- 批量调用更新接口
5. 实现回写失败的处理
- 记录回写失败的记录
- 重试机制
**验收标准：**
- [x] 开单成功后能正确回写✅到"开单状态"字段
- [x] 能正确回写TAPD单号，并生成可点击的链接
- [x] 能正确回写bug状态
- [ ] 开单失败后能正确回写❌到"开单状态"字段
- [ ] 回写失败时有重试机制
- [ ] 所有操作都有详细的日志记录
**技术要点：**
- 智能表格的链接字段格式：CellUrlValue类型
- 批量更新时注意API的请求限制
- 字段类型：文本、链接
**潜在问题记录：**
- 回写失败时是否需要回滚TAPD的bug单（暂不实现）
- 链接字段的格式需要确认
- bug状态的同步频率（需求文档建议15分钟一次）
---
### 第四阶段：access_token自动获取与缓存
**目标：** 实现access_token的自动获取与缓存机制，不再需要手动传入token，该模块应该与其他功能独立
**任务清单：**
1. 实现企业微信认证模块
- 从环境变量读取CORPID和CORPSECRET
- 调用企业微信API获取access_token
- 处理认证失败的情况
2. 设计token缓存文件结构
- 在项目根目录创建token缓存文件（token_cache.json）
- 存储token值
- 存储获取时间（时间戳）
3. 实现token缓存逻辑
- 首次获取时写入缓存文件
- 每次使用前从文件读取并检查是否过期（当前时间 - 获取时间 >= 7200秒）
- 过期则重新获取并更新缓存文件
4. 实现token失效处理
- 检测token失效（API返回42001错误码）
- 自动重新获取并更新缓存
5. 重构现有代码
- 保留命令行传入access_token的逻辑，如无传入则自动从缓存获取
- 所有API调用自动使用缓存的token
- 修改wework_api.py，添加token管理功能
**验收标准：**
- [x] 能从环境变量读取corpid和corpsecret
- [x] 能自动获取access_token并写入缓存文件
- [x] token能正确从文件读取和复用
- [x] token过期时能自动重新获取
- [ ] token失效时（API返回42001）能自动重新获取
- [x] 不再需要手动传入access_token（命令行参数可选）
- [ ] 减少了获取token的API调用次数
- [ ] 环境变量未设置时有清晰的错误提示
- [x] 缓存文件格式清晰易读
*修复了开单状态不为空的记录也被读取的问题：filter_spec的conjunction应该为CONJUNCTION_AND而不是and
**技术要点：**
- token有效期为7200秒（2小时）
- 使用时间戳判断过期（time.time()）
- 使用os.environ读取环境变量
- JSON文件的读写操作
- 异常处理：网络错误、认证失败、文件读写错误等
**缓存文件格式示例：**
```json
{
"access_token": "xxx",
"fetch_time": 1702800000
}
```
**潜在问题记录：**
- 多实例部署时的token文件竞争问题（本阶段暂不处理）
- 时钟不同步导致的过期判断错误
- 环境变量的安全性问题
- 缓存文件的权限问题
---
### 第五阶段：定时任务与服务化
**目标：** 实现定时任务调度，让工具能够自动定期执行开单扫描
#### 阶段5.1：重构main.py核心逻辑
**任务清单：**
1. 重构main.py，提取核心逻辑
- 将main()函数的核心逻辑提取为run_once()函数
- run_once()接收配置对象和access_token作为参数
- run_once()返回执行结果字典（包含成功/失败数量等统计信息）
- 移除run_once()中的sys.exit()调用，改为返回状态码
2. 保持main()函数的单次执行功能
- main()函数继续支持命令行参数解析
- main()调用run_once()并根据返回值调用sys.exit()
- 确保原有的单次执行模式不受影响
**验收标准：**
- [ ] run_once()函数能被独立调用
- [ ] run_once()返回包含执行统计的字典
- [x] 原有的`python main.py`单次执行模式正常工作
- [ ] 异常处理正确，不会导致调用方崩溃
**技术要点：**
- 函数重构和职责分离
- 返回值设计（包含成功数、失败数、开单数等）
- 异常处理策略（捕获但不退出）
---
#### 阶段5.2：扩展配置文件
**任务清单：**
1. 修改config.ini
- 添加[Schedule]配置节
- 添加scan_interval配置项（默认5分钟）
2. 修改config.py
- 添加get_schedule_config()方法
- 读取scan_interval配置
- 提供默认值（5分钟）
- 添加配置验证（必须为正整数）
**验收标准：**
- [x] config.ini包含[Schedule]配置节
- [x] ConfigManager能正确读取scan_interval
- [x] 配置缺失时使用默认值5分钟
- [ ] 配置值非法时有清晰的错误提示
**技术要点：**
- configparser的配置节读取
- 配置验证和默认值处理
---
#### 阶段5.3：创建调度器模块
**任务清单：**
1. 创建scheduler.py
- 使用schedule库实现定时任务
- 创建AutoTAPDScheduler类
- 实现job()方法：调用main.run_once()执行一次开单流程
- 实现start()方法：启动调度器，立即执行一次，然后按间隔执行
- 实现异常捕获：单次执行失败不影响后续执行
2. 集成TokenManager
- 调度器启动时初始化TokenManager
- 每次执行前调用get_token()获取有效token
- 处理token获取失败的情况
3. 集成ConfigManager
- 调度器启动时读取配置
- 根据scan_interval配置调度频率
- 传递配置给run_once()函数
**验收标准：**
- [x] 能通过`python src/scheduler.py`启动调度器
- [x] 启动后立即执行一次开单流程
- [x] 按配置的频率（默认5分钟）自动执行
- [ ] 单次执行失败后能继续下次执行
- [ ] 每次执行后显示简单的统计信息
**技术要点：**
- schedule库的基本使用：schedule.every(n).minutes.do(job)
- 立即执行：启动时手动调用一次job()
- 异常捕获：在job()方法中使用try-except
- 循环执行：while循环 + schedule.run_pending()
---
#### 阶段5.4：实现优雅退出与统计
**任务清单：**
1. 实现信号处理
- 捕获SIGINT信号（Ctrl+C）
- 捕获SIGTERM信号（系统关闭）
- 设置退出标志，等待当前任务完成后退出
2. 实现执行统计
- 记录服务启动时间
- 记录总执行次数
- 记录成功次数和失败次数
- 记录总开单数量
- 记录最后一次执行时间
- 显示下次执行时间
3. 实现统计信息输出
- 每次执行后显示本次统计（扫描X条，成功Y条，失败Z条）
- 退出时显示完整的运行统计
4. 添加命令行参数
- 支持--config参数指定配置文件路径
- 支持--verbose参数显示详细信息
**验收标准：**
- [x] Ctrl+C能优雅退出（不强制中断）
- [x] 退出前显示完整的运行统计
- [x] 每次执行后显示本次执行的统计信息
- [x] 显示下次执行时间
- [ ] 支持命令行参数配置
**技术要点：**
- signal.signal()注册信号处理函数
- 使用标志位控制循环退出
- datetime模块处理时间统计
- schedule.idle_seconds()获取下次执行时间
---
#### 阶段5.5：完善错误处理和日志输出
**任务清单：**
1. 完善异常处理
- 区分不同类型的异常（配置错误、网络错误、API错误等）
- 针对不同异常类型输出不同的提示信息
- 记录异常发生的时间和详情
2. 优化输出格式
- 统一输出格式（使用分隔线、对齐等）
- 添加时间戳到每次执行的输出
- 区分不同级别的信息（INFO、WARNING、ERROR）
3. 添加启动检查
- 启动时检查配置文件是否存在
- 启动时检查环境变量是否设置
- 启动时测试token获取是否正常
- 启动时测试一次完整流程
**验收标准：**
- [ ] 不同类型的错误有清晰的提示信息
- [ ] 输出格式统一、易读
- [x] 每次执行都有时间戳
- [ ] 启动时进行必要的检查，及早发现配置问题
**技术要点：**
- 异常类型判断和分类处理
- 字符串格式化和对齐
- datetime.now()获取当前时间
---
**整体验收标准：**
- [x] 服务能正常启动和停止
- [x] 启动后立即执行一次，然后按配置的频率执行
- [x] 能按配置的频率（默认5分钟）执行开单扫描
- [x] 每次执行都调用main.py的核心逻辑
- [ ] 服务异常时能自动恢复（捕获异常后继续下次执行）
- [x] 有清晰的执行统计信息（每次执行 + 总体统计）
- [x] Ctrl+C能优雅退出
- [ ] 支持命令行参数配置
**技术要点：**
- schedule库的基本使用
- 信号处理（signal模块）
- 异常捕获和恢复
- 循环执行的设计
- 函数重构和职责分离
**潜在问题记录：**
- 长时间运行的内存泄漏问题（后续监控）
- 并发执行的冲突处理（如果上次执行未完成）- 当前通过同步执行避免
- 配置热更新功能（暂不实现，记录为后续优化方向）
- 日志文件的磁盘占用（第九阶段实现日志轮转）
---
### 第六阶段：bug状态同步功能
**目标：** 实现定期同步TAPD的bug状态到智能表格
**任务清单：**
1. 实现状态同步功能模块
- 查询智能表格中已开单的记录（"开单状态"为✅且"TAPD单号"不为空）
- 过滤掉状态为"完成"或"取消"的记录
- 调用TAPD API获取bug最新状态
- 对比状态是否变化
2. 实现状态回写逻辑
- 只有状态发生变化时才更新智能表格
- 批量更新智能表格的"bug状态"字段
3. 集成到定时任务
- 在scheduler.py中添加状态同步任务
- 配置状态同步频率（默认15分钟）
4. 实现配置文件扩展
- 在config.ini中添加状态同步频率配置
5. 完善错误处理
- TAPD API调用失败的处理
- 智能表格更新失败的处理
**验收标准：**
- [x] 能正确查询已开单的记录
- [x] 能正确过滤"完成"和"取消"状态的记录
- [x] 能成功调用TAPD API获取bug状态
- [x] 状态变化时能正确回写到智能表格
- [x] 状态未变化时不进行更新（减少API调用）
- [x] 能按配置的频率执行状态同步
- [ ] 有清晰的同步统计信息（检查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"
}
}'
**任务清单：**
1. 配置文件新增webhook地址
2. 实现开单失败时调用推送功能
3. 实现推送内容设计
- 失败原因
- 失败的记录信息
- 智能表格链接
4. 实现推送频率控制
- 避免频繁推送
- 合并相同类型的错误
5. 实现推送失败处理
- 记录推送失败的日志
- 重试机制
**验收标准：**
- [ ] 开单失败时能正确推送消息
- [ ] 推送内容清晰明确
- [ ] 推送对象配置灵活
- [ ] 推送频率合理
- [ ] 推送失败有日志记录
**技术要点：**
- 企业微信消息推送API
- 消息格式：文本、markdown等
- 频率控制：时间窗口、消息合并
**潜在问题记录：**
- 推送频率限制
- 消息长度限制
---
### 第八阶段：测试
**目标：** 进行边界测试等，防止出现意外情况导致服务出错
**任务清单：**
1.
**验收标准：**
- [ ]
- [ ]
**技术要点：**
-
**潜在问题记录：**
-
---
### 第九阶段：日志系统与性能优化
**目标：** 实现完整的日志记录系统，优化系统性能，添加监控和告警
**任务清单：**
1. 实现日志记录模块
- 使用Python logging模块
- 日志级别：DEBUG、INFO、WARNING、ERROR
- 日志输出：控制台 + 文件
- 日志轮转：按日期或大小分割
2. 重构现有代码
- 将所有print语句替换为日志记录
- 添加详细的日志信息
- 统一日志格式
3. 实现批量处理优化
- 批量创建TAPD bug
- 批量更新智能表格
4. 实现并发处理
- 使用线程池或协程
- 控制并发数量
5. 实现性能监控
- 记录每次扫描的耗时
- 记录API调用的耗时
- 记录成功率
6. 实现告警机制
- 失败率过高时告警
- 服务异常时告警
7. 实现数据统计
- 每日开单数量
- 失败原因统计
- 性能趋势分析
**验收标准：**
- [ ] 日志模块能正常输出到控制台和文件
- [ ] 日志格式统一，信息完整
- [ ] 日志文件能自动轮转
- [ ] 所有关键操作都有日志记录
- [ ] 批量处理性能提升明显
- [ ] 并发处理稳定可靠
- [ ] 有完善的性能监控数据
- [ ] 异常情况能及时告警
- [ ] 有详细的统计报表
**技术要点：**
- 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
```ini
[TAPD]
workspace_id = 10158231
[SmartSheet]
docid = your_doc_id
[Schedule]
# 第五阶段添加
scan_interval = 5
# 第六阶段添加
sync_interval = 15
```
### 环境变量（第四阶段开始使用）
```bash
# 企业微信（第四阶段）
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 # 项目说明
```
## 八、开发原则
1. **小步走原则：** 每个阶段完成一个独立功能，验收通过后再进入下一阶段
2. **先实现后优化：** 前期以完成功能为主，不过度设计，后期再优化性能和潜在问题
3. **异常处理：** 所有外部调用都要有异常处理，关键操作需要重试机制
4. **配置驱动：** 尽量通过配置文件控制行为，避免硬编码
5. **代码复用：** 相同逻辑封装为函数或类，避免重复代码
6. **阶段性验收：** 每个阶段完成后必须通过验收标准才能进入下一阶段
## 九、注意事项
1. **API频率限制：** 注意企业微信和TAPD的API调用频率限制
2. **数据安全：** 敏感信息（如token、密码）不要硬编码，使用环境变量
3. **错误恢复：** 服务异常时要能自动恢复，不影响后续执行
4. **向后兼容：** 配置文件和数据结构的变更要考虑向后兼容
5. **文档更新：** 每个阶段完成后更新相关文档
6. **access_token管理：** 第四阶段前手动传入，第四阶段后自动管理
7. **日志策略：** 第九阶段前使用print，第九阶段后使用logging模块
## 十、阶段依赖关系
```
前期准备（API测试工具）
↓
第一阶段（基础框架 + 数据读取）
↓
第二阶段（TAPD开单）
↓
第三阶段（回写结果）
↓
第四阶段（access_token自动化）
↓
第五阶段（定时任务与服务化）
↓
第六阶段（bug状态同步）
↓
第七阶段（企业微信推送）
↓
第八阶段（测试）
↓
第九阶段（日志系统 + 性能优化）
```
## 十一、后续优化方向
1. 支持多个智能表格和TAPD项目
2. 支持自定义字段映射配置
3. 支持webhook触发（实时开单）
4. 支持双向同步（TAPD更新同步到智能表格）
5. 提供Web管理界面
6. 支持数据统计和报表
7. 支持更多的字段类型和复杂映射规则

55
需求文档.md
View File

@ -1,55 +0,0 @@
# **Debug阶段自动开单工具需求**
## **一、功能概述**
策划在腾讯智能表格填写bug信息，工具定时扫描并自动在TAPD创建bug单，实现表格到TAPD的单向同步。
## **二、表格字段设计**
| **列** | **说明** | **备注** |
| -------- | -------- | ---------------- |
| 标题 | 必填 | 同步为TAPD标题 |
| 详细描述 | 必填 | |
| 优先级 | 必填 | 单选 |
| 严重程度 | 必填 | 单选 |
| 处理人 | 必填 | |
| 验证人 | 必填 | |
| 发现版本 | 必填 | |
| 模块 | 必填 | |
| 开单状态 | 工具回写 | ✅成功 / ❌失败 |
| TAPD单号 | 工具回写 | 可点击跳转 |
| bug状态 | 工具回写 | 同步TAPD当前状态 |
##
## **三、处理逻辑**
​ 1. 定时扫描"开单状态"为空的行
​ 2. 校验必填项是否完整
​ 3. 调用TAPD API创建bug单
​ 4. 回写结果到表格
##
## **四、异常处理**
​ ● 开单成功：开单状态列打✅，回写单号和状态
​ ● 开单失败：开单状态列打❌，企业微信推送报错信息给相关人员
##
## **五、运行机制**
​ ● 轮询频率：建议5分钟一次（可配置）
​ ● bug状态同步频率：建议15分钟一次（可配置）
#