ai-proj-helper/skills-projects/coolbuy-paas-plugin/skills/SKILL.md

---
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测试环境和浏览器自动化指南 |