Skip to content

N
nlt-pufa-interface
Commit 7664aa00 by 蔡杰
Options

feat: 添加项目文档和生产部署配置 

- 新增完整的项目文档体系
  - 业务设计文档（保费支付逻辑、预授信机制）
  - API集成指南（SM2加密、接口调用说明）
  - 部署运维指南（Docker容器化部署）
  - 文档索引README

- 完善生产环境部署配置
  - Makefile：自动化构建和部署脚本
  - deploy.sh：生产部署脚本（支持备份回滚）
  - docker-compose.prod.yml：生产环境Docker配置
  - 交叉编译支持（macOS开发，Linux生产）

- 规范项目配置
  - .gitignore：忽略编译文件和临时文件
  - .dockerignore：优化Docker构建
  - README.md：项目主页文档
parent b7f3d90d
Showing with 781 additions and 0 deletions
.dockerignore 0 → 100644
# Git
.git
.gitignore
# Documentation
*.md
docs/
# Environment files
.env
.env.local
.env.*.local
# Logs
logs/
*.log
# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
# IDE
.vscode/
.idea/
*.swp
*.swo
# Temporary files
tmp/
temp/
\ No newline at end of file
.gitignore 0 → 100644
# 编译生成的可执行文件
pf
# Go 编译缓存
*.exe
*.exe~
*.dll
*.so
*.dylib
# Go 测试二进制文件
*.test
# Go 覆盖率文件
*.out
# Go 工作区文件
go.work
# 构建目录
build/
dist/
# 日志文件
*.log
# 临时文件
*.tmp
*.temp
# IDE 文件
.vscode/
.idea/
*.swp
*.swo
# macOS
.DS_Store
# 环境配置文件
.env
.env.local
.env.*.local
\ No newline at end of file
Makefile 0 → 100644
# Makefile for nlt-pufa-interface
# 变量定义
APP_NAME=pf
BUILD_DIR=./build
PROD_PATH=/data/docker-compose/tk
# 默认目标
.PHONY: help
help:
@echo "可用命令:"
@echo " build - 编译Go程序"
@echo " build-linux - 交叉编译Linux生产版本"
@echo " clean - 清理构建文件"
@echo " dev - 本地开发环境运行"
@echo " deploy - 部署到生产环境"
@echo " restart - 重启生产服务"
@echo " logs - 查看生产日志"
@echo " status - 查看服务状态"
# 本地编译
.PHONY: build
build:
@echo "编译Go程序..."
go build -o $(APP_NAME) .
# 交叉编译Linux版本（用于生产环境）
.PHONY: build-linux
build-linux:
@echo "交叉编译Linux版本..."
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o $(APP_NAME) .
# 清理构建文件
.PHONY: clean
clean:
@echo "清理构建文件..."
rm -f $(APP_NAME)
rm -rf $(BUILD_DIR)
# 部署到生产环境
.PHONY: deploy
deploy: build-linux
@echo "部署到生产环境..."
@if [ ! -d "$(PROD_PATH)" ]; then \
echo "生产目录不存在: $(PROD_PATH)"; \
exit 1; \
fi
cp $(APP_NAME) $(PROD_PATH)/
cp -r html $(PROD_PATH)/
@echo "部署完成，重启服务..."
$(MAKE) restart
# 重启生产服务
.PHONY: restart
restart:
@echo "重启生产服务..."
cd /data/docker-compose/tk && docker-compose -f docker-compose.yml restart tkservice
# 查看生产日志
.PHONY: logs
logs:
@echo "查看生产日志..."
cd /data/docker-compose/tk && docker-compose -f docker-compose.yml logs -f tkservice
# 查看服务状态
.PHONY: status
status:
@echo "查看服务状态..."
cd /data/docker-compose/tk && docker-compose -f docker-compose.yml ps
# 开发环境运行
.PHONY: dev
dev:
@echo "启动开发环境..."
go run main.go
# 测试
.PHONY: test
test:
@echo "运行测试..."
go test ./...
\ No newline at end of file
README.md 0 → 100644
# 普发银行农业贷款接口系统
**nlt-pufa-interface** 是一个基于Go语言开发的农业贷款接口系统，为普发银行提供安全可靠的贷款业务API服务。
## 📋 项目概览
- **项目名称**: nlt-pufa-interface（农业贷款工具包-普发银行接口）
- **技术栈**: Go + Hertz 框架 + MySQL + 国密SM2加密
- **运行端口**: 8970
- **业务场景**: 农业贷款申请、支付状态查询、业务流程跳转
## 🚀 主要功能
### 核心API接口
#### 1. 认证接口 `/nlt/pufa/auth`
- **功能**: 处理用户身份认证和贷款申请
- **方法**: POST
- **验证流程**:
- 通过身份证号查询农户信息
- 验证姓名与身份证号匹配
- 更新贷款订单信息（流水号、金额、期限、跳转URL）
- **返回**: 提供直接跳转URL
#### 2. 支付结果查询 `/nlt/pufa/queryPayResult`
- **功能**: 查询贷款订单的支付状态
- **方法**: POST
- **查询条件**: 状态为37且金额小于等于配额的订单
- **返回数据**: 订单状态（SUCCESS/FAIL）、创建时间、失败原因等
#### 3. 跳转URL查询 `/nlt/pufa/queryJumpUrl`
- **功能**: 获取订单对应的业务跳转链接
- **方法**: POST
- **用途**: 为前端页面提供后续操作的URL
## 🔐 安全机制
项目采用**国密SM2算法**实现端到端安全通信：
### 加密流程
- **请求加密**: 客户端使用SM2公钥加密请求数据
- **响应加密**: 服务端使用SM2公钥加密响应数据
- **数字签名**: 使用SM2私钥进行数字签名
- **签名验证**: 严格的签名验证和解密流程
### 错误代码
| 代码 | 说明 |
|------|------|
| 000000 | 成功 |
| W020103 | 查询无数据 |
| W140001 | 请求参数为空 |
| W140003 | 请求参数格式不正确 |
| W149999 | 系统异常 |
| W380002 | 申请人信息比对不一致 |
| W380005 | 验签错误 |
| W380006 | 解密错误 |
## 🗄️ 数据库设计
### 主要数据表: `loan_orderinfo`
存储农户贷款订单信息，包含以下关键字段：
- `id_num`: 身份证号
- `farmer`: 农户姓名
- `order_sn`: 订单编号
- `serial_no`: 流水号
- `amount_r`: 贷款金额
- `term_r`: 贷款期限
- `status`: 订单状态
- `disburse_sign_url`: 业务跳转URL
- `createtime`: 创建时间
## 🏗️ 项目结构
```
nlt-pufa-interface/
├── main.go # 应用程序入口
├── go.mod # Go模块依赖
├── db/ # 数据库相关
│ └── init.go # 数据库初始化
├── handler/ # HTTP处理器
│ ├── auth.go # 认证接口
│ ├── pay_result.go # 支付结果查询
│ └── jump_url.go # URL跳转查询
├── model/ # 数据模型
│ ├── auth.go # 认证相关模型
│ ├── http_body.go # HTTP请求响应模型
│ └── pay_result.go # 支付结果模型
├── route/ # 路由配置
│ └── register.go # 路由注册
├── nltconst/ # 常量定义
│ ├── const.go # 业务常量
│ └── crypt.go # 加密相关
└── html/ # 前端页面
├── index.html # 担保费缴纳页面
└── logo.jpg # 品牌标识
```
## 🌐 前端界面
提供担保费缴纳提醒页面：
- **功能**: 线下担保费缴纳流程引导
- **交互**: 点击确定按钮自动跳转到相应业务URL
- **响应式**: 自适应手机和桌面设备
- **用户体验**: 简洁美观的界面设计
## 🛠️ 安装与使用
### 环境要求
- Go 1.21.13+
- MySQL 5.7+
- Linux/macOS/Windows
### 安装步骤
1. **克隆项目**
```bash
git clone <repository-url>
cd nlt-pufa-interface
```
2. **安装依赖**
```bash
go mod download
```
3. **配置数据库**
修改 `db/init.go` 中的数据库连接信息：
```go
var dsn = "username:password@tcp(host:port)/database?charset=utf8&parseTime=True&loc=Local"
```
4. **启动服务**
```bash
go run main.go
```
服务将在 `http://localhost:8970` 启动
### API调用示例
#### 认证接口调用
```bash
curl -X POST http://localhost:8970/nlt/pufa/auth \
-H "Content-Type: application/json" \
-d '{
"request": {
"head": {
"requestTime": "20231201120000",
"versionId": "1.0",
"serviceId": "auth",
"serviceSn": "12345",
"channelId": "web",
"sid": "session123",
"businessChannel": "online"
},
"body": "加密后的请求数据"
},
"signature": "数字签名"
}'
```
## 📊 业务流程
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
sequenceDiagram
participant Client as 客户端
participant API as 接口服务
participant DB as 数据库
participant Bank as 银行系统
Client->>API: 1. 身份认证请求(加密)
API->>API: 解密&验签
API->>DB: 查询农户信息
DB-->>API: 返回农户数据
API->>API: 验证身份信息
API->>DB: 更新订单信息
API->>API: 加密&签名
API-->>Client: 返回认证结果
Client->>API: 2. 查询支付结果
API->>DB: 查询订单状态
DB-->>API: 返回状态信息
API-->>Client: 返回支付状态
Client->>API: 3. 获取跳转URL
API->>DB: 查询跳转链接
DB-->>API: 返回URL
API-->>Client: 返回跳转地址
```
## 🔧 开发说明
### 核心依赖
- **Hertz**: 高性能HTTP框架
- **gmsm**: 国密算法实现
- **mysql**: MySQL数据库驱动
### 代码规范
- 遵循Go官方编码规范
- 使用驼峰命名法
- 添加必要的错误处理
- 保持代码简洁可读
### 日志记录
系统包含详细的操作日志，便于：
- 问题排查和调试
- 业务流程跟踪
- 安全审计
## 🚦 部署建议
### 生产环境配置
1. **数据库安全**: 使用独立的数据库用户，限制权限
2. **HTTPS**: 配置SSL证书，启用HTTPS
3. **防火墙**: 限制端口访问，只允许必要的IP
4. **监控**: 配置应用监控和日志收集
5. **备份**: 定期备份数据库和配置文件
### 性能优化
- 数据库连接池优化
- 适当的缓存策略
- 接口限流保护
- 负载均衡配置
## 📝 许可证
本项目仅供农业贷款业务使用，涉及金融数据安全，请严格按照相关法规使用。
## 📚 详细文档
更多详细文档请查看 [`docs/`](./docs/) 目录：
- [📖 文档目录](./docs/README.md) - 完整的文档索引和使用指南
- [🚀 项目部署运行指南](./docs/DEPLOYMENT_GUIDE.md) - 环境配置、启动流程和运维指南
- [🏢 业务设计文档](./docs/BUSINESS_DESIGN.md) - 担保费支付逻辑和风控机制详解
- [🔌 API接口集成文档](./docs/API_INTEGRATION.md) - 外部系统集成指南
## 🤝 贡献
如需贡献代码或报告问题，请联系项目维护团队。
---
**注意**: 本系统处理敏感的金融数据，部署和使用时请严格遵守相关安全规范和法律法规。
\ No newline at end of file
deploy.sh 0 → 100755
#!/bin/bash
# 浦发农联体接口部署脚本
# 用法: ./deploy.sh [options]
set -e # 遇到错误立即退出
# 配置变量
APP_NAME="pf"
PROD_PATH="/data/docker-compose/tk"
DOCKER_COMPOSE_FILE="docker-compose.yml"
BACKUP_DIR="/data/backup/nlt-pufa"
# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# 打印带颜色的消息
print_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
print_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 显示帮助信息
show_help() {
cat << EOF
浦发农联体接口部署脚本
用法: $0 [选项]
选项:
-h, --help 显示此帮助信息
-b, --backup 部署前备份当前版本
-r, --restart-only 仅重启服务，不部署
-l, --logs 查看服务日志
-s, --status 查看服务状态
--rollback 回滚到上一个版本
示例:
$0 # 标准部署
$0 -b # 备份后部署
$0 -r # 仅重启服务
$0 -l # 查看日志
EOF
}
# 检查依赖
check_dependencies() {
print_info "检查部署环境..."
# 检查Go环境
if ! command -v go &> /dev/null; then
print_error "Go环境未安装"
exit 1
fi
# 检查Docker
if ! command -v docker &> /dev/null; then
print_error "Docker未安装"
exit 1
fi
# 检查docker-compose
if ! command -v docker-compose &> /dev/null; then
print_error "docker-compose未安装"
exit 1
fi
# 检查生产目录
if [ ! -d "$PROD_PATH" ]; then
print_error "生产目录不存在: $PROD_PATH"
exit 1
fi
print_info "环境检查通过"
}
# 备份当前版本
backup_current() {
if [ -f "$PROD_PATH/$APP_NAME" ]; then
print_info "备份当前版本..."
# 创建备份目录
mkdir -p "$BACKUP_DIR"
# 生成备份文件名（包含时间戳）
BACKUP_FILE="$BACKUP_DIR/${APP_NAME}_$(date +%Y%m%d_%H%M%S).tar.gz"
# 打包备份
tar -czf "$BACKUP_FILE" -C "$PROD_PATH" "$APP_NAME" html/
print_info "备份完成: $BACKUP_FILE"
else
print_warn "未找到当前版本，跳过备份"
fi
}
# 编译应用
build_app() {
print_info "编译应用程序..."
# 交叉编译Linux版本
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o "$APP_NAME" .
if [ ! -f "$APP_NAME" ]; then
print_error "编译失败"
exit 1
fi
print_info "编译完成"
}
# 部署应用
deploy_app() {
print_info "部署应用到生产环境..."
# 复制可执行文件
cp "$APP_NAME" "$PROD_PATH/"
# 复制静态文件
if [ -d "html" ]; then
cp -r html "$PROD_PATH/"
fi
# 设置执行权限
chmod +x "$PROD_PATH/$APP_NAME"
print_info "文件复制完成"
}
# 重启服务
restart_service() {
print_info "重启Docker服务..."
cd "$PROD_PATH"
# 停止服务
docker-compose -f "$DOCKER_COMPOSE_FILE" stop tkservice
# 启动服务
docker-compose -f "$DOCKER_COMPOSE_FILE" up -d tkservice
print_info "服务重启完成"
}
# 检查服务状态
check_service() {
print_info "检查服务状态..."
cd "$PROD_PATH"
docker-compose -f "$DOCKER_COMPOSE_FILE" ps tkservice
# 等待服务启动
sleep 5
# 检查健康状态
if curl -f http://localhost:8970/ > /dev/null 2>&1; then
print_info "服务运行正常"
else
print_warn "服务可能未正常启动，请检查日志"
fi
}
# 查看日志
show_logs() {
cd "$PROD_PATH"
docker-compose -f "$DOCKER_COMPOSE_FILE" logs -f tkservice
}
# 回滚到上一版本
rollback() {
print_info "查找最新备份..."
if [ ! -d "$BACKUP_DIR" ]; then
print_error "备份目录不存在: $BACKUP_DIR"
exit 1
fi
# 找到最新的备份文件
LATEST_BACKUP=$(ls -t "$BACKUP_DIR"/${APP_NAME}_*.tar.gz 2>/dev/null | head -n1)
if [ -z "$LATEST_BACKUP" ]; then
print_error "未找到备份文件"
exit 1
fi
print_info "回滚到: $LATEST_BACKUP"
# 解压备份
tar -xzf "$LATEST_BACKUP" -C "$PROD_PATH"
# 重启服务
restart_service
print_info "回滚完成"
}
# 主函数
main() {
case "${1:-deploy}" in
-h|--help)
show_help
;;
-l|--logs)
show_logs
;;
-s|--status)
cd "$PROD_PATH"
docker-compose -f "$DOCKER_COMPOSE_FILE" ps
;;
-r|--restart-only)
check_dependencies
restart_service
check_service
;;
--rollback)
check_dependencies
rollback
check_service
;;
-b|--backup|deploy)
check_dependencies
# 如果指定了备份选项
if [ "$1" = "-b" ] || [ "$1" = "--backup" ]; then
backup_current
fi
build_app
deploy_app
restart_service
check_service
print_info "部署完成！"
;;
*)
print_error "未知选项: $1"
show_help
exit 1
;;
esac
}
# 执行主函数
main "$@"
\ No newline at end of file
docker-compose.prod.yml 0 → 100644
version: '3'
services:
tkservice:
image: alios:v3.0.1
container_name: tkservice
restart: always
ports:
- 8970:8970
environment:
- TZ=Asia/Shanghai
volumes:
- /data/docker-compose/tk:/home/tk
working_dir: /home/tk
command: ./pf >> /home/tk/pf.log
networks:
default:
external: true
name: my_network
\ No newline at end of file
docs/README.md 0 → 100644
# 📚 项目文档目录
本目录包含普发银行农业贷款接口系统的所有详细文档。
## 📋 文档列表
### 🏢 业务设计文档
**文件**: [`BUSINESS_DESIGN.md`](./BUSINESS_DESIGN.md)
**内容概述**:
- 担保费支付业务逻辑详解
- 预授信额度控制机制
- 风险控制策略
- 系统架构角色分工
- 业务流程图和数据流转
**适用人群**: 产品经理、业务分析师、系统架构师
---
### 🔌 API接口集成文档
**文件**: [`API_INTEGRATION.md`](./API_INTEGRATION.md)
**内容概述**:
- 外部系统调用本系统的完整指南
- 3个对外接口的详细规范
- 国密SM2加密集成要求
- 技术实现示例和测试指南
- 错误码说明和故障排查
**适用人群**: 外部开发团队、系统集成工程师、测试工程师
---
### 🚀 项目部署运行指南
**文件**: [`DEPLOYMENT_GUIDE.md`](./DEPLOYMENT_GUIDE.md)
**内容概述**:
- 完整的环境配置和依赖安装指南
- 开发和生产环境的启动流程
- 详细的架构说明和组件介绍
- 监控、调试和故障排查方法
- Docker、Systemd等生产部署方案
**适用人群**: 运维工程师、开发工程师、系统管理员
---
## 🔗 相关文档
### 项目概述
- [项目README](../README.md) - 项目总体介绍和快速开始指南
### 技术文档
- [Go模块依赖](../go.mod) - 项目依赖管理
- [数据库配置](../db/init.go) - 数据库连接配置
- [路由配置](../route/register.go) - API路由注册
## 📖 文档使用说明
### 📋 阅读顺序建议
1. **新手入门**:
- 先阅读 [项目README](../README.md) 了解项目概况
- 再阅读 `BUSINESS_DESIGN.md` 理解业务逻辑
2. **系统集成**:
- 重点阅读 `API_INTEGRATION.md`
- 参考技术实现示例进行开发
3. **深入理解**:
- 结合源代码阅读业务设计文档
- 理解系统架构和设计思路
### 🔄 文档更新
- **更新频率**: 跟随系统版本更新
- **维护责任**: 开发团队负责技术文档，产品团队负责业务文档
- **审核流程**: 重要变更需经过技术和业务双重审核
### 📞 文档反馈
如发现文档问题或需要补充说明，请：
1. 提交Issue到项目仓库
2. 联系相关文档维护人员
3. 提出Pull Request进行修改
---
**文档版本**: v1.0
**最后更新**: 2024年
**维护团队**: 普发银行农业贷款系统开发组
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment