# MesaLogo Product Issue

MesaLogo Product Issue 是一个可独立部署的多产品反馈平台。GoodBuddy
是默认接入的第一个产品，后续产品可在管理后台创建并独立筛选。

平台将公开提交 API、内部管理后台、SQLite 数据库和私有截图存储放在
同一套单机部署中，不依赖 GitHub Issue 作为核心数据源。

## 已实现能力

- 版本化公共反馈 API，支持问题、建议、体验和其他反馈
- 可选联系邮箱、客户端环境信息和一张截图
- 按产品和客户端请求 ID 幂等提交
- 默认 `goodbuddy` 产品，以及后台中的多产品创建和启停
- 中文管理后台，包含统计、搜索、筛选、分页和反馈详情
- `待处理 → 已分诊 → 处理中 → 已解决 → 已关闭` 状态流转
- 仅管理员可见的截图和内部备注
- SQLite WAL 持久化，截图使用独立私有目录
- scrypt 管理员密码、HttpOnly 会话 Cookie 和 CSRF 校验
- IP 与安装实例双层限流
- PNG/JPEG/WebP 解码校验、自动旋转、PNG 重编码和元数据清理
- Docker Compose + Caddy 单机部署及自动 HTTPS

## 架构

```text
GoodBuddy / 其他产品
        |
        | HTTPS POST /api/v1/feedback
        v
      Caddy
        |
        v
Fastify + React 管理后台
        |
        +---- SQLite (反馈、产品、管理员、会话、备注)
        |
        +---- 私有 attachments/ (标准化 PNG)
```

管理后台与 API 同源部署。只有 Caddy 暴露 80/443 端口，应用容器不直接
发布端口。

## 快速部署

要求：

- 一台安装了 Docker Engine 和 Docker Compose v2 的 Linux 主机
- 一个已将 A/AAAA 记录指向该主机的域名
- 公网可访问的 TCP 80、TCP 443 和 UDP 443

```sh
cp .env.example .env
```

编辑 `.env`：

- 将 `FEEDBACK_DOMAIN` 改为真实域名
- 用至少 32 字节的随机值替换 `APP_SECRET`

可用以下方式生成 secret：

```sh
APP_SECRET="$(openssl rand -hex 32)"
sed -i "s|^APP_SECRET=.*|APP_SECRET=${APP_SECRET}|" .env
unset APP_SECRET
chmod 600 .env
```

构建镜像并创建首个管理员：

```sh
docker compose build
read -rsp "Administrator password: " PRODUCT_ISSUE_ADMIN_PASSWORD
echo
export PRODUCT_ISSUE_ADMIN_PASSWORD
docker compose run --rm \
  -e PRODUCT_ISSUE_ADMIN_PASSWORD \
  app node dist/server/server/cli/create-admin.js \
  --email admin@example.com \
  --name "MesaLogo Admin"
unset PRODUCT_ISSUE_ADMIN_PASSWORD
```

启动服务：

```sh
docker compose up -d
docker compose ps
curl "https://feedback.example.com/health"
```

将示例域名替换为 `.env` 中的真实域名。管理后台位于
`https://你的域名/admin/`。

> 管理员创建命令也用于密码重置。重置后，该管理员的所有既有会话会立即
> 失效。不要把密码写入 `.env`、命令参数或 Git。

## 本地开发

要求 Node.js 24 或更新版本。

```sh
npm ci
npm run typecheck
npm test
npm run lint
npm run build
```

开发服务器需要通过进程环境提供 `APP_SECRET` 和其他配置。后端默认监听
`127.0.0.1:3000`，管理后台 Vite 服务默认监听 `127.0.0.1:5174` 并代理
`/api`：

```sh
npm run dev
# 另一个终端
npm run dev:admin
```

## 文档

- [公共 API 契约](docs/api.md)
- [部署、升级、备份与恢复](docs/operations.md)
- [数据与隐私边界](docs/privacy.md)
- [GoodBuddy 接入边界](docs/goodbuddy-integration.md)

## 当前边界

- 这是单机部署方案，不提供多节点 SQLite 共享写入。
- 反馈和附件默认持续保留，由部署方制定并执行保留策略。
- 管理后台不对公网提供注册入口，管理员只能通过主机命令创建或重置。
- GoodBuddy 桌面端接入将在生产 API 域名确定后实现。