# YMhut Box 反馈工单服务

这是 `server/feedback-mailer` 下的 Go + Gin + SQLite 反馈服务。旧 PHP 入口已移除，线上入口由 Go 服务接管；`config.txt`、`storage/`、`storage/feedback.sqlite` 和历史 `.ymfb` / `.zip` 文件继续保留并兼容读取。

## 运行

在 `server/feedback-mailer` 目录直接运行：

```bash
go run main.go
```

监听地址以核心配置文件 `config.txt` 的 `listen` 为准：

```php
'listen' => ':8080',
```

服务器部署时也可以显式设置服务根目录：

```bash
export YMHUT_FEEDBACK_HOME=/opt/feedback-mailer
./feedback-mailer
```

后台入口：

```text
http://127.0.0.1:8080/admin/
```

生产构建与检查：

```bash
npm --prefix admin-web install
npm --prefix admin-web run build
go test ./...
go build .
```

## 配置

优先读取当前目录的 `config.txt`，这是线上实际配置文件，部署时不要覆盖。没有 `config.txt` 时才回退读取 `config.json`。

关键字段：

- `listen`：服务监听地址，例如 `:8080`、`:9090`、`127.0.0.1:8080`。
- `admin_password_hash` / `admin_password`：后台登录密码，推荐使用 bcrypt hash。
- `client_signature_key`：旧 WinUI 客户端 HMAC 签名密钥，必须保持一致。
- `package_encryption_key`：`.ymfb` 反馈包解密密钥，必须保持一致。
- `storage_dir`：默认 `storage`，保留历史反馈包。
- `database_path`：默认 `storage/feedback.sqlite`，保留旧 SQLite 数据。
- `rate_limit`：提交、状态查询、验证码、登录和后台 API 的令牌桶限流。
- `upload_guard`：zip 文件数量、解压后大小、单文件大小、压缩比、路径穿越校验。
- `backup.dir` / `backup_dir`：数据库只读备份输出目录，默认 `storage/backups`。
- `webhooks`：通用 Webhook 通知配置，secret 只用于签名，不进入 URL 或配置健康 API。

## 兼容接口

旧客户端提交接口保持不变：

```text
POST /
```

继续接收 `payload`、`timestamp`、`nonce`、`packageSha256`、`signature`、`package`，并保留旧错误码。

旧状态查询保持不变：

```text
GET /?api=status&code=FB-YYYYMMDD-XXXXXX
```

响应保留旧字段，并兼容增加 `statusDetail`、`category`、`priority`。

## 后台能力

- 公共首页 `/`：反馈中心正式页和无需登录的状态查询。
- 后台 `/admin/`：工作台、工单流、状态看板、通知记录、Webhook 集成、运维、配置健康。
- 10 秒轮询刷新：统计卡片、SVG 图表、工单列表、详情、通知和配置摘要都会重绘。
- 工单增强：状态、分类、优先级、SLA、指派人、截止时间、标签、评论、解决说明、内部备注、公开回复。
- 看板操作：按 `new / triaged / investigating / resolved / archived` 分栏，拖动工单即可改状态。
- 批量处理：多选后批量归类、处理中、解决、归档。
- 导出：`GET /api/admin/feedbacks/export?format=csv` 导出当前筛选结果，不包含包文件和密钥。
- 审计日志：登录、工单修改、批量操作、导出、备份、Webhook 测试等都会记录。
- 数据库备份：后台创建和下载 SQLite 备份，不提供在线删除、VACUUM 或破坏性维护。
- Webhook：支持 `feedback.created`、`feedback.updated`、`feedback.status_changed`、`feedback.comment_created`、`mail.failed`。

Webhook 请求头：

```text
X-YMhut-Event
X-YMhut-Delivery
X-YMhut-Signature
```

签名格式为 `sha256=<hex hmac>`。

## 数据升级

服务启动时会对旧 `feedbacks` 表做非破坏性补列，并创建新表：

- `feedback_comments`
- `feedback_tags`
- `audit_logs`
- `webhook_deliveries`
- `feedback_events`

SQLite 默认启用 WAL，并设置 `busy_timeout`。不会删除 `storage/feedback.sqlite`，不会修改历史 `.ymfb`、`.zip` 文件。

## 后台 API

需要登录 session，写接口需要 CSRF：

- `GET /api/admin/overview`
- `GET /api/admin/config`
- `GET /api/admin/feedbacks?page=&perPage=&status=&category=&priority=&mail=&q=&assignee=&tag=&sla=&overdue=&sort=`
- `GET /api/admin/feedbacks/export?format=csv`
- `GET /api/admin/feedbacks/summary`
- `GET /api/admin/feedbacks/:code`
- `PATCH /api/admin/feedbacks/:code`
- `PATCH /api/admin/feedbacks/bulk`
- `POST /api/admin/feedbacks/:code/comments`
- `GET /api/admin/mails?page=&perPage=&status=`
- `POST /api/admin/mails/test`
- `GET /api/admin/audit-logs?page=&perPage=&actor=&type=`
- `GET /api/admin/webhooks/deliveries?page=&perPage=&status=`
- `POST /api/admin/webhooks/test`
- `POST /api/admin/backups/database`
- `GET /api/admin/backups`
- `GET /api/admin/backups/:name`

## 增强依据

- OWASP File Upload Cheat Sheet：上传限额、存储隔离、路径和内容校验、防 zip bomb。
- OWASP REST Security Cheat Sheet：限流、审计、避免敏感信息出现在 URL、统一错误语义。
- SQLite WAL 与备份文档：读写并发和在线备份思路。
- Go `golang.org/x/time/rate`：内存令牌桶限流。
- Gin graceful shutdown 示例：使用 `http.Server.Shutdown()` 优雅停机。

## 验证

```bash
go test ./...
go build .
npm --prefix admin-web run build
go run main.go
```

启动后建议检查：

```text
http://127.0.0.1:8080/
http://127.0.0.1:8080/admin/
http://127.0.0.1:8080/?api=status&code=BAD
http://127.0.0.1:8080/api/auth/captcha
```