# 溯源管理平台 - 后端服务（Node.js 版本）

浙江贝凡溯源管理平台的后端服务，基于 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