Fabric/docs/TODO-backend-center-guild.md

TODO - Backend Center/Guild 开发任务分解

0. 基础工程（本周）

• Backend 拆分：Center / Guild
• NestJS skeleton 初始化（Center/Guild）
• MySQL + TypeORM 接入
• Dockerfile（Center/Guild）
• docker-compose（center/guild + mysql）
• 增加 .env.example（Center/Guild）
• 增加统一 lint/format 配置（eslint + prettier）
• 增加基础 CI（build + lint）

---

1. Fabric.Backend.Center（Identity Hub）

1.1 Auth

• 用户注册（email/password）
• 用户登录（JWT access + refresh）
• token 刷新
• 登出（refresh token 失效）
• 密码哈希（bcrypt/argon2）
• DTO + 参数校验 + 错误码规范

1.2 Guild Node 注册与握手

• POST /nodes/register shared-secret 校验
• node 唯一性校验（nodeId/endpoint）
• node 状态模型（active/offline/revoked）
• GET /nodes 列表 + 分页
• node 心跳接口（可选）

1.3 Center 运维能力

• 审计日志（auth/node 关键操作）
• 健康检查深化（DB ready）
• 配置校验（启动时必填项检查）

---

2. Fabric.Backend.Guild（Guild Node）

2.1 领域模型

• Guild/Channel/DM 实体补全
• Member/Role 基础模型（即使 MVP 权限全开，也先留结构）
• 索引设计（channel_id + seq, created_at 等）

2.2 消息主链路

• 发送消息（content/reply/mentions/attachments 元数据）
• 编辑消息（可编辑窗口策略先简化）
• 删除消息（软删 vs 硬删，先定策略）
• GET messages 分页（seq 区间 + limit）
• seq 分配改为 DB 原子方案（避免并发冲突）

2.3 一致性与回补

• 回补接口：seq_from/seq_to
• 断片检测辅助响应字段（next_expected_seq 等）
• 幂等键支持（写接口）

2.4 实时通信（MVP 后半）

• WebSocket 网关接入
• message.created/updated/deleted 事件广播
• 在线状态 + typing 事件

---

3. Center ↔ Guild 协议层

• 鉴权方案定稿（node token / HMAC）
• 注册握手协议文档化
• 错误码与重试策略统一
• 版本协商（X-Fabric-Version）

---

4. 插件与扩展面（为 OpenclawPlugin 准备）

• Webhook 事件信封落地（event_id/event_type/occurred_at/data）
• HMAC 签名与重放防护
• 出站重试队列（指数退避）
• API Key 入站调用鉴权（不区分 Bot/人类）

---

5. 测试与质量门禁

5.1 自动化测试

• 单元测试（auth/service/message/seq）
• 集成测试（MySQL + API）
• 合约测试（Center-Guild 协议）

5.2 质量门禁

• lint/typecheck/build 全绿
• API 文档（OpenAPI/Swagger）
• 关键链路压测（发送/拉取/回补）

---

6. 部署与运维

• docker-compose.prod.yml（去掉 DB_SYNC=true）
• DB migration 机制（TypeORM migration）
• 结构化日志 + request id
• 基础监控指标（QPS、延迟、错误率）
• 备份与恢复流程文档

---

7. 推荐执行顺序（建议）

1. Center Auth 完整闭环
2. Guild 消息链路 + DB 原子 seq
3. Center-Guild 握手协议固定
4. WebSocket 实时层
5. 插件扩展面 + 回调重试
6. 测试、压测、发布文档

---

8. Definition of Done（MVP）

• 用户可注册登录
• Guild/Channel/DM 可创建并发消息
• 消息 seq 连续可回补
• WebSocket 可实时收发
• 插件可通过统一 API Key 写入消息并接收 webhook
• docker-compose 一键部署可用