# aiProductAdmin

**Repository Path**: codergit.com/ai-product-admin

## Basic Information

- **Project Name**: aiProductAdmin
- **Description**: AI商品管理中心
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 商品管理中心


> 基于 Spring Boot 4 + DDD 分层架构，实现商品全生命周期管理，支持 AI 审核上架/下架、AI 生成商品图片/视频、品类与 SKU 规格管理。

[![Java 21](https://img.shields.io/badge/Java-21-blue.svg)](https://java.com)
[![Spring Boot 4.0](https://img.shields.io/badge/Spring%20Boot-4.0.8-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 目录

- [功能概览](#功能概览)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [核心设计](#核心设计)
- [API 接口一览](#api-接口一览)
- [数据库表概览](#数据库表概览)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [分支策略](#分支策略)
- [贡献指南](#贡献指南)

---

## 功能概览

| 模块 | 能力说明 |
|------|---------|
| **商品管理** | 新增、修改、查询、删除（逻辑），草稿→待审核→已上架/下架→驳回 全状态流转 |
| **品类管理** | 树形品类结构 CRUD，支持一级/二级品类 |
| **SKU 规格** | 按商品维度维护规格属性（颜色、尺寸等）及 JSON 规格值 |
| **AI 审核** | 上架/下架自动触发 AI 文本审核；AI 无法判断时转入人工审核队列 |
| **AI 生成** | 基于商品信息异步生成图片/视频，支持多模型路由与重试 |
| **素材管理** | 图片/视频上传（本地/OSS），支持主图设置、删除替换 |
| **动态配置** | Nacos 配置热刷新，模型路由规则动态下发与回滚 |

---

## 技术栈

| 层级 | 技术选型 |
|------|---------|
| 语言 | JDK 21 |
| 框架 | Spring Boot 4.0.8 + Spring Cloud 2025.1.3 |
| 服务注册/配置 | Nacos Discovery & Config |
| 持久层 | MyBatis-Plus 3.5.17（Spring Boot 4 专用 starter） |
| 缓存/队列 | Redis（Lettuce 连接池） |
| 对象存储 | 阿里云 OSS（aliyun-sdk-oss 3.18.5），一期本地磁盘，二期切换 |
| AI 能力 | 多 LLM 模型抽象层，ModelRouter 策略路由 |
| 构建工具 | Maven（多模块） |
| 测试 | Spring Boot Test + H2（集成/E2E 测试） |

---

## 项目结构

```
ai-product-admin/
├── ai-product-admin-common      # 通用基础层：统一响应体、异常、常量、PageQuery/PageResult
├── ai-product-admin-domain      # 领域层：Product/Category/Sku/AuditTask/AiTask 聚合根、
│                                #    领域服务、Repository 接口定义
├── ai-product-admin-ai          # AI 能力层：LLMProvider 接口、ModelRouter 策略路由、
│                                #    文本审核/图片生成/视频生成 Provider 抽象
├── ai-product-admin-infrastructure  # 基础设施层：MyBatis-Plus Repository 实现、
│                                #    Redis 任务队列、OSS/LocalFileStorage、
│                                #    LLM 远程适配器、DbModelRouteRuleProvider
├── ai-product-admin-application   # 应用层：用例编排、事务边界、DTO 转换
├── ai-product-admin-web           # Web 层：8 个 Controller、CurrentOperator 拦截器、
│                                #    动态配置刷新监听器
├── docs/sql/                      # Flyway 风格的 DDL 脚本（3 个版本迁移文件）
└── pom.xml                        # 父 POM：依赖统一管理、插件配置
```

### 模块依赖关系

```
web → application → domain ← infrastructure → ai
                        ↑
                   common（所有模块依赖）
```

---

## 核心设计

### 1. 领域驱动分层（DDD）

采用标准 DDD 六边形架构风格，严格依赖方向：`web → application → domain ← infrastructure`。

- **Domain 层**：纯业务逻辑，不依赖任何外部框架，定义聚合根、领域服务、Repository 接口。
- **Infrastructure 层**：实现 Domain 的 Repository 接口，接入 MyBatis-Plus、Redis、OSS 等具体技术。
- **Application 层**：用例编排，处理跨聚合的业务流程，定义事务边界。
- **Web 层**：HTTP 请求入口，DTO 转换，参数校验，不承载业务逻辑。

### 2. AI 模型路由策略

```
用户请求
  ↓
ModelRouter（策略路由）
  ├── 商品类型 = 服装 → 路由到「服装专用图片模型」
  ├── 商品类型 = 数码 → 路由到「数码专用图片模型」
  └── 默认 → 路由到「通用图片模型」
  ↓
对应 LLMProvider（远程调用 / Stub 占位）
  ↓
结果解析 → 保存至 OSS/本地 → 更新任务状态
```

- 路由规则存于 `model_route_rule` 表，通过 Nacos 动态下发，支持运行时切换模型。
- 模型调用失败自动重试，最多 2 次；仍失败则任务标记 FAILED。

### 3. 审核异步流程

```
提交上架申请
  → 创建 AuditRecord（status=PENDING）写入 Redis 队列 audit:queue:ai
  → 同步返回请求 ID

AI 审核消费者（Redis 队列消费）
  → 调用文本审核 LLMProvider
  → 通过 → product.status = ON_SHELF
  → 驳回 → product.status = REJECTED，发送站内信
  → 无法判断 → 转入人工审核队列 audit:queue:manual

人工审核队列消费者
  → 等待人工通过 / 驳回接口
  → 更新商品状态，发送站内信通知
```

### 4. 存储可切换设计

`FileStorage` 接口抽象存储后端，一期默认 `LocalFileStorage`，二期切换到 `OssFileStorage`，仅修改配置 `ai-product.oss.enabled=true` 即可切换，业务代码无需改动。

---

## API 接口一览

### 商品管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/products` | 新增商品（状态=草稿） |
| PUT | `/api/products/{id}` | 修改商品 |
| GET | `/api/products/{id}` | 商品详情 |
| GET | `/api/products` | 商品分页查询（支持多条件筛选） |
| DELETE | `/api/products/{id}` | 逻辑删除商品 |

### 品类管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/categories` | 创建品类 |
| GET | `/api/categories/tree` | 获取品类树 |
| PUT | `/api/categories/{id}` | 更新品类 |
| DELETE | `/api/categories/{id}` | 删除品类 |

### SKU 规格

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/products/{productId}/skus` | 新增 SKU 规格 |
| GET | `/api/products/{productId}/skus` | 查询商品 SKU 列表 |
| PUT | `/api/products/{productId}/skus/{skuId}` | 更新 SKU 规格 |
| DELETE | `/api/products/{productId}/skus/{skuId}` | 删除 SKU 规格 |

### 上架/下架审核

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/products/{id}/shelve` | 提交上架审核 |
| POST | `/api/products/{id}/unshelve` | 提交下架审核 |
| GET | `/api/audits` | 查询审核记录列表 |
| POST | `/api/audits/{id}/review` | 人工审核（通过/驳回） |

### AI 生成任务

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/ai-tasks` | 提交 AI 生成任务，返回 taskId |
| GET | `/api/ai-tasks/{id}` | 查询任务状态与结果地址 |
| GET | `/api/ai-tasks` | 按商品/类型/状态分页查询 |

### 文件上传

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/files/images` | 上传图片（≤10MB，jpg/png/webp） |
| POST | `/api/files/videos` | 上传视频（≤30MB，主流格式） |

### 动态配置管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/admin/dynamic-config` | 查看当前配置快照 |
| GET | `/api/admin/dynamic-config/history` | 配置变更历史 |
| POST | `/api/admin/dynamic-config/validate` | 预检配置合法性 |
| POST | `/api/admin/dynamic-config` | 下发新配置 |
| POST | `/api/admin/dynamic-config/rollback/{version}` | 回滚到指定版本 |

---

## 数据库表概览

| 表名 | 说明 | 关键字段 |
|------|------|---------|
| `product` | 商品基本信息 | product_name, category_id, status, ext_json（预留扩展） |
| `category` | 品类表（自关联树形） | parent_id, category_name, level, sort_order |
| `product_sku` | SKU 规格 | product_id, sku_code, spec_json, price/stock（预留） |
| `audit_record` | 审核记录 | product_id, request_id（幂等）, audit_type, audit_method, audit_status, audit_result |
| `ai_task` | AI 生成任务 | product_id, task_type, model_code（路由后回填）, status, result_urls |
| `model_route_rule` | 模型路由规则 | category_id/product_type, capability_type, model_code |

> 完整 DDL 见 [`docs/sql/V1.0.0__init_schema.sql`](docs/sql/V1.0.0__init_schema.sql)。  
> 外键由应用层保证，无物理外键约束。

---

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Redis 6.0+
- Nacos 2.x（可选，本地开发默认 127.0.0.1:8848）

### 本地启动

```bash
# 1. 初始化数据库
mysql -u root -p < docs/sql/V1.0.0__init_schema.sql

# 2. 配置环境变量（或修改 application-dev.yml）
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_DATABASE=ai_product_admin
export MYSQL_USERNAME=root
export MYSQL_PASSWORD=your_password
export REDIS_HOST=127.0.0.1
export REDIS_PORT=6379

# 3. 构建并启动
mvn clean package -DskipTests
cd ai-product-admin-web
java -jar target/ai-product-admin-web-1.0.0-SNAPSHOT.jar --spring.profiles.active=dev

# 服务默认运行在 http://localhost:8080
```

### 运行测试

```bash
# 全量测试（含 H2 内存库 E2E 测试）
mvn test

# 仅运行单元测试
mvn test -pl ai-product-admin-ai,ai-product-admin-common,ai-product-admin-infrastructure
```

---

## 配置说明

### 关键环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `SERVER_PORT` | 8080 | 服务端口 |
| `MYSQL_HOST` | 127.0.0.1 | MySQL 地址 |
| `MYSQL_DATABASE` | ai_product_admin | 数据库名 |
| `REDIS_HOST` | 127.0.0.1 | Redis 地址 |
| `NACOS_SERVER_ADDR` | 127.0.0.1:8848 | Nacos 地址 |
| `OSS_ENABLED` | false | 是否启用 OSS（false 使用本地存储） |
| `OSS_ENDPOINT` | — | OSS Endpoint |
| `OSS_BUCKET_NAME` | — | OSS Bucket 名称 |

> OSS 凭证必须通过环境变量或 Nacos 配置注入，禁止硬编码在源码中。  
> `OSS_ENABLED=false` 时应用正常启动，文件存储走本地磁盘。

### 多环境 Profile

| Profile | 文件 | 说明 |
|---------|------|------|
| `dev` | `application-dev.yml` | 本地开发，H2 + 本地文件存储 |
| `test` | `application-test.yml` | 测试环境 |
| `feature` | `application-feature.yml` | 功能开关（所有环境加载） |
| `prod` | `application-prod.yml` | 生产环境（Nacos + OSS） |

---

## 分支策略

```
main                ← 主干（稳定可发布）
├── feature/100087-ai-product-admin  ← 本期需求开发分支
├── feature/<需求编号>-<简名>        ← 其他功能分支
└── release/<版本号>                 ← 发布分支
```

开发流程：从 `main` 拉取最新代码 → 创建 `feature/*` 分支 → 提交 MR → 合并回 `main`。

---

## 贡献指南

1. Fork 本仓库
2. 新建 `feature/<需求编号>-<功能名>` 分支
3. 遵循 Commit 规范（`feat:` / `fix:` / `refactor:` / `docs:` 等）
4. 提交代码并推送
5. 新建 Pull Request，附上变更说明

---

## 相关文档

- [技术方案](dev-context/context.md) — 完整技术方案与领域模型设计
- [SQL 脚本](docs/sql/) — DDL 初始化与回滚脚本
- [PRD](dev-context/context.md) — 产品需求文档

---

**Copyright © 2024–2026 TianHua. All rights reserved.**