pipexerp/ai-proj-helper
6
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

refactor: 项目技能拆分到 skills-projects/

Browse Source 
将 coolbuy (3) 和 enjoysa (2) 共 5 个项目特定技能从 skills/ 移至 skills-projects/，
保持通用技能与业务项目技能分离。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Qiu
2026-03-14 11:21:53 +10:30
parent 40b36a8e41
commit ea266e9cce
14 changed files with 100 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills-projects/coolbuy-legacy-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "coolbuy-legacy-plugin",
"description": "酷采2.0团购管理系统测试与维护。用于酷采2.0系统的功能测试、问题排查、需求验证和对比测试。",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

414
skills-projects/coolbuy-legacy-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,414 @@
---
name: coolbuy-legacy
description: 酷采2.0团购管理系统测试与维护。用于酷采2.0系统的功能测试、问题排查、需求验证和对比测试。当用户提到酷采2.0、百丽、李宁、遗留系统测试相关任务时自动激活。
---
# Coolbuy Legacy (酷采2.0) Skill
酷采2.0团购管理系统，服务于百丽、李宁等客户的遗留系统，采用 Vue 2 + Element UI + Java Spring 技术栈。
## 项目信息
| 项目 | 值 |
|------|-----|
| 项目编号 | P264 |
| 项目名称 | 酷采 2.0 |
| AI-Proj 项目ID | 164 |
| 源码路径 | `/Users/donglinlai/workspace/coolbuy-legacy` |
| Git 仓库 | `git@gitea.pipexerp.com:pipexerp/coolbuy-legacy.git` |
| 主分支 | main |
| 技术栈 | Vue 2 + Element UI + Java Spring |
---
## 系统访问
### 测试环境
| 项目 | 值 |
|------|-----|
| 测试地址 | http://47.105.185.154:9300/login |
| 管理员账号 | 19090009801 |
| 密码 | 123456 |
| 客户账号 | 17761202551 / 202551 |
| 服务器 | 47.105.185.154 |
### 主要客户
- **百丽集团** - 大型鞋业零售集团
- **李宁体育** - 知名体育用品品牌
---
## 架构概览
```
coolbuy-legacy/
├── cool_lining/module-provider/ # Java 后端服务
│ └── src/main/java/com/jzg/module/
│ ├── action/ # 控制器层
│ │ ├── prd/ # 商品模块控制器
│ │ ├── order/ # 订单模块控制器
│ │ └── customer/ # 客户模块控制器
│ ├── dao/model/ # 数据模型
│ │ ├── prd/ # 商品实体
│ │ ├── order/ # 订单实体
│ │ └── customer/ # 客户实体
│ └── manager/ # 业务逻辑层
│ ├── prd/ # 商品业务逻辑
│ ├── order/ # 订单业务逻辑
│ └── customer/ # 客户业务逻辑
└── ln_admin/ # Vue 2 前端
└── src/views2/module/ # 业务模块页面
├── prd/ # 商品管理页面
├── order/ # 订单管理页面
└── customer/ # 客户管理页面
```
---
## 主要功能模块
### 核心业务模块
1. **推广方案管理**
- 促销活动配置
- 折扣规则设置
- 活动效果统计
2. **销售管理**
- 订单处理流程
- 销售数据统计
- 客户下单管理
3. **草稿单管理**
- 未完成订单保存
- 草稿单编辑
- 批量转正式单
4. **Y码直客**
- 直客订单管理
- Y码生成与核销
- 直客价格体系
5. **库存管理**
- 库存查询
- 库存调拨
- 库存预警
6. **货盘管理**
- 货盘创建
- 货盘分配
- 货盘跟踪
7. **协同仓管理**
- 多仓协同
- 仓库调度
- 发货管理
8. **价格管理**
- 商品定价
- 客户价格体系
- 最低折扣限制
9. **资金管理**
- 账户余额
- 充值记录
- 消费明细
10. **产品管理** ⭐
- 商品信息维护
- SPU/SKU管理
- 商品分类
11. **基础功能**
- 客户管理
- 用户权限
- 系统配置
12. **数据看板**
- 销售数据分析
- 库存报表
- 业务概览
13. **公告通知**
- 系统公告
- 消息推送
- 通知管理
14. **起售数量设置**
- 最小起售量
- 批量设置
- 规则配置
---
## 与酷采3.0的对比
### 技术栈差异
| 项目 | 酷采2.0 (Legacy) | 酷采3.0 (PaaS) |
|------|------------------|----------------|
| 前端框架 | Vue 2 | React 18 |
| UI组件库 | Element UI | Ant Design |
| 前端构建 | Webpack | Vite |
| 后端语言 | Java | Go |
| 后端框架 | Spring Boot | Gin + go-zero |
| 数据库 | MySQL | PostgreSQL |
| 架构模式 | 单体应用 | 微服务 |
| 部署方式 | 传统部署 | Docker + K8s |
### 业务差异
| 功能 | 酷采2.0 | 酷采3.0 |
|------|---------|---------|
| 多租户 | ❌ 单租户 | ✅ 多租户 SaaS |
| 客户隔离 | 账号级别 | 企业级别 |
| 定制化 | 客户专属部署 | 配置化租户 |
| 扩展性 | 垂直扩展 | 水平扩展 |
---
## 测试任务管理
### AI-Proj 项目集成
当前项目在 AI-Proj 系统中的ID为 **164**，包含以下测试任务：
#### 客户最低折扣申请限制功能测试
**父任务**: #4725 (in_progress)
**测试用例**:
- ✅ TC001: 按客户类型配置最低折扣 [P0] - #4726
- ✅ TC002: 按特定客户配置最低折扣 [P0] - #4727
- ✅ TC003: 折扣下限输入验证 [P1] - #4728
- ✅ TC004: 阈值导入模板 [P1] - #4729
- ✅ TC005: 折扣低于下限 - 拦截 [P0] - #4730
- ✅ TC006: 折扣等于下限 - 通过 [P0] - #4731
- ✅ TC007: 折扣高于下限 - 通过 [P1] - #4732
- 🔄 TC008: 多商品触发限制 - 罗列提示 [P0] - #4733
- ⏳ TC009: 非一级账号不受限 [P1] - #4734
- ⏳ TC010: 审核修改折扣低于下限 - 拦截 [P0] - #4735
- ⏳ TC011: 审核修改折扣等于下限 - 通过 [P0] - #4736
- ⏳ TC012: 限价标签显示 [P1] - #4737
- ⏳ TC013: 提示文字验证 [P1] - #4738
### 查询任务
```javascript
// 获取酷采2.0项目任务列表
mcp__ai-proj__list_tasks({ projectId: 164 })
// 获取特定任务详情
mcp__ai-proj__get_detailed_task_info({ taskId: 4725 })
// 获取任务文档
mcp__ai-proj__get_task_document({ taskId: 4725 })
```
---
## Chrome DevTools 浏览器自动化
### 启动调试模式
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-debug
```
### 验证连接
```bash
curl http://127.0.0.1:9222/json/version
```
### 验证码处理规则
**重要**: 当访问需要验证码的系统时：
1. **不要**使用脚本截图方式获取验证码（验证码会快速过期）
2. **直接提醒用户**：
- 请在浏览器中输入验证码
- 或请帮我点击登录按钮
3. 用户操作完成后再继续自动化流程
示例提示：
```
浏览器已打开登录页面，验证码需要手动输入。请在 Chrome 浏览器中：
1. 输入验证码
2. 点击登录按钮
完成后告诉我，我将继续后续操作。
```
### 常用 MCP 操作
```javascript
// 列出所有页面
mcp__chrome-devtools__list_pages()
// 选择页面
mcp__chrome-devtools__select_page({ pageId: 1 })
// 导航到URL
mcp__chrome-devtools__navigate_page({
type: "url",
url: "http://47.105.185.154:9300/login"
})
// 截图
mcp__chrome-devtools__take_screenshot({
format: "png",
filePath: "/tmp/screenshot.png"
})
// 获取页面快照
mcp__chrome-devtools__take_snapshot()
// 点击元素
mcp__chrome-devtools__click({ uid: "element_uid" })
// 填写表单
mcp__chrome-devtools__fill({
uid: "input_uid",
value: "text"
})
// 执行JavaScript
mcp__chrome-devtools__evaluate_script({
function: "() => { return document.title; }"
})
```
---
## 常见测试场景
### 1. 客户最低折扣测试
**测试步骤**:
1. 登录管理员账号 (19090009801)
2. 进入价格管理 → 最低折扣配置
3. 配置客户类型或特定客户的最低折扣
4. 使用客户账号 (17761202551) 登录
5. 创建订单，测试折扣限制规则
**验证点**:
- 折扣低于下限时系统拦截
- 折扣等于或高于下限时通过
- 多商品触发时正确罗列提示
- 非一级账号不受限制
### 2. 订单流程测试
**测试步骤**:
1. 客户账号登录
2. 选择商品加入购物车
3. 提交订单
4. 审核订单 (管理员)
5. 发货处理
6. 订单完成
### 3. 库存管理测试
**测试步骤**:
1. 查询库存
2. 创建库存调拨单
3. 审核调拨单
4. 确认入库
5. 验证库存变化
---
## 需求对比测试流程
当酷采3.0实现新功能时，需要与酷采2.0进行对比：
### 测试流程
1. **功能分析**
- 在酷采2.0中找到对应功能
- 记录现有实现方式
- 识别差异点
2. **页面对比**
- 截图酷采2.0界面
- 对比UI/UX差异
- 记录交互流程
3. **数据对比**
- 对比数据模型
- 验证业务规则
- 确认边界条件
4. **性能对比**
- 记录响应时间
- 对比并发能力
- 评估用户体验
---
## 问题排查
### 常见问题
1. **登录失败**
- 检查账号密码是否正确
- 验证码是否过期
- 网络连接是否正常
2. **页面加载慢**
- 检查网络状况
- 清除浏览器缓存
- 查看服务器日志
3. **数据不同步**
- 刷新页面
- 检查数据库连接
- 查看后端日志
### 日志查看
```bash
# SSH到测试服务器
ssh root@47.105.185.154
# 查看应用日志
tail -f /path/to/coolbuy/logs/application.log
# 查看错误日志
tail -f /path/to/coolbuy/logs/error.log
```
---
## 相关技能
- `coolbuy-paas` - 酷采3.0 SaaS租户端开发
- `coolbuy-platform` - 酷采3.0平台管理端
- `dev-test` - 软件测试技能
- `req` - 需求管理技能
- `siyuan` - 思源笔记（含酷采相关文档）
---
## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-01-21 | 初始版本，创建酷采2.0独立技能 |
---
## 注意事项
⚠️ **重要提醒**:
1. 酷采2.0为遗留系统，主要用于参考和对比测试
2. 新功能开发应在酷采3.0 (coolbuy-paas) 中进行
3. 测试环境数据仅供测试使用，请勿在生产环境操作
4. 百丽、李宁等客户仍在使用此系统，测试时注意不要影响生产数据
5. 发现问题及时记录到 AI-Proj 系统中

8
skills-projects/coolbuy-paas-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "coolbuy-paas-plugin",
"description": "酷采3.0 SaaS 租户端开发与测试。用于商品管理、订单管理等业务模块开发，以及酷采2.0系统对比测试。",
"version": "1.3.0",
"author": {
"name": "qiudl"
}
}

803
skills-projects/coolbuy-paas-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,803 @@
---
name: coolbuy-paas
description: 酷采3.0 SaaS 租户端开发与测试。用于商品管理、订单管理等业务模块开发，以及酷采2.0系统对比测试。当用户提到酷采、coolbuy-paas、商品管理、产品管理、酷采2.0测试相关任务时自动激活。
---
# Coolbuy PaaS Skill
酷采3.0 SaaS 多租户业务系统，采用 Go + React 技术栈。
## 项目信息
| 项目 | 值 |
|------|-----|
| 本地路径 | `/Users/donglinlai/coding/qiudl/coolbuy-paas` |
| 工作区路径 | `/Users/donglinlai/workspace/coolbuy-paas` |
| Git 仓库 | `git@gitea.pipexerp.com:pipexerp/coolbuy-paas.git` |
| 主分支 | main |
| 技术栈 | Go (Gin+GORM) + React 18 (Vite+TypeScript+Ant Design) |
---
## 架构概览
```
coolbuy-paas/
├── erp-service/ # Go 后端 - ERP业务服务 (port 7091)
│ ├── api/ # API 定义 (go-zero)
│ ├── internal/
│ │ ├── product/ # 商品模块
│ │ ├── order/ # 订单模块
│ │ └── inventory/ # 库存模块
│ └── configs/
├── foundation-service/ # 基础服务 (port 7090)
├── auth-service/ # 认证服务 (port 7089)
├── ai-service/ # AI 服务 (port 7092) - AI Chat, Tool Calling
│ ├── api/
│ │ └── etc/ # 配置文件 (多环境)
│ └── services/
│ ├── chat_service.go # 对话服务
│ └── ai_ticket_reporter.go # AI 工单上报
├── gateway/ # API 网关
├── web/ # React 前端 - 租户端 (port 4000)
│ ├── src/
│ │ ├── services/ # API 服务
│ │ │ ├── aiChatApi.ts
│ │ │ └── chatSessionService.ts
│ │ └── components/AIChat/ # AI 聊天组件
│ └── .env.* # 环境配置
└── web-mall/ # React 前端 - 独立商城 (port 5174)
├── src/
│ ├── pages/ # 首页/分类/商品/购物车/结算/个人中心
│ ├── api/ # API 层（共享 erp-service）
│ ├── auth/ # 认证（共享 auth-service JWT）
│ ├── store/ # Zustand 状态管理
│ └── layouts/ # 商城布局（顶部导航，非侧边栏）
├── nginx.conf # 生产 Nginx 配置
└── Dockerfile # 多阶段构建
```
---
## 多环境配置
### 运行环境
| 环境 | 前端配置 | 后端配置 | 说明 |
|------|---------|---------|------|
| development | `.env.development` | `ai-api.yaml` | 本地开发 |
| staging | `.env.staging` | `ai-api.staging.yaml` | 预发布环境 |
| production | `.env.production` | `ai-api.production.yaml` | 生产环境 |
### 核心环境变量
| 变量 | 说明 | 开发环境示例 |
|------|------|------------|
| `VITE_AUTH_SERVICE_URL` | 认证服务 | `http://127.0.0.1:7089` |
| `VITE_FOUNDATION_SERVICE_URL` | 基础服务 | `http://127.0.0.1:7090` |
| `VITE_BUSINESS_SERVICE_URL` | ERP服务 | `http://127.0.0.1:7091` |
| `VITE_AI_SERVICE_URL` | AI服务 | `http://127.0.0.1:7092` |
| `VITE_AI_PROJ_URL` | ai-proj服务 | `http://127.0.0.1:8080` |
### Vite 代理配置 (vite.config.ts)
```typescript
proxy: {
'/api/v1/auth': { target: VITE_AUTH_SERVICE_URL },
'/api/v1/ai': { target: VITE_AI_SERVICE_URL }, // AI Chat
'/api/v1/chat': { target: VITE_AI_PROJ_URL }, // Chat Sessions
'/api/v1': { target: VITE_BUSINESS_SERVICE_URL }, // 默认路由
}
```
---
## AI 服务集成
### AI Chat 功能
| 端点 | 服务 | 说明 |
|------|------|------|
| `/api/v1/ai/chat/stream` | ai-service (7092) | 流式对话 |
| `/api/v1/ai/tools` | ai-service (7092) | 获取可用工具 |
| `/api/v1/chat/sessions` | ai-proj (8080) | 会话管理 |
| `/api/v1/ai-tickets` | ai-proj (8080) | AI 工单 |
### AI Chat 代码路径（重要）
**前端实际调用链**：
```
useChat.ts
→ import * as aiChatService from '@/services/aiChatApi' ← 实际使用的文件！
→ aiChatApi.sendChatMessageStream()
→ aiChatApi.sendStreamingChatRequest() ← 用 fetch() 直接发 SSE 请求
```
**注意**：`@/services/aiChatService.ts` 是遗留文件，**未被使用**。修改 AI Chat 前端逻辑时必须修改 `aiChatApi.ts`。
**流式请求绕过 axios**：`aiChatApi.ts` 使用原生 `fetch()` 发送 SSE 请求，不经过 `request.ts` 的 axios 拦截器。因此 `Authorization`、`X-Tenant-ID` 等 header 需要在 `fetch()` 中手动添加。
### AI Chat 认证链路
```
前端登录 → auth-service 返回 JWT (含 tenant_id, username, roles)
→ localStorage 存储 user_info + token
→ AI Chat 发送请求时:
1. getToken() 获取 JWT
2. getTenantIdFromContext() 获取 tenant_id
3. fetch() 携带 Authorization + X-Tenant-ID header
→ ai-service auth middleware 解析 JWT claims
→ Go context 注入 user_id, username, tenant_id, tenant_code, roles
→ buildUserIdentityContext(ctx) 提取并追加到 system prompt
→ AI 能回答"我的租户ID是什么"等问题
```
**关键文件**：
| 文件 | 作用 |
|------|------|
| `web/src/services/aiChatApi.ts` | 前端 AI Chat API（实际使用） |
| `web/src/hooks/useChat.ts` | Chat 状态管理 Hook |
| `ai-service/api/internal/middleware/auth_middleware.go` | JWT 解析，注入 context |
| `ai-service/services/chat_service.go` | 对话服务，system prompt 注入 |
| `ai-service/services/context_builder.go` | 用户上下文构建 |
**JWT 密钥一致性**：auth-service 和 ai-service 的 `JWT.AccessSecret` 必须一致，否则 ai-service 无法验证 token（开发环境有 flexible parse 兜底）。
### AI 工单上报
ai-service 的错误会自动上报到 ai-proj 的 AI 工单系统：
```yaml
# ai-service/api/etc/ai-api.yaml
AITicketReporter:
Enabled: true
AiProjURL: "http://localhost:8080"
```
错误类型自动分类：
- `api_error` - API 调用错误
- `missing_tool` - 工具调用错误
- `timeout` - 超时错误
- `permission_denied` - 权限错误
---
## 酷采2.0 测试环境 (Legacy)
用于参考和对比酷采3.0开发。
### 访问信息
| 项目 | 值 |
|------|-----|
| 测试地址 | http://47.105.185.154:9300/login |
| 管理员账号 | 19090009801 |
| 密码 | 123456 |
| 客户账号 | 17761202551 / 202551 |
| 技术栈 | Vue 2 + Element UI + Java Spring |
### 主要功能模块
- 推广方案、销售管理、草稿单管理
- Y码直客、库存管理、货盘管理
- 协同仓、价格管理、资金管理
- 基础功能、数据看板、公告通知
- 起售数量设置、**产品管理**
### 源码位置
```
~/workspace/coolbuy-legacy/
├── cool_lining/module-provider/ # Java 后端
│ └── src/main/java/com/jzg/module/
│ ├── action/prd/ # 商品控制器
│ ├── dao/model/prd/ # 商品实体
│ └── manager/prd/ # 商品业务逻辑
└── ln_admin/ # Vue 前端
└── src/views2/module/prd/ # 商品管理页面
```
---
## Chrome DevTools 浏览器自动化
用于系统测试、截图、UI验证。
### 启动 Chrome 调试模式
```bash
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-debug
```
### 验证连接
```bash
curl http://127.0.0.1:9222/json/version
```
### 验证码处理规则
**重要**: 当访问需要验证码的系统时：
1. **不要**使用脚本截图方式获取验证码（验证码会快速过期）
2. **直接提醒用户**：
- 请在浏览器中输入验证码
- 或请帮我点击登录按钮
3. 用户操作完成后再继续自动化流程
示例提示：
```
浏览器已打开登录页面，验证码需要手动输入。请在 Chrome 浏览器中：
1. 输入验证码
2. 点击登录按钮
完成后告诉我，我将继续后续操作。
```
### 常用 CDP 操作
```javascript
// 截图
Page.captureScreenshot({ format: 'png' })
// 导航
Page.navigate({ url: 'http://...' })
// 执行 JS
Runtime.evaluate({ expression: '...' })
// 点击元素
Runtime.evaluate({
expression: `document.querySelector('button').click()`
})
```
---
## 酷采3.0 PRD 参考
PRD 文档存储在 ai-proj 任务系统：
| 模块 | 任务ID | 文档名称 |
|------|--------|----------|
| 商品管理 | #4754 | 酷采3.0商品管理模块 |
| 商品基本信息 | #4770 | 商品基本信息管理模块PRD |
获取 PRD 文档：
```
mcp__ai-proj__get_task_document(taskId: 4770)
```
---
## 本地开发
### 启动服务
```bash
# ERP 服务 (port 7091)
cd erp-service && go run api/main.go -f configs/config.local.yaml
# AI 服务 (port 7092)
cd ai-service && go run api/ai.go -f api/etc/ai-api.yaml
# 租户端前端 (port 4000)
cd web && npm run dev
# 独立商城前端 (port 5174)
cd web-mall && npm run dev
```
### 依赖服务
| 服务 | 端口 | 说明 |
|------|------|------|
| PostgreSQL | 5432 | 本地数据库 |
| Redis | 6379 | 缓存 |
| ai-proj | 8080 | AI 项目管理（可选，用于 Chat Sessions） |
### 本地数据库
| 项目 | 值 |
|------|-----|
| 类型 | PostgreSQL |
| Database | paas_foundation |
| User | coolbuy-dev |
| Password | (空) |
### 远程数据库（生产参考）
| 项目 | 值 |
|------|-----|
| Host | 192.144.137.14 |
| Database | coolbuy_paas |
| User | platform |
| Password | Zhiyuncai2025~ |
### 数据库管理工具 - TablePlus
**推荐工具**: TablePlus - macOS 原生数据库 GUI 客户端，支持 PostgreSQL/MySQL/Redis 等。
#### 安装 TablePlus
```bash
# 使用 Homebrew 安装
brew install --cask tableplus
# 启动 TablePlus
open -a TablePlus
```
#### 自动配置数据库连接
TablePlus 的连接配置存储在 `~/Library/Application Support/com.tinyapp.TablePlus/Data/Connections.plist`。
**快速配置脚本**（已包含本地和远程连接）：
```bash
# 1. 关闭 TablePlus（如果正在运行）
killall TablePlus 2>/dev/null || true
# 2. 备份现有配置
cp ~/Library/Application\ Support/com.tinyapp.TablePlus/Data/Connections.plist \
~/Library/Application\ Support/com.tinyapp.TablePlus/Data/Connections.plist.backup
# 3. 编辑配置文件添加连接（参考下方 plist 格式）
# 4. 重启 TablePlus
open -a TablePlus
```
**连接配置示例**（plist 格式）：
```xml
<!-- 本地开发环境连接 -->
<dict>
<key>ConnectionName</key>
<string>Coolbuy PaaS - Local (开发环境)</string>
<key>DatabaseHost</key>
<string>localhost</string>
<key>DatabasePort</key>
<string>5432</string>
<key>DatabaseName</key>
<string>paas_foundation</string>
<key>DatabaseUser</key>
<string>coolbuy-dev</string>
<key>DatabasePasswordMode</key>
<integer>0</integer>
<key>Driver</key>
<string>PostgreSQL</string>
<key>Enviroment</key>
<string>local</string>
<key>statusColor</key>
<string>#3B82F6</string> <!-- 蓝色标识开发环境 -->
</dict>
```
#### 手动配置步骤
如果自动配置失败，可以手动在 TablePlus GUI 中添加：
1. 打开 TablePlus → 点击 "Create a new connection"
2. 选择 PostgreSQL
3. 填写连接信息：
**本地连接**：
- Name: `Coolbuy PaaS - Local (开发环境)`
- Host: `localhost`
- Port: `5432`
- Database: `paas_foundation`
- User: `coolbuy-dev`
- Password: (留空)
- Color: 蓝色
**生产连接**：
- Name: `Coolbuy PaaS - Production (生产环境)`
- Host: `192.144.137.14`
- Port: `5432`
- Database: `coolbuy_paas`
- User: `platform`
- Password: `Zhiyuncai2025~`
- Color: 红色（警示）
- **重要**：勾选 "Read-only mode" 防止误操作
#### 验证连接
连接成功后运行以下 SQL 验证：
```sql
-- 检查数据库版本
SELECT version();
-- 查看所有表
SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY table_schema, table_name;
-- 查看库存预占记录
SELECT * FROM biz_inventory_reservations
ORDER BY created_at DESC
LIMIT 10;
-- 查看活跃租户
SELECT id, name, code, status
FROM fnd_tenants
WHERE status = 1 AND deleted_at IS NULL;
```
#### TablePlus 常用快捷键
| 快捷键 | 功能 |
|--------|------|
| `Cmd + N` | 新建连接 |
| `Cmd + T` | 新建 Tab |
| `Cmd + K` | 连接列表 |
| `Cmd + R` | 刷新 |
| `Cmd + /` | 注释/取消注释 SQL |
| `Cmd + Enter` | 执行 SQL |
| `Cmd + Shift + E` | 导出数据 |
#### 安全提示
⚠️ **生产数据库操作注意事项**：
1. **必须**启用 "Read-only mode"（连接设置中）
2. **避免**直接执行 UPDATE/DELETE 操作
3. **建议**使用事务测试：`BEGIN; ... ROLLBACK;`
4. **慎用**批量操作
5. **定期**备份重要数据
---
## 独立商城 (web-mall)
独立 B2B 商城前端，与租户端 `web/` 并行运行，共享后端 API。
### 定位对比
| 维度 | 租户端 (web/) | 独立商城 (web-mall/) |
|------|--------------|---------------------|
| 定位 | 内部采购经理 | 终端采购用户 |
| 布局 | ERP 侧边栏 | 商城顶部导航 |
| 选品 | 表单弹窗选择 | 浏览分类/搜索+加购 |
| 下单 | ERP 表单模式 | 购物车→结算 |
### 页面结构
| 页面 | 路径 | 说明 |
|------|------|------|
| 首页 | `/` | 推荐商品、分类入口 |
| 商品列表 | `/products` | 搜索、筛选、排序 |
| 商品详情 | `/products/:id` | SKU 选择、加入购物车 |
| 购物车 | `/cart` | 购物车管理 |
| 结算 | `/checkout` | 提交订单 |
| 个人中心 | `/user` | 订单列表、订单详情 |
### Vite 代理配置 (web-mall/vite.config.ts)
```typescript
proxy: {
'/api/v1/auth': { target: 'http://localhost:7089' }, // auth-service
'/api': { target: 'http://localhost:7091' }, // erp-service
}
```
### Docker 部署
| 环境 | 端口 | 镜像 |
|------|------|------|
| 开发 | 5174 (Vite) | 本地 `npm run dev` |
| 生产 | 8889:80 | `saltthing123/coolbuy-paas-web-mall` |
### 需求来源
REQ-20260214-0001（采购单双模式），PRD 任务 #5874。
---
## 商品模块开发
### 前端页面结构
```
web/src/pages/Product/
├── ProductList/ # 商品列表页
│ ├── index.tsx
│ ├── columns.tsx # 表格列配置
│ └── searchFields.ts # 搜索表单配置
├── ProductForm/ # 商品表单页(新增/编辑)
│ ├── index.tsx
│ ├── BasicInfo.tsx # 基本信息
│ ├── ImageUpload.tsx # 图片上传
│ └── PriceInfo.tsx # 价格信息
└── ProductDetail/ # 商品详情弹窗
└── index.tsx
```
### 后端模块结构
```
erp-service/internal/product/
├── model/
│ ├── spu.go # SPU 模型
│ └── sku.go # SKU 模型
├── biz/
│ ├── spu.go # SPU 业务逻辑
│ └── sku.go # SKU 业务逻辑
├── store/
│ ├── spu.go # SPU 数据访问
│ └── sku.go # SKU 数据访问
└── handler/
└── spu_handler.go # HTTP 处理器
```
### API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/products | 商品列表 |
| GET | /api/v1/products/:id | 商品详情 |
| POST | /api/v1/products | 创建商品 |
| PUT | /api/v1/products/:id | 更新商品 |
| DELETE | /api/v1/products/:id | 删除商品 |
| PATCH | /api/v1/products/:id/status | 上架/下架 |
---
## 研发经验与开发策略
> 本章总结了酷采 3.0 开发过程中积累的研发方法论，指导 Claude Code 高效完成业务模块开发。
### 系统定位
酷采 3.0 是酷采 2.0 的**重构升级版本**，不是 1:1 复刻。核心策略：**用 2.0 的业务逻辑 + 3.0 的代码模式**。
### 两代系统架构对比
| 维度 | 酷采 2.0 (coolbuy-legacy) | 酷采 3.0 (coolbuy-paas) |
|------|--------------------------|------------------------|
| 后端 | Java Spring Boot 单体 | Go 微服务 (5 个独立服务) |
| 前端 | Vue 2 + Element UI | React 18 + Ant Design 5 + Vite |
| 数据库 | MySQL + MyBatis | PostgreSQL + GORM |
| 认证 | Shiro | JWT + Redis 黑名单 |
| 多租户 | company_id 字段 | 原生 SaaS tenant 隔离 |
| 权限 | 多表关联 RBAC | 权限引擎 + 数据权限 |
### 业务模块完成度
| 业务模块 | 2.0 页面 | 3.0 后端 | 3.0 前端 | 优先级 |
|----------|---------|---------|---------|--------|
| 系统管理 (用户/角色/权限/组织) | 9 页 | 95% | 95% | - 已完成 |
| 商品管理 (SPU/SKU/分类/品牌) | 18 页 | 90% | 85% | P1 补齐 |
| 订单管理 (销售/采购/退货/审批) | 22 页 | 85% | 70% | **P0** |
| 仓储管理 (入库/出库/库存/物流) | 6 页 | 70% | 50% | P0 |
| 客户管理 (等级/销售员/供应商) | 17 页 | 60% | 50% | P0 |
| 财务结算 (账户/流水/结算单) | 3 页 | 40% | 30% | P1 |
| 报备授权 (项目/渠道/审核) | 20+ 页 | 20% | 10% | P2 评估 |
| 分销网络 (3.0 新增) | 无 | 75% | 75% | P1 |
| 购物车 & 商城 (web-mall) | 无 | 80% | 80% | P1 |
### 三层工作流 (需求 → 代码)
```
第一层: 需求 → PRD (/req-prd skill)
输入: 2.0 对应页面 + 业务规则描述
输出: PRD 文档 + 原型 HTML (dev-plans/prototypes/)
工具: /req create → /req doc
第二层: PRD → 开发计划 (/req-dev skill)
输入: PRD + 当前 3.0 代码库分析
输出: 文件级开发任务拆分
工具: /req doc → ai-proj tasks
第三层: 任务 → 代码 (/dev-coding skill)
输入: 开发计划 + 参考模块代码
输出: 可运行的前后端代码
工具: Claude Code 直接编码
```
### 模块复制模式 (核心开发方法)
每个新业务模块参照已有成熟模块的代码模式生成：
```
参考模块 (User) 目标模块 (Order)
──────────────────── ────────────────────
api/types.ts (追加接口) → OrderQueryParams, Order, OrderItem...
api/order.ts (新建) → getOrderList, getOrderById, createOrder...
pages/OrderList.tsx → 统计卡片 + 搜索表单 + 工具栏 + 表格
pages/OrderDetail.tsx → 头部信息 + 多 Tab (基本信息/明细/日志)
pages/OrderForm.tsx → Modal 表单 (新增/编辑)
router/tenantRoutes.tsx → 追加路由注册
```
**关键约定**（必须遵循）：
- API 字段使用 `snake_case` (如 `order_status`, `created_at`)
- 响应数据解包：`res.data?.data || res.data`（双层嵌套兼容）
- 分页参数：`{ current, pageSize }` → 后端映射为 `{ page, page_size }`
- 时间格式化：`dayjs(v).format('YYYY-MM-DD HH:mm:ss')`
- 枚举渲染：`<Tag color={colorMap[value]}>{labelMap[value]}</Tag>`
- 表格滚动：`scroll={{ x: 列宽总和 }}`
- 权限控制：`<Permission permission="module:resource:action">` 包裹按钮
### 单模块开发 SOP
| 步骤 | 产出 | 预估时间 |
|------|------|---------|
| 1. 类型定义 | `types.ts` 追加接口/枚举 | 10 min |
| 2. API 层 | `api/xxx.ts` (CRUD + 业务接口) | 10 min |
| 3. 列表页 | `XxxList.tsx` (搜索+表格+工具栏+统计) | 20 min |
| 4. 详情页 | `XxxDetail.tsx` (多 Tab 信息展示) | 20 min |
| 5. 表单页 | `XxxForm.tsx` (新增/编辑 Modal) | 15 min |
| 6. 路由注册 | `tenantRoutes.tsx` 追加 lazy import | 5 min |
| 7. 联调修复 | 对接实际 API 后的字段/格式调整 | 30 min |
**单模块总计约 2 小时**，相比纯手写 2-3 天。
### 参考 2.0 代码的方法
开发新模块时，Claude 应按以下顺序获取业务知识：
```bash
# 1. 读 2.0 前端路由 → 了解页面结构和导航
~/workspace/coolbuy-paas/coolbuy-legacy/ln_admin/src/router/<module>_routers.js
# 2. 读 2.0 前端页面 → 了解字段、搜索条件、操作按钮
~/workspace/coolbuy-paas/coolbuy-legacy/ln_admin/src/views/module/<module>/
# 3. 读 2.0 后端 Manager → 了解业务规则和校验逻辑
~/workspace/coolbuy-paas/coolbuy-legacy/cool_belle/module-provider/src/main/java/com/jzg/module/manager/<module>/
# 4. 读 2.0 数据模型 → 了解表结构和字段
~/workspace/coolbuy-paas/coolbuy-legacy/cool_belle/module-provider/src/main/java/com/jzg/module/dao/model/<module>/
# 5. 读 3.0 已有参考模块 → 了解代码模式
~/coding/qiudl/coolbuy-paas/web/src/modules/foundation/pages/User/
~/coding/qiudl/coolbuy-paas/erp-service/internal/<module>/
```
### 联调经验总结
以下是已验证的联调常见问题和修复模式：
| 问题 | 原因 | 修复模式 |
|------|------|---------|
| 表格空数据 | API 响应格式 `{list,total}` vs `data[]` | `const d = res.data?.data \|\| res.data; setList(d?.list \|\| d)` |
| 按钮不显示 | Permission 组件依赖 `hasPermission()` | 确保 `isSuperAdmin()` 包含 `admin` 角色 |
| 时间显示原始 ISO | 缺少 dayjs 格式化 | 统一用 `formatTime()` helper |
| 统计接口 404 | 后端未部署 | `catch {}` 静默处理，不弹错误 |
| "加载更多"覆盖数据 | setState 替换而非追加 | 加 `append` 参数：`prev => append ? [...prev, ...newList] : newList` |
| TreeSelect undefined | 组织树数据映射缺字段 | 确保 `convertTreeData` 映射 `title/value/key` |
| TS 类型不匹配 | API 返回结构与类型定义不一致 | 用 `: any` 断言，后续补齐类型 |
| antd deprecated | v5.26 废弃 API | `bordered={false}` → `variant="borderless"` |
### 分阶段推进计划
**Phase 1 — 核心交易闭环** (决定系统可用性)
- 订单管理：后端 handler 已有 507 行，前端 20 页面待联调
- 客户管理：基础 CRUD + 客户等级 + 销售员体系
- 仓储管理：入库/出库/库存查询
**Phase 2 — 商品完善 + 财务**
- 商品模块补齐：组合方案、现货加标、生效时间管理
- 财务结算：账户管理、流水查询、结算单
**Phase 3 — 运营支撑**
- 报备/授权模块（评估后选择性迁移，2.0 有 20+ 页面）
- 报表/数据分析
- 小程序/H5 商城增强
### 2.0 订单模块业务知识 (已梳理)
#### 订单状态机
```
创建 → 待支付(01) → 已支付(02) → 已发货(03) → 已收货(04) → 已完成(10)
↘ 已取消(05) ↘ 已退款(08)
待审核(06) 已关闭(07)
待出库(11)
```
#### 支付方式
| 代码 | 方式 | 业务规则 |
|------|------|---------|
| 01 | 预存款 | 扣减预付账户余额，记 BizFundLog |
| 02 | 授信 | 扣减信用额度，需审核 |
| 11 | 银行转账 | 自动生成付款单(MallPay)+收款单(MallReceive) |
| 13 | 货到付款 | 无需预付 |
#### 退款类型
| 类型 | 说明 | 校验规则 |
|------|------|---------|
| 整单退(01) | 全额退款 | 同一用户/订单只能有一个待处理退款 |
| 按数量退(02) | 部分数量退 | 检查可退数量 |
| 按物品退(03) | 指定商品退 | 逐项检查 |
| 退运费(04) | 仅退运费 | 运费大于 0 |
#### 用户角色与操作权限
| userType | 身份 | 可执行操作 |
|----------|------|-----------|
| 01 | 平台管理员 | 直接取消、审核、改价、所有操作 |
| 02 | 供应商 | 申请退款、查看、发货 |
| 03 | 客户 | 申请退款、查看、收货确认 |
| 04 | 前端用户 | 下单、查看、基础操作 |
### 3.0 订单模块现状 (已梳理)
#### 后端 API (erp-service)
```
GET /api/v1/orders # 列表 (支持 OrderNo/Status/Date/Amount 筛选)
GET /api/v1/orders/:id # 详情 (含 items)
POST /api/v1/orders # 创建 (含采购权限/区域/MOQ 校验)
PUT /api/v1/orders/:id # 更新 (仅草稿)
DELETE /api/v1/orders/:id # 删除 (仅草稿)
POST /api/v1/orders/:id/submit-approval # 提交审批
POST /api/v1/orders/:id/approve # 审批通过/拒绝
POST /api/v1/orders/:id/confirm-payment # 确认付款
POST /api/v1/orders/:id/ship # 发货
POST /api/v1/orders/:id/confirm-delivery # 确认收货
POST /api/v1/orders/:id/complete # 完成
POST /api/v1/orders/:id/cancel # 取消
POST /api/v1/orders/:id/refund # 退款
GET /api/v1/orders/:id/status-logs # 状态变更日志
GET /api/v1/orders/:id/approval-history # 审批历史
GET /api/v1/orders/statistics/* # 统计 (6 个子接口)
```
#### 3.0 订单状态 (14 态，比 2.0 更细)
```
Draft(10) → PendingApproval(20) → Approved(29) → PendingPayment(30) → Paid(39)
→ PendingShipment(40) → PartialShipped(45) → Shipped(49)
→ PartialDelivered(55) → Delivered(59) → Completed(90)
→ Rejected(92) / Cancelled(95) / Refunded(97)
```
#### 前端已有页面 (20 个)
```
/order/sales - SalesOrderList
/order/sales/add - SalesOrderForm
/order/business - BusinessOrderList
/order/purchase - PurchaseOrderList
/order/purchase/add - PurchaseOrderForm
/order/purchase/:id - PurchaseOrderDetail
/order/pending-approval - PendingApprovalList
/order/return - ReturnOrderList
/order/return/create - CreateReturnOrder
/order/return/:id - ReturnOrderDetail
/order/statistics - PurchaseOrderStatistics
/checkout - CheckoutPage
```
---
## 相关技能
- `coolbuy-platform` - 平台管理端开发
- `coolbuy-legacy` - 酷采 2.0 测试与参考
- `dev-coding` - 软件编码开发
- `dev-arch` - 软件架构设计
- `dev-test` - 软件测试
- `req-prd` - 产品需求文档编写
- `req-dev` - 需求开发计划编写
- `siyuan` - 思源笔记（含酷采相关文档）
---
## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 1.4.0 | 2026-02-25 | 新增研发经验与开发策略章节：两代系统对比、模块完成度、三层工作流、模块复制模式、联调经验、订单模块业务梳理 |
| 1.3.0 | 2026-02-14 | 新增数据库管理工具章节：TablePlus 安装配置、自动配置脚本、连接验证、安全提示 |
| 1.2.0 | 2026-02-14 | 新增 web-mall 独立商城模块（架构、页面、代理、部署端口） |
| 1.1.0 | 2026-02-13 | 新增 AI Chat 代码路径、认证链路、关键文件说明；记录 aiChatApi vs aiChatService 陷阱 |
| 1.0.0 | 2026-01-10 | 初始版本，添加酷采2.0测试环境和浏览器自动化指南 |

8
skills-projects/coolbuy-platform-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "coolbuy-platform-plugin",
"description": "Coolbuy SaaS 平台管理端开发与部署。用于平台端前后端开发、租户管理、部署发布、翻译检查等任务。",
"version": "1.0.9",
"author": {
"name": "qiudl"
}
}

338
skills-projects/coolbuy-platform-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,338 @@
---
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` - 租户端系统（待创建）

8
skills-projects/enjoysa-deploy-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "enjoysa-deploy-plugin",
"description": "EnjoySA 项目部署到新加坡服务器",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

113
skills-projects/enjoysa-deploy-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,113 @@
# EnjoySA 部署技能
## 触发条件
当用户提到以下内容时自动激活：
- enjoysa 部署
- 部署到新加坡
- deploy enjoysa
---
## 项目信息
| 项目 | 值 |
|------|-----|
| 本地路径 | `/Users/donglinlai/coding/qiudl/enjoysa` |
| Git 仓库 | `https://gitea.pipexerp.com/qiudl/enjoysa.git` |
| 主分支 | main |
---
## 服务器信息
| 项目 | 值 |
|------|-----|
| 服务器 | singapore (43.134.28.147) |
| 用户 | ubuntu |
| SSH 密钥 | ~/.ssh/singpore.pem |
| 部署路径 | /opt/enjoysa |
| 访问地址 | http://43.134.28.147:6066 |
| Web 服务 | Nginx (端口 6066) |
---
## 快速部署
执行部署脚本：
```bash
./scripts/deploy.sh
```
---
## 手动部署步骤
### 1. 构建
```bash
cd web && npm run build
```
### 2. 上传
```bash
scp -r web/dist/* singapore:/opt/enjoysa/
```
### 3. 验证
```bash
ssh singapore "curl -s -o /dev/null -w '%{http_code}' http://localhost:6066/"
```
---
## 常用运维命令
```bash
# 查看 Nginx 状态
ssh singapore "sudo systemctl status nginx"
# 重载 Nginx 配置
ssh singapore "sudo nginx -t && sudo systemctl reload nginx"
# 查看部署目录
ssh singapore "ls -la /opt/enjoysa/"
# 查看 Nginx 访问日志
ssh singapore "sudo tail -f /var/log/nginx/access.log"
# 查看错误日志
ssh singapore "sudo tail -f /var/log/nginx/error.log"
```
---
## Nginx 配置
配置文件: `/etc/nginx/sites-available/enjoysa`
```nginx
server {
listen 6066;
listen [::]:6066;
server_name _;
root /opt/enjoysa;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
```
---
## 注意事项
1. 腾讯云安全组需开放 6066 端口
2. SPA 应用使用 `try_files` 支持前端路由
3. 静态资源设置长期缓存

8
skills-projects/enjoysa-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "enjoysa-plugin",
"description": "Plugin for enjoysa",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

210
skills-projects/enjoysa-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,210 @@
---
name: enjoysa
description: EnjoySA 畅游南澳旅游平台开发。用于前端页面开发、组件开发、i18n国际化。当用户提到 enjoysa、畅游南澳、旅游平台、供应商后台相关任务时自动激活。
---
# EnjoySA 开发技能
畅游南澳旅游平台，面向 C 端游客和 B 端供应商的在线旅游服务系统。
## 项目信息
| 项目 | 值 |
|------|-----|
| 本地路径 | `/Users/donglinlai/coding/qiudl/enjoysa` |
| Git 仓库 | `https://gitea.pipexerp.com/qiudl/enjoysa.git` |
| 主分支 | main |
| 技术栈 | Vite + React 18 + TypeScript + CSS Modules |
| 部署服务器 | singapore (43.134.28.147:6066) |
| 访问地址 | http://43.134.28.147:6066 |
---
## 架构概览
```
enjoysa/
├── web/ # React 前端
│ ├── src/
│ │ ├── components/ # 通用组件
│ │ │ ├── Common/ # Header, Footer, LanguageSwitcher
│ │ │ ├── Auth/ # LoginForm, RegisterForm
│ │ │ └── Supplier/ # SupplierLoginForm, SupplierRegisterForm
│ │ ├── pages/ # 页面组件
│ │ │ ├── LoginPage/ # C端用户登录
│ │ │ ├── SupplierLoginPage/# B端供应商登录
│ │ │ ├── AdminLoginPage/ # 平台管理员登录
│ │ │ ├── TermsPage/ # 服务条款
│ │ │ ├── PrivacyPage/ # 隐私政策
│ │ │ └── Supplier/ # 供应商后台模块
│ │ ├── i18n/ # 国际化
│ │ │ └── locales/ # 翻译文件
│ │ │ ├── zh-CN.json
│ │ │ └── en-US.json
│ │ └── types/ # 类型定义
│ ├── scripts/ # 部署脚本
│ └── dist/ # 构建产物
├── backend/ # Go 后端 (规划中)
└── docs/ # 文档
```
---
## 页面路由
### C 端 (游客)
| 路由 | 页面 | 说明 |
|------|------|------|
| `/` | HomePage | 首页 |
| `/login` | LoginPage | 用户登录/注册 |
| `/terms` | TermsPage | 服务条款 |
| `/privacy` | PrivacyPage | 隐私政策 |
### B 端 (供应商)
| 路由 | 页面 | 说明 |
|------|------|------|
| `/supplier/login` | SupplierLoginPage | 供应商登录 |
| `/supplier/register` | SupplierRegisterPage | 供应商入驻申请 |
| `/supplier` | SupplierDashboard | 供应商仪表盘 |
| `/supplier/products` | SupplierProducts | 产品管理 |
| `/supplier/orders` | SupplierOrders | 订单处理 |
| `/supplier/finance` | SupplierFinance | 财务结算 |
### 管理端
| 路由 | 页面 | 说明 |
|------|------|------|
| `/admin/login` | AdminLoginPage | 管理员登录 |
---
## i18n 国际化
### 翻译文件位置
```
web/src/i18n/locales/
├── zh-CN.json # 简体中文
└── en-US.json # 英文
```
### 命名空间规范
| 命名空间 | 用途 | 示例 |
|---------|------|------|
| `brand.*` | 品牌信息 | brand.name, brand.tagline |
| `auth.*` | 登录注册 | auth.loginTitle, auth.emailPlaceholder |
| `terms.*` | 服务条款 | terms.title, terms.sections.* |
| `privacy.*` | 隐私政策 | privacy.title, privacy.sections.* |
| `supplier.*` | 供应商模块 | supplier.login.*, supplier.dashboard.* |
| `admin.*` | 管理员模块 | admin.login.*, admin.dashboard.* |
| `common.*` | 通用文本 | common.submit, common.cancel |
| `footer.*` | 页脚 | footer.supplierEntry, footer.copyright |
### 添加新翻译步骤
1. 在 `zh-CN.json` 和 `en-US.json` 中同时添加新 key
2. 使用 `useTranslation()` hook 获取 `t` 函数
3. 使用 `t('namespace.key')` 获取翻译文本
```tsx
import { useTranslation } from 'react-i18next';
const MyComponent = () => {
const { t } = useTranslation();
return <h1>{t('brand.name')}</h1>;
};
```
### 注意事项
- **禁止硬编码中文/英文**，所有用户可见文本必须使用 i18n
- 长文本内容（如条款、政策）使用 `\n` 分段
- JSON 中避免使用中文引号 `""` `''`，使用 `「」` 或英文引号
---
## 组件规范
### Common 组件
| 组件 | 用途 | 文件 |
|------|------|------|
| Header | 顶部导航栏 | `components/Common/Header/` |
| Footer | 页脚（含供应商入口） | `components/Common/Footer/` |
| LanguageSwitcher | 语言切换器 | `components/Common/LanguageSwitcher/` |
### Auth 组件
| 组件 | 用途 | 文件 |
|------|------|------|
| LoginForm | C端登录表单 | `components/Auth/LoginForm/` |
| RegisterForm | C端注册表单 | `components/Auth/RegisterForm/` |
### Supplier 组件
| 组件 | 用途 | 文件 |
|------|------|------|
| SupplierLoginForm | 供应商登录表单 | `components/Supplier/SupplierLoginForm/` |
| SupplierRegisterForm | 供应商入驻申请表单 | `components/Supplier/SupplierRegisterForm/` |
---
## 本地开发
### 启动前端
```bash
cd /Users/donglinlai/coding/qiudl/enjoysa/web
npm install
npm run dev
```
### 构建
```bash
npm run build
```
### 部署
```bash
./scripts/deploy.sh
```
或手动部署：
```bash
scp -r web/dist/* singapore:/opt/enjoysa/
```
---
## 供应商类型
系统支持以下供应商类型：
| 类型 | 说明 |
|------|------|
| travel_agency | 旅行社 |
| hotel | 酒店 |
| attraction | 景区 |
| restaurant | 餐厅 |
| car_rental | 租车公司 |
---
## 相关技能
- `enjoysa-deploy` - 部署到新加坡服务器
- `frontend-design` - 前端界面设计
- `dev-coding` - 软件编码开发
---
## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-01-31 | 初始版本，包含项目结构、页面路由、i18n规范 |