feat: 积分商城-供应商-对账-发票3

supplied-service/README.md

@@ -1,61 +1,126 @@
 # supplied-service
 
-Netlify Functions backend for the supplied mall H5 project.
+供应商业务后端，为 supplied-h5、supplied-admin 和 zhgh 平台对接提供接口。当前 HTTP 入口为 `src/server.ts`，默认端口为 `8888`。
 
-## Stack
+## 技术栈
 
-- Netlify Functions
-- TypeScript
-- Prisma ORM
-- Neon Postgres
-- `@prisma/adapter-neon` + `@neondatabase/serverless`
+- Koa、TypeScript：HTTP 服务与业务逻辑。
+- Prisma、MySQL：数据库访问与模型定义。
+- Redis：平台桥接 Token 缓存。
+- MinIO：文件对象存储。
+- Node.js crypto：管理端密码哈希与随机登录 Token。
 
-## Directory
+## 目录结构
 
 ```text
-netlify/
-  functions/        # API entrypoints
-  utils/            # shared function utilities
-  types/            # shared API types
+src/
+  server.ts              # Koa 入口、路由分发、管理端登录校验
+  controllers/           # 请求解析与响应封装
+  services/              # 业务逻辑
+  dao/                   # 数据访问
+  functions/             # 导出各接口处理器
+  utils/                 # 数据库、日志、平台桥接等工具
+  types/                 # 公共类型
 prisma/
-  schema.prisma     # Prisma models
+  schema.prisma          # 数据模型与表映射
+  sql/                   # 专项表结构脚本
+  script/supplier_db.sql # 数据库结构及开发数据快照
+  init-supplied-user.mjs # 管理账号初始化与旧表处理
+tools/                   # 发票等辅助工具
 ```
 
-## Environment
+`src/functions` 保留接口处理器导出，当前本地服务由 Koa 的 `/api` 路由分发。
 
-Copy `.env.example` to `.env` and set:
+## 环境配置
 
-- `DATABASE_URL`: Neon Postgres connection string for Netlify Functions runtime and Prisma CLI
-- `JWT_SECRET`: auth signing secret
-- `UPLOAD_TOKEN`: upload guard token
-- `POINTS_MALL_OPEN_API_BASE`: main platform bridge base URL, for example `http://localhost/open`
+配置文件为本目录 `.env`，可参考 `.env.example`。数据库及存储服务的账号信息不在本文重复列出。
 
-Supplier H5 uses `VUE_APP_SUPPLIER_IDENTIFICATION` to request supplier config from this service. The supplier `clientSecret` stays in the database and is only used by the Netlify Function when requesting the platform bridge token.
+| 配置项 | 用途 |
+| --- | --- |
+| `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` |
 
-## Scripts
+`.env.example` 中的 `JWT_SECRET`、`UPLOAD_TOKEN` 不参与当前管理端登录校验；管理端采用数据库保存 Token 哈希的会话机制。
 
-```bash
-npm run dev
-npm run build
-npm run typecheck
-npm run prisma:generate
-npm run prisma:migrate
-npm run prisma:studio
-```
+H5 通过供应商标识获取配置。供应商 `clientSecret` 保存在后端数据库中，用于请求平台桥接 Token，与管理端登录密码、登录 Token 分开处理。
 
-## Function Routes
+## 已有脚本说明
 
-Netlify exposes functions under `/.netlify/functions/<name>`.
+以下列出 `package.json` 中已有脚本的用途。
 
-Current placeholders:
+| 脚本名 | 用途 |
+| --- | --- |
+| `dev`、`start` | 通过 tsx 运行 Koa 服务 |
+| `build`、`prisma:generate` | 生成 Prisma Client；`build` 不生成后端应用打包产物 |
+| `typecheck` | TypeScript 静态类型检查 |
+| `prisma:migrate` | Prisma 开发迁移 |
+| `prisma:studio` | Prisma 数据查看界面 |
+| `seed:products` | 商品初始化数据脚本 |
 
-- `login`
-- `product-list`
-- `product-detail`
-- `cart-add`
-- `order-create`
-- `order-pay`
-- `user-info`
-- `upload`
-- `supplier-info`
-- `supplier-token`
+## 管理账号与表结构
+
+| 表名 | 用途 |
+| --- | --- |
+| `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 条，服务重启后清空。