fix: 渠道账号群聊同步缓存 key 及成员名称兜底；统一 Docker/Maven 项目约定

AGENTS.md

@@ -0,0 +1,94 @@
+# Sino-MCI 项目约定
+
+> 本文件用于固定开发/部署时的关键操作，避免反复踩坑。
+
+## 1. Java 与 Maven
+
+- **必须使用 JDK 21**：`/Library/Java/JavaVirtualMachines/zulu-21.jdk/Contents/Home`
+- 项目已配置 Maven Toolchain，**必须在 `backend/` 目录下执行完整 reactor 构建**：
+  ```bash
+  cd /Users/marsal/Projects/sino-project/sino-mci/backend
+  mvn clean install -DskipTests
+  ```
+- **不要**用 `-pl` 单模块编译，会跳过 `.mvn/maven.config` 中的 toolchains 配置，导致编译报 JDK 17 错误。
+- 当前环境 `java -version` 可能显示 JDK 17，但 Maven 会通过 toolchain 自动切换到 JDK 21，无需手动修改 `JAVA_HOME`。
+
+## 2. Docker Compose 项目名（重要）
+
+Docker Compose 的 `-p` 参数决定容器前缀和命名卷前缀。反复换 `-p` 会产生多个 MySQL 数据卷，导致数据“丢失”的假象。
+
+**统一使用项目名 `sino-mci`**：
+
+```bash
+cd /Users/marsal/Projects/sino-project/sino-mci
+
+# 启动全部基础设施 + 应用
+# 使用 --profile 同时启用 infra 和 app，否则带 profile 的服务不会启动
+docker compose -p sino-mci --profile infra --profile app up -d
+
+# 只启动基础设施（MySQL/Redis/RabbitMQ/SeaweedFS）
+docker compose -p sino-mci --profile infra up -d
+
+# 只启动应用（mci-server / admin-web / channel-service）
+docker compose -p sino-mci --profile app up -d
+
+# 停止整个项目（不删除数据卷）
+docker compose -p sino-mci --profile infra --profile app down
+```
+
+- 不带 `-p` 时，项目名默认就是目录名 `sino-mci`，与上面等价。
+- **不要**再使用 `-p infrastructure` 或其他名字启动，避免产生新的数据卷。
+
+## 3. 数据卷
+
+当前项目使用的命名卷：
+
+- `sino-mci_mci-mysql-data`
+- `sino-mci_mci-seaweedfs-data`
+- `sino-mci_channel-service-data`
+
+### 检查当前 MySQL 容器挂载的是哪个卷
+
+```bash
+docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/lib/mysql" }}{{ .Name }}{{ end }}{{ end }}' mci-mysql
+```
+
+### 查看所有 sino-mci 相关卷
+
+```bash
+docker volume ls | grep sino-mci
+```
+
+### 历史 `infrastructure_*` 卷
+
+早期用 `-p infrastructure` 启动过，留下以下卷，**目前未被使用**：
+
+- `infrastructure_mci-mysql-data`
+- `infrastructure_mci-seaweedfs-data`
+- `infrastructure_channel-service-data`
+
+如需迁移/核对其中的数据，请先停止当前 `mci-mysql`，再临时挂载该卷启动容器查询，查完立即恢复。
+
+## 4. 常用命令
+
+```bash
+# 查看服务状态
+docker compose -p sino-mci ps
+
+# 查看 mci-server 日志
+docker logs -f mci-server --tail 100
+
+# 进入 MySQL
+docker exec -it mci-mysql mysql -uroot -proot sino_mci
+
+# 进入 Redis
+docker exec -it mci-redis redis-cli
+
+# 重新构建 mci-server 镜像（先执行 mvn clean install -DskipTests）
+docker compose -p sino-mci --profile app build mci-server
+```
+
+## 5. 环境变量
+
+- 复制 `.env.example` 为 `.env` 后再修改本地配置。
+- 默认 root 密码为 `root`，仅本地开发使用。