trade-message-center/.trellis/spec/server/backend/index.md

服务端开发规范

这份规范记录 @trade-message-center/server 当前已经确认的服务端基线。OneTalk WebSocket 契约、Bright 历史读取、Mind HTTP 授权适配器和传输错误码已建立；真实生产 Mind 服务的联调尚未完成，需在真实 Mind 环境单独验收。

当前基线

• 包目录是 apps/server/，已有 Fastify 应用工厂、健康路由、Bright 读取/联调路由、WebSocket 注册和 PostgreSQL ORM 连接模块。
• 运行时依赖为 fastify@^5.12.1、@fastify/websocket@^11.3.0、drizzle-orm@^0.45.2 和 postgres@^3.4.9。
• 根 TypeScript 配置使用严格模式、ES2022 和 NodeNext，服务端代码应复用该配置。
• 当前已建立 Drizzle 迁移配置、OneTalk 事实 schema 和一次性执行入口；本地 Mind 授权模拟与 Bright 联调页归独立的 mind-test-harness，不属于 server。生产日志库仍未引入。OneTalk 协议使用共享 contract 包，测试使用 Node.js 内置 node:test。

共享术语

本目录各契约文档共用以下术语，正文不再重复定义：

术语	含义
canonical connection	connection-store 中唯一登记的已认证 WebSocket 连接；每个副作用边界前都复核当前操作仍属于它
generation	连接代数；连接替换或重连后递增，旧 generation 的回调与副作用一律失效
policy epoch	OneTalkCutoverPolicy 的单调计数；pause() 使旧 epoch 失效并关闭既有连接
admission	cutover policy 对新连接/帧的准入判定（enabled/paused/epoch）；不准入则拒绝，不进入业务处理
commit guard	随事务传入的 OneTalkCommitGuard；事务前后复核，失效即回滚，不返回伪造成功
post-write fence	事务提交成功后、ACK/发布前对 policy epoch、canonical connection、generation 和授权的最后一轮同步复核
pending-send / SendAttempt	registry 预占的发送尝试状态机（reserved → … → terminal）；每个 sendRequestId 只有一个 attempt
fail closed	依赖不可用或校验失败时拒绝动作并暴露稳定错误码；绝不降级为成功、空数据或默认值
HWM（high-water mark）	已上传/已拒绝观察时间的单调水位；不高于水位的观察直接跳过
future-skew	观察 observedAtMs 超过 Bright 接收时间 5 分钟；整批拒绝且只丢弃匹配 pending

规范目录

文档	内容	状态
项目级代码架构	所有包共用的文件职责、共享层级、main-last 与注释规则	项目级必读
目录结构	服务端包边界与目录现状	已建立
数据库规范	数据库能力、项目级 SQL JOIN 禁止默认与内存组合边界	已建立基线
错误处理	HTTP/WS 稳定错误映射与安全边界	已建立
质量规范	工具链与验证方式	已建立基线
日志规范	日志能力的当前边界	已建立基线
服务基础设施	Fastify、WebSocket、ORM 与 OneTalk Mind 公共投影契约	已建立
后台纪要内部网络读取	内部 7777 listener、Docker 网络边界、固定窗口与发布约束	Center 独立契约
Mind HTTP 授权	两个 Mind 授权 HTTP 接口、同域 Cookie、workspace 声明、CORS/Origin 与 fail-closed 边界	Center 已实现；真实 Mind/浏览器联调待验
OneTalk 单会话历史重建	rebuild 独立授权、scoped clear、generation/rebuild correlation、原子 reset 与 completion anchor	已实现；真实 PostgreSQL/浏览器联调另行验证
OneTalk 联系人资料 Bright 持久化	profile composite key、严格时间前进 upsert、future-skew 拒绝、transaction/ACK fence 和 read-model 内存组合	已实现并有 focused tests；真实 PostgreSQL 另行验证
OneTalk 买家事实 Bright 持久化与读取	buyer source replace、transaction/ACK fence、无 JOIN read projection	已实现并有 PostgreSQL integration tests

开始前检查

1. 先阅读 项目级代码架构 与 数据库查询组合，再阅读根 package.json、apps/server/package.json、tsconfig.base.json 及本目录相关文档。
2. HTTP 层、业务逻辑、外部依赖和数据访问的边界，应以首个真实模块为依据建立，不能因为已有 Fastify 依赖就假设项目已经有路由或错误响应格式。
3. 引入数据库、日志或测试依赖时，必须同时写明版本、初始化位置、失败行为和验证命令。
4. 使用根级命令验证：pnpm typecheck、pnpm build、pnpm test。根脚本会跳过没有同名脚本的子包；新增服务端实现后应让服务端声明真实脚本。

文档维护

每形成一个可重复的服务端模式，就用实际文件和测试补充对应文档。若约定尚未被代码或任务明确采用，应保留为“尚未建立”，不要提前制造虚构示例。