supplied-service

供应商业务后端，为 supplied-h5、supplied-admin 和 zhgh 平台对接提供接口。当前 HTTP 入口为 src/server.ts，默认端口为 8888。

技术栈

Koa、TypeScript：HTTP 服务与业务逻辑。
Prisma、MySQL：数据库访问与模型定义。
Redis：平台桥接 Token 缓存。
MinIO：文件对象存储。
Node.js crypto：管理端密码哈希与随机登录 Token。

目录结构

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。

接口入口

路径	用途
`/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 条，服务重启后清空。

5.9 KiB Raw Blame History Unescape Escape