binance-api/.specify/memory/constitution.md

多交易所Delta中性宪章

核心原则

一、优先架构与现实测试

系统设计必须以模块化、可维护和可扩展为核心，采用分层架构

遵循 SOLID 原则和设计模式。

追求高内聚低耦合的设计思维，编写结构良好、可集成、模块化程度高的代码。

为实际业务集成而设计，拒绝为了抽象而变复杂，完全避免过度设计。

系统必须支持模块化、组件化、服务化架构，优先考虑与现有系统的无缝集成，便于敏捷开发、持续集成和高扩展性。

核心HTTP客户端库必须维持企业级性能标准：响应时间<100ms、99.9%可用性、支持1000+并发请求。所有平台适配器必须实现统一接口，支持Ed25519（Pacifica）、EIP-191（Aster）、HMAC-SHA256（Binance）认证。代理管理必须包含负载均衡、健康检查、自动故障转移。

过度设计防护要求：

• 禁止创建不必要的抽象层和桥接模式，除非有明确的技术需求
• 优先使用简单的注册表模式（如AccountRegistry）而非复杂的工厂和适配器组合
• 每季度必须进行架构审查，识别和简化过度复杂的模块间交互
• 任何超过3层的调用链必须有明确的技术理由和性能证明
• 循环依赖必须在设计阶段就被识别和消除
• 接口设计必须直接支持业务需求，避免为了"未来扩展性"而增加当前不需要的复杂性

TypeScript代码质量标准：

• 必须使用严格的TypeScript配置，禁用any类型
• import语句必须不含文件扩展名，使用路径别名(@/)
• ESLint规则必须强制执行：import/extensions、import/order、import/no-unresolved
• 所有模块必须提供完整的类型定义和导出接口
• 代码格式化必须通过Prettier自动执行，保存时自动修复

测试必须使用现实环境：

• 优先使用真实数据库而非模拟
• 使用实际服务实例而非存根
• 实施前必须进行契约测试
• 集成测试必须覆盖真实工作流
• 性能测试必须在生产类似环境中进行
• 所有测试必须在CI中自动运行
• HTTP客户端库必须通过TDD开发，测试先行
• 契约测试必须先于实现，确保测试失败后再开发功能

二、Delta中性优先

所有策略必须在任何时候都针对所有连接的交易所和账户对保持总Delta ≈ 0。除非缓解订单已在途中并已记录，否则每个资产的净敞口必须保持在±0.0005 BTC等值内。当利用率或敞口突破配置阈值时，必须立即进行重新平衡。

三、确定性市场数据摄取

系统必须维持每个交易场所的连续、低延迟订单簿访问（WebSocket主要，5秒内HTTP回退）。订单簿快照必须验证单调买卖价和深度新鲜度<2秒。任何降级的数据源必须在新交易执行前自动触发回退和警报。通用HTTP客户端必须支持实时数据流、批量请求处理和连接池管理。

四、资金保护与风险控制

每个账户必须执行可配置的头寸、杠杆和回撤上限。紧急止损路径必须在触发后30秒内取消或对冲剩余敞口。所有订单流必须携带幂等标识符和回滚计划，以防止部分失败期间的孤立敞口。HTTP客户端必须实现全面错误处理、自动重试机制和熔断器模式。

五、透明可观测性与安全审计

执行、对冲和清理服务必须为每个账户和交易所发出结构化日志、指标和健康信号。订单意图、成交、取消和余额快照必须通过关联ID进行端到端可追踪。历史操作必须通过持久化配置和可重放事件日志保持可重现性。HTTP客户端必须提供性能监控、SLA跟踪和实时健康检查。

凭证管理安全要求：

• 凭证管理模块必须支持多平台热加载，配置更新在100ms内完成
• 所有私钥和API密钥必须在静态时加密存储，传输时使用安全通道
• 签名操作必须在50ms内完成，支持Ed25519、EIP-191、HMAC-SHA256算法
• 平台检测必须智能识别账户类型，自动选择对应签名方法
• 凭证轮换程序必须每季度演练，支持零停机时间更新
• 审计日志必须记录所有凭证访问、签名操作和配置变更

六、架构简化强制要求

系统架构必须定期审查和简化，防止技术债务积累。

简化审查要求：

• 每个功能模块的调用链不得超过3层，除非有明确的性能或安全需求
• 任何包含超过2个中间层的模块间交互必须有简化计划
• 优先使用直接依赖注入而非复杂的工厂模式
• 账户管理必须使用简单注册表模式，避免复杂的适配器桥接
• 认证流程必须直接访问凭证，避免多层转换和包装

强制简化标准：

• 模块间耦合度评估：每月检查循环依赖和过度抽象
• 接口简化：所有对外接口必须直接对应业务需求
• 代码可读性：任何需要超过3层注释才能理解的代码架构必须重构
• 性能影响：架构复杂性不得影响50ms签名性能目标
• 维护成本：新功能添加不得因架构复杂性而需要修改超过5个模块

运营约束

平台必须维持高频信号评估（≤8秒循环），同时保持每次迭代计算在配置预算内。网络访问必须在需要时通过批准的代理路由，而不破坏延迟承诺。HTTP客户端代理池必须支持地理合规、IP轮换和自动故障转移。

敏感凭据必须在静态时保持加密，轮换程序必须每季度演练。交易日志的数据保留必须满足最少90天重放要求。HTTP客户端必须支持多种认证方式的安全存储和自动轮换。

API响应缓存必须考虑数据新鲜度要求，批量请求处理必须包含并发控制和错误隔离。连接池管理必须优化资源利用率并防止连接泄漏。

代码质量保障： 开发环境必须配置自动化代码质量检查，包括ESLint规则验证、TypeScript类型检查和Prettier格式化。所有Pull Request必须通过代码质量门槛，包含完整类型声明、规范的import语句和通过的测试覆盖率。工程师IDE必须配置统一的开发规范，确保代码一致性。

架构健康监控： 持续监控模块间依赖关系，自动检测循环依赖和过度耦合。每个模块的复杂度指标必须低于配置阈值，超出时必须触发重构警告。架构决策必须记录在案，包含简化方案的评估过程。

工作流程与质量门槛

规划产物必须在开发开始前明确将功能映射到这些原则。规格必须声明敞口限制、数据源和测试矩阵。计划和任务必须安排对冲、订单清理、可观测性改进以及HTTP客户端库性能验证的TDD覆盖。

拉取请求必须包含证据（日志、测试输出或仪表板），显示对原则一至六的持续合规性。任何偏差都需要在合并前记录缓解措施。HTTP客户端库的更改必须包含性能基准测试和向后兼容性验证。

新的平台集成必须完整实现数据接口（价格、订单簿、K线、交易历史）和操作接口（订单创建、修改、取消、批量操作），包括WebSocket实时数据流和全面的错误处理。

代码审查标准： 代码审查必须验证TypeScript类型安全、import语句规范性、ESLint合规性和测试覆盖率。凭证管理相关代码必须经过安全审查，确保敏感信息处理符合最佳实践。所有模块化组件必须提供清晰的导出接口和使用文档。

架构审查要求： 每个Pull Request必须评估架构复杂性影响，确保不引入不必要的抽象层。重构请求必须包含简化前后的复杂度对比和性能影响分析。新增依赖必须证明其必要性，避免为解决简单问题而引入复杂方案。

治理

本宪章取代交易堆栈的先前流程指导。修正案需要维护者共识、对保障措施影响的文档以及对依赖模板的更新。版本控制遵循SemVer：主要版本用于原则删除/不兼容治理，次要版本用于新原则或重大范围增加，补丁版本用于澄清。

合规性审查必须至少每月进行一次，检查敞口报告、健康警报、测试覆盖率变化以及HTTP客户端库性能指标。偏差必须记录修复负责人和时间线。库的发布必须遵循语义版本控制，包含完整的变更日志和迁移指南。

代码质量合规性检查必须包括ESLint规则遵守率、TypeScript编译错误率、import语句规范性和测试覆盖率指标。凭证管理模块的安全审查必须验证加密存储、访问控制和审计日志完整性。

架构治理要求： 架构决策记录(ADR)必须包含简化方案的考虑过程。每季度架构审查必须评估系统整体复杂度趋势，制定简化路线图。任何新增的抽象层必须通过架构委员会审批，证明其不可替代性。

版本: 1.6.0 | 批准: 2025-09-29 | 最后修订: 2025-09-29