LinHelp/README.md

# LinHelp 邻小帮

LinHelp（邻小帮）是一个社区生活服务 MVP 项目，覆盖居民端、商家/平台管理端、骑手端与后端 API。当前仓库包含一期实现所需的本地开发环境、核心业务接口、前端页面、小程序页面和测试用例。

## 功能范围

- 居民端微信小程序：商品浏览与下单、团购、快递代取下单、二手信息发布、公告查看、地址管理、个人中心。
- 管理后台：数据看板、商品管理、订单管理、团购管理、快递订单管理、配送调度、二手审核、公告管理。
- 骑手 H5：任务列表、任务详情、送达确认、异常上报、收入汇总。
- 后端服务：登录鉴权、租户上下文、商品/订单/团购/快递/配送/二手/公告/反馈等业务接口。
- 本地支撑：MySQL、Redis、MinIO、Flyway 数据库迁移、Knife4j 接口文档、无数据库 demo profile。

## 技术栈

- 后端：Java 8、Spring Boot 2.7.18、MyBatis Plus、Sa-Token、MySQL、Redis、Flyway、Knife4j、MinIO。
- 管理后台：Vue 3、TypeScript、Vite、Element Plus、Pinia、Vue Router、Vitest。
- 骑手 H5：Vue 3、TypeScript、Vite、Pinia、Vue Router、Vitest。
- 居民端小程序：微信原生小程序、WXML、WXSS、JavaScript、Jest。
- 开发依赖：Docker Desktop、Maven、Node.js 18+、微信开发者工具。

## 目录结构

```text
LinHelp
├── backend/      # Spring Boot 后端服务
├── admin-web/    # 管理后台 Web
├── rider-h5/     # 骑手 H5
├── miniapp/      # 居民端微信小程序
├── deploy/       # 本地依赖编排
└── docs/         # 产品设计、实施计划、部署与测试文档
```

## 本地启动

### 1. 启动基础依赖

```powershell
docker compose -f deploy/docker-compose.dev.yml up -d
```

默认依赖地址：

```text
MySQL: localhost:3306
Redis: localhost:6379
MinIO API: http://localhost:9000
MinIO 控制台: http://localhost:9001
```

默认数据库和对象存储账号请查看 `deploy/docker-compose.dev.yml`。

### 2. 启动后端

```powershell
cd backend
mvn spring-boot:run
```

服务地址：

```text
后端 API: http://localhost:8080
Knife4j 文档: http://localhost:8080/doc.html
```

后端默认启用 `dev` profile，会连接本地 MySQL、Redis 和 MinIO，并通过 Flyway 执行 `backend/src/main/resources/db/migration` 下的迁移脚本。

### 3. 启动管理后台

```powershell
cd admin-web
npm install
npm run dev
```

访问地址：

```text
http://localhost:5173
```

开发模式下 `/api` 默认代理到 `http://localhost:8080`。如果后端使用其他端口，可以设置：

```powershell
$env:VITE_API_PROXY_TARGET="http://localhost:18080"
npm run dev
```

### 4. 启动骑手 H5

```powershell
cd rider-h5
npm install
npm run dev
```

访问地址：

```text
http://localhost:5174
```

骑手 H5 与管理后台一样使用 `/api` 代理后端接口。

### 5. 打开微信小程序

使用微信开发者工具打开：

```text
miniapp/project.config.json
```

小程序请求基础地址在 `miniapp/miniprogram/utils/request.js` 中配置。

## 无数据库演示模式

如果本地没有 Docker/MySQL，或 `8080` 端口被占用，可以启动 demo profile：

```powershell
cd backend
mvn spring-boot:run "-Dspring-boot.run.profiles=demo"
```

演示服务地址：

```text
http://localhost:18080
```

demo profile 不依赖 MySQL，会在内存中初始化商品、公告、团购、团购配送单、二手信息、商品配送任务和快递代取任务等演示数据。

演示账号：

```text
管理员: admin / admin123
商家: merchant / merchant123
骑手: rider / rider123
居民: 本地开发小程序登录
```

## 测试与构建

后端测试：

```powershell
cd backend
mvn test
```

管理后台：

```powershell
cd admin-web
npm test
npm run build
```

骑手 H5：

```powershell
cd rider-h5
npm test
npm run build
```

微信小程序：

```powershell
cd miniapp
npm test
```

## 常用地址

| 应用 | 地址 |
| --- | --- |
| 后端 API | `http://localhost:8080` |
| Demo API | `http://localhost:18080` |
| Knife4j 文档 | `http://localhost:8080/doc.html` |
| 管理后台 | `http://localhost:5173` |
| 骑手 H5 | `http://localhost:5174` |
| MinIO 控制台 | `http://localhost:9001` |

## 参考文档

- `docs/superpowers/specs/2026-07-07-linxiaobang-prd-design.md`
- `docs/superpowers/plans/2026-07-07-linxiaobang-phase-one-implementation.md`
- `docs/api/manual-test-checklist.md`
- `docs/deploy/local-runbook.md`