# Pacifica Delta-Neutral + Dual-Sided Scalping — TS Skeleton

## Overview
本仓库提供一个面向 Pacifica 永续合约的多账户 Delta 中性策略骨架，涵盖连接器、执行路由、风控、策略、行情管线和监控模块，便于快速验证网格/剥头皮等中性策略。

核心模块：
- **connectors**：Pacifica REST/WebSocket 适配器、签名、限频/指标、账户注册表
- **utils**：ShadowBook、MarketDataAdapter 等行情聚合工具
- **execution**：OrderRouter（滑点、post-only、节流、STP）与 GlobalOrderCoordinator
- **risk / portfolio / hedge**：RiskEngine（kill-switch）、PositionManager、HedgeEngine、FundingRateMonitor
- **strategies**：GridMaker、MarketMaker、MicroScalper
- **apps/runner**：加载配置、注册账户、启动策略与风险/行情管线

## Quick Start
```bash
pnpm install
cp .env.example .env
cp config/config.example.yaml config/config.yaml
pnpm run live        # 正常启动
# 常用检查
pnpm lint
pnpm test
pnpm typecheck
```

## Logging
- Runner 默认使用 `pino` 结构化日志，除标准输出外，还会写入 `logs/runner-<timestamp>.log`（目录自动创建）。启动时会在控制台打印实际 log 文件路径，便于后续复盘。
- 可用环境变量定制行为：
  - `LOG_DIR`：日志目录（默认 `logs`，仅在 `LOG_FILE` 未指定时生效）
  - `LOG_FILE`：自定义日志文件（接受相对或绝对路径）
  - `LOG_FILE_LEVEL`：写入文件的最低级别（默认跟随 `LOG_LEVEL`，例如设置 `debug` 捕获全量明细）
- 结构化日志可以直接供 Codex 或外部工具重放，建议在本地调试时保留原始 JSON，必要时再结合 `pino-pretty` 做人类可读打印。

## Docs-first Workflow
- 开发前务必查阅并遵循：`docs/ARCHITECTURE_DESIGN.md`, `docs/IMPLEMENTATION_PLAN.md`, `docs/CODE_DELIVERY_PLAN.md`, `docs/API_CONNECTOR_SPEC.md`, `docs/MODULE_INTERFACES.md`, `docs/SEQUENCE_FLOW.md`, `docs/CONFIG_REFERENCE.md`, `docs/TESTING_PLAN.md`, `docs/OPERATIONS_PLAYBOOK.md`, `docs/MICRO_GRID_CONTROL.md`, `docs/MICRO_GRID_ROADMAP.md`
- 若实现与文档不一致，先更新文档再提交代码，并在 PR 描述说明差异。
- PR 模板要求列出引用章节与测试结果，CI 应覆盖 `pnpm lint` / `pnpm test` / `pnpm typecheck`。

## Codex 准则
1. 以暗猜接口为耻，以认真查阅为荣  
2. 以模糊执行为耻，以寻求确认为荣  
3. 以盲想业务为耻，以人类确认为荣  
4. 以创造接口为耻，以复用现有为荣  
5. 以跳过验证为耻，以主动测试为荣  
6. 以破坏架构为耻，以遵循规范为荣  
7. 以假装理解为耻，以诚实无知为荣  
8. 以盲目修改为耻，以谨慎重构为荣

## Reference Documentation
- **快速上手**：`docs/CONFIG_GUIDE.md`
- **架构与规划**：`docs/ARCHITECTURE_DESIGN.md`, `docs/IMPLEMENTATION_PLAN.md`, `docs/MICRO_GRID_CONTROL.md`, `docs/MICRO_GRID_ROADMAP.md`, `docs/MICRO_GRID_EXECUTION_SCHEDULE.md`
- **接口规范**：`docs/API_CONNECTOR_SPEC.md`, `docs/MODULE_INTERFACES.md`
- **流程与配置**：`docs/SEQUENCE_FLOW.md`, `docs/CONFIG_REFERENCE.md`
- **质量保障与运维**：`docs/TESTING_PLAN.md`, `docs/OPERATIONS_PLAYBOOK.md`
- **即将到来的 M1.6 设计**：`docs/M16_INCREMENTAL_GRID_DESIGN.md`, `docs/M16_PLACEMENT_THROTTLING_DESIGN.md`, `docs/M16_FILL_DRIVEN_TIGHTENING_DESIGN.md`
- **历史资料**：见 `docs/archive/`

## Tests
- 单元测试位于 `tests/` 目录，使用 Vitest (`pnpm test`)
- `pnpm lint` 运行 ESLint (`@typescript-eslint`)，`pnpm typecheck` 执行 `tsc --noEmit`
- 建议在 PR 中附测试日志与关键指标（REST 请求指标、delta_abs、kill-switch 状态等）

## Notes
- 运行前需在 `.env` 中填写 Pacifica API 密钥，`config/config.yaml` 例子说明账户、策略、风险、执行等参数
- `AdapterRegistry` 支持 maker/hedger 多账户，Residence of funding 监控通过 `FundingRateMonitor`
- TODO（见计划）：接入真实 WS 行情、完善资金费率管线、补充更多单测/集成测试