电子礼簿系统

软件测试

电子礼簿系统(参考来源：https://github.com/jingguanzhang/gift-book/)

一款开源、免费的 Web 应用，旨在为各类红白喜事（如婚庆、寿宴、白事等）提供一个现代化、安全、高效的礼金（份子钱）管理解决方案。它彻底告别了传统的手写礼簿，通过数字化的方式解决了记录、统计、查询和存档的全部流程，同时以数据安全和用户隐私为最高设计原则。

版本更新：

更新内容，第一版在测试时，把服务器地址和数据库写了硬编码。导致很多人下载下来直接就能用，没有部署自己的服务，数据也写到我的数据库了，这是重大事故，现在更新了。以后下载后必须要先部署和启动自己的服务以及数据库才能用。

根据github上面的 jingguanzhang     的版本修改，主要修改：

1、数据从IndexedDB 改为mysql 使数据更持久，不至于清理缓存导致记账数据被清理。

2、增加了移动端的查看功能，充分考虑打工人，在外地务工的人员，给家里非至亲好友还礼，人不到场请人带人情的情况可以随时查看，账本不会随时带着。

## 核心优势

- **🥇 数据安全与可靠性**

  - ​**MySQL 数据库存储**：所有数据存储在 MySQL 数据库中，确保数据的安全性和持久性。

  - ​**加密存储**：所有礼金记录均通过您为事项设定的管理密码进行 AES 加密。

  - ​**隐私至上**：您的所有数据，从事项名称到每一笔礼金，都只属于您自己。

- **📚 现代化的事件管理**

  - ​**多事项支持**：可同时创建和管理多个不同的事项，并通过密码安全地切换。

  - ​**个性化主题**：内置“喜庆红”与“肃穆灰”两套界面风格，一键适应不同场合的氛围需求。

  - ​**封面定制**：支持为每个事项上传专属的横向封面图。在打印或导出 PDF 时，该封面将作为精美的首页，提升整体的正式感和仪式感。

- **✒️ 高效的礼金录入**

  - ​**智能防重**：系统会在您录入时自动检测同名或同名同金额的记录，并发出醒目提示，有效避免重复录入的错误。

  - ​**大写转换**：金额输入后，系统将自动生成符合财务规范的中文大写金额。

  - ​**语音播报**：开启后，每成功录入一笔礼金，系统会自动语音播报“xxx 贺礼/奠仪 xxx 元”，方便现场核对，增添现场气氛。

  - ​**超时补录**：即使超出了设定的事项时间，也可通过管理密码进行补录，确保数据完整性。

- **📊 强大的数据处理功能**

  - ​**即时统计**：主界面实时显示总金额、总人数及当前页小计，账目一目了然。

  - ​**多维度查询**：支持按姓名快速检索礼金记录，支持模糊搜索。

  - ​**专业报表导出**：一键将所有礼金明细导出为标准的 Excel (**.xlsx**) 文件，方便进行二次处理或长期存档。

  - ​**精美电子礼薄PDF生成与打印**：

    - **自动生成适合A4纸横向打印的精美礼簿页面。**

    - **若设置了封面，将自动添加为打印文档的第一页。**

    - **所有带备注的记录会自动整理成附录，附加在礼簿末尾，让主账簿保持整洁。**

  - ​**深度统计视图**：提供一个包含所有礼金详情的交互式数据表格，支持即时搜索、排序和筛选，让数据分析变得前所未有的简单。

- **📱 移动端适配**

  - **响应式设计**：支持在手机、平板等移动设备上使用。移动端仅有查询功能，需要修改和记账请在PC端打开系统。

  - **移动端查询页面**：专门为移动设备优化的查询页面，方便随时随地查看礼金记录。

  - **自动设备检测**：系统会自动检测用户设备类型，移动端访问时自动跳转到查询页面，无需手动切换。

## 适用场景

**本系统适用于所有需要记录礼金或馈赠的场合，包括但不限于：**

- **婚嫁喜宴**

- **新生儿满月酒、百日宴**

- **寿星大寿庆典**

- **乔迁新居之喜**

- **升学宴、谢师宴**

- **白事吊唁**

- **开业庆典、宗族活动等**

## 技术栈

- **前端**：HTML5, JavaScript (ES6+)

- **样式**：Tailwind CSS

- **后端**：Node.js, Express

- **数据库**：MySQL

- **核心库**：

  - **CryptoJS**: 用于数据的 AES 加密。

  - **SheetJS (xlsx)**: 用于生成和导出 Excel 文件。

  - **Grid.js**: 用于构建功能强大的统计数据表格。

## 部署指南

### 环境要求

- **Node.js** (v14.0.0 或更高版本)

- **MySQL** (5.7 或更高版本)

### 部署步骤

1. **获取项目文件**

   - 下载项目压缩包并解压，或克隆项目仓库。

2. **安装依赖**

   - 进入项目目录，运行以下命令：

     ```bash

     npm install

     ```

3. **配置数据库**

   - 启动 MySQL 服务。

   - 在项目首次运行时，系统会自动创建数据库和表结构。

   - 访问系统后，在数据库配置页面填写数据库连接信息：

     - 主机：MySQL 服务器地址（默认：localhost）

     - 端口：MySQL 端口（默认：3306）

     - 用户名：MySQL 用户名（默认：root）

     - 密码：MySQL 密码

     - 数据库名：要使用的数据库名称（默认：gift\_book）

   - 点击“测试连接”按钮验证连接是否成功。

   - 点击“保存配置”按钮保存数据库配置。

4. **启动服务**

   - 方法一：直接运行

     ```bash

     node server.js

     ```

   - 方法二：使用启动脚本

     ```bash

     ./start.sh

     ```

5. **访问系统**

   - 打开浏览器，访问：<http://localhost:3000>

   - 移动端查询页面：<http://localhost:3000/query.html>

### 环境变量配置

为了提高安全性，项目支持使用环境变量来配置敏感信息。您可以在项目根目录创建 `.env` 文件，并添加以下配置：

```env

# 服务器配置

PORT=3000

CORS_ORIGIN=*

# 数据库配置

DB_HOST=localhost

DB_PORT=3306

DB_USER=root

DB_PASSWORD=your_database_password

DB_DATABASE=gift_book

```

**环境变量说明**：

- `PORT`：服务器监听端口，默认 3000

- `CORS_ORIGIN`：CORS 来源限制，默认 `*`（允许所有来源）

- `DB_HOST`：MySQL 服务器地址

- `DB_PORT`：MySQL 端口

- `DB_USER`：MySQL 用户名

- `DB_PASSWORD`：MySQL 密码

- `DB_DATABASE`：要使用的数据库名称

**优先级**：环境变量 > `db-config.json` 文件 > 默认值

### 注意事项

- **端口占用**：如果端口 3000 已被占用，启动脚本会自动停止占用该端口的进程。

- **数据库配置**：数据库配置会保存在项目目录下的 `db-config.json` 文件中，环境变量会覆盖配置文件中的对应值。

- **数据备份**：建议定期备份 MySQL 数据库，以防止数据丢失。

- **安全建议**：在生产环境中，建议使用环境变量存储敏感信息，并限制 CORS_ORIGIN 为特定域名。

## 操作指南

### API地址配置

1. 打开应用后，默认使用 http://localhost:3000 作为API地址

2. 点击页面顶部的设置按钮（齿轮图标）

3. 在弹出的对话框中输入后端服务的API地址

4. 点击"保存"按钮，配置会被保存到本地存储

5. 刷新页面后，新的API地址会生效

### 创建事项

1. 访问系统首页：http://localhost:3000

2. 点击“创建新事项”按钮。

3. 填写事项名称、设定管理密码。

4. 在“更多设置”中，根据需要选择界面风格，并上传一张横向的图片作为封面（可选）。

5. 点击“创建并进入”按钮。

### 录入礼金

1. 在主界面左侧的表单中，依次填写来宾姓名、金额、收款方式和备注。

2. 点击“确认录入”按钮。

3. 系统会自动检测重复记录，并在录入成功后语音播报（如果开启）。

### 查询礼金

1. 访问移动端查询页面：http://localhost:3000/query.html

2. 选择一个事项并加载礼金记录。

3. 在搜索框中输入姓名进行模糊搜索。

4. 浏览礼金记录，查看统计信息。

### 管理与导出

1. 使用主界面右侧的功能按钮进行查找、打印、导出 Excel 或查看详细统计。

2. 点击主界面左上角的标题，可以方便地切换到其他事项或返回创建页面。

移动端仅查看

通过网盘分享的知识：

链接: https://pan.baidu.com/s/5zbG6fun_Dcc-qRPJsuSzPg? 复制这段内容后打开百度网盘手机App，操作更方便哦

沐雨57

这类内容应该多一些，对新手很友好。

远山笔记

看完挺有收获的，之前一直没搞明白这块。

言默说事

这个话题最近讨论得挺多，但像这样讲清楚的少。有遇到类似情况的吗？想听听别人的做法。

半盏不眠

这个案例很有代表性，能说明不少问题。

浅夏小筑

这个话题最近讨论得挺多，但像这样讲清楚的少。（补充第15点）

隔壁老王煮酒

楼主说得挺实在，比那些空谈概念的强。

林间寒山

信息量挺足的，看了一遍还想再看一遍。想请教下有没有推荐的上手路径？

一苇

感谢整理，这类总结省了别人很多时间。

有点困

楼主说得挺实在，比那些空谈概念的强。期待后续的补充。