# 失物招领小程序 **Repository Path**: cayley_yu/lost-and-found-mini-program ## Basic Information - **Project Name**: 失物招领小程序 - **Description**: 失物招领小程序，包含发布、管理失物招领信息的基础功能 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2025-11-20 - **Last Updated**: 2025-11-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 校园失物招领小程序

**中山大学失物招领微信小程序系统** 一个基于 UniApp + Vue3 + Gin + MySQL 的全栈失物招领平台 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Gitee](https://img.shields.io/badge/Gitee-项目地址-red.svg)](https://gitee.com/cayley_yu/lost-and-found-mini-program) [![Stars](https://gitee.com/cayley_yu/lost-and-found-mini-program/badge/star.svg)](https://gitee.com/cayley_yu/lost-and-found-mini-program/stargazers) [功能特点](#功能特点) • [技术架构](#技术架构) • [快速开始](#快速开始) • [项目结构](#项目结构) • [API文档](#api-文档)

--- ## 项目简介本项目是一个面向中山大学在校师生的失物招领微信小程序，旨在帮助用户快速发布和查找丢失物品信息，提供便捷的校园失物招领服务。 ### 核心价值 - 📱 **便捷发布**：一键发布失物或招领信息，支持图片上传和地点选择 - 🔍 **智能搜索**：基于 Python 的模糊搜索算法，支持中文拼音和错别字容错 - 👤 **个人中心**：管理个人发布记录，追踪物品状态 - 🎯 **精准匹配**：多维度搜索，快速找到相关信息 --- ## 功能特点 ### 📋 信息管理 - ✅ 发布失物/招领信息 - ✅ 编辑和删除个人发布 - ✅ 标记信息状态（进行中/已完成/已取消） - ✅ 查看发布历史记录 ### 🔎 搜索功能 - ✅ 多字段模糊搜索（标题、描述、地点、分类） - ✅ 中文拼音搜索支持 - ✅ 智能相似度匹配算法 - ✅ 可调节相似度阈值（默认60%） - ✅ 搜索结果按相似度排序 ### 👥 用户系统 - ✅ 微信小程序登录授权 - ✅ JWT Token 认证机制 - ✅ 个人信息管理 - ✅ 用户状态控制 ### 📊 其他特性 - ✅ 分页加载优化 - ✅ 下拉刷新/上拉加载 - ✅ 浏览次数统计 - ✅ 图片上传和展示 - ✅ 地图地点选择 - ✅ 响应式界面设计 --- ## 技术架构 ### 前端技术栈 | 技术 | 版本 | 说明 | |------|------|------| | [uni-app](https://uniapp.dcloud.io/) | 3.0+ | 跨平台应用开发框架 | | [Vue.js](https://vuejs.org/) | 3.3.4 | 渐进式 JavaScript 框架 | | [Pinia](https://pinia.vuejs.org/) | 2.1.6 | Vue 状态管理库 | | [uni-ui](https://uniapp.dcloud.io/component/uniui/uni-ui.html) | 1.5.11 | uni-app 官方 UI 组件库 | | Sass | 1.66.1 | CSS 预处理器 | | TypeScript | 5.1.6 | JavaScript 超集 | ### 后端技术栈 | 技术 | 版本 | 说明 | |------|------|------| | [Go](https://golang.org/) | 1.19+ | 高性能编程语言 | | [Gin](https://gin-gonic.com/) | 1.9.1 | 轻量级 Web 框架 | | [GORM](https://gorm.io/) | 1.25.2 | Go ORM 库 | | [JWT](https://jwt.io/) | 5.0.0 | JSON Web Token 认证 | | [Viper](https://github.com/spf13/viper) | 1.16.0 | 配置管理库 | | MySQL | 8.0+ | 关系型数据库 | ### 算法模块 | 技术 | 说明 | |------|------| | Python | 3.7+ | | [rapidfuzz](https://github.com/maxbachmann/RapidFuzz) | 高性能模糊匹配库（C++实现） | | [pypinyin](https://github.com/mozillazg/python-pinyin) | 中文拼音转换库 | ### 系统架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 微信小程序前端 │ │ (UniApp + Vue3 + Pinia) │ └──────────────────────────┬──────────────────────────────────┘ │ HTTPS/REST API │ ┌──────────────────────────▼──────────────────────────────────┐ │ Gin 后端服务器 │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 路由层 │ │ 中间件 │ │ 业务逻辑 │ │ │ │ (Router) │ │ (Middleware)│ │ (Services) │ │ │ └─────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ └─────────────────┼──────────────────┘ │ │ │ │ │ ┌─────────────────▼──────────────────┐ │ │ │ 数据模型层 (GORM) │ │ │ └─────────────────┬──────────────────┘ │ └───────────────────────────┼──────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ┌─────────▼────────┐ ┌──────▼──────┐ ┌───────▼────────┐ │ MySQL 数据库 │ │ 文件存储 │ │ Python 算法 │ │ │ │ (uploads) │ │ (模糊搜索) │ └──────────────────┘ └─────────────┘ └────────────────┘ ``` --- ## 项目结构 ``` 失物招领小程序/ ├── front-end/ # 前端项目目录 │ ├── src/ │ │ ├── pages/ # 页面文件 │ │ │ ├── index/ # 首页（信息列表） │ │ │ │ └── index.vue │ │ │ ├── publish/ # 发布页面 │ │ │ │ └── publish.vue │ │ │ ├── detail/ # 详情页面 │ │ │ │ └── detail.vue │ │ │ ├── edit/ # 编辑页面 │ │ │ │ └── edit.vue │ │ │ └── profile/ # 个人中心 │ │ │ ├── profile.vue # 个人中心首页 │ │ │ ├── my-publish.vue # 我的发布 │ │ │ ├── settings.vue # 个人设置 │ │ │ └── about.vue # 关于我们 │ │ ├── components/ # 组件 │ │ │ └── SearchBar.vue # 搜索栏组件 │ │ ├── api/ # API 接口封装 │ │ │ ├── auth.js # 认证接口 │ │ │ └── items.js # 物品接口 │ │ ├── utils/ # 工具函数 │ │ │ └── request.js # 请求封装 │ │ ├── store/ # Pinia 状态管理 │ │ ├── static/ # 静态资源 │ │ ├── App.vue # 应用入口 │ │ ├── main.js # 主入口文件 │ │ ├── pages.json # 页面配置 │ │ └── manifest.json # 应用配置 │ ├── package.json # 依赖配置 │ └── vite.config.js # Vite 配置 │ ├── back-end/ # 后端项目目录 │ ├── config/ # 配置管理 │ │ └── config.go # 配置加载（Viper） │ ├── middleware/ # 中间件 │ │ ├── jwt.go # JWT 认证中间件 │ │ └── logger.go # 日志中间件 │ ├── models/ # 数据模型 │ │ ├── database.go # 数据库连接 │ │ └── user.go # 用户模型 │ ├── routes/ # 路由 │ │ ├── router.go # 路由注册 │ │ ├── auth/ # 认证路由 │ │ │ └── auth.go │ │ ├── api/ # API 路由 │ │ │ ├── user.go # 用户相关 │ │ │ ├── items.go # 物品相关 │ │ │ └── fuzzy_search.go # 模糊搜索 │ │ └── upload/ # 上传路由 │ │ └── upload.go │ ├── uploads/ # 文件上传目录 │ ├── logs/ # 日志目录 │ ├── docs/ # 文档 │ │ └── database.sql # 数据库表结构 │ ├── main.go # 主入口文件 │ ├── go.mod # Go 依赖管理 │ └── go.sum # 依赖校验文件 │ ├── algorithm/ # 算法模块 │ ├── fuzzy_search.py # 模糊搜索算法 │ ├── requirements.txt # Python 依赖 │ ├── test_api.py # API 测试脚本 │ ├── test_input.json # 测试输入数据 │ └── README.md # 算法文档 │ ├── README.md # 项目说明文档 └── FUZZY_SEARCH_IMPLEMENTATION.md # 模糊搜索实现文档 ``` --- ## 快速开始 ### 环境要求 - **Node.js**: 14.0+ - **Go**: 1.19+ - **Python**: 3.7+ - **MySQL**: 8.0+ - **微信开发者工具**: 最新版 ### 1. 克隆项目 ```bash git clone https://gitee.com/cayley_yu/lost-and-found-mini-program.git cd lost-and-found-mini-program ``` ### 2. 数据库初始化 ```bash # 登录 MySQL mysql -u root -p # 执行数据库脚本 source back-end/docs/database.sql ``` 数据库表结构包括： - `users` - 用户表 - `lost_found_items` - 失物招领信息表 ### 3. 后端启动 ```bash cd back-end # 安装 Go 依赖 go mod download # 创建配置文件（可选） cp config.example.yaml config.yaml # 编辑 config.yaml 配置数据库连接等信息 # 启动服务 go run main.go ``` 后端服务将运行在 `http://localhost:8080` **默认配置**： - 端口: 8080 - 数据库: lost_found - JWT密钥: your-secret-key-change-in-production（生产环境请修改） ### 4. Python 算法模块安装 ```bash cd algorithm # 安装依赖 pip install -r requirements.txt ``` ### 5. 前端启动 ```bash cd front-end # 安装依赖 npm install # 开发环境运行（微信小程序） npm run dev:mp-weixin # 构建生产版本 npm run build:mp-weixin ``` ### 6. 微信开发者工具配置 1. 打开微信开发者工具 2. 导入项目：选择 `front-end/dist/dev/mp-weixin` 目录 3. 配置 AppID（在 `manifest.json` 中修改） 4. 配置合法域名（在微信公众平台后台配置） 5. 启动项目调试 ### 7. 配置说明 #### 前端配置修改 `front-end/src/utils/request.js` 中的 API 基础路径： ```javascript const BASE_URL = 'http://localhost:8080'; // 开发环境 // const BASE_URL = 'https://your-domain.com'; // 生产环境 ``` #### 后端配置创建 `back-end/config.yaml`（可选，默认使用代码中的默认值）： ```yaml app: name: LostFoundBackend env: development debug: true server: port: 8080 host: 0.0.0.0 database: host: localhost port: 3306 name: lost_found username: root password: your_password charset: utf8mb4 parse_time: true loc: Local jwt: secret: your-secret-key-change-in-production expire_hours: 24 upload: path: ./uploads max_size: 10MB allowed_types: - jpg - jpeg - png - gif log: level: info file: logs/app.log ``` --- ## API 文档 ### 基础信息 - **Base URL**: `http://localhost:8080` - **认证方式**: JWT Bearer Token - **内容类型**: `application/json` ### 认证接口 #### 1. 微信登录 ```http POST /auth/login Content-Type: application/json { "code": "微信登录code" } ``` **响应示例**： ```json { "status": "success", "data": { "token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": 1, "nickname": "张三", "avatar_url": "https://..." } } } ``` #### 2. 刷新 Token ```http POST /auth/refresh Authorization: Bearer {token} ``` #### 3. 登出 ```http POST /auth/logout Authorization: Bearer {token} ``` ### 物品信息接口 #### 1. 获取物品列表（公开） ```http GET /api/public/items?type=1&status=1&page=1&size=10 ``` **查询参数**： - `type`: 类型（1=失物，2=招领） - `status`: 状态（1=进行中，2=已完成，0=已取消） - `page`: 页码（默认1） - `size`: 每页数量（默认10） - `category`: 分类 **响应示例**： ```json { "status": "success", "data": { "items": [ { "id": 1, "title": "黑色钱包丢失", "description": "今天下午2点左右在图书馆三楼...", "type": 1, "category": "证件", "location": "中山大学图书馆三楼", "contact_info": "13800138000", "images": ["https://..."], "status": 1, "view_count": 10, "created_at": "2025-11-20T10:00:00Z", "user": { "id": 1, "nickname": "张三" } } ], "pagination": { "page": 1, "size": 10, "total": 100, "pages": 10 } } } ``` #### 2. 模糊搜索（公开） ```http GET /api/public/items/search?keyword=钱包&threshold=60&page=1&size=10 ``` **查询参数**： - `keyword`: 搜索关键词（必填） - `threshold`: 相似度阈值 0-100（默认60） - `page`: 页码 - `size`: 每页数量 **响应示例**： ```json { "status": "success", "data": { "items": [ { "id": 1, "title": "黑色钱包丢失", "similarity_score": 95.0, "match_field": "title", ... } ], "keyword": "钱包", "threshold": 60, "search_type": "fuzzy", "pagination": { "page": 1, "size": 10, "total": 5, "pages": 1 } } } ``` #### 3. 获取物品详情 ```http GET /api/public/items/:id ``` #### 4. 发布物品信息（需认证） ```http POST /api/items Authorization: Bearer {token} Content-Type: application/json { "type": 1, "title": "黑色钱包丢失", "description": "详细描述...", "category": "证件", "location": "图书馆三楼", "lost_time": "2025-11-20T14:00:00Z", "contact_info": "13800138000", "images": ["https://..."] } ``` #### 5. 更新物品信息（需认证） ```http PUT /api/items/:id Authorization: Bearer {token} Content-Type: application/json ``` #### 6. 删除物品信息（需认证） ```http DELETE /api/items/:id Authorization: Bearer {token} ``` #### 7. 标记完成（需认证） ```http POST /api/items/:id/complete Authorization: Bearer {token} ``` ### 用户接口 #### 1. 获取用户信息 ```http GET /api/user/profile Authorization: Bearer {token} ``` #### 2. 更新用户信息 ```http PUT /api/user/profile Authorization: Bearer {token} Content-Type: application/json { "nickname": "新昵称", "phone": "13800138000", "real_name": "张三" } ``` #### 3. 获取我的发布 ```http GET /api/user/items?page=1&size=10 Authorization: Bearer {token} ``` #### 4. 获取用户统计 ```http GET /api/user/stats Authorization: Bearer {token} ``` ### 文件上传接口 ```http POST /upload/image Authorization: Bearer {token} Content-Type: multipart/form-data file: ``` **响应示例**： ```json { "status": "success", "data": { "url": "http://localhost:8080/uploads/xxx.jpg" } } ``` --- ## 数据库设计 ### 用户表 (users) | 字段 | 类型 | 说明 | |------|------|------| | id | BIGINT | 主键，自增 | | openid | VARCHAR(128) | 微信openid，唯一索引 | | nickname | VARCHAR(50) | 昵称 | | avatar_url | VARCHAR(255) | 头像URL | | phone | VARCHAR(20) | 手机号 | | real_name | VARCHAR(50) | 真实姓名 | | student_id | VARCHAR(20) | 学号/工号（预留） | | campus | VARCHAR(50) | 校区（预留） | | status | TINYINT | 状态（1=正常，0=禁用） | | created_at | TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | 更新时间 | ### 失物招领信息表 (lost_found_items) | 字段 | 类型 | 说明 | |------|------|------| | id | BIGINT | 主键，自增 | | user_id | BIGINT | 用户ID，外键 | | type | TINYINT | 类型（1=失物，2=招领） | | title | VARCHAR(100) | 标题 | | description | TEXT | 详细描述 | | category | VARCHAR(50) | 分类 | | location | VARCHAR(100) | 地点 | | lost_time | TIMESTAMP | 丢失/拾获时间 | | contact_info | VARCHAR(100) | 联系方式 | | images | JSON | 图片URL数组 | | status | TINYINT | 状态（1=进行中，2=已完成，0=已取消） | | view_count | INT | 浏览次数 | | created_at | TIMESTAMP | 创建时间 | | updated_at | TIMESTAMP | 更新时间 | **索引设计**： - `idx_user_id`: 用户ID索引 - `idx_type_status`: 类型和状态联合索引 - `idx_location`: 地点索引 - `idx_category`: 分类索引 - `idx_created_at`: 创建时间索引 - `idx_title`: 标题索引 --- ## 模糊搜索算法 ### 算法特性本项目采用基于 Python 的高性能模糊搜索算法，具备以下特性： #### 1. 多种匹配算法 - **完全包含匹配**：优先级最高，精确匹配 - **WRatio 算法**：对中文友好的模糊比率匹配 - **部分比率匹配**：适用于长文本的部分匹配 - **Token 排序比率**：忽略词序的匹配 - **拼音匹配**：支持拼音搜索（如 "qianbao" 匹配 "钱包"） #### 2. 搜索字段 - 标题 (title) - 描述 (description) - 地点 (location) - 分类 (category) #### 3. 相似度阈值 | 阈值范围 | 匹配程度 | 使用场景 | |---------|----------|----------| | 90-100 | 几乎完全匹配 | 精确搜索 | | 70-89 | 高度相似 | 标准搜索 | | 60-69 | 中等相似 | 宽松搜索（默认） | | 50-59 | 低相似度 | 超宽松搜索 | | <50 | 不相关 | 不推荐 | ### 性能优化 - 使用 rapidfuzz 库（C++ 底层实现） - 支持批量搜索 - 拼音转换结果缓存 - 结果按相似度排序 ### 使用示例 ```bash # 中文搜索 curl "http://localhost:8080/api/public/items/search?keyword=钱包" # 拼音搜索 curl "http://localhost:8080/api/public/items/search?keyword=qianbao" # 调整阈值 curl "http://localhost:8080/api/public/items/search?keyword=手机&threshold=70" ``` 详细文档请参考：[FUZZY_SEARCH_IMPLEMENTATION.md](./FUZZY_SEARCH_IMPLEMENTATION.md) --- ## 部署指南 ### 开发环境已在上面的[快速开始](#快速开始)部分说明。 ### 生产环境部署 #### 1. 前端部署 ```bash cd front-end # 构建微信小程序 npm run build:mp-weixin # 上传至微信公众平台 # 使用微信开发者工具上传代码并提交审核 ``` **微信小程序配置**： 1. 在微信公众平台配置服务器域名 2. 配置业务域名（如需使用 Web-view） 3. 设置合法域名（request、uploadFile、downloadFile） #### 2. 后端部署 **方式一：直接部署** ```bash cd back-end # 构建可执行文件 go build -o lost-found-backend main.go # 运行 ./lost-found-backend ``` **方式二：使用 Docker** ```dockerfile # Dockerfile 示例 FROM golang:1.19-alpine AS builder WORKDIR /app COPY . . RUN go mod download RUN go build -o main . FROM alpine:latest RUN apk --no-cache add ca-certificates python3 py3-pip WORKDIR /root/ COPY --from=builder /app/main . COPY --from=builder /app/algorithm ./algorithm RUN pip3 install -r algorithm/requirements.txt EXPOSE 8080 CMD ["./main"] ``` **方式三：宝塔面板部署** 1. 上传代码到服务器 2. 安装 Go 环境 3. 安装 Python 环境和依赖 4. 配置 Supervisor 守护进程 5. 配置 Nginx 反向代理 6. 配置 SSL 证书 #### 3. Nginx 配置示例 ```nginx server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } location /uploads/ { alias /path/to/uploads/; } } ``` #### 4. 数据库配置 ```sql -- 创建数据库用户（生产环境） CREATE USER 'lost_found'@'localhost' IDENTIFIED BY 'strong_password'; GRANT ALL PRIVILEGES ON lost_found.* TO 'lost_found'@'localhost'; FLUSH PRIVILEGES; -- 导入数据表 USE lost_found; SOURCE /path/to/database.sql; ``` #### 5. 环境变量配置生产环境建议使用环境变量： ```bash export APP_ENV=production export DB_HOST=localhost export DB_PORT=3306 export DB_NAME=lost_found export DB_USER=lost_found export DB_PASSWORD=strong_password export JWT_SECRET=your-super-secret-key export SERVER_PORT=8080 ``` --- ## 开发规范 ### 代码规范 #### 前端 - 遵循 ESLint 规范 - 组件命名使用 PascalCase - 文件命名使用 kebab-case - 使用 Composition API（Vue 3） #### 后端 - 遵循 Go 官方代码规范 - 使用 gofmt 格式化代码 - 包命名使用小写单词 - 导出函数使用大写字母开头 #### Python - 遵循 PEP 8 规范 - 使用 4 空格缩进 - 函数命名使用 snake_case ### Git 提交规范 ``` ():