yunhaifinance/company-finance-system/backend

公司财务系统 - 客户管理API

项目概述

客户管理完整CRUD API，基于Express.js和PostgreSQL。实现了完整的客户管理功能，包括分页、搜索、数据验证和错误处理。

技术栈

• Node.js + Express.js
• PostgreSQL + pg客户端
• express-validator (数据验证)
• cors (跨域支持)
• dotenv (环境变量管理)

安装和运行

1. 安装依赖

cd /opt/company-finance-system/backend
npm install

2. 配置数据库

确保PostgreSQL服务正在运行，然后初始化数据库：

# 启动PostgreSQL服务（如果未运行）
sudo systemctl start postgresql

# 创建数据库和表（使用postgres用户）
sudo -u postgres psql -f init-db.sql

或者手动执行：

# 登录PostgreSQL
sudo -u postgres psql

# 在psql中执行
\i init-db.sql

3. 环境变量配置

已提供 .env 文件，包含默认配置：

DB_HOST=localhost
DB_PORT=5432
DB_NAME=company_finance_db
DB_USER=postgres
DB_PASSWORD=postgres
PORT=3000
NODE_ENV=development

4. 启动服务器

# 开发模式（使用nodemon，自动重启）
npm run dev

# 生产模式
npm start

服务器将在 http://localhost:3000 启动。

API端点列表

健康检查

• GET /health - 检查服务器状态

客户管理API

1. 获取客户列表 (分页、搜索、过滤)

   • GET /api/customers
   • 查询参数：
     • page - 页码 (默认: 1)
     • limit - 每页数量 (默认: 10, 最大: 100)
     • search - 搜索关键词 (在名称、邮箱、公司中搜索)
     • status - 状态过滤 (active/inactive)

2. 获取单个客户

   • GET /api/customers/:id
   • 路径参数：id - 客户ID

3. 创建客户

   • POST /api/customers
   • 请求体 (JSON)：

     {
       "name": "客户名称",        // 必填
       "email": "client@example.com", // 必填，有效邮箱格式
       "phone": "13800138000",    // 可选
       "address": "地址",         // 可选
       "company": "公司名称",     // 可选
       "tax_id": "税号",         // 可选
       "status": "active"        // 可选，默认: active
     }
     

4. 更新客户

   • PUT /api/customers/:id
   • 路径参数：id - 客户ID
   • 请求体：需要更新的字段（部分更新支持）

5. 删除客户

   • DELETE /api/customers/:id
   • 路径参数：id - 客户ID

6. 获取客户联系人

   • GET /api/customers/:id/contacts
   • 路径参数：id - 客户ID

数据验证和错误处理

数据验证

使用express-validator进行全面的数据验证：

1. 创建/更新客户时：

   • 名称：必填，去空格
   • 邮箱：必填，有效邮箱格式，唯一性检查
   • 状态：必须是 'active' 或 'inactive'
   • 所有字段：适当的长度和格式验证

2. 查询参数验证：

   • 页码：最小值为1
   • 每页数量：1-100之间
   • ID参数：必须是正整数

错误处理

统一的错误响应格式：

{
  "success": false,
  "message": "错误描述",
  "errors": [{"msg": "详细验证错误", "param": "字段名", "location": "body"}]
}

HTTP状态码：

• 200 - 成功
• 201 - 创建成功
• 400 - 请求参数错误/验证失败
• 404 - 资源未找到
• 409 - 资源冲突（邮箱已存在）
• 500 - 服务器内部错误

测试方法

1. 使用测试脚本（推荐）

# 确保服务器正在运行
npm run dev

# 在另一个终端运行完整测试
chmod +x test-api.sh
./test-api.sh

2. 使用curl手动测试

# 健康检查
curl http://localhost:3000/health

# 获取客户列表（分页）
curl "http://localhost:3000/api/customers?page=1&limit=5"

# 搜索客户
curl "http://localhost:3000/api/customers?search=张"

# 创建客户
curl -X POST http://localhost:3000/api/customers \
  -H "Content-Type: application/json" \
  -d '{"name":"测试客户","email":"test@example.com","phone":"12345678901"}'

# 获取单个客户
curl http://localhost:3000/api/customers/1

# 更新客户
curl -X PUT http://localhost:3000/api/customers/1 \
  -H "Content-Type: application/json" \
  -d '{"phone":"13888888888"}'

# 删除客户
curl -X DELETE http://localhost:3000/api/customers/1

# 获取客户联系人
curl http://localhost:3000/api/customers/1/contacts

3. 使用Postman

导入 postman-collection.json 文件到Postman，设置环境变量 base_url = http://localhost:3000

数据库表结构

customers表（客户表）

字段名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
name	VARCHAR(100)	NOT NULL	客户名称
email	VARCHAR(100)	UNIQUE, NOT NULL	邮箱（唯一）
phone	VARCHAR(20)		联系电话
address	TEXT		地址
company	VARCHAR(100)		公司名称
tax_id	VARCHAR(50)		税号
status	VARCHAR(20)	DEFAULT 'active'	状态：active/inactive
created_at	TIMESTAMP	DEFAULT CURRENT_TIMESTAMP	创建时间
updated_at	TIMESTAMP	DEFAULT CURRENT_TIMESTAMP	更新时间

contacts表（联系人表）

字段名	类型	约束	说明
id	SERIAL	PRIMARY KEY	自增主键
customer_id	INTEGER	REFERENCES customers(id) ON DELETE CASCADE	客户ID（外键）
name	VARCHAR(100)	NOT NULL	联系人姓名
position	VARCHAR(100)		职位
email	VARCHAR(100)		邮箱
phone	VARCHAR(20)		电话
is_primary	BOOLEAN	DEFAULT false	是否主要联系人
created_at	TIMESTAMP	DEFAULT CURRENT_TIMESTAMP	创建时间
updated_at	TIMESTAMP	DEFAULT CURRENT_TIMESTAMP	更新时间

索引

• idx_customers_email - 邮箱索引（加速查询和唯一性检查）
• idx_customers_status - 状态索引（加速状态过滤）
• idx_contacts_customer_id - 客户ID索引（加速关联查询）

示例数据

初始化脚本已包含示例数据：

• 5个示例客户（3个active，1个inactive）
• 7个示例联系人
• 包含中文数据，便于测试搜索功能

注意事项

1. 数据库连接：确保PostgreSQL服务正在运行，默认使用postgres用户
2. 环境安全：生产环境请修改默认密码，使用更安全的认证方式
3. 性能考虑：
   • 分页查询避免大数据量传输
   • 重要字段已添加索引
   • 使用连接池管理数据库连接
4. 数据完整性：
   • 邮箱唯一性约束
   • 外键约束保证数据一致性
   • 级联删除（删除客户时自动删除联系人）

故障排除

常见问题

1. 数据库连接失败

   # 检查PostgreSQL服务状态
   sudo systemctl status postgresql
   
   # 检查连接配置
   cat .env
   
   # 测试数据库连接
   sudo -u postgres psql -l
   

2. API返回500错误

   • 检查服务器控制台输出
   • 验证数据库表是否存在：sudo -u postgres psql -d company_finance_db -c "\dt"
   • 检查请求数据格式是否正确

3. 邮箱已存在错误（409）

   • 每个客户必须有唯一的邮箱地址
   • 更新操作时也要确保邮箱唯一性

4. 验证错误（400）

   • 检查请求体JSON格式
   • 确保必填字段已提供
   • 验证邮箱格式是否正确

日志查看

• 服务器启动日志：控制台输出
• 数据库错误：服务器控制台和PostgreSQL日志
• API请求日志：服务器控制台

扩展建议

1. 添加身份验证：使用JWT实现API认证
2. 添加日志系统：使用winston或morgan记录请求日志
3. 添加缓存：对频繁查询的数据添加Redis缓存
4. 添加监控：集成Prometheus监控指标
5. API文档：使用Swagger/OpenAPI生成文档

项目结构

/opt/company-finance-system/backend/
├── server-complete.js      # 主服务器文件（客户管理API）
├── db.js                   # 数据库连接配置
├── package.json           # 依赖配置
├── .env                   # 环境变量
├── .env.example          # 环境变量示例
├── init-db.sql           # 数据库初始化脚本
├── test-api.sh           # API测试脚本
├── README.md             # 项目文档
└── postman-collection.json # Postman集合

完成状态

✅ 所有要求的API端点已实现：

1. ✅ GET /api/customers - 获取客户列表（分页、搜索）
2. ✅ GET /api/customers/:id - 获取单个客户
3. ✅ POST /api/customers - 创建客户
4. ✅ PUT /api/customers/:id - 更新客户
5. ✅ DELETE /api/customers/:id - 删除客户
6. ✅ GET /api/customers/:id/contacts - 获取客户联系人

✅ 使用PostgreSQL数据库，连接现有company_finance_db ✅ 包含数据验证和错误处理 ✅ 提供完整的测试方法和文档