# 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` 改为真实域名
- 设置 `INITIAL_ADMIN_EMAIL` 和 `INITIAL_ADMIN_PASSWORD`
- 可按需设置 `INITIAL_ADMIN_NAME`

`APP_SECRET` 可以留空，应用会在数据目录生成并持久化随机 secret。

启动服务：

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

首次启动只在数据库没有管理员时根据 `.env` 创建初始管理员，不会在后续
重启时重置密码。创建完成后建议从 `.env` 删除
`INITIAL_ADMIN_PASSWORD`。

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

> `admin:create` 命令仍可用于创建或重置其他管理员。重置后，该管理员的
> 所有既有会话会立即失效。

## 本地开发

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

```sh
cp .env.example .env
# 示例配置可直接启动；对外部署前必须修改初始管理员凭据
npm ci
npm run typecheck
npm test
npm run lint
npm run build
```

Node 后端和管理员 CLI 会自动读取项目根目录的 `.env`。已由 shell、PM2
或系统服务注入的同名环境变量优先，不会被文件中的值覆盖。可通过
`ENV_FILE=/path/to/file` 指定其他配置文件。

后端默认监听 `127.0.0.1:3000`，管理后台 Vite 服务默认监听
`127.0.0.1:5174` 并代理 `/api`：

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

## PM2 运行

没有 Docker 时可使用 PM2 直接管理构建后的 Node 进程：

```sh
npm install --global pm2
cp .env.example .env
# 示例配置可直接启动；生产环境必须先修改初始管理员凭据
npm run pm2:start
pm2 save
```

初始管理员仅在数据库为空时创建。确认可以登录后，建议删除 `.env` 中的
`INITIAL_ADMIN_PASSWORD`，再执行 `npm run pm2:reload`。未设置
`APP_SECRET` 时，应用会把自动生成的 secret 保存到
`DATA_DIRECTORY/.app-secret`。

更新代码后运行 `npm run pm2:reload`，查看日志使用
`pm2 logs product-issue`。默认访问地址为
`http://127.0.0.1:3000/admin/`。

## 文档

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

## 当前边界

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