# CNC 销售工作台 — 后端服务

为单文件 PWA 前端（`cnc-sales-workbench.html`）提供的 Go + SQLite 后端：
统一认证、多用户数据隔离、客户/任务/资料在线 CRUD、聚合看板与备份导入导出。

## 技术栈

- Go 1.22+（标准库 `net/http` 路由，无 Web 框架）
- SQLite（`modernc.org/sqlite` 纯 Go 驱动，无 CGO，单文件数据库）
- JWT 认证（`golang-jwt/jwt/v5`）+ bcrypt 密码哈希

## 快速开始

```bash
cd cnc-sales-backend
go build -o bin/cnc-server .
./bin/cnc-server
# 启动后访问 http://localhost:8080/（自动跳转到工作台页面）
```

环境变量（均有默认值）：

| 变量 | 默认值 | 说明 |
|---|---|---|
| `PORT` | `8080` | 监听端口 |
| `DB_PATH` | `data/cnc.db` | SQLite 数据文件路径 |
| `STATIC_DIR` | `static` | 前端静态资源目录 |
| `JWT_SECRET` | 开发默认值 | **生产必须设置**，用于 JWT 签名 |

## API 一览

所有业务接口需携带请求头 `Authorization: Bearer <token>`。

### 认证（公开）
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/api/auth/register` | 注册（首个用户自动为 admin） |
| POST | `/api/auth/login` | 登录，返回 `{token, user}` |
| GET | `/api/auth/me` | 当前用户信息 |

### 客户档案
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/customers` | 列表，支持 `stage/level/industry/q` 筛选 |
| POST | `/api/customers` | 新建（company 必填） |
| GET | `/api/customers/{id}` | 详情（含联系人、跟进记录） |
| PUT | `/api/customers/{id}` | 全量更新（子表全量重建） |
| DELETE | `/api/customers/{id}` | 软删除，解除关联任务引用 |
| POST | `/api/customers/{id}/contacts` | 添加联系人 |
| DELETE | `/api/customers/{id}/contacts/{cid}` | 删除联系人 |
| POST | `/api/customers/{id}/followups` | 添加跟进记录 |
| DELETE | `/api/customers/{id}/followups/{fid}` | 删除跟进记录 |

### 任务
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/tasks` | 列表，支持 `status/priority` 筛选 |
| POST | `/api/tasks` | 新建（title 必填） |
| PUT | `/api/tasks/{id}` | 更新 |
| DELETE | `/api/tasks/{id}` | 软删除 |
| POST | `/api/tasks/{id}/toggle` | 完成/取消；完成且带 `repeat` 时自动生成下一周期任务 |

### 资料库
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/notes` | 列表，支持 `cat` 筛选 |
| POST | `/api/notes` | 新建（title 必填） |
| PUT | `/api/notes/{id}` | 更新 |
| DELETE | `/api/notes/{id}` | 软删除 |

### 聚合与备份
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/pipeline/stages` | 8 阶段看板数据（按阶段聚合公司名） |
| GET | `/api/stats/overview` | 统计：客户/任务/资料总数、等级与阶段分布、7 日新增 |
| GET | `/api/today` | 今日待处理：逾期任务/今日到期/跟进到期客户 |
| GET | `/api/backup` | 全量导出 JSON（兼容前端备份格式） |
| POST | `/api/backup` | 全量导入（按 id upsert，归属当前用户） |

## 数据模型

客户字段与前端 `normalizeCustomer` 对齐：`id/company/industry/address/contacts/level/stage/machineModel/budget/workpieceNeeds/painPoints/followUps/nextFollowDate/source/remark/createdAt/updatedAt`。

业务常量（服务端校验）与前端一致：阶段 `s1~s8`、等级 `A/B/C`、优先级 `P0/P1/P2`、状态 `todo/doing/done`、重复 `daily/weekly/monthly`、资料分类 5 类、联系人角色 4 类。ID 生成规则与前端兼容（`id` + 时间戳 36 进制 + 随机串）。

所有业务表按 `owner_id` 隔离数据，删除采用软删除（`deleted_at`），联系人/跟进记录通过外键级联。

## 前端接入

- 静态资源目录 `static/` 托管了前端的 `cnc-sales-workbench.html`、`manifest.webmanifest`、`sw.js`。
- 前端当前仍是 localStorage 单机模式；接入后端可走方案 A（全量同步）：前端 `loadState/saveState` 对接 `GET/PUT /api/state`，并新增登录页调用 `/api/auth/*`。实体级 REST API 已全部就绪，后续可平滑迁移到增量同步。

## 部署注意

- `sw.js`（Service Worker）仅在 http(s) 协议下生效，线上部署需 HTTPS。
- 生产环境务必设置 `JWT_SECRET`，并给数据文件 `data/cnc.db` 做好备份。