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

服务端开发规范

这份规范记录 @trade-message-center/server 当前已经确认的服务端基线。OneTalk WebSocket 契约、Bright 历史读取、Mind HTTP 授权适配器和传输错误码已建立；真实生产 Mind 服务的联调仍留待 08-26-mind-integration-cutover。

当前基线

• 包目录是 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。

规范目录

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

开始前检查

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

文档维护

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