# 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 条，服务重启后清空。