个人发卡网系统（React 版）补充说明

你已经了解了该系统的核心信息、技术栈和基础使用流程，下面为你补充一些实用细节、常见问题排查和二次开发建议，帮助你更好地部署和使用该系统：

一、 部署细节补充（重点解决路由问题）

该系统基于 React Router 实现前端路由，构建后为静态文件，容易出现「刷新 404」「路由跳转失效」问题，补充对应解决方案：

1. Nginx 服务器配置（必看）

如果使用 Nginx 部署，需在nginx.conf或对应站点配置中添加try_files规则，示例完整配置：

server {
    listen 80;
    server_name your-domain.com; # 你的域名（或服务器IP）
    root /usr/share/nginx/html; # dist目录上传后的路径
    index index.html index.php; # 优先加载index.html

    # 解决React Router前端路由刷新404问题
    location / {
        try_files $uri $uri/ /index.html; # 关键规则：找不到文件时默认返回index.html
        expires -1; # 禁止缓存前端路由相关文件
    }

    # 支持PHP（用于路由兼容，无需额外PHP业务代码）
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

配置完成后，重启 Nginx：nginx -s reload。

2. 无需 PHP 的替代方案

如果你的服务器不支持 PHP，可直接删除项目中的.htaccess和index.php文件，仅保留dist目录下的静态资源（html/css/js/assets），只要配置了上述 Nginx 规则（或 Apache 的RewriteRule），即可正常运行（PHP 仅为兼容传统虚拟主机路由，无核心业务依赖）。

3. 部署注意事项

• 上传dist目录文件时，确保完整上传所有文件和子目录（尤其是assets文件夹和index.html），避免资源加载失败。
• 服务器根目录建议单独分配给该系统，避免与其他项目文件冲突。
• 若需使用 HTTPS 部署，只需在 Nginx 配置中添加 SSL 证书相关配置，try_files规则保持不变。

二、 localStorage 数据相关注意事项

该系统使用localStorage存储所有数据，你需要重点了解其局限性和数据安全技巧：

1. 核心局限性（务必知晓）

• 数据仅存储在当前浏览器的本地，换浏览器、清理浏览器缓存、更换设备后，数据会丢失（仅能通过「数据导出」功能备份恢复）。
• localStorage有存储大小限制（约 5MB），不适合存储大量卡密（建议单商品卡密数量不超过 1000 条，总订单数不超过 5000 条）。
• 数据未加密存储，在浏览器开发者工具（Application -> Local Storage）中可直接查看，请勿存储敏感信息（如真实收款账户密码）。

2. 数据备份与恢复技巧

• 主动备份：定期在「系统设置」中执行「数据导出」，导出的 JSON 文件请妥善保存（建议本地 + 云盘双重备份）。
• 手动备份：若无法通过系统导出（如页面异常），可在浏览器开发者工具中，找到对应域名的localStorage，手动复制所有键值对，粘贴到本地 JSON 文件中备用。
• 恢复数据：系统默认无「一键导入」功能，二次开发时可添加导入逻辑，或手动通过开发者工具将备份数据写入localStorage。

三、 常见问题排查

1. 安装依赖失败（pnpm install 报错）
   • 排查：确保 Node.js 版本≥16（推荐 18+），pnpm 已全局安装（npm install -g pnpm）。
   • 解决：清理 pnpm 缓存（pnpm store prune），重新执行pnpm install，若仍失败，可切换 npm 安装（npm install）。
2. 开发环境启动后（pnpm dev），页面空白无内容
   • 排查：Vite 端口被占用，或 TypeScript 类型校验失败。
   • 解决：查看终端报错信息，修复 TypeScript 语法错误；更换启动端口（pnpm dev --port 3001）。
3. 管理员登录后，无法添加卡密 / 修改密码
   • 排查：浏览器禁用了localStorage，或页面存在缓存冲突。
   • 解决：开启浏览器的「本地存储」权限，清理浏览器缓存后刷新页面，重新登录。
4. 明暗主题切换失效
   • 排查：浏览器本地存储中theme字段丢失，或 Tailwind CSS 主题配置未生效。
   • 解决：刷新页面重新触发主题初始化，二次开发时可添加主题字段默认值兜底（如默认亮色主题）。

四、 二次开发建议

如果你需要进行二次开发（如扩展功能、对接后端数据库），以下方向可供参考：

1. 优先扩展的核心功能

• 增加「数据导入」功能：对接导出的 JSON 格式，实现一键恢复数据，解决localStorage数据迁移问题。
• 卡密加密存储：对localStorage中的卡密、管理员密码进行加密（如使用crypto-js），提高数据安全性。
• 对接真实后端：放弃localStorage，使用「React + Express/Koa（Node.js）+ MySQL/MongoDB」搭建后端，实现数据持久化和多设备同步。

2. 技术扩展要点

• 项目结构：Vite+React+TS 项目的核心结构在src目录下，pages存放页面组件，components存放公共组件，utils存放工具函数（如localStorage操作、数据导出），router配置路由。
• 主题切换扩展：当前主题基于 Tailwind CSS 的darkMode: 'class'实现，可在src/utils/theme.ts中扩展自定义主题色。
• 邮件功能落地：默认为模拟发送，可集成nodemailer（后端）或emailjs（前端无后端），配置真实邮箱服务器（如 QQ 邮箱、163 邮箱），实现卡密自动发送。

3. 注意事项

• 二次开发时，保持 TypeScript 类型校验严格（避免any类型滥用），减少后续维护问题。
• 扩展功能时，尽量遵循原项目的代码风格和目录结构，提高代码可维护性。
• 若用于非个人场景，需注意合规性（如电商资质、支付合规等），本系统仅为学习用途。

五、 最后提醒

1. 该系统仅适合个人学习、小型自用（如少量卡密销售），不适合高并发、大规模商业场景。
2. 收款码上传后，建议定期更换，避免收款账户信息泄露。
3. 若发现系统 BUG（如订单统计异常、卡密状态更新失效），可优先排查localStorage中的数据格式是否正常，再检查对应组件的逻辑处理。