points-mall/supplied-service

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