# OMNIAXS Global Hub 技术开发文档（V1.1-r2）

## 0. 文档信息
- 文档名称：OMNIAXS Global Hub 技术开发文档
- 对应 PRD：`PRD_v1.1_zh.md`
- 文档版本：V1.1-r2
- 文档日期：2026-04-03
- 适用阶段：M1-M4（从官网转化到统一交易 API）
- 读者对象：产品、后端、前端、风控、QA、运维、法务合规、对接团队
- 依赖文档：
  - `PRD_v1.1_zh.md`（需求基线）
  - `docs/EXTERNAL_API_SPEC_v1_zh.md`（对外接口语义）
  - `docs/openapi-v1.yaml`（接口字段与路径契约）
  - `docs/system-architecture-baseline.html`（架构冻结基线）
  - `docs/SYSTEM_TEST_GUIDE_v1_zh.md`（系统测试执行基线）
  - `docs/DEV_CODING_STANDARD_2026_zh.md`（开发规范基线）

## 1. 文档目标与范围
### 1.1 目标
本文档用于将 PRD 要求转换为可执行的工程实现方案，覆盖：
1. 系统架构与服务边界。
2. 数据模型与存储设计。
3. 核心业务流程（行情、交易、账户、风控、合规、Waitlist）。
4. 开发规范、测试策略、发布运维、里程碑拆解。
5. 对接连接器的标准协议，保证“一个 API 接入全球多市场”。

### 1.2 范围（In Scope）
1. 官网单页与 Waitlist 留资漏斗。
2. 统一 API 网关（v1）及 Sandbox 环境。
3. 行情、下单、撤单、订单查询、持仓、账户、系统状态能力。
4. 风控前置检查、盘中风险事件、审计日志。
5. 非托管声明、Geo-Fencing、防御性合规文案链路。
6. 首批连接器框架（Alpaca、Quantower 抽象接入）。

### 1.3 非范围（Out of Scope）
1. 资金托管、法币清算、券商账户代开。
2. 面向零售用户的投资建议与收益承诺。
3. 一期覆盖全部国家/交易所，不承诺一次性全覆盖。

### 1.4 文档使用与冲突处理规则（强制）
1. 本文档回答“怎么做”；`PRD` 回答“做什么”；`EXTERNAL_API_SPEC` 回答“对外怎么说”；`openapi-v1.yaml` 回答“字段和路径是什么”。
2. 若文字说明与 OpenAPI 字段冲突，以 `docs/openapi-v1.yaml` 为唯一事实源，并在同一提交中修正文档描述。
3. 若 PRD 新增需求但 API 尚未体现，先在本文档补充“落地方案 + 里程碑归属 + 验收口径”，再更新 OpenAPI。
4. 任何影响控制面/数据面边界、审批状态机、中转路由约束、三语范围的修改，必须走 ACR。

## 2. 总体架构设计
### 2.1 架构原则
1. 非托管：平台仅做技术接入与路由，不触达客户法币资产。
2. 统一抽象：统一 symbol / order / risk / error 语义。
3. 可扩展：连接器插件化，可在 3 周内完成单连接器接入。
4. 可审计：订单、风控、路由、权限操作全链路追踪。
5. 可降级：上游故障时快速熔断/切换，避免级联故障。
6. 控制面与数据面分离：审批与接入编排走控制面，行情/交易走数据面，避免权限和稳定性互相污染。

### 2.2 逻辑架构
```mermaid
flowchart LR
    U[机构用户/量化系统] --> G[API Gateway]
    W[Landing/Waitlist] --> LW[Lead Service]

    G --> AUTH[Auth & Tenant Service]
    G --> MKT[Market Data Service]
    G --> OMS[Order Management Service]
    G --> RMS[Risk Engine Service]
    G --> PMS[Portfolio Service]
    G --> STS[Status Service]

    OMS --> RTR[Router Service]
    RTR --> CNM[Connector Manager]
    CNM --> C1[Connector: Alpaca]
    CNM --> C2[Connector: Quantower]
    CNM --> C3[Connector: Future Venues]

    MKT --> TSDB[(Timeseries DB)]
    OMS --> PG[(PostgreSQL)]
    RMS --> PG
    PMS --> PG
    AUTH --> PG
    LW --> PG

    OMS --> BUS[(Event Bus)]
    RMS --> BUS
    CNM --> BUS
    BUS --> AUD[Audit Service]
    BUS --> NTF[Webhook/Notification Service]

    OBS[Observability Stack] --- G
    OBS --- MKT
    OBS --- OMS
    OBS --- RMS
```

### 2.3 运行时拓扑（默认落地）
1. 区域策略：
   - `ap-southeast-1` 主区域（离岸部署优先）。
   - `ap-northeast-1` 灾备区域（只读与故障切换）。
2. 网络分层：
   - Public 子网：API 网关、WAF、CDN、Landing。
   - Private 子网：核心微服务、数据库、消息总线。
3. 环境隔离：
   - `dev`：开发联调，可使用 connector sandbox。
   - `sandbox`：外部开发者测试，虚拟资金与限流更严格。
   - `prod`：生产交易流量。
4. 基础设施：
   - 容器编排：Kubernetes（EKS/GKE/ACK 同级）。
   - 网关入口：Nginx Ingress + API Gateway Service。
   - 配置中心：`configs/*` + 环境变量注入 + GitOps（版本化）。

### 2.4 服务清单与职责
| 服务 | 核心职责 | 关键输入 | 关键输出 |
|---|---|---|---|
| `landing-web` | 官网展示、i18n（zh/en/ja）、Waitlist 弹层 | 访客请求 | 页面、表单提交 |
| `lead-service` | 留资入库、反垃圾、UTM 记录 | 表单数据 | lead 记录、CRM 事件 |
| `api-gateway` | 统一鉴权、限流、路由、协议适配 | REST/WS 请求 | 标准化响应 |
| `identity-service` | API Key 管理、用户/管理员身份、JWT 发放与审计查询 | 登录/注册请求、Key 管理请求 | 鉴权结果、租户上下文、访问令牌 |
| `market-data-service` | Snapshot/Bars/Trade/Depth 聚合 | symbol/timeframe | 标准行情数据 |
| `oms-service` | 下单/改单/撤单/订单查询 | 标准订单请求 | 订单状态、执行回报 |
| `risk-engine-service` | 前置风控、盘中触发、风险审计 | 订单、持仓、限额规则 | 风控判定、事件 |
| `router-service` | 连接器选择、故障切换、重试 | 合规订单对象 | 路由结果、上游回报 |
| `portfolio-service` | 账户资产、持仓、PnL 聚合 | 上游回报、行情 | 账户与持仓快照 |
| `notification-service` | Webhook 投递、失败重试 | 订单/风控事件 | 回调、投递日志 |
| `admin-portal-web` | 运营后台（审批、配置、审计） | 管理员操作 | 审批结果、配置变更 |
| `access-application-service` | 接入申请管理（用户申请单） | 申请表单/API | 申请状态、审批任务 |
| `approval-workflow-service` | 审批流与SLA计时 | 申请单、审批动作 | 通过/拒绝/补件结果 |
| `provisioning-orchestrator` | 自动开通交易所连接与凭证绑定 | 已审批申请单 | 连接绑定、失败回滚 |
| `exchange-credential-vault` | 交易所 API 凭证托管（平台级） | 开发团队录入/轮换 | 加密凭证、版本记录 |
| `exchange-registry-service` | 交易所目录、能力矩阵、健康评分 | 交易所配置 | 可用交易所清单 |
| `relay-api-service` | 中转 API（统一调用 -> 指定交易所） | 标准化交易请求 | 上游调用与标准化回包 |

### 2.5 控制面/数据面基线（新增强制）
1. 控制面（Control Plane）：
   - 前台申请入口、后台审批中心、交易所配置中心、凭证管理、接入编排。
   - 核心服务：`access-application-service`、`approval-workflow-service`、`exchange-registry-service`、`provisioning-orchestrator`、`exchange-credential-vault`。
2. 数据面（Data Plane）：
   - 行情、交易、持仓、风控、中转 API 请求处理。
   - 核心服务：`api-gateway`、`market-data-service`、`oms-service`、`risk-engine-service`、`relay-api-service`、`router-service`。
3. 强制隔离规则：
   - 控制面可操作数据面配置，但不可直接处理实时交易流量。
   - 数据面仅读取已发布配置，不得绕过审批状态执行自动接入。
   - 生产写入交易所凭证仅允许控制面 `exchange-credential-vault` 完成。

```mermaid
flowchart TB
    subgraph Frontend[Frontend Layer]
      LP[Landing & Dev Portal]
      AP[Admin Portal]
    end

    subgraph CP[Control Plane]
      AAS[Access Application Service]
      AWS[Approval Workflow Service]
      ERS[Exchange Registry Service]
      EVO[Exchange Credential Vault]
      PO[Provisioning Orchestrator]
    end

    subgraph DP[Data Plane]
      G[API Gateway]
      RLY[Relay API Service]
      OMS[OMS]
      RMS[Risk Engine]
      RTR[Router]
    end

    subgraph EX[Exchange Layer]
      EX1[Exchange A]
      EX2[Exchange B]
      EXN[Exchange N]
    end

    LP --> AAS --> AWS
    AP --> AWS
    AP --> ERS
    AP --> EVO
    AWS --> PO --> ERS
    PO --> G
    G --> RLY --> OMS --> RMS --> RTR
    RTR --> EX1
    RTR --> EX2
    RTR --> EXN
```

## 3. 技术选型与工程规范
### 3.1 默认技术栈（如需替换必须走 ACR）
1. 前端：Next.js 15 + TypeScript + Tailwind（Landing 可独立静态部署）。
2. 后端 API：Python 3.12 + FastAPI + Pydantic v2（异步 I/O）。
3. 异步消息：默认 `NATS JetStream`（低延迟）；若吞吐与保留需求超出阈值再评估 Kafka。
4. 关系数据库：PostgreSQL 16。
5. 时序存储：TimescaleDB（Bars/Trade）+ Redis（热数据缓存）。
6. 缓存与限流：Redis Cluster。
7. 任务调度：默认 `Temporal`（用于编排、重试、回补）；轻量任务可用 Arq。
8. 可观测性：OpenTelemetry + Prometheus + Grafana + Loki + Tempo。
9. CI/CD：GitHub Actions + Docker + Helm + ArgoCD。
10. 密钥管理：KMS + Secret Manager（不落盘明文）。

### 3.2 代码与仓库结构基线（已落地）
```text
omniaxs-api-markets/
  apps/
    landing-web/
      src/
      tests/
      README.md
    api-gateway/
      src/
      tests/
      README.md
    lead-service/
      src/
      tests/
      README.md
    market-data-service/
      src/
      tests/
      README.md
    oms-service/
      src/
      tests/
      README.md
    risk-engine-service/
      src/
      tests/
      README.md
    portfolio-service/
      src/
      tests/
      README.md
    router-service/
      src/
      tests/
      README.md
    notification-service/
      src/
      tests/
      README.md
    admin-portal-web/
      src/
      tests/
      README.md
    access-application-service/
      src/
      tests/
      README.md
    approval-workflow-service/
      src/
      tests/
      README.md
    provisioning-orchestrator/
      src/
      tests/
      README.md
    exchange-credential-vault/
      src/
      tests/
      README.md
    exchange-registry-service/
      src/
      tests/
      README.md
    relay-api-service/
      src/
      tests/
      README.md
  libs/
    core-models/
      src/
      tests/
      README.md
    connector-sdk/
      src/
      tests/
      README.md
    auth-signature/
      src/
      tests/
      README.md
    risk-rules/
      src/
      tests/
      README.md
    observability/
      src/
      tests/
      README.md
  infra/
    helm/
      README.md
    terraform/
      README.md
  tests/
    contract/
    integration/
    e2e/
    system/
    performance/
    chaos/
    README.md
  scripts/
    dev/
    ci/
    ops/
    README.md
  configs/
    locales/
      zh-CN/
      en-US/
      ja-JP/
    geo-fencing/
    README.md
  docs/
    TECH_DEV_GUIDE_v1.1_zh.md
    EXTERNAL_API_SPEC_v1_zh.md
    SYSTEM_TEST_GUIDE_v1_zh.md
    DEV_CODING_STANDARD_2026_zh.md
    openapi-v1.yaml
```

目录职责说明：
1. `apps/*`：独立可部署服务，每个目录一个服务边界，不混放跨域逻辑。
2. `libs/*`：跨服务复用库，只放通用模型与公共能力。
3. `tests/*`：跨服务测试资产；服务内单元测试放在 `apps/*/tests`。
4. `scripts/*`：自动化脚本入口，按开发/CI/运维分层。
5. `configs/*`：非密钥配置与规则（多语言、Geo-Fencing）；敏感信息仅通过密钥管理系统注入。
6. `infra/*`：部署与基础设施定义（Helm/Terraform）。

### 3.3 工程标准
1. API Schema 统一由 OpenAPI 驱动，禁止手写不一致 DTO。
2. 所有写接口必须通过 Header `Idempotency-Key` 传入幂等键。
3. 所有服务必须注入 `trace_id`，并贯穿日志/事件/响应头。
4. Connector 通过契约测试（contract tests）后方可接入生产。
5. 变更要求：PR 至少 1 名后端 + 1 名 QA 审阅。
6. 幂等存储唯一键必须至少包含：`tenant_id + endpoint + idempotency_key`，禁止全局单列唯一。

### 3.4 多语言基线（新增强制）
1. 支持语言：`zh-CN`、`en-US`、`ja-JP`（简称中/英/日）。
2. 前端站点（Landing、开发者中心、后台管理）必须支持三语切换。
3. 后端接口必须支持 `Accept-Language`，并在响应文案（如 `message`）按语言返回。
4. 缺失翻译回退规则：`ja-JP -> en-US`，`zh-CN -> en-US`，最终不得返回空文案。
5. 错误消息采用 `error_code + i18n_key` 机制，禁止仅用硬编码中文或英文。
6. 文案来源统一配置中心管理，禁止在多处复制粘贴造成语义漂移。

### 3.5 契约同步与发布规则（强制）
1. 接口新增/删改顺序固定为：先改 `openapi-v1.yaml`，再改实现，最后回填 `EXTERNAL_API_SPEC` 示例。
2. CI 必须执行 OpenAPI breaking-change 检查，`/v1` 不允许破坏性字段变更。
3. 每次发布必须产出契约版本标签（如 `api-v1.0.3`）并记录在发布说明。
4. 文档示例 JSON 必须来源于联调测试快照，禁止手写与实际响应不一致的示例。
5. 编码风格、命名、注释和长度约束统一遵循 `docs/DEV_CODING_STANDARD_2026_zh.md`。

## 4. 领域模型与数据设计
### 4.1 核心实体
1. 租户（Tenant）与 API 凭证（Credential）。
2. 市场定义（Market Instrument）与会话日历（Session Calendar）。
3. 订单（Order）、路由（Order Route）、成交（Execution）。
4. 账户（Account Snapshot）、持仓（Position Snapshot）、PnL。
5. 风控规则（Risk Policy）与风控事件（Risk Event）。
6. 留资线索（Waitlist Lead）。
7. 审计日志（Audit Log）与回调投递（Webhook Delivery）。

### 4.2 数据库表（核心）

#### 4.2.1 `tenants`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 租户主键 |
| `name` | varchar(128) | not null | 机构名 |
| `env` | varchar(16) | idx | `sandbox`/`prod` |
| `status` | varchar(16) | idx | `active`/`suspended` |
| `created_at` | timestamptz | not null | 创建时间 |
| `updated_at` | timestamptz | not null | 更新时间 |

#### 4.2.2 `api_credentials`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 凭证主键 |
| `tenant_id` | uuid | FK+idx | 关联租户 |
| `api_key` | varchar(64) | unique | 对外 Key |
| `api_secret_ciphertext` | text | not null | 加密密文 |
| `sign_algo` | varchar(32) | default `HMAC-SHA256` | 签名算法 |
| `scopes` | jsonb | not null | 权限集合 |
| `status` | varchar(16) | idx | `active`/`revoked` |
| `last_used_at` | timestamptz | idx | 最近使用 |

#### 4.2.3 `waitlist_leads`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 线索 ID |
| `email` | varchar(255) | idx,not null | 工作邮箱 |
| `contact_handle` | varchar(255) | null | WhatsApp/Telegram/X |
| `country_region` | varchar(64) | idx,not null | 国家地区 |
| `institution_type` | varchar(64) | null | 机构类型 |
| `preferred_language` | varchar(8) | default `en-US` | 偏好语言（zh-CN/en-US/ja-JP） |
| `consent` | boolean | not null | 同意条款 |
| `utm_source` | varchar(64) | idx | 来源 |
| `utm_campaign` | varchar(64) | idx | 活动 |
| `referrer` | varchar(1024) | null | 来源页 |
| `ip_hash` | varchar(128) | idx | 脱敏 IP 哈希 |
| `created_at` | timestamptz | idx | 提交时间 |

#### 4.2.4 `market_instruments`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 主键 |
| `symbol` | varchar(64) | idx | 平台标准 symbol |
| `venue` | varchar(32) | idx | 交易场所 |
| `venue_symbol` | varchar(64) | idx | 上游 symbol |
| `asset_class` | varchar(32) | idx | `equity`/`fx`/`crypto`... |
| `session_type` | varchar(32) | | 正常/盘前/盘后/24x5 |
| `price_precision` | int | | 价格精度 |
| `qty_precision` | int | | 数量精度 |
| `status` | varchar(16) | idx | `active`/`halted` |
| `updated_at` | timestamptz | | 更新时间 |

#### 4.2.5 `orders`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 平台订单 ID |
| `tenant_id` | uuid | FK+idx | 租户 |
| `client_order_id` | varchar(64) | idx | 客户订单号 |
| `idempotency_key` | varchar(72) | idx | 幂等键（参与联合唯一约束） |
| `idempotency_scope` | varchar(64) | idx | 幂等作用域（如 `POST /v1/orders`） |
| `symbol` | varchar(64) | idx | 标的 |
| `side` | varchar(8) | idx | `buy`/`sell` |
| `type` | varchar(16) | idx | `market`/`limit`/`stop` |
| `time_in_force` | varchar(8) | | `GTC`/`IOC`... |
| `price` | numeric(28,10) | null | 限价/止损价 |
| `quantity` | numeric(28,10) | null | 数量（与 `notional` 二选一） |
| `notional` | numeric(28,10) | null | 名义金额 |
| `reduce_only` | boolean | default false | 仅减仓 |
| `post_only` | boolean | default false | 仅挂单 |
| `strategy_id` | varchar(64) | idx | 策略标签 |
| `status` | varchar(16) | idx | `new`/`filled`/`rejected`... |
| `reject_code` | varchar(64) | null | 拒单码 |
| `created_at` | timestamptz | idx | 创建时间 |
| `updated_at` | timestamptz | idx | 更新时间 |

#### 4.2.6 `order_routes`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 路由主键 |
| `order_id` | uuid | FK+idx | 关联订单 |
| `connector` | varchar(64) | idx | 使用连接器 |
| `venue` | varchar(32) | idx | 目标 venue |
| `attempt_no` | int | | 第几次尝试 |
| `upstream_order_id` | varchar(128) | idx | 上游订单号 |
| `latency_ms` | int | | 路由时延 |
| `result` | varchar(16) | idx | `success`/`failed` |
| `error_payload` | jsonb | null | 上游错误透传 |
| `created_at` | timestamptz | idx | 时间 |

#### 4.2.7 `executions`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 成交 ID |
| `order_id` | uuid | FK+idx | 平台订单 |
| `execution_id` | varchar(128) | unique | 上游成交号 |
| `price` | numeric(28,10) | not null | 成交价 |
| `quantity` | numeric(28,10) | not null | 成交量 |
| `fee` | numeric(28,10) | default 0 | 费用 |
| `liquidity` | varchar(8) | null | `maker`/`taker` |
| `executed_at` | timestamptz | idx | 成交时间 |

#### 4.2.8 `position_snapshots`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | bigserial | PK | 主键 |
| `tenant_id` | uuid | FK+idx | 租户 |
| `symbol` | varchar(64) | idx | 标的 |
| `net_qty` | numeric(28,10) | | 净仓 |
| `avg_price` | numeric(28,10) | | 均价 |
| `unrealized_pnl` | numeric(28,10) | | 未实现盈亏 |
| `realized_pnl` | numeric(28,10) | | 已实现盈亏 |
| `snapshot_at` | timestamptz | idx | 快照时间 |

#### 4.2.9 `account_snapshots`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | bigserial | PK | 主键 |
| `tenant_id` | uuid | FK+idx | 租户 |
| `equity` | numeric(28,10) | | 账户权益 |
| `available_margin` | numeric(28,10) | | 可用保证金 |
| `maintenance_margin` | numeric(28,10) | | 维持保证金 |
| `risk_ratio` | numeric(12,6) | idx | 风险率 |
| `snapshot_at` | timestamptz | idx | 快照时间 |

#### 4.2.10 `risk_policies`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 规则 ID |
| `tenant_id` | uuid | FK+idx | 作用租户 |
| `policy_type` | varchar(32) | idx | `pre_trade`/`intraday` |
| `rule_key` | varchar(64) | idx | 规则键 |
| `rule_value` | jsonb | not null | 阈值配置 |
| `enabled` | boolean | idx | 是否启用 |
| `version` | int | | 规则版本 |
| `updated_at` | timestamptz | | 更新时间 |

#### 4.2.11 `risk_events`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 事件 ID |
| `tenant_id` | uuid | FK+idx | 租户 |
| `order_id` | uuid | FK+idx | 可空 |
| `event_type` | varchar(32) | idx | `reject`/`alert`/`circuit_break` |
| `severity` | varchar(16) | idx | `info`/`warn`/`critical` |
| `reason_code` | varchar(64) | idx | 触发原因码 |
| `payload` | jsonb | | 上下文 |
| `occurred_at` | timestamptz | idx | 发生时间 |

#### 4.2.12 `audit_logs`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | bigserial | PK | 主键 |
| `trace_id` | varchar(64) | idx | 链路 ID |
| `tenant_id` | uuid | idx | 租户 |
| `actor` | varchar(128) | | 调用方 |
| `action` | varchar(64) | idx | 操作类型 |
| `resource` | varchar(128) | idx | 资源 |
| `before` | jsonb | null | 变更前 |
| `after` | jsonb | null | 变更后 |
| `created_at` | timestamptz | idx | 时间 |

#### 4.2.13 `access_applications`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 申请单 ID |
| `tenant_id` | uuid | FK+idx | 申请租户 |
| `requester_email` | varchar(255) | idx | 申请人邮箱 |
| `target_markets` | jsonb | not null | 目标市场（US/HK/JP/Crypto...） |
| `target_exchanges` | jsonb | not null | 期望交易所列表 |
| `expected_volume` | numeric(28,10) | null | 预估月交易量 |
| `preferred_language` | varchar(8) | default `en-US` | 沟通语言偏好 |
| `status` | varchar(24) | idx | `submitted/reviewing/approved/rejected/provisioning/active` |
| `notes` | text | null | 申请备注 |
| `created_at` | timestamptz | idx | 提交时间 |
| `updated_at` | timestamptz | idx | 更新时间 |

#### 4.2.14 `access_application_reviews`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 审批记录 ID |
| `application_id` | uuid | FK+idx | 关联申请单 |
| `reviewer_id` | uuid | idx | 审批人 |
| `action` | varchar(16) | idx | `approve/reject/request_info` |
| `reason` | text | null | 审批意见 |
| `sla_due_at` | timestamptz | idx | 审批 SLA 截止 |
| `reviewed_at` | timestamptz | idx | 审批时间 |

#### 4.2.15 `exchange_api_credentials`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 记录 ID |
| `exchange_code` | varchar(64) | idx | 交易所代码 |
| `credential_name` | varchar(128) | idx | 凭证别名 |
| `api_key_ciphertext` | text | not null | 加密 API Key |
| `api_secret_ciphertext` | text | not null | 加密 Secret |
| `passphrase_ciphertext` | text | null | 额外密钥（如需要） |
| `status` | varchar(16) | idx | `active/rotating/revoked` |
| `scope` | jsonb | not null | 可访问权限范围 |
| `created_by` | uuid | idx | 创建人 |
| `created_at` | timestamptz | idx | 创建时间 |
| `rotated_at` | timestamptz | null | 最近轮换时间 |

#### 4.2.16 `tenant_exchange_bindings`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 绑定 ID |
| `tenant_id` | uuid | FK+idx | 租户 |
| `application_id` | uuid | FK+idx | 来源申请单 |
| `exchange_code` | varchar(64) | idx | 交易所 |
| `connector` | varchar(64) | idx | 连接器 |
| `binding_status` | varchar(24) | idx | `pending/active/failed/suspended` |
| `binding_config` | jsonb | not null | 路由、限额、市场白名单 |
| `activated_at` | timestamptz | null | 生效时间 |
| `updated_at` | timestamptz | idx | 更新时间 |

#### 4.2.17 `provisioning_jobs`
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `id` | uuid | PK | 编排任务 ID |
| `application_id` | uuid | FK+idx | 来源申请 |
| `tenant_id` | uuid | FK+idx | 租户 |
| `job_type` | varchar(32) | idx | `bind_exchange/rotate_credential/revoke_exchange` |
| `status` | varchar(24) | idx | `queued/running/succeeded/failed/rolled_back` |
| `current_step` | varchar(64) | null | 当前步骤 |
| `error_code` | varchar(64) | null | 失败码 |
| `error_message` | text | null | 失败信息 |
| `started_at` | timestamptz | null | 开始时间 |
| `finished_at` | timestamptz | null | 结束时间 |
| `created_at` | timestamptz | idx | 创建时间 |

### 4.3 保留策略与分区策略
1. `orders/order_routes/executions`：保留 5 年，按月分区。
2. `risk_events/audit_logs`：保留 7 年，按月分区并归档到对象存储。
3. `bars/trades`：在线 180 天，冷存 2 年。
4. `waitlist_leads`：按隐私政策保留 24 个月，可按请求删除。
5. `access_applications/access_application_reviews/provisioning_jobs`：保留 5 年，满足审计追溯。
6. `exchange_api_credentials`：长期保存版本元数据，密文字段按安全策略托管。
7. 多语言文案配置与发布记录：保留 24 个月，支持按版本回滚。

### 4.4 关键数据约束（强制）
1. `orders` 联合唯一键：`(tenant_id, idempotency_scope, idempotency_key)`。
2. `orders` 业务约束：
   - `quantity` 与 `notional` 必须且仅能二选一。
   - 当 `type in (limit, stop)` 时 `price` 必填。
3. `access_applications.status` 仅允许状态机定义的迁移路径，禁止跨级跳转写库。
4. `tenant_exchange_bindings` 联合唯一键：`(tenant_id, exchange_code, connector)`，避免重复生效绑定。
5. `audit_logs` 对交易关键路径（下单、改单、撤单、审批、绑定）必须写入，且 `trace_id` 不可为空。

## 5. 连接器框架设计（Connector SDK）
### 5.1 设计目标
1. 统一连接器生命周期：注册、心跳、能力声明、熔断、恢复。
2. 统一数据转换：symbol 映射、精度归一、错误码映射。
3. 隔离上游不稳定性：连接器内吸收差异，对网关输出标准模型。

### 5.2 连接器能力声明 `connector_manifest`
```json
{
  "name": "alpaca",
  "version": "1.0.0",
  "asset_classes": ["equity", "crypto"],
  "supports": {
    "order_types": ["market", "limit", "stop"],
    "time_in_force": ["DAY", "GTC", "IOC"],
    "batch_order": true,
    "depth_stream": false,
    "amend": true
  },
  "rate_limit": {
    "orders_per_second": 20,
    "quotes_per_second": 100
  },
  "session_modes": ["regular", "extended"]
}
```

### 5.3 连接器标准接口（伪代码）
```python
class BaseConnector(Protocol):
    async def health(self) -> HealthStatus: ...
    async def list_markets(self) -> list[MarketInstrument]: ...
    async def get_quote(self, symbol: str) -> Quote: ...
    async def get_bars(self, req: BarsRequest) -> list[Bar]: ...
    async def place_order(self, req: PlaceOrderRequest) -> UpstreamOrderResult: ...
    async def amend_order(self, req: AmendOrderRequest) -> UpstreamOrderResult: ...
    async def cancel_order(self, req: CancelOrderRequest) -> UpstreamOrderResult: ...
    async def fetch_orders(self, req: OrderQuery) -> list[UpstreamOrder]: ...
    async def fetch_positions(self, account_id: str) -> list[UpstreamPosition]: ...
    async def stream_subscribe(self, channels: list[str]) -> AsyncIterator[Event]: ...
```

### 5.4 错误码映射规则
1. 上游错误先映射为标准 `pm_error_code`，并附带 `upstream_code`。
2. 是否可重试由连接器维护白名单字段 `retryable=true/false`。
3. 典型映射：
   - 上游 `INSUFFICIENT_BUYING_POWER` -> `RISK_MARGIN_INSUFFICIENT`。
   - 上游 `MARKET_CLOSED` -> `MARKET_SESSION_CLOSED`。
   - 上游 `TOO_MANY_REQUESTS` -> `RATE_LIMITED_UPSTREAM`（retryable=true）。

### 5.5 连接器接入流程（<=3 周）
1. 第 1 周：需求确认、能力清单、沙盒连通、符号映射。
2. 第 2 周：订单流/行情流联调、错误码映射、限流校准。
3. 第 3 周：契约测试、压测、灰度接入、生产发布。

## 6. 核心业务流程
### 6.1 Waitlist 提交流程
```mermaid
sequenceDiagram
    participant User as 访客
    participant Web as Landing Web
    participant Lead as Lead Service
    participant DB as PostgreSQL
    participant CRM as CRM/通知

    User->>Web: 填写并提交表单
    Web->>Lead: POST /public/v1/waitlist
    Lead->>Lead: 字段校验 + Geo-Fencing 预检 + 反刷 + referrer/IP 采集
    Lead->>DB: 写入 waitlist_leads
    Lead->>CRM: 发送跟进事件
    Lead-->>Web: success + 预计联系时间
    Web-->>User: 成功态展示
```
补充约束：
1. `referrer` 由服务端从请求头提取，`ip_hash` 仅存脱敏哈希，不回传前端。
2. `work_email + country_region + 24h 时间窗` 用于防重复提交提示，不阻断真实重提。

### 6.2 下单流程（含幂等与风控）
```mermaid
sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant A as Auth Service
    participant RL as Relay API Service
    participant R as Risk Engine
    participant O as OMS
    participant RT as Router
    participant CN as Connector
    participant AD as Audit

    C->>G: POST /v1/orders + Idempotency-Key
    G->>A: 验签/鉴权/限流
    A-->>G: tenant context
    G->>RL: 进入中转层（校验可用绑定）
    RL->>O: 创建订单意图（幂等检查）
    O->>R: pre-trade risk check
    R-->>O: pass/reject
    alt pass
        O->>RT: route(order)
        RT->>CN: place_order
        CN-->>RT: upstream result
        RT-->>O: route result
        O->>AD: write audit log
        O-->>RL: standard order response
    else reject
        O->>AD: write risk event + audit log
        O-->>RL: risk reject response
    end
    RL-->>G: standard response
    G-->>C: JSON response
```

### 6.3 连接器故障降级
1. 触发条件：
   - 30 秒内 `5xx` 比例 > 20%。
   - 心跳连续 3 次失败。
2. 动作：
   - 标记连接器 `degraded`，新订单停止路由。
   - 尝试切换同资产级别备选连接器。
   - 推送 `risk.alert` 和运维告警。
3. 恢复条件：
   - 连续 5 分钟心跳正常且错误率恢复阈值内。

### 6.4 用户接入申请 -> 后台审批 -> 自动接入流程（新增基线）
```mermaid
sequenceDiagram
    participant User as 机构用户
    participant FE as Frontend Portal
    participant AAS as Access Application Service
    participant AP as Admin Portal
    participant AWS as Approval Workflow Service
    participant PO as Provisioning Orchestrator
    participant ERS as Exchange Registry
    participant EVO as Exchange Credential Vault
    participant BIND as Tenant Exchange Binding

    User->>FE: 提交接入申请（目标市场/交易所）
    FE->>AAS: POST /v1/access-applications
    AAS->>AAS: status=submitted
    AAS->>AWS: 创建审批任务（进入 reviewing）
    AP->>AWS: 审批（通过/拒绝/补件）
    alt 审批通过
        AWS->>AAS: 回写 status=approved
        AWS->>PO: 触发自动开通任务
        PO->>AAS: 回写 status=provisioning
        PO->>ERS: 读取可用交易所与连接器能力
        PO->>EVO: 申请可用平台凭证
        PO->>BIND: 建立 tenant-exchange 绑定
        PO-->>AAS: 全部绑定生效后回写 status=active
        AAS-->>User: 通知接入成功
    else 审批拒绝/编排失败
        AWS-->>AAS: 回写 status=rejected + reason
        AAS-->>User: 通知拒绝与原因（可重新提交）
    end
```

### 6.5 中转 API（Relay API）调用流程（新增基线）
1. 用户仅调用统一 API，不直接调用交易所 API。
2. `relay-api-service` 根据 `tenant_exchange_bindings` 与实时健康评分选择目标交易所。
3. 若首选交易所不可用，按优先级自动切换到备选交易所（在合规许可范围内）。
4. 中转调用结果统一标准化后返回，透传 `upstream_code` 以便排障。
5. 中转链路必须记录审计日志：`tenant -> request -> selected_exchange -> result`。

### 6.6 改单/撤单/查单流程基线
1. 改单：`PATCH /v1/orders/{order_id}` 仅允许变更 `price/quantity/time_in_force`。
2. 撤单：`POST /v1/orders/cancel` 支持 `order_ids` 或 `strategy_id` 或 `symbol` 至少一个条件。
3. 查单：`GET /v1/orders` 必须支持 `status/symbol/strategy_id/start/end/page_*` 过滤。
4. 以上流程统一复用签名、限流、幂等、审计中间件，不允许旁路实现。

### 6.7 实时流（WebSocket）基线
1. 地址：`wss://stream.omniaxs.com/v1/ws`，连接后先发送 `auth`。
2. 主题：`quotes.*`、`trades.*`、`orders.*`、`risk.*`。
3. 心跳：服务端 20 秒 `ping`，客户端 10 秒内 `pong`。
4. 重连：指数退避，重连后必须重新鉴权与订阅。
5. 事件模型必须与 REST 错误码/订单状态语义保持一致，禁止单独定义另一套状态枚举。

## 7. 风控系统落地
### 7.1 前置风控（同步阻断）
1. 单笔金额阈值：`order_notional <= max_single_notional`。
2. 净敞口阈值：`abs(current_exposure + delta) <= max_net_exposure`。
3. 杠杆阈值：`projected_leverage <= max_leverage`。
4. 黑白名单：symbol、venue、账户级限制。
5. 订单频控：单位时间订单次数阈值。

### 7.2 盘中风控（异步监控）
1. 波动触发：标的波动超过配置阈值，进入审慎模式。
2. 回撤触发：策略净值回撤超过阈值，触发限仓或暂停。
3. 熔断策略：连接器故障或异常成交密集时，按策略停单。

### 7.3 风控事件审计
1. 每次风控判定写入 `risk_events`。
2. 事件必须关联 `trace_id` 和 `tenant_id`。
3. 提供回放接口（内部）用于监管与事故复盘。

## 8. 合规与法务能力落地
### 8.1 非托管声明
1. 前端固定位置展示 Non-Custodial 声明，默认中英日三语可切换。
2. API 文档与 ToS 中同样声明，确保口径一致。
3. 涉及资金字段标注“上游回报展示，非托管结算”。

### 8.2 Geo-Fencing 实施
1. 判定输入：IP 归属地、用户声明地区、租户标签。
2. 数据来源：合规名单服务（动态配置，不前端硬编码）。
3. 执行层级：
   - Landing：限制提交并提示不可用地区。
   - API Gateway：硬阻断并返回 `GEOFENCE_BLOCKED`。
4. 名单更新：至少每日同步 1 次，支持紧急热更新。

### 8.3 政策页与 Footer
1. Footer 必须包含 BVI 主体声明占位。
2. `Terms of Service` 与 `Privacy Policy` 链接必须常驻。
3. 文案版本号入配置中心，可审计。

## 9. API 网关与协议规范（实现层）
### 9.1 鉴权与签名
1. 必填头：`X-PM-API-KEY`、`X-PM-TIMESTAMP`、`X-PM-SIGNATURE`。
2. 时间戳偏差：默认 `±30s`，超出返回 `AUTH_TIMESTAMP_EXPIRED`。
3. 签名串：
```text
{timestamp}\n{method_upper}\n{path}\n{query_string}\n{sha256(body)}
```
4. 签名算法：`HMAC-SHA256(secret, canonical_string)`，hex 小写。
5. 响应语言必须返回 `Content-Language`，并与 `Accept-Language` 回退策略一致。

### 9.2 幂等策略
1. 写请求必须携带 `Idempotency-Key`。
2. 幂等窗口：24 小时（可配置）。
3. 相同 key + 相同请求体：返回首次结果。
4. 相同 key + 不同请求体：返回 `409 IDEMPOTENCY_CONFLICT`。

### 9.3 限流策略
1. 维度：`tenant_id + env + endpoint_group`。
2. 默认配额（sandbox）：
   - 行情查询：120 req/min。
   - 交易写操作：30 req/min。
3. 超限返回 `429 RATE_LIMITED`，附 `X-RateLimit-*` 头。

### 9.4 标准错误对象
```json
{
  "success": false,
  "error": {
    "code": "RISK_NET_EXPOSURE_EXCEEDED",
    "message": "Net exposure limit exceeded",
    "message_i18n_key": "error.risk.net_exposure_exceeded",
    "retryable": false,
    "upstream_code": null
  },
  "trace_id": "trc_01J..."
}
```

### 9.5 中转 API 机制（新增强制）
1. 中转目标：将租户请求路由到“已审批并已绑定”的交易所集合。
2. 路由决策输入：
   - `tenant_exchange_bindings`（审批与生效状态）。
   - `exchange-registry-service` 健康评分与能力矩阵。
   - 订单类型/资产类别/时段可用性。
3. 路由决策输出：
   - `selected_exchange`、`connector`、`fallback_chain`、`reason`。
4. 失败处理：
   - 无可用绑定时返回 `ACCESS_NOT_PROVISIONED`。
   - 绑定存在但全部不可用时返回 `CONNECTOR_UNAVAILABLE` 并触发告警。
5. 审批约束：
   - 未通过审批的租户，不允许进入真实交易所中转链路。
   - 仅允许 `sandbox` 虚拟中转（如启用）。

### 9.6 v1 接口实现归属矩阵（开发必看）
| 接口 | 服务归属 | 里程碑 | 必测项 |
|---|---|---|---|
| `POST /public/v1/waitlist` | `landing-web` + `lead-service` | M1 | 校验/Geo-Fencing/反刷/入库 |
| `GET /v1/status` | `api-gateway`（status 聚合模块） | M1 | Demo 标识、组件状态聚合 |
| `GET /v1/markets` | `market-data-service` | M2 | 分页、资产类别过滤 |
| `GET /v1/quotes` | `market-data-service` | M2 | 多 symbol、盘口档位、P95 |
| `GET /v1/bars` | `market-data-service` | M2 | timeframe、limit 边界 |
| `GET /v1/calendar` | `market-data-service` | M2 | 时段/节假日返回正确 |
| `POST /v1/orders` | `api-gateway` + `relay-api-service` + `oms-service` | M2 | 幂等、风控、路由、审计 |
| `POST /v1/orders/batch` | `oms-service` | M2 | 部分成功/失败逐单返回 |
| `PATCH /v1/orders/{order_id}` | `oms-service` | M2 | 可改字段白名单 |
| `POST /v1/orders/cancel` | `oms-service` | M2 | 单笔/批量/按策略撤单 |
| `GET /v1/orders` | `oms-service` | M2 | 条件筛选、分页游标 |
| `GET /v1/positions` | `portfolio-service` | M2 | 跨市场持仓聚合 |
| `GET /v1/accounts` | `portfolio-service` | M2 | 账户权益与风险率 |
| `POST /v1/access-applications` | `access-application-service` | M2 | 状态机起点、幂等 |
| `GET /v1/access-applications` | `access-application-service` | M2 | 租户隔离、分页 |
| `GET /v1/access-applications/{application_id}` | `access-application-service` | M2 | 编排进度与绑定状态 |
| `GET /v1/access-bindings` | `access-application-service` | M2 | 仅返回生效绑定 |
| `GET /internal/v1/admin/access-applications` | `admin-portal-web` + `approval-workflow-service` | M1-M2 | 管理员鉴权、过滤条件 |
| `POST /internal/v1/admin/access-applications/{application_id}/approve` | `approval-workflow-service` | M2 | 审批记录、触发编排 |
| `POST /internal/v1/admin/access-applications/{application_id}/reject` | `approval-workflow-service` | M2 | 拒绝原因码与通知 |
| `POST /internal/v1/admin/exchange-credentials` | `exchange-credential-vault` | M2 | 密文托管、轮换审计 |
| `GET /internal/v1/admin/provisioning/jobs/{job_id}` | `provisioning-orchestrator` | M2 | 步骤状态可追踪 |

## 10. 可观测性与运维
### 10.1 SLI/SLO 指标
| 维度 | 指标 | SLO |
|---|---|---|
| 可用性 | API Gateway 月可用性 | >= 99.9% |
| 延迟 | `GET /v1/quotes` P95 | < 400ms |
| 交易成功率 | 路由成功率（剔除上游不可用） | >= 99.0% |
| 数据质量 | bars 缺口率 | < 0.5% |
| 留资漏斗 | Waitlist 提交成功率 | >= 98% |
| 国际化质量 | 三语文案缺失率（zh/en/ja） | < 0.5% |

### 10.2 日志与链路
1. 日志字段最小集：`timestamp, level, trace_id, tenant_id, endpoint, latency_ms, error_code`。
2. 关键操作（下单/撤单/规则变更）必须记录审计日志。
3. Trace 采样：
   - 交易写操作：100% 采样。
   - 行情读操作：10%-20% 采样（按负载动态）。

### 10.3 告警策略
1. `P1`：下单成功率 < 97%（5 分钟窗口）。
2. `P1`：核心连接器连续不可用 > 2 分钟。
3. `P2`：行情接口 P95 > 400ms 连续 10 分钟。
4. `P2`：Waitlist 提交失败率 > 3%。

## 11. 安全设计
### 11.1 传输与存储安全
1. 全链路 TLS1.2+，禁用弱密码套件。
2. API Secret 使用 KMS 包装加密，不保存明文。
3. PII 字段（email、contact）按列加密。

### 11.2 访问控制
1. API Scope 控制：`market:read`、`trade:write`、`account:read`、`risk:read`。
2. 内部管理后台采用 RBAC（最小权限原则）。
3. 关键操作需双人复核（规则发布、生产连接器启停）。

### 11.3 防护机制
1. WAF 与基础 DDoS 防护。
2. 请求体大小限制与 schema 验证。
3. 防重放：签名 + 时间戳 + nonce（可选）。

## 12. 测试策略与验收
### 12.1 测试分层
1. 单元测试：领域逻辑、风控规则、签名算法。
2. 集成测试：服务间调用、数据库事务、缓存一致性。
3. 契约测试：对接连接器输入输出一致性。
4. 回放测试：历史行情和成交回放验证策略行为。
5. 压测：行情读接口与下单写接口分开压测。
6. Chaos 演练：连接器故障、消息堆积、数据库只读场景。
7. 系统测试执行细则、用例 ID、准入准出标准以 `docs/SYSTEM_TEST_GUIDE_v1_zh.md` 为准。

### 12.2 UAT 对照（PRD 第14章）
| PRD 验收项 | 技术实现检查点 |
|---|---|
| Hero 核心价值文案 | i18n 配置项与 UI 自动化校验 |
| 语言切换能力 | 前端支持 `zh-CN/en-US/ja-JP` 且默认语言策略生效 |
| CTA 弹层表单 | 前端 E2E 测试 + API 提交成功用例 |
| 必填校验与成功反馈 | 表单 schema + 后端 `422`/`200` 用例 |
| All Systems Operational | `api-gateway` status 聚合数据源 + Demo 标识开关 |
| Python 示例 | 文档站 SDK 示例集成测试 |
| 非托管/Geo-Fencing 声明 | 合规模块快照测试 |
| Footer ToS/Privacy/BVI | 前端静态扫描断言 |
| Labs 归档能力可见 | 页面区块存在性测试 |
| 接入申请与审批流 | `submitted -> reviewing -> approved/rejected -> provisioning -> active` 状态机测试 |
| 中转 API 路由约束 | 仅可路由到 `tenant_exchange_bindings.active` 的交易所 |
| WebSocket 四类主题 | `quotes/trades/orders/risk` 订阅与心跳重连测试 |

### 12.3 出口准入（Release Gate）
1. 所有 P0/P1 缺陷关闭。
2. 下单主链路集成测试通过率 100%。
3. 压测达到 SLO 基线且无明显资源瓶颈。
4. 安全扫描无高危未处理项。

## 13. CI/CD 与发布流程
### 13.1 分支策略
1. `main`：始终可发布。
2. `feature/*`：功能分支。
3. `release/*`：阶段发布分支（可选）。

### 13.2 流水线
1. `lint + test + contract-test`。
2. 构建镜像并产出 SBOM。
3. 安全扫描（SAST/依赖漏洞/镜像漏洞）。
4. 部署到 `dev` -> 自动集成测试。
5. 手动批准后部署 `sandbox`。
6. 灰度发布 `prod`（5% -> 25% -> 100%）。

### 13.3 回滚策略
1. 应用回滚：按版本标签快速回滚。
2. 数据回滚：仅做向前兼容迁移，禁止破坏性变更直上。
3. 连接器回滚：可按连接器粒度降级到上一稳定版本。

## 14. 里程碑拆解（执行版）
### M1（1-2 周）：Landing + Waitlist + 合规 + Status
- 交付物：
  1. 单页上线（中英日切换、CTA 弹层、合规区、Footer 声明）。
  2. `POST /public/v1/waitlist` 与数据入库。
  3. `GET /v1/status` Demo 版。
  4. `admin-portal-web` MVP（申请单列表与审批入口）。
- 技术验收：
  1. 表单成功率监控可见。
  2. Geo-Fencing 文案与阻断链路可配置。
  3. 后台可查看全部申请单并执行审批动作。
  4. 三语文案完整度与回退策略通过 QA 验收。

### M2（3-6 周）：统一 API v1 + Sandbox
- 交付物：
  1. `GET /v1/markets`、`GET /v1/quotes`、`GET /v1/bars`、`GET /v1/calendar`、`POST /v1/orders`、`POST /v1/orders/batch`、`PATCH /v1/orders/{order_id}`、`POST /v1/orders/cancel`、`GET /v1/orders`、`GET /v1/positions`、`GET /v1/accounts`。
  2. 鉴权签名、幂等、限流。
  3. Python SDK alpha。
  4. 接入申请与审批 API（用户侧 + 管理侧）。
  5. `provisioning-orchestrator` 自动绑定第一批交易所。
- 技术验收：
  1. 下单链路端到端打通。
  2. 契约测试覆盖率 >= 90%。
  3. 审批通过后可自动创建 tenant-exchange 绑定并生效。

### M3（6-10 周）：多市场连接器扩展
- 交付物：
  1. US/JP/HK/Crypto/FX/Futures/Metals 核心清单接入。
  2. 路由策略与故障切换上线。
  3. 中转 API 多交易所自动切换策略上线。
- 技术验收：
  1. 连接器单次接入周期 <= 3 周。
  2. 路由成功率达到目标。
  3. 审批状态与中转可用性一致性检查通过。

### M4（10-14 周）：风险中心 + 审计回放 + 报表
- 交付物：
  1. 风险规则中心（版本化、灰度）。
  2. 审计回放查询。
  3. 机构报表导出。
- 技术验收：
  1. 风险事件可追溯、可检索。
  2. 报表与账务核对一致率达标。

## 15. 人员与职责建议（最小编制）
1. 后端工程师 3-4 人：网关/订单/连接器/风险。
2. 前端工程师 1-2 人：Landing、文档站、开发者中心。
3. QA 1-2 人：自动化 + 性能 + 契约测试。
4. DevOps/SRE 1 人：可观测性、发布、应急。
5. 合规/法务接口 1 人：文案与 Geo-Fencing 流程审批。
6. 运营审批专员 1 人：接入申请审核与异常工单处理。

## 16. 关键风险与应对（工程视角）
1. 风险：连接器语义不一致导致统一模型失真。
   - 应对：强制 connector contract test + 统一错误映射基线。
2. 风险：跨市场时段差异导致策略行为异常。
   - 应对：引入 `session calendar service` 并在下单前校验。
3. 风险：上游波动导致 API 抖动。
   - 应对：读写隔离、缓存、熔断、限流与回退数据。
4. 风险：合规名单更新滞后。
   - 应对：动态配置中心 + 紧急热更新通道。
5. 风险：审批状态与实际绑定状态不一致导致误放行。
   - 应对：审批流与绑定生效使用同一状态机，禁止双写。

## 17. 开发启动清单（Checklist）
1. 建立仓库目录与基础服务脚手架。
2. 定义统一 OpenAPI 与 JSON Schema。
3. 搭建 PostgreSQL/Redis/NATS 本地开发环境。
4. 实现签名中间件、幂等中间件、限流中间件。
5. 落地第一个连接器（Alpaca）并通过契约测试。
6. 打通端到端最小闭环：`bars -> signal -> risk -> order`。
7. 上线监控看板与告警策略。
8. 完成 M1 验收后再开启 M2 范围。
9. 上线申请审批流：`submitted -> reviewing -> approved/rejected -> provisioning -> active`。
10. 上线交易所凭证录入/轮换 SOP，并接入 `exchange-credential-vault`。
11. 建立三语文案资源仓与发布流程（`zh-CN/en-US/ja-JP`）。

## 18. 约束与待确认项（含临时默认值）
1. BVI 实体全称待法务提供：使用配置键 `legal.bvi_entity_name` 占位，生产发布门禁要求该值非空。
2. Geo-Fencing 数据源供应商待采购确认：确认前按“名单服务 + 人工复核”双轨执行，默认拒绝高风险地区请求。
3. 生产环境区域与云厂商待成本评审：冻结前按 2.3 默认拓扑（`ap-southeast-1` 主、`ap-northeast-1` 备）实施。
4. 初始连接器优先级待业务最终确认：冻结前默认 `Alpaca > Quantower > Other`。
5. 第一批自动接入白名单待运营与法务联合确认：未确认前仅允许 `sandbox` 自动开通，不开启 `prod` 自动放行。

## 19. 架构基线冻结与变更控制（强制）
1. 本文档与 `docs/system-architecture-baseline.html` 一起作为开发基线。
2. 以下内容默认冻结，未经评审不得偏离：
   - 控制面/数据面分层。
   - 申请审批状态机。
   - 中转 API 只路由到已审批绑定交易所。
   - 三语支持范围（zh-CN/en-US/ja-JP）与回退规则。
3. 变更流程：
   - 提交 `Architecture Change Request (ACR)`。
   - 架构负责人 + 合规负责人 + 后端负责人三方审批。
   - 更新文档版本号与变更记录后方可实施。
4. 代码守护：
   - CI 增加配置一致性检查（审批状态与路由策略联动）。
   - 关键路径（审批、绑定、中转）必须有集成测试覆盖。

## 20. 从 0 到 1 开发执行顺序（可直接排期）
### 20.1 Sprint 0（第 1 周）：契约冻结与基础设施
1. 冻结 `openapi-v1.yaml` 的 v1 首批接口清单并打标签。
2. 搭建本地开发基座：PostgreSQL + Redis + NATS + 可观测性最小栈。
3. 建立通用中间件：签名鉴权、幂等、限流、`trace_id` 注入。
4. 输出结果：`/public/v1/waitlist` 与 `/v1/status` 可在本地联调。

### 20.2 Sprint 1（第 2 周）：Landing 与合规闭环
1. 交付 Landing 的三语切换、Waitlist 弹层、Footer 合规模块。
2. 落地 `lead-service`：入库、反刷、Geo-Fencing 预检、CRM 事件。
3. 建立前端 E2E 与提交漏斗指标看板。
4. 输出结果：M1 验收项全部可测。

### 20.3 Sprint 2（第 3-4 周）：行情与账户基础能力
1. 落地 `market-data-service`：`markets/quotes/bars/calendar`。
2. 落地 `portfolio-service`：`positions/accounts`。
3. 打通缓存策略与时序存储分层。
4. 输出结果：行情读链路满足 P95 与数据完整性基线。

### 20.4 Sprint 3（第 5-6 周）：交易主链路
1. 落地 `oms-service`：下单/改单/撤单/查单。
2. 落地 `risk-engine-service`：前置风控、事件审计。
3. 落地 `relay-api-service` + `router-service`：只路由到已生效绑定。
4. 输出结果：`bars -> signal -> risk -> order` 端到端闭环通过。

### 20.5 Sprint 4（第 7-8 周）：申请审批与自动接入
1. 落地 `access-application-service`、`approval-workflow-service`。
2. 落地 `exchange-credential-vault`、`provisioning-orchestrator`。
3. 打通管理后台审批动作与编排任务追踪。
4. 输出结果：`submitted -> ... -> active` 状态机全链路可回放。

### 20.6 Sprint 5（第 9-10 周）：实时流与发布就绪
1. 落地 WebSocket（`quotes/trades/orders/risk`）与重连机制。
2. 完成压测、混沌演练、安全扫描与发布演练。
3. 完成 Release Gate，准备灰度发布到 `prod`。
4. 输出结果：M2/M3 主干能力可生产灰度。