name: parcel-station-chat
description: "Build a courier station AI chat system with Express, GPT-5.5, local JSON DB, OCR, and WeChat-style frontend."

快递驿站智能客服系统

快速搭建快递驿站 AI 客服系统。Express 后端 + GPT-5.5 对话 + JSON 本地数据库 + 面单 OCR + 微信风格聊天前端。

系统架构

用户 (微信小程序/浏览器)
        │
   POST /api/chat
   POST /api/ocr
   GET  /api/packages/:code
        │
┌───────▼──────────────────────┐
│  Express server.js (v3.1)    │
│  ├ loadApiConfig() → SU2     │
│  ├ buildLookupBlock()        │
│  │  ├ extractPickupCode()    │
│  │  └ extractTrackingTail()  │
│  ├ callAI() → GPT-5.5       │
│  └ handleFallback()          │
├──────────────────────────────┤
│  db.js (JSON 文件存储)        │
│  ├ findByPickupCode()        │
│  ├ findByTrackingTail()      │
│  ├ findByPhoneTail()         │
│  ├ listPackages() (分页)     │
│  └ insertPackage()           │
├──────────────────────────────┤
│  ocr.js (GPT-5.5 Vision)    │
│  └ recognizeWaybill()        │
└──────────────────────────────┘

取件码格式

1-2-25001
│ │ ││││
│ │ │││└── 001 = 当天第1个包裹
│ │ ││└─── 25 = 日期(当月第几天)
│ │ └┴──── 5位日期序号(DDNNN)
│ └────── 排号
└──────── 货架号

正则：/(\d{1,2})\s*[-－—–]\s*(\d{1,2})\s*[-－—–]\s*(\d{5})/

搭建步骤

1. 初始化项目

mkdir parcel-help && cd parcel-help
npm init -y
npm install express

2. 创建 db.js

JSON 文件存储，零原生依赖。关键函数：

• findByPickupCode(code) — 取件码查询
• findByTrackingTail(tail) — 运单号后5位查询
• findByPhoneTail(tail) — 手机尾号4位查询
• listPackages({page, pageSize, q}) — 分页+搜索
• insertPackage(p) — 新增包裹（含冲突检测）

种子数据：12条包裹覆盖全部货架，当天日期自动计算。

3. 创建 ocr.js

调用 GPT-5.5 Vision 识别面单，返回 JSON：

{"pickup_code":"","tracking_no":"","recipient_name":"","recipient_phone_tail":"","carrier":"","confidence":"low|medium|high"}

注意：AI 可能返回 markdown 包裹的 JSON，parseOcrJson 需处理 `json ` 。

4. 创建 server.js

核心逻辑流程：

1. loadApiConfig() → 读 SU2APIKEY + baseUrl
2. buildLookupBlock(message) → 自动识别取件码/运单号尾号
3. 有 AI → callAI() → 带会话历史 + 查库结果
4. 无 AI → handleFallback() → 本地关键词+查库

会话管理：30分钟 TTL，保留最近5轮对话。

5. 创建前端 (public/index.html)

微信风格聊天界面，注意：

• ❌ 不加入"管理"入口（客户端）
• ✅ 底部快捷按钮：找不到包裹 / 取件码说明 / 运单号查询
• ✅ 支持图片上传拍照
• ✅ 移动端优化

6. 启动测试

node server.js
# 聊天界面: http://localhost:3000
# 管理后台: http://localhost:3000/admin.html
# 健康检查: http://localhost:3000/api/health

API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/health | 健康检查（版本、AI状态、数据库总量） |
| POST | /api/chat | 聊天（message + image + sessionId） |
| POST | /api/ocr | 面单识别（image） |
| GET | /api/packages | 包裹列表（page, pageSize, q） |
| POST | /api/packages | 录入包裹 |
| GET | /api/packages/:code | 按取件码查询 |

核心设计决策

1. 不用 better-sqlite3 — Windows 需要 VC++ 编译工具，改用纯 JS JSON 文件存储
2. 不用 shelfcolor/shelfarea — 真实驿站用"第X号货架 第Y排"，不设颜色/区号
3. 取件码正则匹配 5 位日期序号 — 区别于其他数字输入
4. 运单号查询 — 匹配 5 位及以上连续数字，支持部分单号
5. 管理后台单独存在 — 不和客户端 UI 混在一起

坑与注意事项

• better-sqlite3 在 Windows 编译失败 → 换 JSON
• Unicode 中文在 taskkill /F /IM node.exe 后可能输出乱码，但服务正常
• API 调用超时默认 30s，中转站偶尔延迟需重试
• curl.exe 在 PowerShell 中 JSON 引号会转义出错 → 用 Invoke-RestMethod