优化

2026-04-25 16:36:34 +08:00
commit db90e7579b
1876 changed files with 189777 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,112 @@
+# Sales Chat 插件项目说明
+
+## 项目信息
+- **类型**: Tailchat 插件 + Flutter 移动端
+- **位置**: `/Users/sion/Desktop/projects/tailchat-sales/`
+- **插件目录**: `server/plugins/com.msgbyte.saleschat/`
+- **推荐 Node 版本**: 18（Dockerfile 基础镜像 node:18.18.0-alpine）
+- **推荐 pnpm 版本**: 8（通过 corepack 或 `npm install -g pnpm@8`）
+
+## 项目结构
+```
+tailchat-sales/
+├── server/                              # 后端服务（Tailchat）
+│   ├── plugins/com.msgbyte.saleschat/   # 销售聊天插件
+│   ├── admin/                           # 管理后台（独立前端）
+│   └── packages/sdk/                    # Tailchat Server SDK
+├── client/
+│   ├── web/                             # Web 前端（Tailchat 聊天界面）
+│   ├── flutter/                         # Flutter 移动端（独立应用）
+│   └── shared/                          # 前端共享代码
+├── Dockerfile                           # 生产构建（Node 18）
+└── docker-compose.yml                   # 全套服务编排
+```
+
+## 启动方式
+
+### 方式一：Docker（推荐）
+```bash
+docker-compose up -d          # 启动全部服务
+docker-compose logs -f tailchat  # 查看日志
+docker-compose down           # 停止服务
+```
+- 后端 + 前端: `http://localhost:3000`
+- MinIO Console: `http://localhost:9001`
+- 管理员: tailchat / com.msgbyte.tailchat
+
+### 方式二：本地开发（需要 Node 18）
+```bash
+npx pnpm@8 install
+DISABLE_REPL=true TS_NODE_TRANSPILE_ONLY=true npx pnpm@8 --filter tailchat-server dev:main   # 后端
+NODE_OPTIONS='--no-experimental-strip-types' npx pnpm@8 --filter tailchat-web dev             # 前端
+```
+- 后端: `http://localhost:11000`
+- 前端: `http://localhost:11011`
+
+> **注意**: 本地开发需要先启动 MongoDB、Redis、MinIO（可用 `docker-compose up -d mongo redis minio`）
+
+## 环境变量
+
+### 开发环境（server/.env）
+```
+PORT=11000
+SECRET=dev-secret-key
+MONGO_URL=mongodb://tailchat:tailchat_secret@127.0.0.1:27017/tailchat?authSource=admin
+REDIS_URL=redis://127.0.0.1:6379/
+MINIO_URL=127.0.0.1:9000
+MINIO_USER=tailchat
+MINIO_PASS=tailchat_secret
+ADMIN_USER=tailchat
+ADMIN_PASS=com.msgbyte.tailchat
+DISABLE_TRACING=true
+```
+
+### Docker 环境（docker-compose.yml）
+已内置配置，无需额外 .env 文件。
+
+## 插件开发
+
+### 插件结构
+```
+server/plugins/com.msgbyte.saleschat/
+├── package.json
+├── services/
+│   ├── invite.service.ts    # 邀请管理
+│   ├── stats.service.ts     # 数据统计
+│   └── admin.service.ts     # 管理功能
+├── models/
+│   ├── invite.model.ts
+│   └── stats.model.ts
+└── test/
+    └── integration.spec.ts
+```
+
+### 构建 & 测试
+```bash
+cd server/plugins/com.msgbyte.saleschat
+pnpm build
+pnpm test
+```
+
+## Flutter 移动端
+```bash
+cd client/flutter
+flutter pub get
+flutter run
+```
+
+## 已知问题
+
+### Node 23 不兼容
+本项目依赖 moleculer 0.14、typegoose 9、ts-node 10，与 Node 23 不兼容：
+- `performance.now()` this 上下文问题
+- ts-node ESM 模块解析冲突
+- typegoose 装饰器类型推断失败
+
+**解决方案**: 使用 Node 18（Docker 已内置），或用 `fnm` 管理多版本：
+```bash
+fnm install 18 && fnm use 18
+```
+
+### pnpm 版本
+lockfile 是 v6 格式（pnpm 8），pnpm 10 不兼容。用 `npx pnpm@8` 或 `corepack` 管理。