本文介绍发卡平台系统安装搭建：先准备Node.js和pnpm，克隆代码并执行`pnpm install`安装依赖；系统基于localStorage存储，支持本地开发、静态构建和Nginx部署。平台包含商品浏览、自助下单、订单查询、公告展示及后台商品、订单、内容、邮箱、管理员配置，首次登录需修改默认密码并关注数据安全。

# 发卡平台系统安装搭建指南

## 环境准备

在安装本系统之前，请确保您的服务器或本地环境已经安装了以下软件：

1. **Node.js** (v16.0.0或更高版本)
– 可以通过 [Node.js官网](https://nodejs.org/) 下载安装
– 安装完成后，可以通过以下命令验证安装是否成功：
“`bash
node -v
“`

2. **pnpm** 包管理器
– 可以通过以下命令安装：
“`bash
npm install -g pnpm
“`
– 安装完成后，可以通过以下命令验证安装是否成功：
“`bash
pnpm -v
“`

## 安装步骤

### 1. 克隆项目代码

首先，将项目代码克隆到您的本地或服务器上：

“`bash
git clone [项目仓库地址]
cd [项目目录名]
“`

### 2. 安装项目依赖

进入项目目录后，执行以下命令安装项目依赖：

“`bash
pnpm install
“`

这个过程可能需要一些时间，具体取决于您的网络速度。

### 3. 配置项目

本项目使用本地存储(localStorage)来保存数据，不需要额外的数据库配置。系统默认已经配置了基本的商品分类、公告内容等初始数据。

## 开发环境运行

如果您需要在本地进行开发或调试，可以使用以下命令启动开发服务器：

“`bash
pnpm dev
“`

开发服务器启动后，您可以通过浏览器访问 `http://localhost:3000` 来查看项目运行效果。

开发模式下，代码修改后会自动热重载，方便您进行开发和调试。

## 生产环境构建

当您完成开发或准备部署到生产环境时，可以执行以下命令构建生产版本：

“`bash
pnpm build
“`

构建完成后，项目会在 `dist/static` 目录下生成优化后的静态文件，可以直接部署到Web服务器上。

## 部署指南

### Nginx部署示例

以下是使用Nginx部署本项目的简单配置示例：

1. 将构建后的 `dist/static` 目录下的所有文件复制到Nginx的Web根目录（如 `/usr/share/nginx/html`）

2. 编辑Nginx配置文件（如 `/etc/nginx/conf.d/default.conf`），添加以下配置：

“`nginx
server {
listen 80;
server_name your_domain.com;  # 替换为您的域名或IP地址

root /usr/share/nginx/html;  # 静态文件所在目录
index index.html;

location / {
try_files $uri $uri/ /index.html;  # 处理单页应用路由
}

# 可选：添加gzip压缩
gzip on;
gzip_types text/plain text/css application/javascript application/json;
}
“`

3. 重启Nginx服务：

“`bash
nginx -s reload
“`

现在，您应该可以通过浏览器访问您的域名或IP地址来使用系统了。

## 项目结构说明

项目的主要结构如下：

“`
├── src/                # 源代码目录
│   ├── components/     # 公共组件
│   ├── contexts/       # React Context，用于状态管理
│   ├── hooks/          # 自定义React Hooks
│   ├── lib/            # 工具函数
│   ├── pages/          # 页面组件
│   │   ├── Home.tsx    # 首页
│   │   ├── SelfOrderingPage.tsx # 自助下单页面
│   │   └── AdminPage.tsx # 后台管理页面
│   ├── App.tsx         # 应用入口组件
│   ├── index.css       # 全局样式
│   └── main.tsx        # 程序入口文件
├── index.html          # HTML模板文件
├── package.json        # 项目依赖和脚本配置
├── tailwind.config.js  # Tailwind CSS配置
└── vite.config.ts      # Vite配置
“`

## 主要功能

1. **前台功能**：
– 商品浏览和搜索
– 自助下单
– 订单查询和卡密获取
– 滚动公告展示

2. **后台管理**：
– 商品分类和商品管理
– 订单管理和卡密分配
– 前台内容配置（标题、按钮文字、收款码等）
– 邮箱配置（用于发送卡密邮件）
– 管理员账号安全设置

## 管理员登录

系统默认的管理员账号信息：

– 用户名：admin
– 密码：admin123

首次登录后，建议立即修改管理员账号和密码以保证系统安全。

## 常见问题解决

1. **依赖安装失败**：
– 检查网络连接
– 确保pnpm版本正确
– 尝试删除 `node_modules` 目录和 `pnpm-lock.yaml` 文件后重新安装

2. **构建失败**：
– 检查是否有语法错误
– 确保所有依赖都已正确安装

3. **部署后页面刷新404**：
– 确保Nginx配置中包含了单页应用路由处理（try_files配置）
– 其他Web服务器请参考相应的单页应用部署指南

## 注意事项

1. 本系统使用localStorage存储数据，数据仅保存在浏览器本地。如果需要更可靠的数据存储方案，建议对接后端数据库。

2. 邮箱发送功能目前为模拟实现，实际使用时需要配置正确的SMTP服务器信息。

3. 收款码上传后仅保存在浏览器本地，刷新页面后不会丢失，但如果清除浏览器缓存，数据将会丢失。

4. 请妥善保管管理员账号和密码，避免未授权访问。