backend-node/README.md

溯源管理平台 - 后端服务

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

pnpm install

2. 配置环境变量：

cp .env.example .env

3. 编辑 .env 文件，设置你的配置（特别是 JWT_SECRET）

开发

启动开发服务器（支持热重载）：

pnpm start:dev

服务器将在 http://localhost:3000 运行

构建

构建 TypeScript 为 JavaScript：

pnpm build

生产

启动生产服务器：

pnpm start:prod

数据库初始化

初始化数据库和默认管理员账户：

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。可以使用以下命令生成：

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