# Planting Service 文档中心

## 概述

Planting Service 是 RWA Durian Queen 平台的核心微服务，负责处理榴莲树认种业务的完整生命周期。

### 核心功能

- **认种订单管理** - 创建、支付、取消订单
- **省市选择机制** - 5秒确认机制防止误操作
- **资金分配** - 10种目标的精确分配（2199 USDT/棵）
- **持仓管理** - 用户认种持仓统计与追踪
- **资金池注入** - 5天批次管理机制

### 技术栈

| 技术 | 版本 | 用途 |
|-----|------|------|
| NestJS | 10.x | Web 框架 |
| TypeScript | 5.x | 开发语言 |
| PostgreSQL | 16 | 数据库 |
| Prisma | 5.x | ORM |
| Jest | 29.x | 测试框架 |
| Docker | 24.x | 容器化 |

---

## 文档索引

| 文档 | 描述 | 适用人员 |
|-----|------|---------|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | 系统架构设计 | 架构师、技术负责人 |
| [API.md](./API.md) | API 接口文档 | 前端开发、测试 |
| [DEVELOPMENT.md](./DEVELOPMENT.md) | 开发指南 | 后端开发 |
| [TESTING.md](./TESTING.md) | 测试文档 | 开发、测试 |
| [DEPLOYMENT.md](./DEPLOYMENT.md) | 部署文档 | DevOps、运维 |

---

## 快速开始

### 1. 环境准备

```bash
# 要求
Node.js >= 20.x
PostgreSQL >= 16
Docker >= 24.x (可选)
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置环境

```bash
cp .env.example .env
# 编辑 .env 文件配置数据库等
```

### 4. 初始化数据库

```bash
npx prisma generate
npx prisma migrate dev
```

### 5. 启动服务

```bash
# 开发模式
npm run start:dev

# 生产模式
npm run build
npm run start:prod
```

### 6. 访问服务

- 服务地址: http://localhost:3003
- API 文档: http://localhost:3003/api/docs
- 健康检查: http://localhost:3003/api/v1/health

---

## 常用命令

```bash
# 开发
make dev              # 启动开发服务器
make build            # 构建项目

# 测试
make test-unit        # 单元测试
make test-integration # 集成测试
make test-e2e         # E2E 测试
make test-cov         # 覆盖率测试
make test-all         # 所有测试

# 数据库
make prisma-generate  # 生成 Prisma Client
make prisma-migrate   # 运行迁移
make prisma-studio    # 打开 Prisma Studio

# Docker
make docker-build     # 构建镜像
make docker-up        # 启动容器
make test-docker-all  # Docker 测试

# 代码质量
make lint             # 代码检查
make format           # 代码格式化
```

---

## 项目结构

```
planting-service/
├── docs/                    # 文档目录
│   ├── README.md           # 文档索引
│   ├── ARCHITECTURE.md     # 架构文档
│   ├── API.md              # API 文档
│   ├── DEVELOPMENT.md      # 开发指南
│   ├── TESTING.md          # 测试文档
│   └── DEPLOYMENT.md       # 部署文档
├── prisma/                  # 数据库
│   ├── schema.prisma       # 模型定义
│   └── migrations/         # 迁移文件
├── src/                     # 源代码
│   ├── api/                # API 层
│   ├── application/        # 应用层
│   ├── domain/             # 领域层
│   ├── infrastructure/     # 基础设施层
│   └── main.ts             # 入口
├── test/                    # E2E 测试
├── docker-compose.yml       # Docker 编排
├── Dockerfile              # 生产镜像
└── Makefile                # 构建脚本
```

---

## 业务规则概览

### 定价

- 单价: **2199 USDT/棵**
- 单次限制: 1-1000 棵
- 个人限制: 最多 1000 棵

### 资金分配

| 目标 | 比例 | 金额 (USDT) |
|-----|------|------------|
| 资金池 | 90% | 1979.1 |
| 运营 | 5% | 109.95 |
| 省代 | 0.6% | 13.194 |
| 市代 | 0.3% | 6.597 |
| 社区长 | 0.5% | 10.995 |
| 一级推荐 | 1.5% | 32.985 |
| 二级推荐 | 1.0% | 21.99 |
| 三级推荐 | 0.5% | 10.995 |
| 平台 | 0.3% | 6.597 |
| 储备 | 0.3% | 6.597 |

### 订单状态流转

```
CREATED → PROVINCE_CITY_SELECTED → PROVINCE_CITY_CONFIRMED
        → PAID → FUND_ALLOCATED → POOL_SCHEDULED
        → POOL_INJECTED → MINING_ENABLED

任意状态(PAID前) → CANCELLED
```

---

## 测试报告

### 测试概览

| 类型 | 数量 | 状态 |
|-----|------|-----|
| 单元测试 | 45+ | ✅ 通过 |
| 集成测试 | 12+ | ✅ 通过 |
| E2E 测试 | 17+ | ✅ 通过 |

### 覆盖率

| 模块 | 覆盖率 |
|-----|-------|
| 应用服务 | 89% |
| 领域服务 | 93% |
| 聚合根 | 69% |

---

## 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 提交规范

使用 [Conventional Commits](https://www.conventionalcommits.org/):

- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `test`: 测试
- `refactor`: 重构

---

## 相关链接

- [NestJS 文档](https://docs.nestjs.com/)
- [Prisma 文档](https://www.prisma.io/docs/)
- [TypeScript 文档](https://www.typescriptlang.org/docs/)

---

## 联系方式

如有问题或建议，请通过以下方式联系:

- 项目 Issues
- 技术负责人邮箱