SkillGo

SkillGo·技能到家是一个面向本地生活服务、活动执行和即时履约场景的前后端一体化演示项目。项目提供技能者展示、需求发布、订单履约跟踪、聊天沟通、评价与信用分、AI 客服、LBS 热区展示以及管理员后台，适合课程设计、原型演示、功能验证和二次开发。

本仓库当前同时包含：

• React + Vite 前端应用
• Node.js + Express 后端 API
• SQLite 本地数据库
• Node:test + supertest 接口测试

项目亮点

• 首页集成 3D 地球、热区地图、标签云、即时订单播报和 Flash Squad Lab 编队模块
• 技能广场支持按标签、地点、专长快速筛选，并可直接发起联系
• 发布需求后会自动匹配技能者，并生成完整的订单详情与履约节点
• 订单详情支持双向评价，评价结果会实时影响双方信用分
• 聊天中心支持一对一会话，后端会去重重复会话
• AI 客服可读取数据库内容回答平台问题，支持管理员自定义 API 地址、Key、模型和系统提示词
• AI 客服在上游模型不可用时会自动回退到常见可用模型
• 管理后台支持首页文案、用户、技能者、订单流程和 AI 配置管理
• 支持深色 / 浅色主题切换

技术栈

前端

• React 18
• Vite 5
• TypeScript
• React Router DOM 6
• Framer Motion
• Three.js

后端

• Node.js ESM
• Express 4
• SQLite + sqlite3

测试

• Node:test
• supertest

主要功能

1. 首页

首页不是简单的静态落地页，而是一个带业务状态的总览面板，包含：

• Hero 区域和平台核心指标
• EarthGlobe 3D 视图，展示技能者点位和订单履约点位
• LbsExplorer 热区地图，接入高德 JS API 2.0，失败时自动降级为静态热区模式
• 标签云和即时订单动态
• Flash Squad Lab 任务编队器，根据最新需求和技能者数据生成“主力位 + 支持位 + 执行建议”
• 最新雇佣需求列表
• 右下角快捷入口，包括聊天、发布需求、AI 客服等

2. 技能广场与技能者主页

• /providers 展示技能者卡片列表
• 支持按关键词搜索名称、专长、地点、标签
• 技能卡片支持一键联系
• /providers/:id 展示技能者详情页
• 详情页使用 ProfileMirror 聚合展示信用分、近期评价和技能档案

3. 发布需求与自动匹配

• /requests/new 支持创建新需求
• 表单字段包括雇佣者、需求主题、服务地点、预算、期望时间、优先标签
• 提交后后端自动匹配一个技能者并生成订单详情
• 订单会自动带出履约流程节点

4. 订单详情、履约和评价体系

• /requests/:id 展示订单概览、匹配技能者、履约时间线
• 同时展示雇佣者与服务者的信用分
• 支持双向评价
• 每次评价都会实时回写到被评价人的信用分
• 技能者主页会同步显示近期评价和信用信息

5. 聊天中心

• /chat 支持雇佣者和技能者一对一沟通
• 通过技能卡片“一键联系”进入会话
• 后端会对相同双方的直接会话做幂等处理
• 仓库启动时也会尝试合并历史上重复生成的会话

6. AI 客服

• /ai-support 提供对话式 AI 客服
• AI 会读取数据库中的技能者、订单和站点配置上下文来回答问题
• 管理员可配置：
  • API URL
  • API Key
  • 模型名
  • System Prompt
• 支持只填写基础地址，例如 https://api.openai.com/v1，后端会自动补成 /chat/completions
• 支持清空会话
• 支持显示当前登录昵称；未登录时显示“我”
• 当前配置模型不可用时，后端会自动回退尝试：
  • gpt-4o-mini
  • gpt-4.1-mini
  • gpt-4.1

7. 管理后台

• /admin 仅管理员可见
• 提供分区式控制台，包含：
  • 概览
  • 首页配置
  • 新增雇佣者 / 技能者
  • 用户管理
  • 技能者管理
  • 订单与流程管理
  • AI 配置管理

页面与路由

路由	说明
/	首页总览
/login	登录 / 注册
/providers	技能广场
/providers/:id	技能者详情页
/requests/new	发布需求
/requests/:id	订单详情、履约、评价
/chat	聊天中心
/ai-support	AI 客服
/admin	管理后台

项目结构

SkillGo/
├─ public/ # 静态资源
├─ server/
│ ├─ data/ # SQLite 数据库默认目录
│ ├─ tests/ # 后端接口测试
│ ├─ app.js # Express 应用与 API 路由
│ ├─ db.js # 数据库、种子数据、Repository
│ └─ index.js # 后端启动入口
├─ src/
│ ├─ components/ # 通用 UI 组件
│ ├─ data/ # 前端兜底数据
│ ├─ hooks/ # Auth/useAsyncData 等 hooks
│ ├─ layouts/ # 首页/详情页布局组件
│ ├─ pages/ # 路由页面
│ ├─ services/ # API 请求封装
│ ├─ styles/ # 全局样式
│ ├─ types/ # TypeScript 类型定义
│ ├─ App.tsx # 路由注册
│ └─ main.tsx # 前端入口
├─ .storybook/ # Storybook 配置
├─ package.json
├─ vite.config.ts
└─ README.md

环境要求

建议环境：

• Node.js 20+，最低建议 18+
• npm 9+

项目使用了：

• ESM
• 顶层 await
• 原生 fetch

因此不建议使用过旧的 Node 版本。

快速开始

1. 安装依赖

npm install

2. 可选：配置本地地图环境变量

在项目根目录创建 .env.local：

VITE_AMAP_KEY=你的高德 Web Key
VITE_AMAP_SECURITY_JS_CODE=你的高德安全密钥

如果不配置，地图模块会自动退化为静态热区模式，页面仍可正常使用。

3. 启动后端

npm run dev:server

默认监听：

• API: http://localhost:3001

4. 启动前端

npm run dev

默认监听：

• Vite 开发端口: http://localhost:4173

5. 同时启动前后端

npm run dev:full

环境变量

前端变量

变量名	说明	默认值
VITE_AMAP_KEY	高德地图 Web Key	无
VITE_AMAP_SECURITY_JS_CODE	高德地图安全密钥	无

后端变量

变量名	说明	默认值
PORT	后端服务端口	3001
SKILLGO_DB_PATH	SQLite 数据库文件路径	server/data/skillgo.db

默认账号

项目内置了演示账号，登录页也会直接提示：

角色	账号	密码
高级管理员	admin	admin123
雇佣者	customer	customer123
技能者	provider-er	provider123

同时前端也支持注册：

• customer
• provider

注册成功后会自动登录。

默认演示数据

首次启动后端时会自动创建数据库并写入种子数据，包括：

• 技能者
• 雇佣需求
• 首页站点内容
• 管理员与普通用户账号
• AI 设置默认值

当前默认数据量大致为：

• 10+ 技能者
• 10+ 雇佣需求

重要的数据持久化说明

当前仓库更偏“演示 / 课程项目”模式，数据库种子在启动时会重复执行。

这意味着：

• 内置的首页文案、内置用户、内置技能者、内置订单会在启动时被种子数据重新 upsert
• 你在后台修改这些“内置演示数据”后，重启服务可能被种子覆盖
• AI 设置表使用 ON CONFLICT DO NOTHING，管理员保存后的 AI 配置会保留
• 聊天消息、评价记录、运行中新创建的数据会写入 SQLite 文件中

如果你准备把项目用于长期运行，建议下一步把“只在数据库首次创建时 seed”改成更标准的迁移/初始化模式。

可用脚本

命令	说明
npm run dev	启动前端开发服务器
npm run dev:server	启动后端 API
npm run dev:full	同时启动前后端
npm run build	构建前端生产包
npm run preview	预览前端构建产物
npm run start	启动后端生产服务
npm run test:server	运行后端接口测试
npm run storybook	启动 Storybook
npm run build-storybook	构建 Storybook

API 概览

以下为主要接口分组。

认证

• POST /api/auth/login
• POST /api/auth/register
• GET /api/auth/me

面板与技能者

• GET /api/dashboard
• GET /api/providers
• GET /api/providers/:id

需求与订单

• GET /api/requests
• GET /api/requests/:id
• POST /api/requests
• POST /api/requests/:id/reviews

聊天

• GET /api/chat/conversations
• POST /api/chat/conversations
• GET /api/chat/conversations/:id/messages
• POST /api/chat/conversations/:id/messages

AI 客服

• GET /api/ai/settings
• PUT /api/ai/settings
• POST /api/ai/support

管理后台

• GET /api/admin/snapshot
• PUT /api/admin/site-content
• POST /api/admin/users
• PUT /api/admin/users/:id
• DELETE /api/admin/users/:id
• POST /api/admin/providers
• PUT /api/admin/providers/:id
• DELETE /api/admin/providers/:id
• PUT /api/admin/requests/:id
• DELETE /api/admin/requests/:id

核心业务规则

1. 评价与信用分

• 评分必须是 1 到 5 的整数
• 评论内容必填，最多 280 字
• 评价成功后会立即更新被评价人的信用分
• 订单详情页与技能者详情页会同步展示最新评价信息

2. 聊天会话去重

• 同一对用户直接发起会话时，后端会复用已有会话
• 仓库启动时也会尝试合并重复的历史直聊会话

3. AI 客服上下文

AI 客服不会只做纯文本聊天，而是会在请求时读取数据库上下文，主要包括：

• 相关技能者
• 相关订单
• 平台站点配置

如果 AI 上游返回的是不支持当前模型的错误，后端会自动回退常见模型，并在全部失败时给出更友好的中文提示。

4. 地图降级策略

若高德地图 SDK 加载失败、Key 不可用、域名未加白名单或运行时不可用：

• 页面会显示静态热区模式
• 不会阻塞首页其余业务功能

测试说明

运行：

npm run test:server

当前后端测试覆盖了以下核心场景：

• 仪表盘和种子数据可用
• 发布需求能自动生成订单详情和履约事件
• 同一对用户创建聊天会话保持幂等
• 评价会回写信用分
• AI 配置保存成功
• AI 请求可带数据库上下文
• AI 模型不可用时可自动回退
• 所有回退模型不可用时返回友好提示
• 仓库启动时可合并重复会话
• 管理员可新增雇佣者与技能者
• 请求表单校验有效

生产部署

推荐部署方式

推荐采用“前端静态站点 + Node API + Nginx 反向代理 + SQLite”的方式。

原因：

• 前端构建产物是 dist
• 后端 npm run start 只启动 API，不负责托管前端静态文件
• 前端生产请求使用相对路径 /api
• 因此生产环境需要 Web 服务器将 /api 代理到 Node 服务

通用部署步骤

1. 安装依赖

npm install

2. 配置生产环境变量

# 前端
VITE_AMAP_KEY=你的高德 Key
VITE_AMAP_SECURITY_JS_CODE=你的高德安全密钥
# 后端
PORT=3001
SKILLGO_DB_PATH=/your/path/skillgo.db

3. 构建前端

npm run build

4. 启动后端

npm run start

5. 用 Nginx 托管 dist，并将 /api 反代到后端

Nginx 配置示例

location / {try_files$uri$uri/ /index.html;}location /api/ {proxy_passhttp://127.0.0.1:3001;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;}

宝塔部署建议

如果你使用宝塔面板，推荐按下面方式部署：

1. 安装 Nginx
2. 安装 Node.js 管理器 或 PM2 管理器
3. 上传项目到服务器
4. 执行：

cd /www/wwwroot/SkillGo
npm install
npm run build

5. 在宝塔创建 Node 项目

• 项目目录：项目根目录
• 启动命令：npm run start
• 端口：3001

6. 配置后端环境变量

PORT=3001
SKILLGO_DB_PATH=/www/wwwroot/skillgo-data/skillgo.db

7. 新建网站，根目录指向：

/www/wwwroot/SkillGo/dist

8. 在站点 Nginx 配置里加入上面的 / 与 /api/ 规则

9. 如果要启用地图：

• 到高德开放平台配置正式域名白名单
• 填写 VITE_AMAP_KEY
• 填写 VITE_AMAP_SECURITY_JS_CODE

常见问题

1. 首页地图只显示静态热区

通常是以下原因之一：

• 未配置 VITE_AMAP_KEY
• 未配置 VITE_AMAP_SECURITY_JS_CODE
• 高德控制台域名白名单未配置
• 当前网络无法加载高德 SDK

2. 生产环境页面能打开，但接口 404

通常说明：

• Nginx 没有把 /api 反代到 Node 服务
• 或后端没有启动成功

3. AI 客服提示模型不可用

请检查管理员后台中的模型名是否为渠道真实支持的名称。当前系统会优先尝试管理员填写的模型，并在失败时自动回退常见模型。

4. npm run start 之后前端页面打不开

这是正常的。npm run start 只启动后端 API，不会直接提供 Vite 打包后的前端静态资源。生产环境需要 Nginx 或其他静态服务器托管 dist。

5. Windows 终端看到中文乱码

如果你在 Windows PowerShell / CMD 中看到中文乱码，通常是终端编码问题，不一定代表源码本身损坏。建议使用 UTF-8 终端或 Windows Terminal，并确认编辑器以 UTF-8 保存文件。

6. 后台修改的数据重启后丢失

请先确认你修改的是不是“内置种子数据”。当前种子逻辑会在启动时重复 upsert 一部分演示数据，详见上方“重要的数据持久化说明”。

后续优化建议

如果你准备把这个项目从课程演示继续推进到更正式的应用，建议优先做这些改造：

• 将数据库 seed 改成只在首次初始化时执行
• 为后端补充迁移脚本
• 将 SQLite 切换为 MySQL / PostgreSQL
• 将鉴权改为更完整的会话或 JWT 体系
• 为聊天加入轮询或 WebSocket
• 为 AI 客服增加模型列表与健康检测
• 增加 CI、Lint、格式化和端到端测试

License

本项目包含 LICENSE 文件，请按仓库中的许可证使用。