161 lines
4.3 KiB
Markdown
161 lines
4.3 KiB
Markdown
# 溯源管理平台 - 后端服务
|
||
|
||
浙江贝凡溯源管理平台的后端服务，基于 NestJS + TypeScript + SQLite。
|
||
|
||
## 技术栈
|
||
|
||
- **NestJS**: 渐进式 Node.js 框架
|
||
- **TypeScript**: 类型安全
|
||
- **Prisma**: 现代化 ORM（使用 better-sqlite3 适配器）
|
||
- **SQLite**: 轻量级数据库
|
||
- **better-sqlite3**: 高性能 SQLite 驱动
|
||
- **@nestjs/jwt**: JWT 身份认证
|
||
- **bcryptjs**: 密码加密
|
||
- **Zod**: 运行时类型验证
|
||
- **nestjs-zod**: NestJS 与 Zod 集成
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
backend/
|
||
├── src/
|
||
│ ├── auth/ # 认证模块
|
||
│ │ ├── auth.controller.ts
|
||
│ │ ├── auth.guard.ts
|
||
│ │ ├── auth.module.ts
|
||
│ │ ├── auth.service.ts
|
||
│ │ └── dto/
|
||
│ ├── companies/ # 企业模块
|
||
│ │ ├── companies.controller.ts
|
||
│ │ ├── companies.module.ts
|
||
│ │ └── companies.service.ts
|
||
│ ├── database/ # 数据库模块
|
||
│ │ ├── database.module.ts
|
||
│ │ └── database.service.ts
|
||
│ ├── serials/ # 序列号模块
|
||
│ │ ├── serials.controller.ts
|
||
│ │ ├── serials.module.ts
|
||
│ │ ├── serials.service.ts
|
||
│ │ └── dto/
|
||
│ ├── types/ # 类型定义
|
||
│ │ └── index.d.ts
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── app.module.ts # 根模块
|
||
│ ├── health.controller.ts
|
||
│ └── main.ts # 应用入口
|
||
├── data/ # 数据文件
|
||
├── scripts/ # 脚本
|
||
├── .env # 环境变量
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── README.md
|
||
```
|
||
|
||
## 安装
|
||
|
||
1. 安装依赖：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
2. 配置环境变量：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. 编辑 `.env` 文件，设置你的配置（特别是 `JWT_SECRET`）
|
||
|
||
## 开发
|
||
|
||
启动开发服务器（支持热重载）：
|
||
|
||
```bash
|
||
pnpm start:dev
|
||
```
|
||
|
||
服务器将在 http://localhost:3000 运行
|
||
|
||
## 构建
|
||
|
||
构建 TypeScript 为 JavaScript：
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
## 生产
|
||
|
||
启动生产服务器：
|
||
|
||
```bash
|
||
pnpm start:prod
|
||
```
|
||
|
||
## 数据库初始化
|
||
|
||
初始化数据库和默认管理员账户：
|
||
|
||
```bash
|
||
pnpm init-db
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
创建 `.env` 文件（参考 `.env.example`）：
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
| ------------------- | ------------------------ | ----------------------------- |
|
||
| `PORT` | 服务器端口 | `3000` |
|
||
| `JWT_SECRET` | JWT 签名密钥（必须修改） | - |
|
||
| `DATABASE_URL` | SQLite 数据库文件路径 | `file:./data/database.sqlite` |
|
||
| `MAX_REQUEST_SIZE` | 最大请求体大小 | `10mb` |
|
||
| `VITE_API_BASE_URL` | API 基础路径 | `/api` |
|
||
|
||
**安全提示**：在生产环境中，请务必设置一个强随机字符串作为 `JWT_SECRET`。可以使用以下命令生成：
|
||
|
||
```bash
|
||
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
||
```
|
||
|
||
## 默认账户
|
||
|
||
初始化后默认创建的管理员账户：
|
||
|
||
- 用户名: admin
|
||
- 密码: Beifan@2026
|
||
|
||
## API 接口
|
||
|
||
### 认证接口
|
||
|
||
- `POST /api/auth/login` - 用户登录
|
||
- `GET /api/auth/profile` - 获取用户信息
|
||
- `POST /api/auth/change-password` - 修改密码
|
||
- `PUT /api/auth/profile` - 更新用户资料
|
||
|
||
### 序列号接口
|
||
|
||
- `POST /api/serials/generate` - 生成序列号
|
||
- `POST /api/serials/generate-with-prefix` - 使用自定义前缀生成序列号
|
||
- `POST /api/serials/:serialNumber/qrcode` - 生成二维码
|
||
- `GET /api/serials/:serialNumber/query` - 查询序列号
|
||
- `GET /api/serials/` - 获取序列号列表
|
||
- `PATCH /api/serials/:serialNumber` - 更新序列号
|
||
- `POST /api/serials/:serialNumber/revoke` - 吊销序列号
|
||
|
||
### 企业接口
|
||
|
||
- `GET /api/companies/` - 获取企业列表
|
||
- `GET /api/companies/:companyName` - 获取企业详情
|
||
- `PATCH /api/companies/:companyName` - 更新企业信息
|
||
- `DELETE /api/companies/:companyName` - 删除企业
|
||
- `DELETE /api/companies/:companyName/serials/:serialNumber` - 删除企业下的序列号
|
||
- `POST /api/companies/:companyName/revoke` - 吊销企业
|
||
- `GET /api/companies/stats/overview` - 获取统计数据
|
||
|
||
## License
|
||
|
||
MIT
|