127 lines
5.9 KiB
Markdown
127 lines
5.9 KiB
Markdown
# supplied-service
|
||
|
||
供应商业务后端，为 supplied-h5、supplied-admin 和 zhgh 平台对接提供接口。当前 HTTP 入口为 `src/server.ts`，默认端口为 `8888`。
|
||
|
||
## 技术栈
|
||
|
||
- Koa、TypeScript：HTTP 服务与业务逻辑。
|
||
- Prisma、MySQL：数据库访问与模型定义。
|
||
- Redis：平台桥接 Token 缓存。
|
||
- MinIO：文件对象存储。
|
||
- Node.js crypto：管理端密码哈希与随机登录 Token。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/
|
||
server.ts # Koa 入口、路由分发、管理端登录校验
|
||
controllers/ # 请求解析与响应封装
|
||
services/ # 业务逻辑
|
||
dao/ # 数据访问
|
||
functions/ # 导出各接口处理器
|
||
utils/ # 数据库、日志、平台桥接等工具
|
||
types/ # 公共类型
|
||
prisma/
|
||
schema.prisma # 数据模型与表映射
|
||
sql/ # 专项表结构脚本
|
||
script/supplier_db.sql # 数据库结构及开发数据快照
|
||
init-supplied-user.mjs # 管理账号初始化与旧表处理
|
||
tools/ # 发票等辅助工具
|
||
```
|
||
|
||
`src/functions` 保留接口处理器导出，当前本地服务由 Koa 的 `/api` 路由分发。
|
||
|
||
## 环境配置
|
||
|
||
配置文件为本目录 `.env`，可参考 `.env.example`。数据库及存储服务的账号信息不在本文重复列出。
|
||
|
||
| 配置项 | 用途 |
|
||
| --- | --- |
|
||
| `DATABASE_URL` | MySQL 连接地址 |
|
||
| `PORT` | Koa 服务端口，默认 `8888` |
|
||
| `PRISMA_CLIENT_ENGINE_TYPE` | Prisma 引擎设置，示例为 `binary` |
|
||
| `POINTS_MALL_OPEN_API_BASE` | zhgh 平台接口根地址，例如 `http://localhost/open` |
|
||
| `SUPPLIER_OPEN_SM4_KEY_HEX`、`SUPPLIER_OPEN_SM4_IV_HEX` | 供应商开放接口 SM4 配置 |
|
||
| `REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`、`REDIS_DB` | 平台 Token 缓存连接配置 |
|
||
| `MINIO_ENDPOINT`、`MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY` | MinIO 地址与访问凭据 |
|
||
| `MINIO_BUCKET`、`MINIO_REGION` | 存储桶与区域；本项目配置示例使用 `njupt` |
|
||
|
||
`.env.example` 中的 `JWT_SECRET`、`UPLOAD_TOKEN` 不参与当前管理端登录校验；管理端采用数据库保存 Token 哈希的会话机制。
|
||
|
||
H5 通过供应商标识获取配置。供应商 `clientSecret` 保存在后端数据库中，用于请求平台桥接 Token，与管理端登录密码、登录 Token 分开处理。
|
||
|
||
## 已有脚本说明
|
||
|
||
以下列出 `package.json` 中已有脚本的用途。
|
||
|
||
| 脚本名 | 用途 |
|
||
| --- | --- |
|
||
| `dev`、`start` | 通过 tsx 运行 Koa 服务 |
|
||
| `build`、`prisma:generate` | 生成 Prisma Client；`build` 不生成后端应用打包产物 |
|
||
| `typecheck` | TypeScript 静态类型检查 |
|
||
| `prisma:migrate` | Prisma 开发迁移 |
|
||
| `prisma:studio` | Prisma 数据查看界面 |
|
||
| `seed:products` | 商品初始化数据脚本 |
|
||
|
||
## 管理账号与表结构
|
||
|
||
| 表名 | 用途 |
|
||
| --- | --- |
|
||
| `supplied_user` | 管理端账号、密码哈希、会话及失败登录状态 |
|
||
| `supplied_cart_item` | 购物车条目，Prisma 模型为 `CartItem` |
|
||
|
||
管理端密码使用随机盐和 scrypt 哈希，格式为 `scrypt$盐$哈希`。登录时校验密码后签发随机 Token，数据库仅保存 Token 的 SHA-256 哈希及有效期。
|
||
|
||
- 会话有效期：8 小时，同一账号仅保留最新一次登录。
|
||
- 连续输错密码：启用账号累计 5 次后锁定 15 分钟。
|
||
- 退出登录：清除当前 Token 哈希与有效期。
|
||
- 登录请求密码不会写入供应商调试日志。
|
||
- 购物车 `userId` 仍为业务用户 ID，不关联 `supplied_user` 中的管理员。
|
||
|
||
### 账号初始化脚本
|
||
|
||
`prisma/init-supplied-user.mjs` 读取本目录 `.env`，创建账号表并插入管理账号：
|
||
|
||
- `SUPPLIED_ADMIN_USERNAME`：初始化账号，默认 `admin`。
|
||
- `SUPPLIED_ADMIN_PASSWORD`：初始化密码；未指定时随机生成，长度要求为 12–128 位。
|
||
- 账号创建成功后输出账号和密码，已存在账号不会覆盖密码。
|
||
- 可将旧 `cartitem` 重命名为 `supplied_cart_item`；新旧表同时存在时停止，避免覆盖数据。
|
||
- 旧 `user` 表有数据时停止；为空时移除。表结构处理发生在账号是否已存在的判断之前。
|
||
- 此脚本不会创建缺失的购物车表，也不处理曾使用过的 `supplied_cartitem` 名称。
|
||
|
||
当前开发账号见 [项目 README](../README.md#管理端登录)。
|
||
|
||
## 接口入口
|
||
|
||
| 路径 | 用途 |
|
||
| --- | --- |
|
||
| `/api/:name` | H5 及通用业务接口 |
|
||
| `/api/admin/:name` | 管理端入口，除 `login` 外校验 Bearer Token |
|
||
| `/supplierOpenApi/pointOrder/*` | zhgh 调用的供应商开放接口 |
|
||
| `/api/supplier-logs` | 查询或清除当前进程保存的调试日志 |
|
||
|
||
### 管理端登录接口
|
||
|
||
| 方法 | 路径 | 请求内容 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/admin/login` | JSON：`username`、`password` |
|
||
| POST | `/api/admin/admin-session` | Bearer Token，返回用户信息及过期时间 |
|
||
| POST | `/api/admin/admin-logout` | Bearer Token，使当前登录失效 |
|
||
|
||
登录成功返回 `data.token`、`data.expiresAt` 和 `data.user`。管理端后续请求通过 `Authorization: Bearer <token>` 携带凭据。
|
||
|
||
### 业务接口分组
|
||
|
||
- 商品：`product-list`、`product-detail`、`merchant-product-*`。
|
||
- 订单：`order-create`、`order-pay`、`order-list`、`order-detail`、取消及事件推送接口。
|
||
- 商家处理：`merchant-order-*`、`merchant-after-sale-*`。
|
||
- 对账：`merchant-reconciliation-*`、`supplier-reconciliation-*`。
|
||
- 发票：`supplier-invoice-apply`、`supplier-invoice-info`、`supplier-file-base64-info`。
|
||
- 平台授权：`supplier-info`、`supplier-session`、`supplier-token`。
|
||
|
||
完整路由以 `src/server.ts` 为准。`cart-add`、`user-info` 仍为占位实现。
|
||
|
||
## 调试日志
|
||
|
||
`GET /api/supplier-logs` 返回当前后端接收请求、向 zhgh 发送请求、接收 zhgh 请求的记录；`DELETE /api/supplier-logs` 清除记录。日志保存在进程内存中，最多保留 200 条，服务重启后清空。
|