From e958f73af024ddca28a9417abe5c7c6f4e1227df Mon Sep 17 00:00:00 2001 From: zelong <2895587166@qq.com> Date: Thu, 25 Dec 2025 15:14:03 +0800 Subject: [PATCH] 'remove-useless-md' --- config/config.ini | 4 +- 开发路线.md | 830 ---------------------------------------------- 需求文档.md | 55 --- 3 files changed, 2 insertions(+), 887 deletions(-) delete mode 100644 开发路线.md delete mode 100644 需求文档.md diff --git a/config/config.ini b/config/config.ini index 4a0c0f0..cad2c68 100644 --- a/config/config.ini +++ b/config/config.ini @@ -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 diff --git a/开发路线.md b/开发路线.md deleted file mode 100644 index 4eee20a..0000000 --- a/开发路线.md +++ /dev/null @@ -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. 支持更多的字段类型和复杂映射规则 diff --git a/需求文档.md b/需求文档.md deleted file mode 100644 index d049f3c..0000000 --- a/需求文档.md +++ /dev/null @@ -1,55 +0,0 @@ -# **Debug阶段自动开单工具需求** - -## **一、功能概述** - -策划在腾讯智能表格填写bug信息，工具定时扫描并自动在TAPD创建bug单，实现表格到TAPD的单向同步。 - - - -## **二、表格字段设计** - -| **列** | **说明** | **备注** | -| -------- | -------- | ---------------- | -| 标题 | 必填 | 同步为TAPD标题 | -| 详细描述 | 必填 | | -| 优先级 | 必填 | 单选 | -| 严重程度 | 必填 | 单选 | -| 处理人 | 必填 | | -| 验证人 | 必填 | | -| 发现版本 | 必填 | | -| 模块 | 必填 | | -| 开单状态 | 工具回写 | ✅成功 / ❌失败 | -| TAPD单号 | 工具回写 | 可点击跳转 | -| bug状态 | 工具回写 | 同步TAPD当前状态 | - -## - -## **三、处理逻辑** - -​ 1. 定时扫描"开单状态"为空的行 - -​ 2. 校验必填项是否完整 - -​ 3. 调用TAPD API创建bug单 - -​ 4. 回写结果到表格 - -## - -## **四、异常处理** - -​ ● 开单成功：开单状态列打✅，回写单号和状态 - -​ ● 开单失败：开单状态列打❌，企业微信推送报错信息给相关人员 - -## - -## **五、运行机制** - -​ ● 轮询频率：建议5分钟一次（可配置） - -​ ● bug状态同步频率：建议15分钟一次（可配置） - -# - - \ No newline at end of file