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

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

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

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

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

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

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

• /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

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

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 版本。

npm install

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

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

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

npm run dev:server

默认监听：

• API: http://localhost:3001

npm run dev

默认监听：

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

npm run dev:full

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

同时前端也支持注册：

• customer
• provider

注册成功后会自动登录。

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

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

当前默认数据量大致为：

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

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

这意味着：

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

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

以下为主要接口分组。

• 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

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

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

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

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

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

若高德地图 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 反代到后端

location / {
    try_files $uri $uri/ /index.html;
}

location /api/ {
    proxy_pass http://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

通常是以下原因之一：

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

通常说明：

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

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

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

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

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

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

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

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