John Qiu
ea266e9cce
将 coolbuy (3) 和 enjoysa (2) 共 5 个项目特定技能从 skills/ 移至 skills-projects/， 保持通用技能与业务项目技能分离。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
339 lines
8.4 KiB
Markdown
339 lines
8.4 KiB
Markdown
---
|
||
name: coolbuy-platform
|
||
description: Coolbuy SaaS 平台管理端开发与部署。用于平台端前后端开发、租户管理、部署发布、翻译检查等任务。当用户提到 coolbuy-platform、平台端、租户管理后台相关任务时自动激活。
|
||
---
|
||
|
||
# Coolbuy Platform Skill
|
||
|
||
Coolbuy SaaS 平台管理端，用于管理所有租户、功能授权、计费、运营分析等。
|
||
|
||
## 项目信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 本地路径 | `/Users/donglinlai/coding/qiudl/coolbuy-platform` |
|
||
| Git 仓库 | `git@gitea.pipexerp.com:pipexerp/coolbuy-platform.git` |
|
||
| 主分支 | main |
|
||
|
||
---
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
coolbuy-platform/
|
||
├── service/ # Go 后端 (Gin + GORM)
|
||
│ ├── cmd/ # 入口 main.go
|
||
│ ├── internal/admin/ # 核心业务
|
||
│ │ ├── api/ # HTTP handlers
|
||
│ │ ├── biz/ # 业务逻辑
|
||
│ │ ├── store/ # 数据访问
|
||
│ │ ├── model/ # 领域模型
|
||
│ │ └── middleware/ # 中间件
|
||
│ └── configs/ # 配置文件
|
||
└── web/ # React 前端 (Vite + TypeScript)
|
||
├── src/
|
||
│ ├── api/ # API 客户端
|
||
│ ├── components/ # 组件
|
||
│ ├── pages/ # 页面
|
||
│ ├── stores/ # Zustand 状态
|
||
│ └── locales/ # i18n 翻译
|
||
└── dist/
|
||
```
|
||
|
||
---
|
||
|
||
## 部署环境
|
||
|
||
### 生产服务器
|
||
|
||
| 服务 | 地址 | 端口 | 容器名 |
|
||
|------|------|------|--------|
|
||
| 前端 | http://platform.pipexerp.com | 4999 | coolbuy-platform-web |
|
||
| 后端 | http://39.105.150.219 | 7090 | coolbuy-platform-service |
|
||
| Auth | http://39.105.150.219 | 7089 | coolbuy-auth-service |
|
||
|
||
### 服务器信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| IP | 39.105.150.219 |
|
||
| 用户 | root |
|
||
| SSH 密钥 | ~/.ssh/coolbuy3.pem |
|
||
| 操作系统 | Ubuntu 24.04 |
|
||
|
||
### 数据库
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| 类型 | PostgreSQL 16 |
|
||
| Host | 172.18.0.1 (Docker 网关) |
|
||
| Port | 5432 |
|
||
| Database | paas_platform |
|
||
| User | platform |
|
||
| Password | Coolbuy2025~ |
|
||
|
||
### Docker Registry
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| Registry | Docker Hub |
|
||
| 账号 | saltthing123 |
|
||
| 前端镜像 | saltthing123/coolbuy-platform-web |
|
||
| 后端镜像 | saltthing123/coolbuy-platform-service |
|
||
| Auth镜像 | saltthing123/coolbuy-auth-service |
|
||
|
||
---
|
||
|
||
## 快速部署命令
|
||
|
||
### 部署前端
|
||
|
||
```bash
|
||
cd /Users/donglinlai/coding/qiudl/coolbuy-platform/web
|
||
|
||
# 1. 构建
|
||
npx vite build
|
||
|
||
# 2. 打包 Docker 镜像
|
||
~/.orbstack/bin/docker build --platform linux/amd64 \
|
||
-t saltthing123/coolbuy-platform-web:<version> \
|
||
-t saltthing123/coolbuy-platform-web:latest .
|
||
|
||
# 3. 推送镜像
|
||
~/.orbstack/bin/docker push saltthing123/coolbuy-platform-web:<version>
|
||
~/.orbstack/bin/docker push saltthing123/coolbuy-platform-web:latest
|
||
|
||
# 4. 部署到服务器
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "
|
||
docker pull saltthing123/coolbuy-platform-web:<version> && \
|
||
docker stop coolbuy-platform-web && \
|
||
docker rm coolbuy-platform-web && \
|
||
docker run -d --name coolbuy-platform-web \
|
||
--restart unless-stopped \
|
||
-p 4999:80 \
|
||
saltthing123/coolbuy-platform-web:<version>
|
||
"
|
||
```
|
||
|
||
### 部署后端
|
||
|
||
```bash
|
||
cd /Users/donglinlai/coding/qiudl/coolbuy-platform/service
|
||
|
||
# 1. 构建二进制
|
||
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o coolbuy-platform-service cmd/main.go
|
||
|
||
# 2. 打包 Docker 镜像
|
||
~/.orbstack/bin/docker build --platform linux/amd64 \
|
||
-t saltthing123/coolbuy-platform-service:<version> \
|
||
-t saltthing123/coolbuy-platform-service:latest .
|
||
|
||
# 3. 推送镜像
|
||
~/.orbstack/bin/docker push saltthing123/coolbuy-platform-service:<version>
|
||
~/.orbstack/bin/docker push saltthing123/coolbuy-platform-service:latest
|
||
|
||
# 4. 部署到服务器
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "
|
||
docker pull saltthing123/coolbuy-platform-service:<version> && \
|
||
docker stop coolbuy-platform-service && \
|
||
docker rm coolbuy-platform-service && \
|
||
docker run -d --name coolbuy-platform-service \
|
||
--restart unless-stopped \
|
||
-p 7090:7090 \
|
||
-v /data/coolbuy-platform/logs:/app/logs \
|
||
-v /data/coolbuy-platform/storage:/app/storage \
|
||
-v /data/coolbuy-platform/configs:/app/configs:ro \
|
||
-e TZ=Asia/Shanghai \
|
||
saltthing123/coolbuy-platform-service:<version> \
|
||
--config configs/config.prod.yaml
|
||
"
|
||
```
|
||
|
||
---
|
||
|
||
## 本地开发
|
||
|
||
### 启动后端
|
||
|
||
```bash
|
||
cd /Users/donglinlai/coding/qiudl/coolbuy-platform/service
|
||
go run cmd/main.go -config configs/config-dev.yaml
|
||
```
|
||
|
||
### 启动前端
|
||
|
||
```bash
|
||
cd /Users/donglinlai/coding/qiudl/coolbuy-platform/web
|
||
npm run dev
|
||
```
|
||
|
||
### 构建测试
|
||
|
||
```bash
|
||
# 后端测试
|
||
cd service && go test -v ./...
|
||
|
||
# 前端测试
|
||
cd web && npm run test
|
||
```
|
||
|
||
---
|
||
|
||
## 翻译管理
|
||
|
||
### 翻译文件位置
|
||
|
||
- 简体中文: `web/src/locales/zh-CN.ts`
|
||
- 繁体中文: `web/src/locales/zh-TW.ts`
|
||
|
||
### 检查翻译缺失
|
||
|
||
```bash
|
||
# 查找组件中使用的翻译 key
|
||
cd /Users/donglinlai/coding/qiudl/coolbuy-platform/web
|
||
grep -r "t(['\"]" src/components/ src/pages/ | grep -oE "t\(['\"][^'\"]+['\"]" | sort | uniq
|
||
```
|
||
|
||
### 翻译 key 命名规范
|
||
|
||
| 模块 | 前缀 | 示例 |
|
||
|------|------|------|
|
||
| 租户管理 | tenant.* | tenant.form.nameRequired |
|
||
| 用户管理 | user.* | user.createSuccess |
|
||
| 角色管理 | role.* | role.permissionAssigned |
|
||
| 菜单管理 | menu.* | menu.iconRequired |
|
||
| 通知中心 | notification.* | notification.markAllRead |
|
||
|
||
---
|
||
|
||
## API 端点
|
||
|
||
### 认证 (Auth Service - 7089)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/auth/login | 登录 |
|
||
| POST | /api/v1/auth/logout | 登出 |
|
||
| POST | /api/v1/auth/refresh | 刷新 Token |
|
||
|
||
### 平台管理 (Platform Service - 7090)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/v1/admin/tenants | 租户列表 |
|
||
| POST | /api/v1/admin/tenants | 创建租户 |
|
||
| GET | /api/v1/admin/users | 用户列表 |
|
||
| GET | /api/v1/admin/roles | 角色列表 |
|
||
| GET | /api/v1/admin/menus | 菜单列表 |
|
||
| GET | /api/v1/admin/dashboard/overview | 仪表盘概览 |
|
||
|
||
### 健康检查
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| /health | 基础健康检查 |
|
||
| /health/detailed | 详细状态 |
|
||
| /readiness | K8s 就绪探针 |
|
||
| /liveness | K8s 存活探针 |
|
||
|
||
---
|
||
|
||
## 数据库迁移
|
||
|
||
### 自动迁移
|
||
|
||
配置 `migration.auto: true` 时，服务启动自动运行迁移。
|
||
|
||
### 手动迁移
|
||
|
||
```bash
|
||
psql -h 172.18.0.1 -U platform -d paas_platform \
|
||
-f service/configs/migrations/001_create_platform_admin_tables.sql
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1. 翻译 key 不显示
|
||
|
||
组件使用的 key 与 locale 定义不匹配。检查：
|
||
- 组件使用 `t('tenant.domainConfig.*')` 但 locale 定义为 `tenant.domain.*`
|
||
- 需要添加别名命名空间
|
||
|
||
### 2. SSE 连接错误
|
||
|
||
通过 Cloudflare Tunnel 访问时 SSE 长连接会中断，属于已知问题，会自动重连。
|
||
|
||
### 3. Docker 构建失败
|
||
|
||
确保使用 OrbStack 的 docker：`~/.orbstack/bin/docker`
|
||
|
||
### 4. 数据库连接失败
|
||
|
||
Docker 网关 IP 是 `172.18.0.1`，不是默认的 `172.17.0.1`。
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| 1.0.9 | 2026-01-05 | 修复租户管理全部翻译缺失 |
|
||
| 1.0.8 | 2026-01-04 | 修复租户列表翻译 |
|
||
| 1.0.7 | 2026-01-04 | 修复租户表单翻译 |
|
||
| 1.0.0 | 2026-01-03 | 初始版本 |
|
||
|
||
---
|
||
|
||
## SSH 快捷命令
|
||
|
||
```bash
|
||
# 连接服务器
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219
|
||
|
||
# 查看容器状态
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "docker ps | grep coolbuy"
|
||
|
||
# 查看后端日志
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "docker logs -f coolbuy-platform-service --tail 100"
|
||
|
||
# 查看前端日志
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "docker logs -f coolbuy-platform-web --tail 100"
|
||
|
||
# 健康检查
|
||
ssh -i ~/.ssh/coolbuy3.pem root@39.105.150.219 "curl -s http://localhost:7090/health"
|
||
```
|
||
|
||
---
|
||
|
||
## 创建租户
|
||
|
||
```bash
|
||
# 通过 API 创建租户
|
||
curl -X POST http://39.105.150.219:7090/api/v1/admin/tenants \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer <token>" \
|
||
-d '{
|
||
"name": "租户名称",
|
||
"code": "tenant_code",
|
||
"contact": "联系人",
|
||
"phone": "13800138000",
|
||
"email": "contact@example.com",
|
||
"user_limit": 50,
|
||
"storage_limit": 10,
|
||
"schema_type": "shared",
|
||
"admin_username": "tenantadmin",
|
||
"admin_real_name": "管理员姓名",
|
||
"status": "normal"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 相关技能
|
||
|
||
- `ops-tools` - DevOps 运维工具，包含 Jenkins/Gitea 管理
|
||
- `dev-coding` - 软件编码开发
|
||
- `coolbuy-paas` - 租户端系统（待创建）
|