后端数据库【免费下载链接】ArcherySQL 审核查询平台项目地址https://gitcode.com/gh_mirrors/ar/Archery点击查看免费下载导读本文围绕 ArcherySQL 审核查询平台中SQL Workflow 工单操作 API 迁移特性展开系统讲解该特性从规格质量校验、功能需求分解、数据模型设计到 REST 契约落地、源码实现与测试验收的完整过程。读完本文你将掌握为什么选择WorkflowAudit.audit_id作为工单操作接口的唯一外部标识、14 组/api/v1/sql-workflows/路由的设计与调用方式、审批/拒绝/取消/执行/定时/在线改表等操作的底层实现链路以及如何通过 pytest 单测与契约校验保障迁移质量。本文主体以 specs/003-migrate-workflow-api/checklists/requirements.md 校验的规格文档为骨架并以仓库内对应源码与契约文件作为佐证。一、特性背景为什么要把工单操作迁移到 REST APIArchery 的 SQL 工单SQL Workflow此前依赖服务端渲染视图function-based views完成提交、审批、执行、定时等操作前端通过workflow_id拼接近原页面路由。该特性由用户需求驱动我想把这个文件里涉及到的对工单的操作都迁移至 rest api 来进行实现并删除原有的 view。迁移的目标对应规格中的 spec.md可以概括为三点接口化将工单操作全部暴露为 REST 端点FR-001标识统一新接口一律使用audit_id作为操作标识FR-014workflow_id仅在响应中作为参考字段返回清理旧代码REST 端点覆盖原行为后删除遗留的基于函数的工单操作视图FR-011、FR-012。规格同时明确了一个关键约束每个迁移后的操作必须直接实现在对应的 REST API view 中不得新增仅作转发或包装的一行服务函数FR-013这也体现在 Clarifications 会话 2026-08-26 的回答中。二、规格质量清单解读成文前的三道校验关卡本文所依据的 checklists/requirements.md 是一份规格质量校验清单Specification Quality Checklist其作用是在进入规划planning之前验证规格的完整性与质量。它包含三个维度全部校验通过每个条目均为[x]1. 内容质量Content Quality无实现细节泄漏不涉及语言、框架、API 等具体技术选型聚焦用户价值与业务需求面向非技术干系人可读所有强制章节已完成。2. 需求完整性Requirement Completeness无[NEEDS CLARIFICATION]标记残留需求可测试、无歧义成功标准可度量成功标准与技术实现无关所有验收场景已定义边界情况已识别范围边界清晰依赖与假设已列出。3. 特性就绪度Feature Readiness所有功能需求均有明确验收标准用户场景覆盖主流程特性满足成功标准中定义的可度量结果规格中不泄漏实现细节。清单的 Notes 特别说明REST endpoints 一词属于需求方明确的功能边界除此之外规格避免了实现选择——这正是面向业务、技术中立规格撰写方式的体现。下面的章节正是这份清单校验的对象完整特性规格的内容展开。三、需求规格主体三个用户故事与验收场景规格通过三个用户故事User Story组织全部需求其中 US1、US2 为 P1 优先级US3 为 P2。User Story 1 — 管理工单决策P1授权参与者可以通过 REST 接口对 SQL 工单执行审批approve、拒绝reject、取消cancel并保持审核状态与工单状态一致。验收场景要点审核人对待审核工单提交审批后审批被记录当必需的审批序列完成后工单进入审核通过状态发起人或被授权的取消操作者对可取消工单提供取消原因后取消动作被记录为取消/中止工单变为手工终止审核人对符合条件工单提供拒绝原因后拒绝被记录为审核人拒绝工单变为手工终止请求者权限不足、或缺少必填的取消/拒绝原因时决策被拒绝且工单与审核状态均不改变。这里对应一个规格澄清中的重要决定拒绝与取消拆分为两个独立动作——reject仅审核人可用cancel仅发起人或具备终止权限者可用FR-015避免由后端猜测请求者意图。User Story 2 — 执行与定时工单P1授权执行者可以对工单执行自动执行、手工执行、定时执行保证运维工作具有准确的状态与审核历史。验收场景要点授权执行者在允许执行时间段内请求自动执行工单进入执行队列、已有定时任务被移除、追加执行审核日志授权执行者确认手工执行完成工单标记完成并记录完成时间与手工执行日志授权执行者提供允许时间段内的未来时间工单标记为定时状态并恰好创建一个匹配的定时执行请求未授权、超出允许时间段、或定时时间为过去时间请求被拒绝不产生执行动作、不改变工单状态。User Story 3 — 查看与调整工单操作P2授权参与者可以按audit_id获取工单状态、读取详情与回滚语句有权限时、调整执行时间窗口、控制进行中的在线改表OSC操作。验收场景要点可查看工单的用户按 audit ID 获取详情直接得到保存的 SQL Workflow 详情字段无需先做列表过滤请求工单内容或当前状态时返回对应的审核/执行结果与当前状态具备回滚权限时返回可用回滚语句否则返回明确的失败结果且不泄露未授权数据授权审核人调整工单执行窗口新值被保留供后续执行检查使用授权用户控制进行中的 OSC 操作返回操作记录与状态消息。边界情况Edge Cases规格显式列出了必须处理的边界情况它们也是测试用例的输入来源工单标识缺失、格式错误或不存在请求必须失败且不改变状态工单存在定时任务时被取消或拒绝匹配的定时任务必须在请求完成前被移除审批/拒绝/取消/定时/执行在验证后失败工单与审核记录不得停留在部分更新状态工单没有保存的审核/执行结果或包含遗留结果数据授权用户仍能得到合法、可读的结果表示请求使用不支持的执行模式或 OSC 命令必须被拒绝且不改变工单状态。四、功能需求详解FR-001 ~ FR-016FR 是规格的核心也是实现与测试的验收依据FR-001为遗留工单操作视图提供的每个工单操作暴露 REST 端点覆盖工单列表、提交 SQL Workflow、按 audit ID 读取详情、读取内容、读取回滚语句、调整执行窗口、审批、拒绝、取消、执行、定时、读取当前状态、查看 OSC 进度、控制 OSC 执行FR-002每次操作前强制执行与原来相同的认证、角色、资源组、工单状态、时间窗口授权规则FR-003缺失、格式错误、不存在、未授权或无效的操作请求必须以清晰的结构化错误拒绝且不得改变工单、审核或定时数据FR-004审批、审核人拒绝、发起人取消、自动执行、手工执行、定时执行动作必须记录到工单审核历史包含操作者与操作详情FR-005每次成功操作后一致地更新工单状态与相关时间戳FR-006定时任务的创建/替换/移除必须与定时、自动执行、取消、拒绝动作保持一致定时工单被取消或拒绝时必须移除其匹配的定时任务FR-007保留审批、取消、拒绝、手工执行的既有通知行为包括该通知阶段是否启用FR-008保留工单列表的过滤、分页、搜索、可见性规则与现有工单消费者所需的响应数据FR-009详情、状态、回滚语句、OSC 控制结果仅返回给对该工单与动作有授权的用户FR-010状态变更类操作必须原子化处理失败的请求不得留下不一致的工单状态、审核历史或定时状态FR-011REST 端点覆盖遗留视图行为后删除基于函数的工单操作视图且不得有活跃路由依赖已删除的遗留视图FR-012任何有意退役的遗留端点或请求/响应行为必须记录在案并在删除前为活跃消费者提供迁移路径FR-013每个迁移操作直接实现在对应 REST API view 中不得新增仅转发/包装的一行服务函数FR-014新接口只接受audit_id详情、内容、状态、日志、回滚、执行窗口、审批、拒绝、取消、执行、定时、OSC 进度与控制响应可同时包含audit_id与遗留workflow_id但客户端不得用workflow_id调用这些接口FR-015审核人拒绝与工单取消必须为独立 API 动作reject要求审核人权限cancel要求发起人或显式授权的取消操作者FR-016本次强制的audit_id迁移范围限定为 SQL Workflow API查询权限、归档、离线导出 API 不在范围内除非它们已共享 SQL Workflow 端点。五、测试策略约束TSC-001 ~ TSC-004规格对测试策略给出四条硬性约束体现了单元测试优先、集成测试最小化的工程纪律TSC-001验证计划必须优先使用 pytest 单元测试覆盖工单权限校验、状态迁移、审核记录创建、通知资格判定、定时任务生命周期TSC-002共享测试基建必须通过 conftest.py 与可复用 fixtures 实现禁止重复搭建测试环境对应仓库根目录 conftest.pyTSC-003集成测试仅限 REST 请求处理、认证与授权、以及单元测试无法证明的持久化边界TSC-004任何新增集成测试必须附带简短理由说明为何单元测试不足以覆盖。这一约束在 test_workflow_operations_api.py 的模块 docstring 中得到印证模块内 HTTP 集成用例只覆盖URL 分发与会话身份这类服务级单元测试无法证明的边界。六、关键实体与数据模型依据>def get_sql_workflow_by_audit_id(audit_id): try: audit WorkflowAudit.objects.get(audit_idaudit_id) except WorkflowAudit.DoesNotExist as exc: raise NotFound(工单不存在) from exc if audit.workflow_type ! WorkflowType.SQL_REVIEW: raise NotFound(工单不存在) try: workflow SqlWorkflow.objects.get(idaudit.workflow_id) except SqlWorkflow.DoesNotExist as exc: raise NotFound(工单不存在) from exc return audit, workflow9.2 统一的变更响应与通知开关mutation_response 生成所有变更操作的标准响应redirect_url通过reverse(sql:detail, args(workflow_id,))指向前端详情页should_notify 读取SysConfig的notify_phase_control配置按Apply/Pass/Cancel/Execute阶段决定是否投递通知空配置默认全量开启test_should_notify_defaults_to_enabled_when_config_is_empty覆盖了该行为。9.3 审批 / 拒绝 / 取消US1三个决策端点共用transaction.atomic()包裹的原子事务审批WorkflowApprovalView校验sql.sql_review权限后经 sql/utils/workflow_audit.py 的get_auditor执行WorkflowAction.PASS审核操作当审核状态达到PASSED时工单状态更新为workflow_review_pass若通知阶段配置开启通过transaction.on_commitasync_task异步投递 Pass 通知拒绝WorkflowRejectionView要求reject_remark必填执行WorkflowAction.REJECT工单置为workflow_abort若原本是定时工单workflow_timingtask提交后移除sqlreview-timing-{workflow_id}定时任务并投递 Cancel 通知取消WorkflowTerminationView通过can_cancel校验发起人身份按操作者是否为工单提交人自动选择WorkflowAction.ABORT或WorkflowAction.REJECT后者额外要求sql.sql_review权限同样原子地中止工单、清理定时任务。三者的审核异常统一捕获AuditException记录日志后转为净化后的ValidationError({detail: ...})——这正是 FR-003 与 FR-010 的落地形态。9.4 执行与定时US2执行WorkflowExecutionView先校验sql.sql_execute/sql.sql_execute_for_resource_group权限与can_execute再用 sql/utils/sql_review.py 的on_correct_time_period校验执行窗口modeauto时工单进入workflow_queuing、写入执行工单日志事务提交后由submit_auto_execution删除同名定时任务并async_task派发 sql/utils/execute_sql.py 的异步执行modemanual时工单置为workflow_finish并记录finish_time与手工执行日志按配置投递 Execute 通知定时WorkflowScheduleViewrun_date必须晚于当前时间且落在执行窗口内工单置为workflow_timingtask写入定时执行日志提交后通过 sql/utils/tasks.py 的add_sql_schedule创建sqlreview-timing-{workflow_id}定时任务。9.5 查看与调整US3详情/内容/状态/日志WorkflowDetailView、WorkflowContentView、WorkflowStatusView、WorkflowLogView均先解析audit_id再执行可见性校验ensure_viewable/ensure_log_viewable内容接口对空或遗留 JSON 数据做规范化ReviewSet/ReviewResult重建解析失败时返回执行结果 Json 解析失败请联系管理员的友好错误而不暴露异常文本回滚WorkflowRollbackView校验can_rollback后委托引擎适配器get_engine(instance).get_rollback(workflow)失败时记录日志并返回净化后的{status: 1, msg: 获取回滚语句失败}执行窗口WorkflowExecutionWindowView要求sql.sql_review权限且Audit.can_review通过仅更新run_date_start/run_date_end两个字段PATCH语义同时兼容POSTOSCWorkflowOscViewGETcommandget仅需查看权限即可获取进度pause/resume/kill额外要求ensure_workflow_executable最终委托get_engine(workflow.instance).osc_control(...)执行。9.6 列表接口的 audit_id 注入WorkflowListView与WorkflowAuditListViewapi_workflow_operations.py保留原有的过滤状态/实例/资源组/时间范围、搜索提交人/工单名模糊匹配、分页与可见性规则超管与sql.audit_user全量可见、sql_review/资源组执行权限按组过滤、其余仅本人仅在行数据上通过一次批量WorkflowAudit查询为每行注入audit_id避免 N1 查询。十、任务编排与增量交付策略plan.md 与 tasks.md 将实现拆为 6 个阶段、共 49 个任务T001-T049全部采用checkbox 序号 可选[P]并行标记 用户故事[US#] 精确文件路径的统一格式Phase 1 Setupconftest 共享 fixtures认证用户、工单行、审核记录、内容、权限、mock 引擎/调度/通知、聚焦的 API 测试模块、OpenAPI 契约健全性测试、旧workflow_id消费方盘点Phase 2 Foundational阻塞所有故事audit_id系列序列化器、统一解析器、变更响应 helper、净化错误与日志 helper、提交后副作用 helper、路由注册与对应单测——T005 到 T011 完成后才允许故事阶段开工Phase 3 US1P1MVP审批/拒绝/取消实现T016-T020与测试T012-T015Phase 4 US2P1执行/定时实现T025-T028与测试T021-T024Phase 5 US3P2提交/列表/详情/内容/状态/日志/回滚/执行窗口/OSC 实现T034-T043与测试T029-T033Phase 6 Polish删除/弃用遗留视图与旧路由、更新退役端点迁移说明、仓库级检查T047 会失败于仍构造/api/v1/workflows/workflow_id/旧路由的调用、聚焦与全量回归T048/T049。依赖关系上US1/US2/US3 在基础阶段完成后相互独立、可并行除共享文件外每个用户故事内部遵循先测试后实现 → 序列化器/helper 先于 API view → API view 先于模板消费方的固定顺序。实施策略采用MVP 优先先完成 US1 独立验证决策链路与增量交付基础 → US1 → US2 → US3 → 清理收尾。十一、验证与验收11.1 可度量的成功标准SC-001 ~ SC-005SC-001FR-001 中识别的 SQL Workflow 操作能力 100% 通过已文档化的 REST 端点提供且无活跃路由调用遗留工单操作视图SC-002自动化测试中100% 的授权审批/拒绝/取消/执行/定时/详情/状态场景产生预期的工单状态与审核结果SC-003自动化测试中100% 的未授权或无效状态变更请求保持工单状态、审核历史与定时执行不变SC-004100% 的自动化测试运行中通过 REST 取消或拒绝的定时工单在请求完成后没有待执行的匹配定时任务SC-005既有工单用户可通过其支持客户端完成审批/拒绝/取消/执行/定时无需手工编辑工单记录。11.2 快速验证命令quickstart.md 给出三层验证# 1. 聚焦 API 测试 pytest sql_api/test_workflow_operations_api.py # 2. 工单审核单元测试 pytest sql/utils/test_workflow_audit.py sql/utils/tests.py # 3. API 回归测试 pytest sql_api/tests.py预期结果提交返回audit_id与workflow_id详情/内容/状态/日志/回滚/执行窗口/审批/拒绝/取消/执行/定时/OSC 端点接受audit_id新操作端点拒绝workflow_id作为标识用户可见的校验失败不暴露原始异常文本。11.3 前端消费方检查rg workflows/.workflow_id|workflow_id|/workflow/log/ sql/templates sql/static sql_api预期结果剩余的workflow_id仅出现在响应展示/参考字段、服务端内部解析或明确不在范围内的遗留 API 中已迁移的 SQL Workflow 前端调用一律使用audit_id构造路由与请求身份。11.4 手工浏览器冒烟在开发服务器上以具备 SQL 提交/审核/执行权限的认证用户依次执行提交工单 → 确认跳转携带audit_id→ 详情页审批 → 拒绝另一工单并核对审计历史中的拒绝原因 → 取消定时工单并确认定时任务被移除 → 手工模式执行已审批工单并核对状态与完成时间 → 对 OSC 能力工单查看进度并运行支持的控制命令。十二、迁移范围边界与后续方向规格的 Assumptions 明确划定了边界避免范围蔓延既有认证用户、权限、资源组规则、工单状态、审核记录、定时任务与通知配置仍是事实来源SQL Workflow 操作能力以sql_workflow.py中的函数为界无关的工单展示页与非工单模块不在范围内除路由与消费方更新所需查询权限query privilege与归档archive工单操作非本次强制交付物可后续以 SQL Workflow 的audit_id契约为参照模式迁移——这正是 tasks.md 与规格 Clarifications 中本次只要求 SQL Workflow 样本闭环的落点遗留端点退役前会先识别活跃消费者需要过渡的消费者将获得文档化的 REST 端点与载荷指引REST 响应沿用项目既有的结构化结果约定端点契约在规划阶段确定见 contracts/workflow-operations.openapi.yaml。结语一份可复用的规格→契约→实现→验收闭环从 checklists/requirements.md 这道质量闸门出发该特性完整走过了用户故事与验收场景 → 16 条功能需求 → 数据模型与状态迁移 → 设计决策 → OpenAPI 契约 → 源码实现 → 任务编排 → 三层验证的闭环。对阅读者而言这套体系的价值不仅在于 Archery 自身的接口演进更在于它示范了一种可复制的工程方法以audit_id这类天然稳定的业务标识统一 API 资源形态、以单元测试优先 契约测试兜底 最小化集成测试控制迁移风险、以同一变更集内完成前端消费方改造实现平滑的破坏性变更。后续如需扩展其他工单类型的 API 化本特性中的audit_id契约与增量交付节奏就是现成的参照模板。赞分享后端数据库【免费下载链接】ArcherySQL 审核查询平台项目地址https://gitcode.com/gh_mirrors/ar/Archery点击查看免费下载相关推荐Archery SQL 工单操作 REST API 迁移指南以 audit_id 为核心标识的 Workflow Operations 接口设计Archery SQL 工单操作 REST API 迁移指南以 audit_id 为核心标识的 Workflow Operations 接口设计 导读 本文基后端数据库Archery SQL Workflow 操作 API 迁移指南以 audit_id 为统一标识的 REST 化重构方案Archery SQL Workflow 操作 API 迁移指南以 audit_id 为统一标识的 REST 化重构方案 导读 本文基于 Archery 仓库后端数据库VPet 桌宠Windows 三步编译出一只还能嵌入你的程序VPet 桌宠Windows 三步编译出一只还能嵌入你的程序 刚把一下午的鼠标拖拽和窗口切换熬完你想的是一只在屏幕角落能被摸一下的宠物。VPet 是一个开源后端数据库上一篇Discord.Net 深度解析消息组件中的按钮机制下一篇PurpleLlama项目LlamaFirewall自定义扫描器开发指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考