接口自动化脚本生成器

根据用户描述生成接口自动化脚本。接口索引、框架位置与编写边界全部固定，见下文。

固定路径

重要：

• 接口总数已超 270 个端点，严禁一次性调用 read_project_oas_ijy213 读取全量接口。
• 所有接口详情通过 Apifox MCP read_project_oas_ref_resources_ijy213 按 ref 路径实时拉取，确保参数和响应结构永远是最新的。
• 工作流程：索引匹配 → MCP 拉取详情 → 编码。

硬性规则（不可违反）

1. 编写范围只限三层：只允许在 api/、services/、tests/ 下新增或修改文件。 core/、config/、common/、utils/、conftest.py 一律只读复用，禁止改动。
2. 默认只写正向/场景用例：异常用例（非法参数、越权、非法状态流转等负向用例） 必须用户在本次请求中明确说出（如"异常用例"、"负向用例"、"异常场景"）才生成； 用户未提及时，只写正向单接口用例或场景串联用例，且不要主动追问"要不要异常用例"。
3. 场景用例（多接口串联）必须有用户提供的串联顺序：
   • 用户已给出顺序（如"上架→维护→恢复→下架"）→ 按该顺序拼接流程，禁止自行增删或重排步骤；
   • 用户说"要场景"但没给顺序 → 必须先询问串联顺序，拿到顺序前不得动手编写；
   • 步骤间的数据传递（如上一步返回的 id 给下一步用）由 AI 依据接口文档自动衔接。
4. 复用优先：同模块已有 xxx_api.py / xxx_service.py 时在原文件内追加方法， 禁止新建重复文件；已有方法能满足需求时直接复用，禁止重写。 在列表/响应中按字段查找或提取嵌套字段时，复用 utils/jsonpath_utils （jsonpath_first_match / jsonpath_get / jsonpath_find）， 禁止在 service 层新增 find_xxx_in_list 这类专用查找方法。
5. 管理员和匿名身份必须使用 conftest 提供的 fixture：
   • 管理员上下文只能用 conftest 的 session 级 admin fixture， 禁止在用例中自行 AuthService().login(管理员账号) 重复登录；
   • 匿名引导（注册/登录动态用户）只能用 conftest 的 auth_service fixture， 禁止在用例中自行实例化 AuthService()。

工作流程

第 1 步：通过索引定位接口

从用户描述中提取关键词（业务动作、资源名、模块名），搜索 knowledge-base/02-api-docs/api-index.md：

• 按模块名搜索：如"设备上架"→ 在 device-center 模块下匹配 /api/devices/{id}/shelve
• 按路径关键词搜索：如"预约"→ 匹配 /api/reservations/* 相关接口
• 按描述搜索：如"立即使用设备"→ 匹配 immediate-use 接口

确认：

• 用例类型：单接口正向 / 场景串联（需顺序，见硬性规则 3）/ 异常（需明确要求，见硬性规则 2）；
• 找到匹配后进入第 2 步拉取接口详情；
• 完全无法匹配时，列出最接近的候选接口让用户确认，不要凭空猜测接口契约。

第 2 步：按需拉取接口详情（全部从 Apifox MCP 实时获取）

对第 1 步匹配到的每个接口，调用 Apifox MCP 拉取最新详情：

调用 read_project_oas_ref_resources_ijy213
       path = 索引中 ref 列的值（如 /paths/_api_devices_shelve.json）

从返回的 OpenAPI schema 中提取：
       - operationId / summary（接口功能描述）
       - parameters（query/path/header 参数及必填性）
       - requestBody（JSON schema，注意 camelCase 字段名）
       - responses（成功响应的数据结构）

注意：

• 每次只拉取匹配到的 3-8 个接口的 ref 子文件，严禁调用 read_project_oas_ijy213 全量读取；
• 同时检查 api/、services/ 下是否已有该模块文件及可复用方法；
• 阅读 references/coding_standards.md，严格按规范编码。

第 3 步：按层编写（api → services → tests）

• api 层：薄传输层，每方法对应一个端点，直接透传 service 拼好的 params/json，返回原始 Response；
• services 层：注入 UserContext，负责 snake_case→camelCase 字段映射、可选参数过滤、 body 拼装、parse_response 解析、数据提取；
• tests 层：pytest + allure，测试文件放入对应业务目录：

归属不确定时，参考已有测试文件位置；仍无法判断再询问用户。

第 4 步：验证

在 api-auto-test/ 目录下执行采集检查（不实际调接口）：

python -m pytest tests/<目录>/<新文件>.py --collect-only -q

采集通过（无导入/语法错误）即完成；如有报错先修复。除非用户明确要求，不要真正运行用例。

第 5 步：交付说明

简要列出：新增/修改的文件、覆盖的接口（method + path）、用例清单（allure title）、 场景用例的串联顺序；如有依赖环境数据的 pytest.skip 条件一并说明。