哈尔滨美食地图

README.md

@@ -0,0 +1,112 @@
+# 哈尔滨美食地图（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 数据