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 2071 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/API_INTEGRATION.md 0 → 100644
# API接口集成文档
## 📋 文档说明
本文档面向需要集成**普发银行农业贷款接口系统**的外部开发团队，详细说明如何调用本系统提供的API接口。
## 🏗️ 系统架构说明
### 角色定位
- **本系统**: 接口服务提供者，负责业务流程管理和状态查询
- **银行系统**: 接口调用方，通过API获取业务服务
- **业务平台**: 接口调用方，管理贷款业务流程
- **前端页面**: 通过JavaScript调用部分接口
### 集成模式
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
graph TD
A[银行核心系统] --> D[本系统API]
B[业务管理平台] --> D
C[第三方集成系统] --> D
D --> E[身份认证]
D --> F[支付状态查询]
D --> G[URL跳转服务]
H[前端页面] --> G
style D fill:#e3f2fd,stroke:#1976d2
style A fill:#fff8e1,stroke:#f57c00
style B fill:#fff8e1,stroke:#f57c00
style C fill:#fff8e1,stroke:#f57c00
```
## 🔌 API接口清单
### 接口总览
| 接口名称 | 方法 | 路径 | 功能描述 | 调用方 |
|----------|------|------|----------|--------|
| 身份认证接口 | POST | `/nlt/pufa/auth` | 用户身份验证和贷款申请处理 | 银行系统/业务平台 |
| 支付状态查询 | POST | `/nlt/pufa/queryPayResult` | 查询担保费支付状态 | 银行系统/业务平台 |
| 跳转URL查询 | POST | `/nlt/pufa/queryJumpUrl` | 获取业务流程跳转链接 | 前端页面/系统 |
## 🔐 安全要求
### 1. 国密SM2加密
**所有接口均采用国密SM2算法进行端到端加密**
#### 加密流程
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
sequenceDiagram
participant Client as 调用方
participant API as 接口系统
Note over Client: 1. 准备请求数据
Client->>Client: 2. SM2公钥加密body
Client->>Client: 3. SM2私钥签名整个请求
Client->>API: 4. 发送加密请求
API->>API: 5. 验证签名
API->>API: 6. SM2私钥解密body
API->>API: 7. 处理业务逻辑
API->>API: 8. SM2公钥加密响应
API->>API: 9. SM2私钥签名响应
API->>Client: 10. 返回加密响应
Client->>Client: 11. 验证签名并解密
```
#### 密钥配置
**调用方需要配置的密钥信息**:
```json
{
"本系统公钥": "04A7CD09260A67113F988F530154AD6A70B2A4DD3E00BD27BB124E7E7051FC0C97E7AC3C5A6CB6C9BB459BEF252761AD1AE727718498CA3130D67CFC84F9B1BB1F",
"银行测试私钥": "308a6311076aa18ec591ce0b300c6f92b1e58438d0ab0962d67b7d163b0e2f8d",
"银行测试公钥": "041f41683ee8d5204958db303b16c97a912b1d2a7ee640f767001395ccfcc16c48e9e81ed2b0e540c53a0836040665ef98f2488ee4cc7e9c525d8ecc92e42d62f1"
}
```
### 2. 请求响应格式
#### 统一请求格式
```json
{
"request": {
"head": {
"requestTime": "yyyyMMddHHmmss",
"versionId": "V1.0",
"serviceId": "服务标识",
"serviceSn": "请求流水号",
"channelId": "渠道标识",
"sid": "会话标识",
"businessChannel": "业务渠道"
},
"body": "SM2加密后的业务数据(Hex编码)"
},
"signature": "SM2数字签名(Hex编码)"
}
```
#### 统一响应格式
```json
{
"response": {
"head": {
"code": "响应码",
"serviceTime": "yyyyMMddHHmmss",
"serviceSn": "请求流水号"
},
"body": "SM2加密后的响应数据(Hex编码)"
},
"signature": "SM2数字签名(Hex编码)"
}
```
## 📝 接口详细规范
### 1. 身份认证接口
#### 接口信息
- **路径**: `POST /nlt/pufa/auth`
- **功能**: 处理用户身份认证和贷款申请
- **调用场景**: 用户提交贷款申请时
#### 请求参数 (解密后的body内容)
```json
{
"cellPhone": "手机号码",
"userName": "用户姓名",
"idNo": "身份证号",
"addr": "地址",
"loanAmt": "申请金额(分)",
"term": "贷款期限(月)",
"duebillNoOrg": "外部流水号",
"jumURL": "跳转URL"
}
```
#### 响应数据 (解密后的body内容)
```json
{
"payOrderNo": "支付订单号",
"directURL": "直接跳转URL"
}
```
#### 业务逻辑
1. 验证身份证号和姓名匹配
2. 将申请金额从分转换为元存储
3. 更新订单信息到数据库
4. 返回担保费缴纳页面URL
#### 调用示例
```bash
curl -X POST https://api.example.com/nlt/pufa/auth \
-H "Content-Type: application/json" \
-d '{
"request": {
"head": {
"requestTime": "20240101120000",
"versionId": "V1.0",
"serviceId": "pfyhcxzfjg",
"serviceSn": "202401011200001",
"channelId": "BANK001",
"sid": "session_202401011200001",
"businessChannel": "online"
},
"body": "SM2加密后的Hex字符串"
},
"signature": "SM2签名后的Hex字符串"
}'
```
### 2. 支付状态查询接口
#### 接口信息
- **路径**: `POST /nlt/pufa/queryPayResult`
- **功能**: 查询担保费支付状态
- **调用场景**: 检查用户是否已完成担保费缴纳
#### 请求参数 (解密后的body内容)
```json
{
"duebillNoOrg": "外部流水号"
}
```
#### 响应数据 (解密后的body内容)
```json
{
"payOrderNo": "支付订单号",
"duebillNoOrg": "外部流水号",
"status": "SUCCESS/FAIL",
"orderTime": "订单时间",
"failMsg": "失败原因"
}
```
#### 业务规则
- 查询条件: `status = 37 AND amount_r <= quota_r`
- 状态转换: 数据库status=37 → 返回"SUCCESS"
- 额度校验: 申请金额必须小于等于预授信额度
### 3. 跳转URL查询接口
#### 接口信息
- **路径**: `POST /nlt/pufa/queryJumpUrl`
- **功能**: 获取业务流程跳转链接
- **调用场景**: 担保费缴纳完成后获取下一步链接
#### 请求参数 (非加密，直接JSON)
```json
{
"duebillNoOrg": "外部流水号"
}
```
#### 响应数据 (非加密，直接JSON)
```json
{
"head": {
"code": "000000",
"serviceTime": "20240101120000"
},
"body": "https://next-step-url.com"
}
```
## 🔧 集成技术要求
### 1. 开发环境
#### 推荐技术栈
- **编程语言**: Java/Go/Python/C#等
- **加密库**: 支持国密SM2算法的加密库
- **HTTP客户端**: 支持POST请求和JSON处理
#### 国密SM2算法库推荐
| 语言 | 推荐库 | 说明 |
|------|--------|------|
| Java | BC (Bouncy Castle) | 支持国密算法 |
| Go | github.com/tjfoc/gmsm | 专门的国密算法库 |
| Python | gmssl | 国密SSL/TLS协议库 |
| .NET | GmSSL.NET | .NET平台国密实现 |
### 2. 集成步骤
#### Step 1: 环境准备
1. 安装国密SM2算法库
2. 配置密钥对(公钥用于加密，私钥用于签名)
3. 准备HTTP客户端工具
#### Step 2: 实现加密解密
```python
# Python示例代码框架
def encrypt_request(data, public_key):
"""使用SM2公钥加密请求数据"""
# 实现SM2加密逻辑
pass
def sign_request(data, private_key):
"""使用SM2私钥签名请求"""
# 实现SM2签名逻辑
pass
def call_api(endpoint, business_data):
"""调用API接口"""
# 1. 构造请求头
head = {
"requestTime": datetime.now().strftime("%Y%m%d%H%M%S"),
"versionId": "V1.0",
"serviceId": "your_service_id",
"serviceSn": generate_serial_number(),
"channelId": "your_channel_id",
"sid": generate_session_id(),
"businessChannel": "online"
}
# 2. 加密业务数据
encrypted_body = encrypt_request(business_data, public_key)
# 3. 构造请求
request_data = {
"request": {
"head": head,
"body": encrypted_body
}
}
# 4. 签名请求
signature = sign_request(request_data["request"], private_key)
request_data["signature"] = signature
# 5. 发送HTTP请求
response = requests.post(endpoint, json=request_data)
# 6. 处理响应
return process_response(response)
```
#### Step 3: 错误处理
```python
def process_response(response):
"""处理API响应"""
if response.status_code != 200:
raise APIException(f"HTTP错误: {response.status_code}")
data = response.json()
code = data.get("response", {}).get("head", {}).get("code")
if code == "000000":
# 成功，解密响应数据
return decrypt_response(data)
else:
# 业务错误
error_msg = get_error_message(code)
raise BusinessException(f"业务错误[{code}]: {error_msg}")
```
## 📊 错误码说明
| 错误码 | 错误描述 | 处理建议 |
|--------|----------|----------|
| 000000 | 成功 | 正常处理 |
| W020103 | 查询无数据 | 检查流水号是否正确 |
| W140001 | 请求参数为空 | 检查必填参数 |
| W140003 | 请求参数格式不正确 | 验证参数格式 |
| W149999 | 系统异常 | 稍后重试或联系技术支持 |
| W380002 | 申请人信息比对不一致 | 检查姓名和身份证号匹配 |
| W380005 | 验签错误 | 检查签名算法和密钥配置 |
| W380006 | 解密错误 | 检查加密算法和密钥配置 |
## 🧪 测试指南
### 1. 接口测试环境
#### 测试环境信息
```
测试域名: https://test.nlt-api.example.com
端口: 8970
协议: HTTPS
```
#### 测试账号
```
测试用户: 张三
身份证号: 420982198604026032
手机号: 13811111111
```
### 2. 测试用例
#### 用例1: 身份认证成功
```json
{
"cellPhone": "13811111111",
"userName": "张三",
"idNo": "420982198604026032",
"addr": "湖北省武汉市",
"loanAmt": "1000000",
"term": "12",
"duebillNoOrg": "TEST202401011200001",
"jumURL": "https://bank.example.com/next-step"
}
```
#### 用例2: 支付状态查询
```json
{
"duebillNoOrg": "TEST202401011200001"
}
```
### 3. 常见问题
#### Q1: 加密后的数据过长怎么办？
A: SM2加密会增加数据长度，建议：
- 使用gzip压缩原始数据
- 采用分段加密处理大数据
#### Q2: 签名验证失败如何排查？
A: 检查顺序：
1. 确认使用正确的私钥
2. 验证JSON序列化顺序
3. 检查字符编码(建议UTF-8)
4. 确认签名算法参数
#### Q3: 如何处理网络超时？
A: 建议配置：
- 连接超时: 10秒
- 读取超时: 30秒
- 重试机制: 3次，间隔2秒
## 📞 技术支持
### 联系方式
- **技术支持**: [tech-support@example.com]
- **API文档**: [https://docs.nlt-api.example.com]
- **问题反馈**: [issues@example.com]
### 支持时间
- **工作日**: 9:00 - 18:00
- **紧急问题**: 7x24小时支持
---
**文档版本**: v1.0
**最后更新**: 2024年
**维护团队**: 接口集成支持组
\ No newline at end of file
docs/BUSINESS_DESIGN.md 0 → 100644
# 普发银行农业贷款接口系统 - 业务设计文档
## 📋 文档概述
本文档详细说明了普发银行农业贷款接口系统的核心业务逻辑，包括担保费支付流程、预授信额度控制机制和风险管控策略。
## 💰 担保费支付业务逻辑
### 🔄 核心业务流程
#### 1. 状态定义与含义
| 状态值 | 业务含义 | 说明 |
|--------|----------|------|
| **37** | 担保费已支付/审批通过 | 系统中表示支付成功的关键标识符 |
| 其他状态 | 担保费未支付/处理中 | 表示支付流程尚未完成 |
#### 2. 完整业务流程
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
graph TD
A[用户身份认证] --> B[认证成功]
B --> C[返回担保费缴纳页面URL]
C --> D[用户访问担保费页面]
D --> E[显示：请线下缴纳担保费]
E --> F[用户线下缴纳担保费]
F --> G[银行/机构更新订单状态为37]
G --> H[用户点击确定按钮]
H --> I[调用queryJumpUrl获取下一步链接]
I --> J[跳转到业务页面]
K[外部系统查询] --> L[调用queryPayResult接口]
L --> M{状态是否为37?}
M -->|是| N[返回SUCCESS]
M -->|否| O[返回FAIL]
style E fill:#fff2cc,stroke:#d6b656
style G fill:#d5e8d4,stroke:#82b366
style M fill:#f8cecc,stroke:#b85450
```
#### 3. 关键代码实现
**支付状态查询逻辑**:
```go
// 查询条件：状态为37且实际金额小于等于预授信额度
rows, err := db.DB.Query("select serial_no,status,createtime,reject_cause from loan_orderinfo where serial_no = ? and status = 37 and amount_r <= quota_r order by createtime", &req.Request.DuebillNoOrg)
// 状态转换逻辑
if resp.Response.Status == "37" {
resp.Response.Status = "SUCCESS" // 担保费已支付
} else {
resp.Response.Status = "FAIL" // 担保费未支付
}
```
**前端交互处理**:
```javascript
// 用户确认担保费缴纳后的跳转逻辑
document.getElementById("confirmButton").onclick = function () {
fetch("https://tknlt.agrolinking.cn/api/nlt/pufa/queryJumpUrl", {
method: "POST",
body: JSON.stringify({duebillNoOrg: idParam})
}).then(response => response.json())
.then(res => {
if (res.head.code == "000000") {
window.location.href = res.body; // 跳转到下一业务环节
}
});
};
```
## 💳 预授信额度控制机制
### 🔍 核心对比逻辑
系统实现了严格的**预授信额度控制**，确保用户申请的贷款金额不超过其预设的信用额度。
#### 1. 字段定义
| 字段名 | 数据类型 | 业务含义 | 数据来源 |
|--------|----------|----------|----------|
| `amount_r` | DECIMAL | **实际申请贷款金额** | 用户申请时提交，系统验证后存储 |
| `quota_r` | DECIMAL | **预授信额度** | 银行风控系统预先设定的最大可贷金额 |
#### 2. 额度判断条件
**核心规则**: `amount_r <= quota_r`
只有当**实际申请金额**小于等于**预授信额度**时，系统才认为该订单符合放贷条件。
#### 3. 金额处理流程
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
graph TD
A[用户提交申请金额] --> B[系统接收LoanAmt]
B --> C[金额单位转换: 分→元]
C --> D[更新amount_r字段]
D --> E[支付完成: status=37]
E --> F[查询时验证]
F --> G{amount_r <= quota_r?}
G -->|是| H[返回SUCCESS - 符合授信]
G -->|否| I[不返回记录 - 超出授信]
style C fill:#fff2cc,stroke:#d6b656
style G fill:#f8cecc,stroke:#b85450
style H fill:#d5e8d4,stroke:#82b366
style I fill:#ffcccc,stroke:#ff6666
```
#### 4. 代码实现
**金额转换与存储**:
```go
amt := req.Request.LoanAmt
// 从分转换为元 (金融系统常见做法，避免浮点数精度问题)
float32Value, err := strconv.ParseFloat(amt, 32)
value := float32Value / 100
// 更新实际贷款金额
_, err = db.DB.Exec("update loan_orderinfo set serial_no = ?,disburse_sign_url=?,amount_r=?,term_r=? where order_sn=? ",
&req.Request.DuebillNoOrg, &req.Request.JumURL, &value, &req.Request.Term, &ordersn)
```
## 🛡️ 风险控制策略
### 1. 多层次风控机制
| 控制层级 | 控制点 | 实现方式 | 风险防范 |
|----------|--------|----------|----------|
| **申请阶段** | 身份验证 | 身份证号+姓名匹配 | 防止冒名申请 |
| **额度阶段** | 预授信控制 | amount_r <= quota_r | 防止超额放贷 |
| **支付阶段** | 状态管控 | status = 37 | 确保担保费已缴纳 |
| **查询阶段** | 综合验证 | 多条件AND查询 | 多重校验确保合规 |
### 2. 业务合规性保障
**查询条件组合**:
```sql
SELECT serial_no, status, createtime, reject_cause
FROM loan_orderinfo
WHERE serial_no = ?
AND status = 37
AND amount_r <= quota_r
ORDER BY createtime
```
**三重验证机制**:
1. **流水号匹配**: 确保查询的是正确订单
2. **支付状态确认**: 必须是已支付状态(37)
3. **额度合规验证**: 申请金额不能超过预授信额度
### 3. 异常处理策略
| 异常情况 | 系统响应 | 业务处理 |
|----------|----------|----------|
| 超出预授信额度 | 不返回查询结果 | 提示额度不足，建议重新申请 |
| 担保费未支付 | 返回FAIL状态 | 引导用户完成担保费缴纳 |
| 订单不存在 | 返回NODATA | 提示订单信息错误 |
## 📊 系统架构角色分工
### 1. 角色职责划分
| 系统角色 | 主要职责 | 核心功能 |
|----------|----------|----------|
| **本接口系统** | 流程引导与状态查询 | • 身份认证<br>• 担保费缴纳页面<br>• 支付状态查询<br>• 业务流程跳转 |
| **银行/支付机构** | 担保费收取与状态更新 | • 线下担保费处理<br>• 订单状态更新(status=37)<br>• 资金清算 |
| **风控系统** | 额度管理与风险评估 | • 预授信额度设定(quota_r)<br>• 用户信用评估<br>• 风险监控 |
| **业务系统** | 贷款流程管理 | • 贷款申请处理<br>• 状态监控<br>• 业务流程控制 |
## 🔌 外部接口集成关系
### 1. 接口调用方向说明
**重要说明**: 本系统是**接口服务提供者**，不主动调用银行接口，而是**被外部系统调用**。
#### 1.1 本系统对外提供的接口
| 接口名称 | 调用方 | 接口路径 | 用途 |
|----------|--------|----------|------|
| **身份认证接口** | 银行系统/业务平台 | `POST /nlt/pufa/auth` | 处理用户身份验证和贷款申请 |
| **支付状态查询** | 银行系统/业务平台 | `POST /nlt/pufa/queryPayResult` | 查询担保费支付状态 |
| **跳转URL查询** | 前端页面 | `POST /nlt/pufa/queryJumpUrl` | 获取业务流程跳转链接 |
#### 1.2 外部系统调用本系统的场景
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
graph LR
A[银行核心系统] --> B[本接口系统]
C[业务管理平台] --> B
D[前端页面] --> B
E[第三方系统] --> B
B --> F[数据库]
G[银行线下系统] --> F
style B fill:#e1f5fe,stroke:#0277bd
style A fill:#fff3e0,stroke:#f57c00
style C fill:#fff3e0,stroke:#f57c00
style E fill:#fff3e0,stroke:#f57c00
style G fill:#ffebee,stroke:#d32f2f
```
#### 1.3 数据更新机制
**担保费状态更新方式**:
- ❌ **非接口调用**: 银行不通过API接口更新状态
- ✅ **直接数据库操作**: 银行线下处理后直接更新数据库字段
- 更新 `status = 37` (担保费已支付)
- 系统通过查询接口返回最新状态
### 2. 系统集成架构
#### 2.1 实际的系统调用关系
| 调用方向 | 说明 | 实现方式 |
|----------|------|----------|
| **外部 → 本系统** | 银行等外部系统调用本系统接口 | HTTP POST + 国密SM2加密 |
| **本系统 → 数据库** | 查询和更新业务数据 | MySQL数据库连接 |
| **银行线下 → 数据库** | 担保费处理后更新状态 | 直接数据库操作 |
| **前端 → 本系统** | 页面获取跳转URL | JavaScript fetch调用 |
#### 2.2 不存在的调用关系
❌ **本系统不会调用以下接口**:
- 银行支付接口
- 银行账户查询接口
- 银行资金划转接口
- 第三方支付平台接口
**原因**: 本系统定位为**业务流程管理和状态查询服务**，担保费支付采用**线下处理模式**。
### 2. 数据流转图
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
sequenceDiagram
participant U as 用户
participant API as 接口系统
participant DB as 数据库
participant Bank as 银行系统
participant Risk as 风控系统
Note over Risk: 预设quota_r额度
U->>API: 1. 提交贷款申请
API->>DB: 2. 验证身份&更新amount_r
API-->>U: 3. 返回担保费页面URL
U->>Bank: 4. 线下缴纳担保费
Bank->>DB: 5. 更新status=37
U->>API: 6. 查询支付状态
API->>DB: 7. 验证: status=37 AND amount_r<=quota_r
DB-->>API: 8. 返回符合条件的记录
API-->>U: 9. 返回SUCCESS/FAIL
```
## 🔧 技术实现要点
### 1. 数据精度处理
**金融金额处理最佳实践**:
- 前端传输：以"分"为单位，避免浮点数传输精度问题
- 后端存储：转换为"元"，使用DECIMAL类型确保精度
- 业务计算：统一单位，避免精度丢失
### 2. 状态机设计
订单状态遵循严格的状态机转换：
```
初始状态 → 审核中 → 担保费待缴 → 担保费已缴(37) → 放款成功
```
### 3. 安全性考虑
- **国密加密**: 使用SM2算法保护敏感数据传输
- **数字签名**: 确保数据完整性和身份认证
- **多重验证**: 身份、额度、支付状态的多层验证
- **日志记录**: 完整的操作审计日志
## 📈 业务指标监控
### 1. 关键业务指标
| 指标类型 | 监控指标 | 业务意义 |
|----------|----------|----------|
| **风控指标** | 超额申请率 | amount_r > quota_r 的申请占比 |
| **支付指标** | 担保费缴纳率 | status=37的订单占比 |
| **效率指标** | 平均处理时长 | 从申请到放款的时间 |
| **质量指标** | 异常订单率 | 各类异常情况的发生频率 |
### 2. 预警机制
- **额度预警**: 当超额申请率超过阈值时触发预警
- **支付预警**: 担保费缴纳超时自动提醒
- **系统预警**: API调用异常或响应超时告警
---
**文档版本**: v1.0
**最后更新**: 2024年
**维护团队**: 农业贷款系统开发组
\ No newline at end of file
docs/DEPLOYMENT_GUIDE.md 0 → 100644
# 🚀 项目部署运行指南
## 📋 环境要求
### Go环境
- **Go版本**: `1.21.13+`
- **操作系统**: Linux/macOS/Windows
- **内存**: 建议 2GB+
- **存储**: 建议 1GB+ 可用空间
### 数据库环境
- **数据库**: MySQL 5.7+
- **数据库名**: `pr_order`
- **核心数据表**: `loan_orderinfo`
- **字符集**: UTF-8
- **网络**: 确保应用可访问数据库
### 网络要求
- **应用端口**: `8970` (HTTP服务)
- **数据库端口**: `3306` (MySQL默认)
## 🔧 快速启动
### 1. 环境检查
```bash
# 检查Go版本
go version
# 输出应显示: go version go1.21.13 或更高版本
# 检查Git（用于代码下载）
git --version
# 检查MySQL连接
mysql -h数据库主机 -u用户名 -p数据库名
```
### 2. 代码部署
```bash
# 克隆项目（如果需要）
git clone <repository-url>
# 进入项目目录
cd nlt-pufa-interface
# 查看项目结构
ls -la
```
### 3. 依赖安装
```bash
# 下载Go模块依赖
go mod download
# 验证依赖完整性
go mod verify
# 查看依赖列表
go list -m all
```
### 4. 数据库配置
#### 当前配置
文件: `db/init.go`
```go
var dsn = `demeter:ajc4crb.buj-GHJ!pzw@tcp(10.0.0.2:3306)/pr_order?useUnicode=true&characterEncoding=utf8&useSSL=false`
```
#### 生产环境配置
**重要**: 修改为您的实际数据库信息
```go
var dsn = "用户名:密码@tcp(主机:端口)/数据库名?charset=utf8&parseTime=True&loc=Local"
```
#### 配置示例
```go
// 本地开发环境
var dsn = "root:password@tcp(127.0.0.1:3306)/pr_order?charset=utf8&parseTime=True&loc=Local"
// 生产环境
var dsn = "prod_user:prod_pass@tcp(192.168.1.100:3306)/pr_order?charset=utf8&parseTime=True&loc=Local"
```
### 5. 启动服务
#### 开发模式
```bash
# 直接运行（适合开发调试）
go run main.go
# 输出日志示例:
# 2024/01/01 12:00:00 Server listening on :8970
```
#### 生产模式
```bash
# 编译为可执行文件
go build -o nlt-pufa-interface main.go
# 运行可执行文件
./nlt-pufa-interface
# 后台运行
nohup ./nlt-pufa-interface > app.log 2>&1 &
```
### 6. 服务验证
```bash
# 检查服务状态
curl http://localhost:8970/
# 应该返回担保费缴纳HTML页面
# 检查进程
ps aux | grep nlt-pufa-interface
# 检查端口监听
netstat -tulpn | grep :8970
# 或使用lsof
lsof -i :8970
```
## 🏗️ 详细架构说明
### 启动流程图
```mermaid
%%{init: {'theme':'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000'}}}%%
graph TD
A[启动main.go] --> B[初始化Hertz服务器]
B --> C[配置监听端口:8970]
C --> D[注册API路由]
D --> E[数据库连接初始化]
E --> F[设置静态资源路由]
F --> G[启动HTTP服务监听]
G --> H[等待客户端请求]
I[数据库连接失败] --> J[程序异常退出]
E --> I
style A fill:#e3f2fd,stroke:#1976d2
style G fill:#c8e6c9,stroke:#388e3c
style H fill:#fff3e0,stroke:#f57c00
style I fill:#ffebee,stroke:#d32f2f
style J fill:#ffebee,stroke:#d32f2f
```
### 服务组件
| 组件 | 文件位置 | 作用 | 端口/配置 |
|------|----------|------|-----------|
| **HTTP服务器** | main.go | 处理API请求 | :8970 |
| **路由系统** | route/register.go | 接口路径映射 | 3个POST接口 |
| **数据库连接** | db/init.go | 数据持久化 | MySQL连接池 |
| **业务处理器** | handler/*.go | 业务逻辑 | 认证、支付查询等 |
| **数据模型** | model/*.go | 数据结构和加密 | SM2加密 |
| **常量配置** | nltconst/*.go | 系统常量 | 错误码、密钥等 |
| **静态资源** | html/ | 前端页面 | 担保费页面 |
### 启动代码解析
```go
func main() {
// 1. 创建Hertz服务器实例
h := server.Default(
server.WithHostPorts(":8970"), // 监听8970端口
)
// 2. 注册业务API路由
route.Register(h) // 注册3个POST接口
// 3. 静态资源路由（担保费页面）
h.GET("/", func(c context.Context, ctx *app.RequestContext) {
ctx.HTML(200, "index.html", nil)
})
// 4. 启动服务并阻塞等待
h.Spin() // 开始监听请求
}
```
## 🌐 可访问的接口
### 服务地址
- **基础URL**: `http://localhost:8970`
- **协议**: HTTP
- **内容类型**: JSON (API接口)
### 路由清单
| 方法 | 路径 | 功能 | 加密 | 用途 |
|------|------|------|------|------|
| **GET** | `/` | 担保费缴纳页面 | ❌ | 前端界面 |
| **POST** | `/nlt/pufa/auth` | 身份认证接口 | ✅ SM2 | 用户认证和贷款申请 |
| **POST** | `/nlt/pufa/queryPayResult` | 支付状态查询 | ✅ SM2 | 查询担保费支付状态 |
| **POST** | `/nlt/pufa/queryJumpUrl` | 跳转URL查询 | ❌ | 获取业务跳转链接 |
### 接口访问示例
```bash
# 1. 访问首页
curl http://localhost:8970/
# 2. 测试URL查询接口（无加密）
curl -X POST http://localhost:8970/nlt/pufa/queryJumpUrl \
-H "Content-Type: application/json" \
-d '{"duebillNoOrg":"test123"}'
# 3. 测试加密接口（需要SM2加密，较复杂）
# 参考 docs/API_INTEGRATION.md 了解加密调用方式
```
## 🐛 开发调试
### 热重载开发
```bash
# 安装air工具
go install github.com/cosmtrek/air@latest
# 创建.air.toml配置文件
cat > .air.toml << EOF
root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"
[build]
bin = "./tmp/main"
cmd = "go build -o ./tmp/main ."
delay = 1000
exclude_dir = ["assets", "tmp", "vendor", "testdata"]
exclude_file = []
exclude_regex = ["_test.go"]
exclude_unchanged = false
follow_symlink = false
full_bin = ""
include_dir = []
include_ext = ["go", "tpl", "tmpl", "html"]
kill_delay = "0s"
log = "build-errors.log"
stop_on_root = false
[color]
app = ""
build = "yellow"
main = "magenta"
runner = "green"
watcher = "cyan"
[log]
time = false
[misc]
clean_on_exit = false
EOF
# 启动热重载
air
```
### 日志调试
```bash
# 启用详细日志
export DEBUG=true
go run main.go
# 查看特定模块日志
export LOG_LEVEL=debug
go run main.go
# 重定向日志到文件
go run main.go > app.log 2>&1
```
### 性能分析
```bash
# 启用性能分析
go run main.go -cpuprofile=cpu.prof -memprofile=mem.prof
# 分析CPU使用
go tool pprof cpu.prof
# 分析内存使用
go tool pprof mem.prof
```
## 📊 运行监控
### 健康检查脚本
```bash
#!/bin/bash
# health_check.sh
# 检查服务是否运行
check_service() {
local response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8970/)
if [ "$response" = "200" ]; then
echo "✅ 服务运行正常"
return 0
else
echo "❌ 服务异常，HTTP状态码: $response"
return 1
fi
}
# 检查数据库连接
check_database() {
local response=$(curl -s -X POST http://localhost:8970/nlt/pufa/queryJumpUrl \
-H "Content-Type: application/json" \
-d '{"duebillNoOrg":"health_check"}')
if echo "$response" | grep -q "head"; then
echo "✅ 数据库连接正常"
return 0
else
echo "❌ 数据库连接异常"
return 1
fi
}
# 执行检查
echo "🔍 开始健康检查..."
check_service && check_database
echo "✨ 健康检查完成"
```
### 系统资源监控
```bash
# 监控进程资源使用
top -p $(pgrep -f nlt-pufa-interface)
# 监控内存使用
ps aux | grep nlt-pufa-interface
# 监控网络连接
netstat -tulpn | grep :8970
# 监控日志输出
tail -f app.log
```
### 性能指标
```bash
# CPU使用率
top -p $(pgrep -f nlt-pufa-interface) -n 1 | grep nlt-pufa
# 内存使用
ps -o pid,ppid,cmd,%mem,%cpu --sort=-%mem | grep nlt-pufa
# 网络连接数
netstat -an | grep :8970 | wc -l
# 磁盘IO
iotop -p $(pgrep -f nlt-pufa-interface)
```
## ⚠️ 注意事项
### 安全配置
1. **数据库密码**: 生产环境请使用强密码
2. **端口访问**: 配置防火墙限制8970端口访问
3. **SSL证书**: 生产环境建议配置HTTPS
4. **密钥管理**: SM2密钥请妥善保管
### 运维建议
1. **备份策略**: 定期备份数据库和配置文件
2. **日志轮转**: 配置日志轮转避免磁盘空间不足
3. **监控告警**: 配置服务和数据库监控告警
4. **版本管理**: 使用Git标签管理版本发布
### 故障排查
1. **服务无法启动**:
- 检查端口是否被占用
- 检查数据库连接配置
- 查看启动日志错误信息
2. **数据库连接失败**:
- 验证数据库服务是否运行
- 检查网络连通性
- 确认用户名密码正确
3. **接口调用异常**:
- 检查请求格式是否正确
- 验证SM2加密是否正确
- 查看服务端日志
## 🔧 生产环境部署
### 实际生产环境配置
本项目在生产环境中使用Docker容器化部署，具体配置如下：
#### 生产环境架构
- **服务器路径**: `/data/docker-compose/tk`
- **容器名称**: `tkservice`
- **基础镜像**: `alios:v3.0.1` (自定义阿里云OS镜像)
- **可执行文件**: `pf` (编译后的二进制文件)
- **网络**: `my_network` (外部网络)
- **日志文件**: `pf.log`
#### 实际的 docker-compose.yml 配置
```yaml
# /data/docker-compose/tk/docker-compose.yml
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
```
### 部署流程
#### 使用部署脚本（推荐）
项目提供了自动化部署脚本 `deploy.sh`：
```bash
# 标准部署
./deploy.sh
# 备份后部署
./deploy.sh -b
# 仅重启服务
./deploy.sh -r
# 查看服务状态
./deploy.sh -s
# 查看日志
./deploy.sh -l
# 回滚到上一版本
./deploy.sh --rollback
```
#### 使用 Makefile
```bash
# 编译生产版本
make build-linux
# 部署到生产环境
make deploy
# 重启生产服务
make restart
# 查看生产日志
make logs
# 查看服务状态
make status
```
#### 手动部署步骤
1. **编译应用**：
```bash
# 交叉编译Linux版本
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o pf .
```
2. **部署文件**：
```bash
# 复制到生产目录
cp pf /data/docker-compose/tk/
cp -r html /data/docker-compose/tk/
chmod +x /data/docker-compose/tk/pf
```
3. **重启服务**：
```bash
cd /data/docker-compose/tk
docker-compose restart tkservice
```
### 生产环境监控
#### 服务状态检查
```bash
# 检查容器状态
docker ps | grep tkservice
# 检查服务详情
cd /data/docker-compose/tk
docker-compose ps
# 检查端口监听
netstat -tlnp | grep 8970
```
#### 日志监控
```bash
# 实时查看日志
cd /data/docker-compose/tk
tail -f pf.log
# 查看Docker容器日志
docker-compose logs -f tkservice
# 日志分析
grep "ERROR" pf.log
grep "panic" pf.log
```
#### 健康检查脚本
```bash
#!/bin/bash
# health_check.sh
ENDPOINT="http://localhost:8970/"
TIMEOUT=5
if curl -f --connect-timeout $TIMEOUT "$ENDPOINT" > /dev/null 2>&1; then
echo "✅ 服务运行正常"
exit 0
else
echo "❌ 服务异常，请检查日志"
exit 1
fi
```
### 备份与恢复
#### 自动备份
部署脚本提供自动备份功能：
```bash
# 部署前自动备份
./deploy.sh -b
```
备份文件存储在 `/data/backup/nlt-pufa/` 目录下。
#### 手动备份
```bash
# 创建备份目录
mkdir -p /data/backup/nlt-pufa
# 备份当前版本
cd /data/docker-compose/tk
tar -czf "/data/backup/nlt-pufa/pf_$(date +%Y%m%d_%H%M%S).tar.gz" pf html/
```
#### 恢复操作
```bash
# 自动回滚到最新备份
./deploy.sh --rollback
# 手动恢复指定备份
cd /data/docker-compose/tk
tar -xzf /data/backup/nlt-pufa/pf_20240101_120000.tar.gz
docker-compose restart tkservice
```
---
**文档版本**: v1.0
**最后更新**: 2024年
**维护团队**: 普发银行农业贷款系统运维组
\ 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