起因

看这个博客发布的日常记录就知道，我是咖啡癌晚期患者，当然，我家那位也是一样。每到过年这段假期，很多咖啡馆都会歇业放假，但也有部分咖啡馆照常营业，于是，每年她都会整理出长沙市区过年期间依旧营业的咖啡馆发布出来供大家参考，今年是第六年了，往年整理见：2025年 2024年 2023年 2022年 2021年

每年整理成表格再转成图片发布，这就导致发布之后的变动不能及时更新，于是，今年我决定给她开发一个小程序，既可以方便传播信息，又能及时更新，于是经过大概一周的加班加点诞生了“咖啡小花吃”这个微信小程序。

咖啡小花吃是一个微信小程序，基于一个全栈式的咖啡馆管理与服务平台，旨在为用户提供便捷的咖啡店查找、导航及信息查询服务，同时为管理员提供强大的后台管理能力。项目涵盖了从商户数据采集、后台管理到C端用户服务的完整生态。

架构

整个小程序实际分为几个部分：

• 管理端后端：NestJS + TypeORM + MySQL 部署于 字节火山引擎轻量服务器
• 管理端前端：React + Vite + TypeScript 部署于腾讯云 EdgeOne Pages
• 商户信息收集前端：React + Vite + TypeScript 部署于腾讯云 EdgeOne Pages
• 小程序端：微信小程序原生

项目模块概览

1.管理端后端 (admin/backend)

1.1 技术栈

• 框架: NestJS (基于 Node.js 的渐进式框架)
• 语言: TypeScript
• 数据库: MySQL (使用 mysql2 驱动)
• ORM: TypeORM (Data Mapper 模式)
• 认证授权: Passport + JWT (@nestjs/passport, bcryptjs)
• 工具库:
  • class-validator / class-transformer: 数据验证与转换
  • lunar-javascript: 农历/节假日处理
  • swagger: API 文档自动生成

1.2 核心功能

• 商户管理: 商户的基础信息、地理位置、营业时间（常规/特殊/节假日）管理。
• 小程序服务: 专为小程序提供的 API，包括首页列表（按距离/时间排序）、地图数据、用户认证。
• 权限系统: 基于 RBAC (Role-Based Access Control) 的用户-角色-权限管理。
• 数据统计: 仪表盘数据聚合，展示商户状态、用户活跃度等关键指标。
• 空间计算: 基于 MySQL Spatial Extensions (POINT, ST_Distance_Sphere) 的地理位置服务。

1.3 架构设计

• 模块化架构: 采用 NestJS 推荐的 Module-Controller-Service 分层架构，业务逻辑解耦。
• RESTful API: 遵循标准 REST 风格设计接口，统一响应格式。
• 安全设计: 敏感配置加密存储，全局异常过滤器，JWT 无状态认证。

1.4 优势

• 类型安全: 全链路 TypeScript 支持，减少运行时错误。
• 高性能: 利用 MySQL 8.x 空间索引进行地理位置查询，支持高并发。
• 可维护性: 清晰的模块划分和依赖注入机制，易于测试和扩展。

1.5 核心逻辑

• 商户排序: 根据用户经纬度，利用数据库空间函数实时计算距离并排序，实现“离我最近”功能。
• 动态营业时间: 结合常规营业时间、特殊日期调整和法定节假日模板，动态计算商户当前的营业状态（营业中/ 已打烊/即将营业/休息中）。

2.管理端前端 (admin/frontend)

2.1 技术栈

• 框架: React
• 构建工具: Vite (极速冷启动与热更新)
• 语言: TypeScript
• UI 组件: 自定义组件 + lucide-react (图标库)
• 图表库: recharts (数据可视化)
• HTTP 客户端: axios
• 工具: xlsx (Excel 导出)

2.2 核心功能

• 仪表盘: 可视化展示系统关键指标和流量趋势。
• 商户全生命周期管理: 商户的创建、编辑、状态变更及图片管理。
• 系统设置: 全局参数配置、文件资源管理。
• 权限管理界面: 用户、角色、权限的可视化配置。

2.3 架构设计

• 组件化: 页面拆分为独立的业务组件（如 MerchantManagement, TrafficChart），提高复用性。
• 服务层封装: services/ 目录统一管理 API 请求，与 UI 层解耦。
• Context 状态管理: 使用 React Context (admin-profile) 处理全局用户状态，避免 Props Drilling。

2.4 优势

• 开发体验: Vite 带来的秒级启动和 HMR 体验。
• 轻量级: 不依赖庞大的 UI 框架，按需引入必要的库，保持包体积小巧。
• 响应式: 适配不同尺寸屏幕，提供良好的管理体验。

2.5 核心逻辑

• 数据交互: 采用 Hooks + Axios 模式进行数据获取与状态更新，支持分页、筛选和排序。
• 动态表单: 根据商户类型或状态动态渲染表单项，支持复杂的数据校验。

3. 商户信息收集前端 (admin/collect)

3.1 技术栈

• 框架: React
• 构建工具: Vite
• 语言: TypeScript
• 样式: CSS Modules / 原生 CSS

3.2 核心功能

• 信息采集表单: 提供简洁的界面供商户或地推人员快速录入基础信息。
• 位置标注: 集成地图组件，辅助用户准确选择商户坐标。
• 图片上传: 支持商户封面图和环境图的上传与预览。

3.3 架构设计

• 单页应用 (SPA): 专注于表单填写流程，结构扁平。
• 轻量化: 剥离了复杂的管理功能，仅保留核心采集逻辑，便于在移动端浏览器运行。

3.4 优势

• 易用性: 极简的 UI 设计，降低用户使用门槛。
• 部署灵活: 可独立部署，与管理后台解耦。

3.5 核心逻辑

• 分步验证: 表单提交前进行严格的客户端校验，确保数据完整性。
• 数据转换: 将前端友好的表单数据转换为后端所需的 DTO 格式。

4. 小程序端 (miniprogram)

4.1 技术栈

• 框架: 微信小程序原生框架
• 语言: JavaScript / WXML / WXSS
• API: 微信原生 API (Location, Request, Login等)

4.2 核心功能

• 首页列表: 展示附近的咖啡店，支持下拉刷新和触底加载分页。
• 地图模式: 在地图上标记所有商户，支持聚合显示和导航。
• 商户详情: 展示商户详细信息、营业时间状态、照片墙。
• 用户中心: 收藏管理、关于我们。

4.3 架构设计

• Page-Component: 页面与组件分离，通用功能（如商户卡片）封装为组件。
• 按需加载: 启用 lazyCodeLoading，优化首屏启动速度。

4.4 优势

• 原生体验: 流畅的动画和交互，深度集成微信生态。
• 位置服务: 充分利用微信的位置能力，实现精准的导航和距离计算。

4.5 核心逻辑

• 分页排序: 结合后端空间索引，实现基于用户当前位置的实时距离排序分页，而非前端假排序。
• 智能缓存: 对位置信息和静态数据进行适度缓存，减少不必要的网络请求。

小程序成品