238 lines
5.4 KiB
Markdown
238 lines
5.4 KiB
Markdown
# 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
|
||
- 技术负责人邮箱
|