企业官网建设流程全解析

• 金融科技
• 后端
• 前端

本文档是binance-trading-bot仓库对任何编码 Agent（Claude Code、Cursor、Codex 等）的行为契约，原文见仓库根目录 AGENTS.md。它不重复docs/里的架构细节，而是锁定四条不可协商的核心不变量、依赖编排与技术选型、Agent 必须掌握的命令集、整套 lint 与 CI 质量门，以及必须拒绝的反模式。读完本文，你能理解该仓库"为什么这样设计"以及"改动代码时必须守住哪些红线"，在接手任何 Issue 或提交 PR 前先对齐这些约束。

项目定位：单操作者、多账户、多 Profile 的可靠性优先交易平台

binance-trading-bot是一个运行在 Binance 上的单操作者（single-operator）、多账户（multi-account）、多 Profile（multi-profile）、可靠性优先、移动端优先的交易平台。概念模型是一条清晰的归属链：

• 一个操作者拥有 N 个"一等公民"的 Binance 账户，每个账户 =一对 API Key + 一个运行环境（binance_mode）+ 一条用户数据流（user-data stream）；
• 每个账户上运行 N 个策略Profile，共享该账户的钱包；
• 策略是插件（plugin）——trailing-trade是第一个插件，事实来源（source of truth）在 packages/strategy/trailing-trade/，契约在 packages/strategy/core/ 与 docs/architecture/extensibility.md。

这个定位决定了仓库的整个工程取向：正确性优先、绿地基（Greenfield，尚未部署上线），没有历史兼容包袱，因此"宁可选择正确且可扩展的设计，也不追求最小 diff"，可以自由重构，但在动手前必须先说出自己要做一个大型重构。

架构原则：Correctness first

在写任何代码之前，先确认设计是健全的：

• 把权衡（tradeoffs）摆到桌面上；
• 选择能守住下文"核心不变量"的最简单方案；
• 任何版本/API 断言都要引用权威来源；
• 拿不准就 push back，而不是猜。

四条核心不变量

1. 可扩展性：策略与通知器必须是插件

策略是packages/strategy-core背后的插件；通知器是@app/notify的./providers/*子路径导出。硬性规定：

• apps/api/apps/worker严禁直接 import 某个具体的strategy-*包或某个@app/notify/providers/*提供者（除各自的注册表引导代码外）；
• apps/web可以 import 策略包，因为它是"类型化事件载荷的消费方"；
• 新增一个策略= 新建一个包 + 在注册表里加一行；新增一个通知器= 新增一个 provider 模块 + 在buildNotifyRegistry加一行——永远不需要改apps/api/apps/worker。

这条不变量在代码里有三层印证：

• apps/worker/src/strategies.ts与apps/api/src/strategies.ts都只调用buildStrategyRegistry()（定义在 packages/strategy/registry/src/index.ts），由它统一注册trailingTrade、momentum、rebalance三个插件，两个进程因此持有完全一致的注册集合；
• packages/notify/src/registry.ts的buildNotifyRegistry()统一注册 slack / telegram / webhook 三个 provider；
• scripts/ci/no-plugin-leak.sh 在 lint 阶段扫描apps/{api,worker}的.ts/.tsx文件，凡在 import 位置出现@app/strategy-*（除-core/-backtest基础设施外）或@app/notify/providers/*即视为泄漏，并做空扫（vacuity）防护——如果扫描结果为 0 个插件引用，直接判失败，防止门"静默失明"。

2. 可靠性：Crash-only

• Crash-only：进程崩溃后直接重启即可恢复，无需人工干预；
• 幂等任务（Idempotent jobs）：任务重复执行与执行一次结果等价；
• 每账户 Binance 限速隔离（Per-account Binance-rate isolation）：不同账户的请求额度互不干扰；
• 没有静默失败（No silent failures）：任何失败要么显式报错、要么写日志/告警，绝不悄悄吞掉。

可靠性机制在 docs/architecture/reliability.md 中有展开：例如 Binance 时钟漂移自愈（-1021时合并式地重取一次/api/v3/time再重试一次）、已下架标的与无权限标的的 tick 自愈路径。单副本下"单次执行"由四个机制共同保证：BullMQjobId合并、进程内chainByKey串行化、幂等clientOrderId、带版本号的symbol_states乐观 CAS（详见 docs/architecture/worker-pipeline.md）。

3. 易用且响应式：面向单人操作者，移动端优先

• 操作者是单人、非金融专业人士：要用大白话，交易术语第一次出现时就给出注释（gloss），绝不假设用户有屏幕之外的知识；
• 移动端优先：每个视图在 375×667 分辨率下都可用，然后向上扩展。

4. 账户隔离：按行（row）而不是按约定（convention）

这是最容易被改坏的一条，值得详细拆解：

数据模型：一个操作者（users）→ 多个accounts→ 多个profiles。accounts.owner_id → users.id；每个账户持有一对 Binance Key、一个binance_mode、一条用户数据流。profiles.account_id把每个 Profile 绑定到其账户，共享该账户的 Key/钱包/数据流。

双层品牌化 Scope（Branded two-tier scope）：

• AccountScope{db, operatorId, accountId}由scopeAccount铸造；
• ProfileScope{db, operatorId, accountId, profileId}由scopeProfile铸造；
• 两者在一次查询里证明完整的所有权链（operator owns account、account owns profile）；
• UserId与AccountId是不同的品牌化类型——把其中一个误当另一个用，编译期就会报错。

实现细节在 packages/db/src/repo/_scoped.ts：每个 scope 携带一个模块私有的unique symbol品牌键（accountScopeBrand/profileScopeBrand）。品牌键不导出，意味着没有任何消费者能凭空合成一个带品牌的 scope——手工构造的字面量无法满足类型，强转也会因为无法命名该 symbol 键而失败。唯一的铸造入口就是scopeAccount/scopeProfile两个构造函数，它们内部各自跑一条所有权查询（scopeAccount查accounts.id = accountId AND accounts.owner_id = operatorId；scopeProfile用profiles ⋈ accounts三条件连接）。另外两点约束：

• scope禁止序列化：JSON.stringify会丢掉 symbol 键，一个 JSON 往返过的 scope 会在运行时失去品牌证明——scope 只能作为请求内缓存令牌（per-request cache token），绝不能放进 BullMQ 载荷或其他线格式；
• toAccountScope(ProfileScope)是从已证明的 Profile 链里"免费"宽化出 Account 链的唯一合法路径（worker 的订单对账是账户域，而 tick 只持有 Profile scope）。

访问规则：应用代码只能通过profileRepo(...)/profileRepoFromScope(scope)（账户级表面如 api-keys 则用accountRepo(...)/accountRepoFromScope）访问账户作用域数据，来源是@app/db。禁止手动(db, operatorId, …)参数传递；每个账户作用域 repo 函数第一个参数必须是AccountScope/ProfileScope，而 scope 只能由scopeAccount/scopeProfile铸造——所有权在编译期只被证明一次。扁平的repo.<x>只保留给操作者/全局函数（repo.users.*、repo.accounts.create/listForOwner、保留期清理等）。

路由约定：API 在/api/accounts/:accountId/...之下，Web 在/accounts/$accountId/...之下。

强制手段：packages/db/__tests__/repo/ast-check.test.ts+ 跨账户集成测试；数据库侧没有 RLS。详见 docs/architecture/account-isolation.md 与 docs/architecture/database.md。隔离文档还覆盖了"基础资产独占性"（一个基础资产在一个账户下最多被一个 Profile 管理）、报价币冲突、以及 Profile/账户的破坏性删除语义（Profile 删除会 detach 订单ON DELETE SET NULL，账户删除才 CASCADE）。

策略状态的作用域：策略状态在存储层和tick()中都是按 (profile, symbol)切片的——每次调用每个 symbol 一个切片。跨 symbol 状态必须走每 Profile 的 KV 存储：通过set-kv/delete-kv决策写入策略自有的命名空间键，再通过TickInput.profileKv读回合并快照（需在capabilities.needsProfileKv中显式开启）。KV 写入对兄弟 symbol 在后续tick 才可见，绝不在同一 tick 内。这一定义与Decision联合类型中的set-kv/delete-kv变体一一对应（见 packages/strategy/core/src/decision.ts），在 docs/architecture/extensibility.md 的"State scope"一节有专门的状态流转图。

技术栈

版本一律以package.json/ lockfile 为准（这是唯一事实来源），AGENTS.md 只给名字：

注意："金额 = Decimal"有对应的 lint 强制：oxlint 的no-restricted-imports在packages/strategy-*、packages/indicators、packages/contracts下游禁止number（IEEE-754）参与金额计算，decimal.js只在 money-math 包内可用（见下文 Linting 节与 .oxlintrc.json）。

仓库布局

apps/ api/ web/ worker/ server/ # server = ROLE 可选入口（api + worker） packages/ strategy/ core/ trailing-trade/ # core = 契约 + Executor；TT = 第一个插件 indicators/ # 纯函数、Decimal 类型化的蜡烛/窗口数学 notify/ # @app/notify: 契约 + 注册表 + providers/{slack,telegram,webhook} binance/ db/ contracts/ config/ core/ # 共享运行时工具；子路径导出（./env, …） deploy/compose/ scripts/ci/

一个值得注意的约定：packages/strategy/*的目录分组只是文件系统层面，npm 包名保持扁平（@app/strategy-trailing-trade）；@app/notify是单一包，providers 是子路径导出。

必会命令

AGENTS.md 给出了一张完整的命令表，这是 Agent 在仓库里的日常操作手册：

对应实现可以在 package.json 的 scripts 字段里逐条核对。

文档构建的 uv 陷阱

文档构建运行在uv 管理的 Python 环境（pyproject.toml的[dependency-groups] docs）里，绝不使用 PATH 上恰好存在的mkdocs。直接跑裸mkdocs build --strict会捡到一个无关的解释器，然后死在The "<plugin>" plugin is not installed——这个报错意味着环境不对，而不是配置坏了，所以手动去装报错点名的插件是错误修法。正确做法是始终走bun run docs:build/docs:serve（它们通过uv run调用 mkdocs）；先跑bun run docs:install（uv sync --group docs）创建该环境。

Linting 体系

oxlint 是唯一的 lint 路径（配置在 .oxlintrc.json，全仓库单次扫描，这样import/no-cycle能看到完整依赖图）：开启correctness+typescript/import/oxc/react插件，并通过overrides强制仓库不变量——尤其是策略/指标的纯净性（no-restricted-globals/no-restricted-imports）和decimal.js 边界。

几个容易踩的配置点：

• react插件开着是因为react/no-unstable-nested-components（在另一个组件的渲染体内声明的组件每次渲染都会重挂其子树，在 WebKit 上会钳制scrollTop）；开启插件也同时武装了所有reactcorrectness规则，所以react/exhaustive-deps被显式off，待处理它已有的违规；
• 纯净性 override 覆盖packages/strategy/*/src/**、packages/indicators/src/**、packages/discovery/src/**，禁止Date（用注入的clock.now()）、Math（用注入的RNG）、process/performance，以及fs/net/http/https/crypto/ioredis/pg/drizzle-orm等一切 I/O——这与契约中"策略与指标必须是纯函数、worker 注入Clock和RNG"的反模式条目呼应（见 packages/strategy/core/src/contract.ts 的Clock/RNG定义）。

oxlint 表达不了的不变量 →scripts/ci/*.sh门

oxlint 无法表达的不变量全部下沉为scripts/ci/*.sh门，由lint.sh统一驱动（见 scripts/ci/lint.sh）。典型代表：

• no-plugin-leak（不变量 1，实现见 scripts/ci/no-plugin-leak.sh）；
• no-arbitrary-color-token——禁止在 web 里用任意颜色 token；
• no-phantom-env-var——环境变量必须登记，禁止"幽灵变量"；
• no-invalid-mermaid——文档里的 mermaid 图必须合法；
• no-undeclared-workspace-import——workspace 内 import 必须声明；
• no-wider-metrics-sink——只有apps/worker/src/metrics/catalog.ts可以声明指标 sink；第二个类型为name: string的 sink 能通过类型检查并逃出目录，所以必须用门守住；
• no-unreviewed-tofixed——apps/web/src/**下每个直接.toFixed(和固定两位maximumFractionDigits的站点都要在 scripts/ci/tofixed-inventory.json 里登记"模式身份 + 事实性的取值理由"（一次硬舍入就能让一个亚美分的报价余额渲染成0.00）；
• no-dropped-lint-rule——断言最终解析出的 oxlint 配置仍然武装了承载不变量的规则；
• no-backfilled-migration——新NNNN_*.sql必须取下一个未用序号（runner 按文件名顺序应用，插在高水位线以下的文件会在所有已迁移库上最后执行）；
• no-mutated-applied-migration——已上线的NNNN_*.sql不可变；每个套件都从全新库迁移，所以只有钉死的摘要清单能看到会卡死已部署库的漂移；
• no-bun-version-skew——九个 Bun 钉版本点必须一致（Renovate 不能可靠覆盖它们）；
• no-blind-walk——每个从树遍历读结论的门都要用 scripts/ci/lib/walk.mjs 的collectOrExit，它拒绝没有声明锚点的根，并保留GUARD_ROOT覆盖接缝供自测使用：一个只是变窄了的遍历仍能返回几百个文件，所以门打印的计数只有在"被证明仍然到达规则保护的模块、且其 stop 已被观察触发"时才是证据。

每个门都遵循"先自测后门"（selftest 在前，gate 在后）的编排，lint.sh里还专门对no-web-api-query-drift、no-bun-version-skew、no-stale-comment-refs、no-backfilled-migration、no-dropped-lint-rule等解释了为什么自测必须先行（门在自己那一次失败时，自测回答"是树漂移了还是检查器坏了"）。完整性规则见 docs/contributing/coding-rules.md。

质量门：CI 必须强制执行

AGENTS.md 明确列出 9 条质量门，任何 Agent 的改动都必须过：

1. Lint 干净；

2. Typecheck 干净；

3. 行为变化时文档必须同步更新——每个论断都能追溯到来源，而不是记忆。机器强制部分：bun run docs:build（docs:gen --check检查配置表与环境变量引用，然后uv run mkdocs build --strict）、no-invalid-mermaid.sh、no-stale-migration-doc.sh；叙述准确性留作 review 门，见 docs/contributing/coding-rules.md#documentation-accuracy；

4. 每 workspace 完整套件的覆盖率阈值达标（packages/config/vitest/coverage-policy.js）——例如@app/binance、@app/discovery、@app/indicators、@app/money、@app/notify、@app/strategy-core及各策略包都是 100/100 或接近全量的线/分支阈值；

5. 策略 golden-fixture 回放 diff = 0；

6. Playwright 流水线绿灯：browser-bootstrap证明四个配置的浏览器项目都能启动并报告每次跳过的应用执行及其原因（不声称关键路径覆盖）；app-e2e在回环 Binance fixture 上启动一个封闭的 ROLE=all 栈并跑全部四个项目中的 P0 旅程，任何跳过和任何 fixture 未应答的 Binance 流量都判失败；

7. bun run compose:build对每个应用都成功；

8. 迁移契约：手写NNNN_*.sql按顺序由校验和追踪 runner 应用（packages/db/src/migrate.ts，记录在_app_migrations表），packages/db套件对真实 Postgres 跑migrate()。已上线的迁移不可变，且破坏它的两种方式失败方式不同：

   • 编辑（连注释都算）会改变摘要，把每个已迁移数据库卡死在该文件，后续迁移无法修复；
   • 重命名或删除对 runner 不可见（它按名字索引）：文件会像新的一样重新应用，并把旧的账本行变成孤儿——静默发生。

   正确做法是用新迁移去改变旧迁移；no-mutated-applied-migration强制这点（新库套件看不到这两种情况），migrate-immutability.test.ts（packages/db/tests/migrate-immutability.test.ts）把两个行为都钉死。编号是同一契约的另一半：新迁移取下一个未用序号，绝不取空洞、字母后缀或低于0001的号——因为"名字顺序 = 应用顺序"，no-backfilled-migration从目录清单强制它，这是唯一能区分"回填"与"新树"的 oracle。

   底层 runner 的细节值得展开：packages/db/src/migrate.ts用pg_advisory_lock串行化并发迁移者（当前驱动是并行 vitest worker 共享测试库），按文件名排序后逐条应用：先比对_app_migrations里的历史摘要，一致则跳过、不一致则拒绝改写历史并抛错；新文件在事务里执行 SQL 并写入(name, checksum)，失败回滚。摘要算法是 SHA-256（sha256导出），no-mutated-applied-migration.sh钉住的正是 runner 自己算的这份摘要；

9. JSDoc 质量是 review 门而非 lint 门：每个导出或非平凡函数都要带块注释，每个参数一行@param、有返回值就写@returns。标签上方的话承载 WHY；每个标签解释该值意味着什么——禁止复述名字（@param symbol - The symbol），禁止空块。一个名不副实或容易被误读的名字，其@param行是读者唯一被告知的地方，所以即使类型看起来不言自明也必须写。另外注释不要硬折行（hard-wrap）：一段话一行，一个@param/@returns标签一行，无论多长——这就是prettier.config.mjs对 Markdown 已应用的proseWrap: 'never'规则的同一理由：硬折行的散文把每一次后续编辑变成多行重排，diff 会隐藏真正改动的句子。编辑器软折行，diff 不折行。

必须拒绝的反模式（Anti-patterns to refuse）

这份清单是"code review 红线"，任何 Agent 提交的代码踩到其中任何一条都应当被拒：

1. NotifyProvider 单一事实来源：provider 形状活在@app/notify；apps/api消费notifyProviders.describeAll()，绝不自建 provider 接口；
2. 无分布式锁：禁止redlock、intents:Redis 集合、软余额预留或同类物（scripts/ci/no-locks.sh 会失败，还扫描packages/binance）。允许的共享 Redis 原语只有"限速/可见性"，不是锁（无 owner、无 release/refund）：消费-衰减的请求权重桶和自过期SET NX PX通知器缺口节流器；
3. 磁盘上无明文 API Key（Postgres 例外之外），且只在 docs/architecture/auth.md 的缓解措施下允许（单租户、操作者侧 Binance IP 白名单）。任何新的存储面（备份、副本、导出、多租户）都要求先有静态加密；
4. LIVE_DEMO响应中无密钥：公开 demo 注入了唯一操作者 id，所以每个未在requireNotDemo之后的 route 都可匿名访问。凭据等价物——Binance API Key、通知器webhook URL、bot token、auth header、AI-provider key——绝不能序列化进任何响应体。在投影边界剥掉（api-key →last4，ai-provider →has*布尔，notifiers 用secretFields声明密钥），使泄漏在构造上不可能。requireNotDemo是黑名单/纵深防御：默认情况下，任何新的读密钥或写凭据的 route 都是暴露的——既要加入拒绝清单，也要加入 apps/api/tests/routes/live-demo-guard.test.ts 的完整性断言；
5. 无投机性抽象：特性开关、可配置性、"为了未来"的间接层都需要一个带具体消费者的已追踪 Issue；
6. 金额数学 =Decimal：number（IEEE-754）在packages/{strategy-*,indicators,contracts}下游被禁；decimal.js 导入边界由 oxlintno-restricted-imports强制（见 .oxlintrc.json）；
7. Decision联合保持通用：noop/place-order/cancel-order/replace-order/emit-event/set-kv/delete-kv（见 packages/strategy/core/src/decision.ts）。通用的交易所请求形状（如replace-order）属于联合；策略特定的副作用走emit-event+ 命名空间键，不加策略特定的新变体；跨 symbol 耦合走set-kv/delete-kv。被删除的变体要带走它的 worker 侧端口——不留空闲接缝（idle seams）；
8. 策略与指标必须纯净：packages/strategy-*/src/**和packages/indicators/src/**内禁止ioredis/pg/drizzle-orm/fs/net/http/crypto/Date/Math.random；tick()内禁止 I/O（worker 注入Clock和RNG）；decimal.js允许；
9. 注释讲"为什么"不讲"什么"：代码里禁止 Spec / Issue / Phase /@see引用；commit 和 PR 承载这些。CI 拒绝；
10. 测试放在<pkg>/__tests__/，绝不放在src/旁边。CI 拒绝；
11. 新的共享运行时工具进@app/core的新子路径，而不是新包——除非该工具具有清晰的领域边界（strategy、notifier、binance、db、contracts）。

给 Agent 的实战操作顺序

把整份契约压缩成改动流程，一个合规的 Agent 工作流应该是：

1. 动手前：确认设计满足四条不变量——新增策略/通知器只动注册表；金额计算全程Decimal；策略状态按 (profile, symbol) 切片、跨 symbol 走 KV；账户数据只经 scope repo 访问；
2. 实现时：遵循反模式清单，tick()保持纯净，注释写 WHY 且不硬折行，新迁移取下一个未用序号且永不回填；
3. 提交前：跑bun run lint与bun run typecheck必须全绿；行为变化则跑bun run docs:build让文档门通过；新策略补 golden-fixture 回放 diff = 0 与 metric 名登记；
4. 测试：bun run test过各 workspace 覆盖率阈值（packages/config/vitest/coverage-policy.js）；涉及 worker 行为时按需跑bun run test:worker-integration（需 Docker）；端到端由 Playwright 流水线覆盖。

这套流程把"正确性优先"的架构原则落到了每一次提交上——这正是 AGENTS.md 作为工程契约希望任何编码 Agent 内化的行为模式。

• 金融科技
• 后端
• 前端