[Documentation] Define TestPlatform integration contract

.gitignore

@@ -20,6 +20,7 @@ Reports/allure-results/
 Reports/allure-report/
 Reports/api-results/
 Reports/ui-results/
+Reports/platform/
 Reports/logs/
 UI_Automation/screenshots/
 *.log
@@ -58,7 +59,12 @@ allure-results-history/
 config/local.yml
 
 # ==================== Web UI 运行产物 ====================
+Reports/webui-runs/
 Reports/webui-runs/*/logs.txt
 Reports/webui-runs/*/allure-results/
 Reports/webui-runs/*/allure-report/
 tools/webui/.env
+
+# ==================== Local Playwright probes ====================
+recon.py
+test_basic.py

README.md

@@ -10,7 +10,11 @@
 
 ## 📋 项目简介
 
-本项目是一个完整的 **iOS 移动端自动化测试框架**，以**云鹿商城 App** 为测试对象，实现了 **UI 自动化测试**、**接口自动化测试**、**性能测试** 三位一体的测试解决方案，并内置 **Web 控制台**，支持在浏览器中浏览代码、执行测试、查看实时日志和 Allure 报告。
+本项目是一个完整的 **iOS 移动端自动化测试工程**，以**云鹿商城 App** 为测试对象，实现了 **UI 自动化测试**、**接口自动化测试**、**性能测试** 三位一体的测试解决方案。
+
+它在通用测试平台体系中的定位是：**测试代码载体和第一个接入样板**。本仓库负责“怎么测”，例如 pytest/Appium 用例、Page Object、测试数据、断言和报告输出；通用平台和 Local Agent 负责“谁来调度、在哪里执行、如何回传结果”。
+
+内置的 `tools/webui` 仅作为单项目本地 Demo 控制台，用于浏览代码、执行测试、查看实时日志和 Allure 报告，不承担平台中心或通用 Agent 职责。
 
 ### 核心特性
 
@@ -22,7 +26,8 @@
 | 📈 **Allure 报告** | 可视化测试报告，支持历史趋势 |
 | 🔄 **GitHub Actions CI** | 自动化流水线，PR 触发执行 |
 | ⚡ **性能测试** | 基于 Locust 的压力测试脚本 |
-| 🌐 **Web 控制台** | 本地 Web UI，支持代码浏览、测试执行、AI 问答 |
+| 🌐 **本地 Demo 控制台** | 本地 Web UI，支持代码浏览、测试执行、AI 问答 |
+| 🔗 **平台接入协议** | 通过 `test-platform.yml` 描述套件、命令、依赖和产物路径 |
 
 ---
 
@@ -37,7 +42,7 @@ graph TD
 
     B & C & D --> E[🛠️ 基础设施层<br/>Config / Logger / Utils]
     E --> F[🚀 CI/CD 层<br/>GitHub Actions / Fastlane]
-    E --> G[🌐 Web 控制台<br/>FastAPI + Alpine.js]
+    E --> G[🌐 本地 Demo 控制台<br/>FastAPI + Alpine.js]
 ```
 
 ---
@@ -47,6 +52,7 @@ graph TD
 ```
 iOS-Automation-Framework/
 ├── README.md                      # Project documentation
+├── test-platform.yml              # TestPlatform suite contract
 ├── requirements.txt               # Python dependencies
 ├── pytest.ini                     # pytest configuration
 ├── conftest.py                    # Global fixtures
@@ -122,7 +128,7 @@ iOS-Automation-Framework/
 │           └── allure-report/     # Allure HTML 报告
 │
 ├── tools/                         # 工具目录
-│   └── webui/                     # Web 控制台
+│   └── webui/                     # 本地 Demo 控制台
 │       ├── app.py                 # FastAPI 主入口
 │       ├── config.py              # 配置（读取环境变量）
 │       ├── models.py              # Run 任务模型
@@ -138,7 +144,8 @@ iOS-Automation-Framework/
 │           └── index.html         # Alpine.js 单页前端
 │
 └── docs/                          # Documentation
-    └── design.md                  # Design notes
+    ├── design.md                  # Design notes
+    └── platform-integration.md    # TestPlatform integration notes
 ```
 
 | 目录 | 说明 |
@@ -150,7 +157,9 @@ iOS-Automation-Framework/
 | `Performance/` | Locust 性能压测脚本 |
 | `CI/` | GitHub Actions / Fastlane 配置 |
 | `Reports/` | Allure 报告输出目录，webui-runs/ 存放 Web UI 运行记录 |
-| `tools/webui/` | Web 控制台：代码浏览、测试执行、AI 问答 |
+| `test-platform.yml` | 平台接入协议：声明项目、套件、命令、依赖和产物路径 |
+| `tools/webui/` | 本地 Demo 控制台：代码浏览、测试执行、AI 问答 |
+| `docs/platform-integration.md` | 与 TestPlatform / Local Agent 的职责边界和接入说明 |
 
 ---
 
@@ -212,11 +221,37 @@ cd Performance/locust_scripts
 locust -f locustfile.py --host=https://api-dev.yunlu.com
 ```
 
+### 平台接入执行
+
+通用平台或 Local Agent 应读取仓库根目录的 `test-platform.yml`，根据任务选择 suite 并执行其中的命令。
+
+示例：
+
+```bash
+# 平台任务 task_id=local-demo-001 时，API 全量套件可写入固定产物目录
+python -m pytest API_Automation/cases -v --alluredir=Reports/platform/local-demo-001/allure-results
+
+# UI 套件由 Local Agent 负责准备 Appium、设备和 ipa/app 包路径
+python -m pytest UI_Automation/Tests -v -n 0 --alluredir=Reports/platform/local-demo-001/allure-results
+```
+
+平台触发的运行建议统一输出到：
+
+```text
+Reports/platform/{task_id}/
+├── logs.txt
+├── allure-results/
+├── allure-report/
+└── screenshots/
+```
+
+被测 `.ipa` / `.app` 包应作为平台任务参数传入，例如 `app_path` 或 `app_url`。本仓库不负责构建 App，也不负责通用任务调度。
+
 ---
 
-## 🌐 Web 控制台
+## 🌐 本地 Demo 控制台
 
-内置本地 Web UI，无需命令行即可浏览代码、执行测试、查看实时日志和 Allure 报告。
+内置本地 Web UI，无需命令行即可浏览代码、执行测试、查看实时日志和 Allure 报告。它只用于本仓库本地调试和演示，不是通用测试平台。
 
 ### 启动
 
@@ -270,6 +305,7 @@ cp tools/webui/.env.example tools/webui/.env
 
 - iOS UI 测试需要 **macOS + Xcode + Appium**，Windows/Linux 下 UI 模块自动禁用
 - Web UI 仅供本地单用户 Demo 使用，不适合生产部署
+- 通用 Local Agent 应放在 TestPlatform 侧，本仓库只暴露测试套件和执行命令
 - 接入真实 AI 需设置 `AI_PROVIDER=claude` 和 `AI_API_KEY`
 
 ### 为什么选择 Page Object 模式？

docs/platform-integration.md

@@ -0,0 +1,64 @@
+# Test Platform Integration
+
+This repository is a test project, not the test platform itself.
+
+It provides the automation code and suite metadata that a platform-side Local Agent can execute. The platform is responsible for task creation, scheduling, executor management, report indexing, and AI analysis.
+
+## Responsibilities
+
+This repository owns:
+
+- API automation tests under `API_Automation/`.
+- iOS UI automation tests under `UI_Automation/`.
+- Performance scripts under `Performance/`.
+- Test data, page objects, fixtures, and assertions.
+- `test-platform.yml`, which describes executable suites and required capabilities.
+
+This repository does not own:
+
+- Multi-project management.
+- Platform authentication or authorization.
+- Platform database tables.
+- Generic task scheduling.
+- Generic Local Agent implementation.
+- Long-term executor lifecycle management.
+
+## Execution Model
+
+```text
+TestPlatform
+  -> creates a task with project, suite, environment, and optional app artifact
+
+Local Agent
+  -> reads test-platform.yml
+  -> downloads or locates the ipa/app artifact when needed
+  -> runs the selected suite command
+  -> collects logs, screenshots, and Allure results
+  -> uploads results back to TestPlatform
+
+iOS-Automation-Framework
+  -> contains the test code and produces test outputs
+```
+
+## App Artifacts
+
+UI suites can test an app package passed by the platform as:
+
+- `app_path`: local `.ipa` or `.app` path.
+- `app_url`: remote artifact URL downloaded by the Local Agent.
+
+The test code should read the final local app path from local configuration or environment variables prepared by the Local Agent.
+
+## Output Convention
+
+Platform-triggered runs should write outputs under:
+
+```text
+Reports/platform/{task_id}/
+├── logs.txt
+├── allure-results/
+├── allure-report/
+└── screenshots/
+```
+
+The Local Agent owns log capture and upload. This repository only needs to make sure suite commands can write deterministic report paths.

test-platform.yml

@@ -0,0 +1,100 @@
+schema_version: 1
+
+project:
+  key: yunlu-ios
+  name: Yunlu iOS automation tests
+  description: API, iOS UI, and performance automation suites for Yunlu Mall.
+  type: mobile_app_tests
+
+repository:
+  role: test_repository
+  framework:
+    - pytest
+    - appium
+    - locust
+    - allure
+  platform:
+    - ios
+
+artifacts:
+  default_root: Reports/platform
+  allure_results: Reports/platform/{task_id}/allure-results
+  allure_report: Reports/platform/{task_id}/allure-report
+  logs: Reports/platform/{task_id}/logs.txt
+  screenshots: Reports/platform/{task_id}/screenshots
+
+parameters:
+  app_path:
+    description: Local ipa/app path or downloaded artifact path used by UI suites.
+    required: false
+  app_url:
+    description: Remote ipa/app artifact URL. The Local Agent should download it before running UI suites.
+    required: false
+  environment:
+    description: Target test environment, such as dev, staging, or prod.
+    required: true
+    default: staging
+
+suites:
+  - id: api_smoke
+    name: API smoke tests
+    type: api
+    command: python -m pytest API_Automation/cases -v -m smoke --alluredir=Reports/platform/{task_id}/allure-results
+    report:
+      allure: true
+    outputs:
+      allure_results: Reports/platform/{task_id}/allure-results
+
+  - id: api_all
+    name: API full regression
+    type: api
+    command: python -m pytest API_Automation/cases -v --alluredir=Reports/platform/{task_id}/allure-results
+    report:
+      allure: true
+    outputs:
+      allure_results: Reports/platform/{task_id}/allure-results
+
+  - id: ios_ui_smoke
+    name: iOS UI smoke tests
+    type: ui
+    command: python -m pytest UI_Automation/Tests -v -n 0 -m smoke --alluredir=Reports/platform/{task_id}/allure-results
+    requires:
+      - macos
+      - xcode
+      - appium
+      - ios_device_or_simulator
+    accepts_artifact:
+      - ipa
+      - app
+    report:
+      allure: true
+    outputs:
+      allure_results: Reports/platform/{task_id}/allure-results
+      screenshots: Reports/platform/{task_id}/screenshots
+
+  - id: ios_ui_all
+    name: iOS UI full regression
+    type: ui
+    command: python -m pytest UI_Automation/Tests -v -n 0 --alluredir=Reports/platform/{task_id}/allure-results
+    requires:
+      - macos
+      - xcode
+      - appium
+      - ios_device_or_simulator
+    accepts_artifact:
+      - ipa
+      - app
+    report:
+      allure: true
+    outputs:
+      allure_results: Reports/platform/{task_id}/allure-results
+      screenshots: Reports/platform/{task_id}/screenshots
+
+  - id: performance_all
+    name: Performance tests
+    type: performance
+    command: locust -f Performance/locust_scripts/locustfile.py --headless
+    requires:
+      - network
+    report:
+      allure: false