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

将 coolbuy (3) 和 enjoysa (2) 共 5 个项目特定技能从 skills/ 移至 skills-projects/，保持通用技能与业务项目技能分离。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 11:21:53 +10:30
parent 40b36a8e41
commit ea266e9cce
14 changed files with 100 additions and 94 deletions
--- a/skills-projects/coolbuy-paas-plugin/skills/SKILL.md
+++ b/skills-projects/coolbuy-paas-plugin/skills/SKILL.md
@@ -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测试环境和浏览器自动化指南 |