Skip to content

Commit 2757d70

Browse files
PigbibiPigbibi
authored
Document platform notification outcomes (#45)
1 parent 9c4ea78 commit 2757d70

4 files changed

Lines changed: 123 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ For the stricter end-state rules for new US equity strategies, see:
5353
- [`docs/us_equity_release_cutover_plan.zh-CN.md`](./docs/us_equity_release_cutover_plan.zh-CN.md)
5454
- [`docs/us_equity_live_switch_runbook.md`](./docs/us_equity_live_switch_runbook.md)
5555
- [`docs/us_equity_live_switch_runbook.zh-CN.md`](./docs/us_equity_live_switch_runbook.zh-CN.md)
56+
- [`docs/platform_notification_outcomes.md`](./docs/platform_notification_outcomes.md)
57+
- [`docs/platform_notification_outcomes.zh-CN.md`](./docs/platform_notification_outcomes.zh-CN.md)
5658
- [`docs/strategy_plugin_runtime_contract.md`](./docs/strategy_plugin_runtime_contract.md)
5759

5860
## Package layout

‎README.zh-CN.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@
3939
- [`docs/us_equity_release_cutover_plan.zh-CN.md`](./docs/us_equity_release_cutover_plan.zh-CN.md)
4040
- [`docs/us_equity_live_switch_runbook.md`](./docs/us_equity_live_switch_runbook.md)
4141
- [`docs/us_equity_live_switch_runbook.zh-CN.md`](./docs/us_equity_live_switch_runbook.zh-CN.md)
42+
- [`docs/platform_notification_outcomes.md`](./docs/platform_notification_outcomes.md)
43+
- [`docs/platform_notification_outcomes.zh-CN.md`](./docs/platform_notification_outcomes.zh-CN.md)
4244

4345
[English README](./README.md)
4446

‎docs/platform_notification_outcomes.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Platform Notification Outcomes
2+
3+
Platform runtimes should use the shared execution outcome and notification
4+
envelope helpers in `quant_platform_kit` instead of defining private stage or
5+
notification sink semantics in each repository.
6+
7+
## Execution Stages
8+
9+
`quant_platform_kit.common.execution_outcomes` defines the shared strategy-run
10+
stages used by platform persistence, API responses, logs, and notifications:
11+
12+
| Stage | Terminal | Meaning |
13+
| --- | --- | --- |
14+
| `ORDERS_PLANNED` | No | A plan was built before execution. |
15+
| `DRY_RUN_COMPLETED` | No | Dry-run execution finished without live orders. |
16+
| `NO_ACTION` | No | Live cycle completed with no order needed. |
17+
| `SUBMITTED` | Yes | One or more live orders were submitted. |
18+
| `EXECUTION_BLOCKED` | No | No order was submitted because of a retryable execution blocker. |
19+
| `PARTIAL_SUBMITTED` | No | Some orders were submitted, but at least one execution blocker remains. |
20+
| `FUNDING_BLOCKED` | Yes | No order was submitted because available cash cannot buy the required whole share. |
21+
| `RECONCILED` | Yes | A submitted run was reconciled by a platform-specific process. |
22+
| `COMPLETED` | Yes | A run was marked complete by a platform-specific process. |
23+
24+
Terminal stages block duplicate live order submission for the same
25+
account/profile/period. Non-terminal execution blockers can be retried by the
26+
platform scheduler while the strategy execution window remains open.
27+
28+
## Skip Reasons
29+
30+
The shared helper treats these skip reasons as execution blockers by default:
31+
32+
- `buy_quantity_zero`
33+
- `insufficient_cash_for_whole_share`
34+
- `quote_unavailable`
35+
- `sell_quantity_zero`
36+
37+
`insufficient_cash_for_whole_share` is a terminal funding block when it is the
38+
only blocking reason and no live order was submitted. This keeps logs and
39+
notifications explicit without repeatedly retrying the same underfunded run.
40+
41+
## Notification Envelope
42+
43+
`quant_platform_kit.notifications.events` provides:
44+
45+
- `RenderedNotification(detailed_text, compact_text)`
46+
- `NotificationPublisher(log_message, send_message)`
47+
- `publish_rendered_notification(...)`
48+
49+
Platform renderers may keep broker-specific layout and order details, but they
50+
should publish through the shared envelope so logs and user notifications have a
51+
consistent delivery contract.
52+
53+
## Platform Responsibilities
54+
55+
Platform repositories should:
56+
57+
- use shared stage constants and stage resolution helpers
58+
- include the resolved stage in persisted run state and API responses
59+
- render execution blockers consistently in logs and notifications
60+
- keep broker-specific order payloads, account labels, and transport wiring local
61+
- avoid documenting deployment-specific live strategy selections in public docs

‎docs/platform_notification_outcomes.zh-CN.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# 平台通知与执行结果语义
2+
3+
平台运行时应复用 `quant_platform_kit` 里的共享执行结果和通知 envelope
4+
helper，不要在每个仓库里各自定义一套 stage 或通知投递语义。
5+
6+
## 执行 Stage
7+
8+
`quant_platform_kit.common.execution_outcomes` 定义了平台持久层、API 返回、
9+
日志和通知共用的 strategy-run stage：
10+
11+
| Stage | 是否终态 | 含义 |
12+
| --- | --- | --- |
13+
| `ORDERS_PLANNED` | 否 | 已生成执行计划，尚未完成执行。 |
14+
| `DRY_RUN_COMPLETED` | 否 | 模拟运行完成，没有提交真实订单。 |
15+
| `NO_ACTION` | 否 | 实盘周期完成，但不需要下单。 |
16+
| `SUBMITTED` | 是 | 已提交一个或多个真实订单。 |
17+
| `EXECUTION_BLOCKED` | 否 | 因可重试的执行阻塞导致没有提交订单。 |
18+
| `PARTIAL_SUBMITTED` | 否 | 部分订单已提交，但仍有执行阻塞需要关注。 |
19+
| `FUNDING_BLOCKED` | 是 | 现金不足以买入所需的一整股，因此没有提交订单。 |
20+
| `RECONCILED` | 是 | 已由平台自己的 reconciliation 流程完成核对。 |
21+
| `COMPLETED` | 是 | 已由平台自己的流程标记为完成。 |
22+
23+
终态会阻止同一账户、同一 profile、同一周期重复提交实盘订单。非终态执行阻塞
24+
可以在策略执行窗口仍然开放时，由平台 scheduler 后续重试。
25+
26+
## 跳过原因
27+
28+
共享 helper 默认把这些 skipped-order reason 视为执行阻塞：
29+
30+
- `buy_quantity_zero`
31+
- `insufficient_cash_for_whole_share`
32+
- `quote_unavailable`
33+
- `sell_quantity_zero`
34+
35+
当 `insufficient_cash_for_whole_share` 是唯一阻塞原因，并且没有任何真实订单已提交时，
36+
该周期会记为终态 `FUNDING_BLOCKED`。这样日志和通知会明确说明资金不足，同时避免
37+
每天重复重试同一个资金不足的运行周期。
38+
39+
## 通知 Envelope
40+
41+
`quant_platform_kit.notifications.events` 提供：
42+
43+
- `RenderedNotification(detailed_text, compact_text)`
44+
- `NotificationPublisher(log_message, send_message)`
45+
- `publish_rendered_notification(...)`
46+
47+
各平台可以保留券商自己的通知布局和订单细节，但应通过共享 envelope 投递，
48+
使日志和用户通知具备一致的交付契约。
49+
50+
## 平台仓库职责
51+
52+
平台仓库应当：
53+
54+
- 使用共享 stage 常量和 stage 解析 helper
55+
- 在持久状态和 API 返回中包含解析后的 stage
56+
- 在日志和通知里一致展示执行阻塞
57+
- 将券商专属订单 payload、账户标签和传输层逻辑留在本仓库内
58+
- 不在公开文档里写部署实例当前选择的实盘策略

0 commit comments

Comments
 (0)