# agri-trace-platform

**Repository Path**: panarea/agri-trace-platform

## Basic Information

- **Project Name**: agri-trace-platform
- **Description**: 基于 Spring Boot 3 + Vue 3 的智慧农产品溯源管理平台，实现农产品从生产、加工、运输、入库到销售的全生命周期追踪与管理。系统支持批次管理、溯源时间轴查询、异常监控、统计分析、权限控制等功能，并通过状态模式、模板方法模式、观察者模式、单例模式等设计模式实现核心业务逻辑。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧农产品溯源管理平台

英文名：**smart-agri-trace-system**

轻量级企业供应链溯源后台系统，记录农产品从生产到销售的完整流转过程，支持批次溯源、状态流转、异常监控与数据可视化。

**课程：** 云南大学软件学院 · 软件设计模式（2026 春季）  
**期末报告（定稿）：** [`docs/软件设计模式期末报告 (6).md`](docs/软件设计模式期末报告%20(6).md)

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Java 21、Spring Boot 3、Spring Security、JWT、Spring Data JPA、MySQL、Maven |
| 前端 | Vue3、TypeScript、Vite、Element Plus、Pinia、Axios、ECharts |
| 工程化 | Git、Docker Compose |

## 设计模式

六种设计模式均参与业务实现，答辩核心围绕**批次状态流转**。

| 模式 | 应用场景 | 核心类 |
|------|----------|--------|
| 状态模式 | 批次生命周期流转 | `designpattern/state/*` |
| 单例模式 | 批次号生成（Spring Singleton Bean + UNIQUE 兜底） | `BatchCodeGenerator` |
| 模板方法 | 校验 → 更新状态 → 保存 trace → 后置通知 | `AbstractTransitionHandler` |
| 工厂模式 | 集中创建溯源记录 | `TraceRecordFactory` |
| 观察者模式 | 异常标记后写入通知 | `AbnormalEventPublisher` → `NotificationObserver` |
| 代理模式（AOP） | 操作日志横切（`BatchService` 使用 CGLIB 代理） | `@OperationLog` + `OperationLogAspect` |

详见 [`docs/design-patterns.md`](docs/design-patterns.md)。

**单元测试：** 4 个测试类、14 个测试用例（状态 / 单例 / 工厂 / 模板方法）；观察者、代理通过集成运行验证。

## 快速启动

### 1. 启动 MySQL

```bash
docker compose up -d
```

### 2. 启动后端

```bash
cd backend
# Windows
.\mvnw.cmd spring-boot:run
# Linux / macOS
# ./mvnw spring-boot:run
```

后端地址：`http://localhost:8080`

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端地址：`http://localhost:5173`

## 默认账号

密码均为 `password`（`sql/data.sql` 中 BCrypt 入库）。

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | password | 管理员 |
| producer1 | password | 生产商 |
| transporter1 | password | 运输商 |
| seller1 | password | 销售商 |

## 批次状态流转

```
已生产(PRODUCED) → 已加工(PROCESSED) → 运输中(IN_TRANSIT) → 已入库(IN_STOCK) → 已销售(SOLD)
```

任意非终态可经独立接口标记为 **异常(ABNORMAL)**（不经过状态模式的 `transitionTo`）。

## Demo 演示批次

空库启动后 `DataInitializer` 自动初始化：

| 批次号 | 说明 |
|--------|------|
| `B20260520001` | 苹果，完整 5 步正常链（答辩首选） |
| `B20260522001` | 牛奶，完整正常链 |
| `B20260524001` | 茶叶，异常链 + 观察者通知 |

详见 [`docs/demo-data.md`](docs/demo-data.md)。

## 答辩演示路径（约 8～12 分钟）

| 步骤 | 要点 |
|------|------|
| 1 | `admin/password` 登录，切换角色看菜单差异 |
| 2 | 统计看板 KPI 与图表 |
| 3 | 创建批次（单例 + 工厂） |
| 4 | 状态流转（状态模式 + 模板方法） |
| 5 | 溯源 `B20260520001` |
| 6 | 异常批次 / 异常记录（观察者） |
| 7 | 操作日志（代理模式 AOP） |
| 8 | 口述六种模式与 14 条单测 |
| 0′（可选） | 登录页 → `/public` → 查 `B20260520001`（消费者公开溯源，只读） |

完整说明见期末报告 **6.4.2** 或 [`docs/答辩PPT文字大纲.md`](docs/答辩PPT文字大纲.md)。

## 项目结构

```
agri-trace-platform/
├── sql/                 # 数据库脚本
├── docs/                # 项目文档
├── docker-compose.yml
├── backend/             # Spring Boot 后端
└── frontend/            # Vue3 前端
```

文档索引见 [`docs/project-overview.md`](docs/project-overview.md)。

## API 概览

| 接口 | 说明 |
|------|------|
| POST `/api/auth/login` | 登录 |
| GET `/api/batches` | 批次列表 |
| POST `/api/batches` | 创建批次 |
| POST `/api/batches/transition` | 状态流转 |
| POST `/api/batches/abnormal` | 标记异常 |
| GET `/api/batches/trace/{batchCode}` | 溯源时间轴 |
| GET `/api/public/products` | 消费者公开：全部产品 + 最近批次摘要（免登录） |
| GET `/api/public/batches/recent` | 消费者公开：最近批次列表（免登录） |
| GET `/api/public/batches/code/{batchCode}` | 消费者公开：批次摘要（免登录） |
| GET `/api/public/batches/trace/{batchCode}` | 消费者公开：溯源时间轴（免登录） |
| GET `/api/dashboard` | 统计看板 |
| GET `/api/notifications` | 异常通知列表 |
| GET `/api/operation-logs` | 操作日志列表（ADMIN） |

完整接口见 [`docs/api-design.md`](docs/api-design.md)。

> **开发提示：** 修改后端 Java 后需重启 Spring Boot。详见 [`docs/current-project-status.md`](docs/current-project-status.md) 第七节。

## 运行测试

```bash
cd backend
# Windows
.\mvnw.cmd test
# Linux / macOS
# ./mvnw test
```

预期：4 测试类、14 用例全部通过。

## 项目状态

- P0 / P1 / UI Polish：✅ 全部完成
- P2-1 消费者公开溯源：✅ 已完成；P2 其余（Swagger、详情抽屉等）：未做（可选）
- 期末报告：✅ 定稿 [`docs/软件设计模式期末报告 (6).md`](docs/软件设计模式期末报告%20(6).md)

详情见 [`docs/current-project-status.md`](docs/current-project-status.md)。