# 哈尔滨美食地图（0451meishiditu）管理后台 & 后端

## 技术栈

- 后端：Go + Gin + GORM + MySQL + Redis
- 管理后台：Vue3 + Vite + TypeScript + Element Plus + ECharts
- 部署：Docker Compose + Nginx

## 快速启动（Docker Compose）

1. 复制环境变量文件
   - `backend/.env.example` → `backend/.env`
   - `admin/.env.example` → `admin/.env`

2. 启动（会同时启动 MySQL、Redis、后端、管理后台、Swagger UI）
   - `docker compose -f deploy/docker-compose.full.yml up -d --build`

3. 访问
   - 管理后台：`http://localhost:5173`
   - 后端健康检查：`http://localhost:8080/healthz`
   - Swagger 文档：`http://localhost:8081`（加载 `docs/openapi.yaml`）

## 已实现模块（管理后台）

- 数据概览（Dashboard）
- 店铺管理（列表/详情/上下架/删除）
- 分类管理
- 评论管理（审核/删除）
- 商家入驻审核（通过/拒绝）
- 排行管理（查看/重算综合分）
- 用户管理（列表/详情/启用禁用）
- 管理员管理（新增/重置密码/启用禁用）
- APIKey 管理（创建/撤销/查看使用时间）
- 系统设置（CORS）

## 认证与安全（非常重要）

1) APIKey（所有 `/api/**` 必须携带）
- Header：`X-API-Key: <apikey>`
- 开发环境默认值来自 `backend/.env`：`API_KEY=dev-api-key-change-me`

2) 管理端 JWT（管理端 `/api/admin/**`，除登录外必须携带）
- Header：`Authorization: Bearer <admin_token>`

3) 用户端 JWT（用户端需要登录的接口必须携带）
- Header：`Authorization: Bearer <user_token>`

## 默认管理员账号（首次启动初始化）

由 `backend/.env` 控制（首次启动会自动创建）：
- `ADMIN_INIT_USERNAME=admin`
- `ADMIN_INIT_PASSWORD=admin123456`

建议：
- 生产环境务必修改 `JWT_SECRET`、`API_KEY`（或使用 `API_KEY_HASH`）
- 首次进入后台后，在「管理员管理」创建新管理员，并禁用默认管理员

## CORS 跨域设置（支持手动配置）

默认允许：
- `http://localhost:5173`

配置方式：
1) 推荐：在管理后台「系统设置」配置
- 一行一个 Origin，例如：
  - `http://localhost:5173`
  - `https://admin.example.com`
- 支持 `*`（仅建议开发环境）
- 保存后立即生效（内存热更新 + 持久化到 DB）

2) 通过 `backend/.env` 配置
- `CORS_ALLOW_ORIGINS`：使用英文逗号分隔
- 示例：`CORS_ALLOW_ORIGINS=http://localhost:5173,https://admin.example.com`

## 用户注册/登录验证码

- `GET /api/captcha/new` 获取验证码（返回 `captcha_id` + `svg`）
- `POST /api/user/register`、`POST /api/user/login` 需要携带：
  - `captcha_id`
  - `captcha_code`

## 管理员登录验证码

- `POST /api/admin/login` 同样需要携带 `captcha_id` + `captcha_code`（防止暴力破解）
- 管理后台登录页已集成验证码展示与点击刷新

## 公共读取接口（前端可调用）

这些接口仍然需要 `X-API-Key`，但不需要管理员 JWT：
- 分类列表：`GET /api/categories`（只返回 enabled=true）
- 店铺列表：`GET /api/stores`（只返回 active）
- 店铺详情：`GET /api/stores/:id`（只返回 active）
- 店铺评论：`GET /api/stores/:id/reviews`（只返回 approved）
- 店铺排行：`GET /api/rankings/stores`

详见：`docs/API.md`（中文说明）和 `docs/openapi.yaml`（Swagger）

## 图片上传与目录权限

- 上传接口：`POST /api/admin/upload`（`multipart/form-data`，字段名 `file`）
- Docker 下默认把上传目录挂载到数据卷：`backend_uploads:/app/static/upload`
- 已处理常见的 `mkdir failed` 权限问题（容器启动时自动创建/授权上传目录）

## 文档

- Swagger/OpenAPI：`docs/openapi.yaml`（Swagger UI：`http://localhost:8081`）
- 中文接口说明：`docs/API.md`

## 常见启动问题

- 容器名/端口/数据卷冲突：执行 `docker compose -f deploy/docker-compose.full.yml down -v` 后再 `up -d --build`
  - 注意：`down -v` 会清空 MySQL/Redis 数据