上传文件至「/」

2026-07-11 20:13:35 +00:00
commit ac03d9e67b
5 changed files with 767 additions and 0 deletions
@@ -0,0 +1,162 @@
+# QuantDinger Extension Guide
+
+This guide explains how to add features without making the backend harder to
+maintain. Prefer small, boring, easy-to-review changes.
+
+## Before You Start
+
+1. Find the closest existing module.
+2. Read `docs/ARCHITECTURE.md` and `docs/MODULE_BOUNDARIES.md`.
+3. Decide whether the change is API, service, adapter, data, worker, or docs.
+4. Keep route paths and response fields backward-compatible unless a breaking
+   change is explicitly approved.
+
+## Add a Human Web API Endpoint
+
+Use this flow for routes consumed by the web or mobile UI:
+
+1. Add the route in the closest route module, or create a small sibling module
+   if the current file is already large.
+2. Keep the route thin: validate input, call a service, return JSON.
+3. Put workflow logic in `app/services/<feature>/...` when the feature has more
+   than one workflow. Use a flat service file only for small one-off helpers.
+4. Add or update OpenAPI tag metadata in `app/openapi/register.py` and
+   `app/openapi/tags.py` when introducing a new route family.
+5. Regenerate the human API spec:
+
+```bash
+cd backend_api_python
+python scripts/export_openapi.py
+```
+
+6. Run the OpenAPI smoke test when dependencies are available:
+
+```bash
+cd backend_api_python
+python -m pytest tests/test_openapi.py -q
+```
+
+## Add an Agent Gateway Endpoint
+
+Use this flow for external AI agents, MCP clients, and automation:
+
+1. Add code under `app/routes/agent_v1`.
+2. Enforce token scopes using the existing agent security helpers.
+3. Keep write/trade actions explicit and auditable.
+4. Update `docs/agent/agent-openapi.json`.
+5. Do not mix agent-only routes into the human OpenAPI spec.
+
+## Add a Market Data Source
+
+1. Implement the adapter in `app/data_sources`.
+2. Return normalized rows:
+
+```python
+{
+    "time": 1710000000,
+    "open": 1.0,
+    "high": 1.2,
+    "low": 0.9,
+    "close": 1.1,
+    "volume": 1000.0,
+}
+```
+
+3. Register selection logic in `DataSourceFactory`.
+4. Keep provider-specific column names inside the adapter.
+5. Include market, symbol, timeframe, exchange, and market type in cache keys
+   where relevant.
+6. Add a small smoke check or script if the provider has fragile symbol rules.
+
+## Add a Symbol Master Data Source
+
+1. Prefer database-backed master data over hardcoded symbol lists.
+2. Put sync/import logic in scripts or service modules, not route files.
+3. Keep seed SQL deterministic so fresh Docker installs work offline.
+4. Make search tolerant of symbol, name, alias, and localized company names.
+5. Do not hardcode large symbol lists in Python route modules.
+
+## Add an Exchange or Broker Adapter
+
+1. Put low-level API calls under `app/services/live_trading`.
+2. Normalize account, position, order, fill, and error shapes.
+3. Keep exchange precision and sizing logic near the adapter.
+4. Keep strategy lifecycle outside the adapter.
+5. Add explicit notes for market type support:
+   - spot
+   - swap/perpetual
+   - US stock
+   - paper/live
+6. If an adapter supports live orders, document idempotency and retry behavior.
+
+## Add a Strategy Runtime Feature
+
+1. Avoid adding more unrelated logic to `trading_executor.py`.
+2. Extract new behavior into a focused service module first.
+3. Keep order intent creation separate from order execution.
+4. Keep market data reads separate from account mutation.
+5. Add safeguards for duplicate starts, duplicate orders, and worker restarts.
+
+## Add a Backtest Feature
+
+1. Avoid growing `backtest.py` unless the change is tiny.
+2. Prefer extracting:
+   - data loading
+   - signal evaluation
+   - execution model
+   - metrics
+   - report formatting
+3. Preserve historical result compatibility.
+4. Clearly document fill assumptions.
+
+## Add an AI Feature
+
+1. Keep prompts and skill definitions separate from provider calls.
+2. Keep provider adapters behind a service boundary.
+3. Localize user-facing text through translation/i18n structures.
+4. Do not let AI flows place live orders without explicit existing trade APIs,
+   permissions, billing checks, and audit logs.
+5. For streaming routes, handle cancellation and partial failures.
+
+## Add Settings
+
+1. Define the setting in the backend settings registry.
+2. Choose whether it is public, admin-only, or internal.
+3. Keep secrets out of public config endpoints.
+4. If the setting changes OpenAPI behavior, regenerate `docs/api/openapi.yaml`.
+5. Keep environment variable names stable and documented.
+
+## Add Background Work
+
+1. Put startup wiring in `app/startup.py`.
+2. Put worker behavior in a dedicated service module.
+3. Add a clear owner/lock model for multi-process deployments.
+4. Make work idempotent before adding retries.
+5. Log start, stop, retry, and failure states in English.
+
+## Verification Checklist
+
+Run the smallest useful checks for the change:
+
+```bash
+python -m py_compile path/to/changed_file.py
+python scripts/check_mojibake.py
+```
+
+For API changes:
+
+```bash
+cd backend_api_python
+python scripts/export_openapi.py
+python -m pytest tests/test_openapi.py -q
+```
+
+For Docker/deploy changes:
+
+```bash
+docker compose config
+```
+
+For frontend-only work, use the frontend dev server. Do not run production
+builds during every small iteration unless the change touches bundling,
+environment injection, or release assets.