diff --git a/Fabric.Backend.Center/.env.example b/Fabric.Backend.Center/.env.example new file mode 100644 index 0000000..19b5b08 --- /dev/null +++ b/Fabric.Backend.Center/.env.example @@ -0,0 +1,20 @@ +# Server +PORT=7001 + +# MySQL +DB_HOST=mysql-center +DB_PORT=3306 +DB_USER=fabric +DB_PASSWORD=fabric +DB_NAME=fabric_center +DB_SYNC=true +DB_LOGGING=false + +# Auth (to be used in auth module) +JWT_ACCESS_SECRET=change-me-access +JWT_REFRESH_SECRET=change-me-refresh +JWT_ACCESS_EXPIRES_IN=15m +JWT_REFRESH_EXPIRES_IN=30d + +# Center <-> Guild handshake +CENTER_SHARED_SECRET=change-me-center-secret diff --git a/Fabric.Backend.Guild/.env.example b/Fabric.Backend.Guild/.env.example new file mode 100644 index 0000000..5cfdc17 --- /dev/null +++ b/Fabric.Backend.Guild/.env.example @@ -0,0 +1,20 @@ +# Server +PORT=7002 + +# MySQL +DB_HOST=mysql-guild +DB_PORT=3306 +DB_USER=fabric +DB_PASSWORD=fabric +DB_NAME=fabric_guild +DB_SYNC=true +DB_LOGGING=false + +# Guild identity +GUILD_NODE_ID=guild-node-1 +GUILD_NODE_NAME=Guild Node 1 +GUILD_PUBLIC_ENDPOINT=http://localhost:7002 + +# Center handshake +CENTER_BASE_URL=http://backend-center:7001 +CENTER_SHARED_SECRET=change-me-center-secret diff --git a/docs/TODO-backend-center-guild.md b/docs/TODO-backend-center-guild.md new file mode 100644 index 0000000..d299df0 --- /dev/null +++ b/docs/TODO-backend-center-guild.md @@ -0,0 +1,120 @@ +# TODO - Backend Center/Guild 开发任务分解 + +## 0. 基础工程(本周) +- [x] Backend 拆分:Center / Guild +- [x] NestJS skeleton 初始化(Center/Guild) +- [x] MySQL + TypeORM 接入 +- [x] Dockerfile(Center/Guild) +- [x] docker-compose(center/guild + mysql) +- [x] 增加 `.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 签名与重放防护 +- [ ] 出站重试队列(指数退避) +- [ ] Bot Token 入站调用鉴权 + +--- + +## 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 可实时收发 +- [ ] 插件可通过 Bot Token 写入消息并接收 webhook +- [ ] docker-compose 一键部署可用