surprising-ex

Imported from lilaizhencn/surprising-ex (AGENTS.md). Install upstream with npx skills add lilaizhencn/surprising-ex. Copyright stays with the author.

AGENTS.md

Surprising-EX 是交易所后端核心项目。改动必须严谨，资金安全优先于交付速度。

项目边界

• 这是 Java / Maven 多模块项目，业务包括现货、永续、交割、期权。
• 保持现有架构统一：ProductLine、instrument、Kafka topic、账户、撮合、风控、WebSocket、结算等边界不要随意重构。
• 遵循后端 mvc 开发模式,优先沿用现有模块、事件模型、repository、outbox、Kafka topic 和 Maven 测试。
• 除非任务明确需要，交易后端测试不要启动 wallet 服务。
• 产品未上线，不要在代码逻辑里 fallback，legacy

六产品线规则

• 六条业务线必须隔离：现货、永续（U本位，币本位）、交割（U本位，币本位）、期权不能混用订单逻辑、账户类型、topic、instrument、风险模型。
• 永续需要重点验证资金费、标记价、强平、ADL、保险基金。止盈止损
• 交割需要重点验证到期结算、交割流水、持仓归零或结算后状态。止盈止损
• 期权需要重点验证权利金、行权、到期失效、买卖方权益和风险边界。止盈止损
• 现货需要重点验证买卖资产冻结、成交扣减、解冻和余额准确。止盈止损

设计约束：业务语义与可读性优先

代码必须让维护者能够按业务顺序理解。功能正确、测试和压测通过，不能替代可读性；新增复杂度的必要性由实现者证明。

• 先写清业务，再写代码。 动手前用简短业务步骤说明本次改动：入口、校验、状态变化、结果及异常处理，并指出现有类如何承担；不先设计框架。明确后直接实施，不为常规实现增加审批流程。
• 主流程应能顺着读。 一个业务动作有明确入口，在主方法中看得出业务步骤和先后关系；细节可提取为有业务含义的方法，不为缩短方法或文件机械拆类，也不把所有职责塞进一个大类。跨线程或异步时明确交接的数据、负责的线程和完成条件。
• 命名说明职责。 优先使用下单、撤单、成交、冻结、持仓、结算等业务概念；技术组件使用准确的技术名称。不得用含糊的 Manager、Coordinator、Processor、Context 等后缀代替职责说明；不因名称本身批量改名。
• 默认直接实现。 优先在现有业务模块内完成；只有独立业务职责、明确状态所有权或实际协议、持久化、并发边界才拆分。不为单一实现新增接口、工厂、策略注册或通用执行框架；已有契约及外部依赖隔离确有需要时，说明具体边界。未来扩展、统一风格、方便测试不能单独作为理由。
• 每层都要承担实际职责。 不新增仅透传参数、转发调用或重复搬运字段的层；协议转换和必要的线程交接除外。一次确定性成交事件直接交给对应 owner lane 串行应用，不拆出无业务意义的任务、barrier 或 commit 阶段。
• 一个状态一个权威来源。 新增状态、Map/List/Set、索引或缓冲区必须说明所有者、生命周期、读写方，以及现有数据为何不能满足。不得重复维护同一业务事实、逐命令复制快照或为未来场景预留容器；必要索引、恢复快照须明确与权威状态的一致性关系。
• 技术机制留在必要边界。 不把排序、canonicalization、rolling hash、导出视图和快照物化从协议、查询、恢复或持久化边界带入 matcher、settlement 或 Account Lane 热路径；不为统一抽象引入全表扫描、临时聚合或状态副本。能直接消费不可变事件、使用 primitive 数组/集合或复用固定容量缓冲区时，不改用 boxed 集合或动态临时集合。
• 复杂优化必须有实测依据。 按统一压测标准定位实际瓶颈，优先做局部改进；引入数据结构或处理阶段前先说明业务/正确性需求和简单方案为何不够，完成后用受影响路径的 JMH/JFR 验证成本。不得用“高性能”“解耦”“可扩展”代替证据。
• 交付前检查并删除多余抽象。 对本次新增的类、接口、状态和阶段，简要说明“负责什么业务或技术边界、为什么现有代码不能直接承担”；没有具体理由就合并或删除。交付以业务流程和关键源码入口说明改动，不能只列抽象类名。
• 简化不破坏正确性边界。 保留产品线隔离、资金不变量、状态所有权、确定性顺序、结算完成及恢复要求。只简化本次影响范围；不得借可读性优化发起无关架构重写，也不得照搬已有过度设计继续扩散。

测试要求

• 所有 Java 构建、Maven 测试、集成测试及性能采样统一使用 HotSpot JDK 27；执行前检查 java -version 和 mvn -version。
• 根据 CodeGraph 调用方、Maven 依赖和数据/事件边界确定影响面，不按文件数量判断，也不默认跑全量：
  • 文档、注释、格式及不影响运行时的配置：git diff --check 和必要的静态检查。
  • 局部逻辑：受影响模块及对应测试类；跨模块边界：所有直接受影响模块测试及集成测试。
  • 共享协议、根 POM、公共 topic、核心状态模型或影响面无法界定：扩大到相关产品线，必要时全量测试。
• 精确测试使用 mvn -pl <module> -Dtest=<TestClass> test；需要依赖模块时使用 mvn -pl <module> -am test。端到端优先用 Maven 模块测试，不引用已删除的 scripts/ 路径。
• 每次只启动受影响产品线，共享或跨产品线改动才扩大范围。交易链路测试保持做市运行；用模拟用户 API 覆盖改动涉及的下单、撤单、成交、持仓、主动平仓、强平、风控和 WebSocket 推送。
• 可能影响资金或持仓时，核对用户及做市账户余额、冻结、持仓、订单终态和资金守恒：期初、充值/调整、成交、手续费、资金费、强平费、交割/行权流水、期末余额。
• Topic 改动检查 ProductTopicNames、初始化配置、consumer group、key 校验和 WebSocket fanout；共享 topic 覆盖所有消费者。
• 交付说明必须写明已测范围、未测范围及依据、无法启动的环境和已知缺口，不得因测试耗时跳过受影响路径。
• 测试前及运行中检查磁盘空间，限制日志和录制大小；空间不足时停止并记录环境异常。分析入档后停止本轮进程，清理本轮临时集群、Archive、JFR、堆转储、日志及报告；只删除确认属于本轮的生成文件。记录追加清理状态，已删除路径仅作历史定位。

文档

• 新增或调整产品线、资金模型、撮合、风控、交割、期权、WebSocket、Kafka Topic 后，要同步中文 README 和相关文档。
• 说明要结合源码路径和关键类，避免只写概念。

提交

• 仅在 master 分支开发、提交和推送；未经用户明确要求，不再创建或切换开发分支。
• 每完成一个模块并通过测试后 commit and push。