# OMNIAXS Global Hub 系统测试指南（V1）

## 0. 文档信息
- 文档名称：OMNIAXS Global Hub 系统测试指南
- 文档版本：V1.0
- 文档日期：2026-04-03
- 适用范围：M1-M4（Landing、统一 API、审批接入、中转交易、风控、实时流）
- 读者对象：QA、测试开发、后端、前端、SRE、产品经理
- 关联文档：
  - `PRD_v1.1_zh.md`
  - `docs/TECH_DEV_GUIDE_v1.1_zh.md`
  - `docs/EXTERNAL_API_SPEC_v1_zh.md`
  - `docs/openapi-v1.yaml`
  - `docs/system-architecture-baseline.html`

## 1. 测试目的（测试人员必须明确）
1. 验证产品是否满足 PRD 的业务目标与验收标准，而不是仅验证接口可用。
2. 验证“统一 API + 中转路由 + 审批状态机 + 合规约束”是否形成闭环。
3. 尽早发现跨服务回归风险，降低发布后故障率与合规风险。
4. 为发布决策提供客观证据：是否达到上线门槛，风险是否可接受。

## 2. 测试对象与范围
### 2.1 In Scope
1. Landing + Waitlist：提交、校验、Geo-Fencing、成功反馈、三语切换。
2. 市场数据 API：`markets/quotes/bars/calendar`。
3. 交易 API：下单、批量下单、改单、撤单、查单。
4. 账户 API：持仓、账户资产总览。
5. 接入申请链路：提交、审批、自动接入、绑定查询。
6. 中转路由与风控：绑定约束、失败降级、错误码一致性。
7. 实时流：WebSocket 鉴权、订阅、心跳、重连。
8. 非功能：性能、稳定性、安全、审计、可观测性。

### 2.2 Out of Scope
1. 交易所自身系统稳定性（仅验证平台侧容错行为）。
2. 未在 OpenAPI v1 中声明的实验接口。
3. 零售交易端 UI（当前项目非零售端）。

## 3. 2026 测试原则（本项目基线）
1. 风险驱动优先：先测交易主链路、审批状态机、中转路由约束。
2. 契约先行：所有 API 测试以 `openapi-v1.yaml` 作为字段与状态码事实源。
3. 自动化优先：可重复回归场景必须自动化，手工仅用于探索与例外验证。
4. 可追溯：每个测试项必须能追溯到 PRD 需求或架构基线条款。
5. 数据可复现：测试数据、时间窗、账户状态可复盘，避免“偶现无法复现”。
6. 左移 + 右移：发布前集成验证，发布后监控回归与告警有效性。

## 4. 测试环境与账号策略
### 4.1 环境矩阵
| 环境 | 用途 | 数据特性 | 放行要求 |
|---|---|---|---|
| `dev` | 开发联调 | 回放数据集 + 本地数据 | 不作为放行依据 |
| `sandbox` | 对外联调与系统测试主场 | 虚拟资金、受控限流 | 作为 M1/M2 准出依据 |
| `preprod`（建议） | 发布前演练 | 近生产配置 | 作为 prod 放行前置 |
| `prod` | 生产 | 真实流量 | 仅做灰度与回归抽检 |

### 4.2 账号与权限
1. 至少准备三类租户：`normal_tenant`、`restricted_tenant`、`unprovisioned_tenant`。
2. 至少准备两类管理员：`ops_admin`、`compliance_admin`。
3. API Scope 覆盖：`market:read`、`trade:write`、`account:read`、`risk:read`。

### 4.3 测试数据基线
1. 标的覆盖：`US_EQ`、`HK_EQ`、`CRYPTO` 至少各 1 组。
2. 订单覆盖：`market/limit/stop`、`buy/sell`、`quantity/notional`。
3. 状态覆盖：`submitted/reviewing/approved/rejected/provisioning/active`。
4. 语言覆盖：`zh-CN/en-US/ja-JP` + 回退 `en-US`。

### 4.4 测试目录约定（与仓库结构对齐）
1. 服务内测试：`apps/<service>/tests`（偏单元与服务内集成）。
2. 跨服务契约测试：`tests/contract`。
3. 跨服务集成测试：`tests/integration`。
4. 端到端测试：`tests/e2e`。
5. 系统测试与发布前回归：`tests/system`。
6. 性能与稳定性演练：`tests/performance`、`tests/chaos`。

## 5. 测试类型与目标
| 类型 | 目的 | 主要对象 | 通过标准 |
|---|---|---|---|
| API 契约测试 | 保证字段、状态码、错误码一致 | `/v1/*`、`/public/v1/*`、`/internal/v1/admin/*` | 100% 通过，无破坏性变更 |
| 集成测试 | 保证跨服务链路正确 | 下单链路、审批链路、中转路由 | 关键链路全绿 |
| E2E 测试 | 验证用户可用闭环 | Waitlist、审批、绑定后交易 | 核心路径可重复通过 |
| 回归测试 | 防止历史功能退化 | M1-M4 已上线能力 | 高优先回归 100% |
| 性能测试 | 验证延迟与吞吐门槛 | `quotes`、`orders` | 满足 SLO |
| 安全测试 | 验证认证授权与防护 | 签名、重放、RBAC、敏感数据 | 无高危未处理 |
| 稳定性测试 | 验证故障场景行为 | 连接器降级、重试、熔断 | 行为符合预期 |

## 6. 系统测试清单（按模块）
### 6.1 Landing / Waitlist
| 用例 ID | 目的 | 关键断言 | 优先级 |
|---|---|---|---|
| `ST-WL-001` | 必填校验有效 | 缺失 `work_email/country_region/consent` 返回 `422` | P0 |
| `ST-WL-002` | Geo-Fencing 阻断有效 | 限制地区返回 `403 GEOFENCE_BLOCKED` | P0 |
| `ST-WL-003` | 提交成功闭环 | 成功返回 `lead_id` 与预计联系时间 | P1 |
| `ST-WL-004` | i18n 回退正确 | 不支持语言时回退 `en-US` 且有 `Content-Language` | P1 |

### 6.2 交易主链路
| 用例 ID | 目的 | 关键断言 | 优先级 |
|---|---|---|---|
| `ST-TRD-001` | 下单成功 | `POST /v1/orders` 返回 accepted，生成订单记录 | P0 |
| `ST-TRD-002` | 幂等一致 | 同 key+同请求返回首次结果 | P0 |
| `ST-TRD-003` | 幂等冲突 | 同 key+不同请求返回 `409 IDEMPOTENCY_CONFLICT` | P0 |
| `ST-TRD-004` | 风控拦截 | 超阈值返回 `RISK_*` 且写 `risk_events` | P0 |
| `ST-TRD-005` | 中转绑定约束 | 未生效绑定返回 `ACCESS_NOT_PROVISIONED` | P0 |
| `ST-TRD-006` | 故障切换 | 首选连接器故障时按策略切备 | P1 |
| `ST-TRD-007` | 改单字段白名单 | 非允许字段修改被拒绝 | P1 |
| `ST-TRD-008` | 撤单条件校验 | 无 `order_ids/strategy_id/symbol` 返回 `422` | P1 |

### 6.3 审批接入链路
| 用例 ID | 目的 | 关键断言 | 优先级 |
|---|---|---|---|
| `ST-ACC-001` | 申请单创建 | 状态为 `submitted` | P0 |
| `ST-ACC-002` | 审批状态迁移 | 只允许定义状态迁移，禁止跨级跳转 | P0 |
| `ST-ACC-003` | 审批通过后编排 | 进入 `provisioning` 并产出 job | P0 |
| `ST-ACC-004` | 绑定生效后可交易 | `access-bindings` 可见且交易放行 | P0 |
| `ST-ACC-005` | 审批拒绝通知 | 状态 `rejected`，返回拒绝原因 | P1 |

### 6.4 实时流与可观测
| 用例 ID | 目的 | 关键断言 | 优先级 |
|---|---|---|---|
| `ST-WS-001` | WS 鉴权 | `auth` 成功后才允许订阅 | P1 |
| `ST-WS-002` | 心跳与重连 | `ping/pong` 与重连后重订阅成功 | P1 |
| `ST-OBS-001` | 审计可追溯 | 关键交易操作均有 `trace_id` 日志 | P0 |
| `ST-OBS-002` | 告警可触发 | 连接器不可用可触发 P1 告警 | P1 |

## 7. 需求追溯矩阵（最小）
| 需求来源 | 关键条目 | 对应系统测试 |
|---|---|---|
| PRD 8.1/14 | Waitlist 必填 + 成功反馈 | `ST-WL-001/003` |
| PRD 8.4 | 幂等、错误语义、限流 | `ST-TRD-002/003/008` |
| PRD 8.8 | 前置风控、故障降级 | `ST-TRD-004/006` |
| PRD 9.2 | Geo-Fencing | `ST-WL-002` + API 阻断专项 |
| 架构基线第 5 节 | 只路由到已审批绑定交易所 | `ST-TRD-005` + `ST-ACC-004` |

## 8. 缺陷等级与处理 SLA
| 等级 | 定义 | 处理目标 |
|---|---|---|
| `P0` | 核心路径不可用、数据错乱、合规失效 | 4 小时内止血，24 小时内修复 |
| `P1` | 关键功能受损、有稳定绕过方案 | 24 小时内修复 |
| `P2` | 次要功能异常，不阻塞上线 | 迭代内修复 |
| `P3` | 文案/体验类问题 | 进入待办排期 |

## 9. 准入与准出标准
### 9.1 准入（开始系统测试前）
1. OpenAPI 契约冻结并完成版本标记。
2. 测试环境可用，测试账号与权限准备完成。
3. 测试数据就绪，关键回放场景可稳定复现。
4. 已完成冒烟测试，主链路可跑通。

### 9.2 准出（允许发布前）
1. 所有 P0/P1 缺陷关闭或获得明确业务豁免。
2. 系统测试清单中 P0 全通过，P1 通过率 >= 95%。
3. 性能结果达到 SLO：`GET /v1/quotes` P95 < 400ms。
4. 安全扫描无高危未处理项。
5. 发布回滚与应急预案演练通过。

## 10. 测试执行节奏与产出物
1. 每日：测试执行日报（进度、阻塞、缺陷趋势）。
2. 每轮：系统测试报告（覆盖率、通过率、风险清单）。
3. 发布前：Go/No-Go 建议（结论 + 风险 + 豁免项）。

## 11. 测试报告模板（建议）
1. 测试范围与版本。
2. 执行统计（总用例、通过、失败、阻塞、跳过）。
3. 关键链路结果（Waitlist、交易、审批、中转、WS）。
4. 缺陷分析（按等级、模块、根因）。
5. 风险与建议（上线建议、回滚触发条件）。

## 12. 自动化与质量门禁
1. API 契约测试：每次 PR 必跑。
2. 关键链路 E2E：每日定时 + 发布前全量。
3. 回归套件：按模块分层，P0/P1 全自动化。
4. 失败自动通知：同步到研发和 QA 负责人。

## 13. 注意事项（测试团队）
1. 不允许跳过审批状态机直接造“active”数据绕过系统验证。
2. 不允许使用生产凭证或真实资金进行系统测试。
3. 任何与合规相关异常必须单独标注，不可降级为普通缺陷。