582485ba2b
需求：前台壁纸站支持切换到开源壁纸平台，并能展示后台上传的自家图库， 保留原有「浏览器实时生成」能力（扩展而非替换），PC / 移动双端一致。 设计要点（受服务器 5M 出口带宽约束）： - 开源平台图片一律走官方 CDN 直链，后端只代理元数据，零带宽消耗。 - 自建图库落盘到 /data/www/wallpaper，由 nginx 的 /wallpaper/ 直出， Go 服务不参与传图；三档尺寸（480 缩略 / 1920 预览 / 原图仅供下载）。 - 内存缓存平台响应（Bing 1h、搜索类 10min），避免撞第三方配额。 内容： - 平台插件：Bing 每日一图、Picsum、Unsplash、Pexels、Wallhaven。 新增平台 = 写一个 provider_xxx.go 并在 allProviders() 加一行， 刻意不用 init() 自注册，避免隐式副作用。所有适配器支持 config.baseUrl 覆盖，用于绕开 DNS 污染（实测 wallhaven.cc 解析到境外无关 IP）。 - 自建图库：上传（MD5 秒传去重 / 尺寸前置校验 / 失败清理孤儿文件）、 元信息编辑、删除、统计；随机取图用「数总数 → 随机偏移」而非 ORDER BY RAND()。 - 接口：open 组 4 个（sources / list / random / download-track）， admin 组 8 个（list / upload / save / delete / stats / source.list|save|test）。 全部 POST 且 URL 无参数，符合工作空间接口规范；上传走 multipart 例外。 - 安全：purity 默认锁死 SFW；apiKey 只回传布尔不回传明文； 保存时留空表示保留旧值；open 组错误信息对外脱敏。 - 配置：clientMaxBodySize 提到 64M（gf 默认 8M 会截断 20MB 原图）； wallpaper.root / baseUrl 支持环境变量注入并在占位符未替换时兜底。 依赖：golang.org/x/image@v0.23.0（仅用于缩略图缩放，保持 go 1.23.0 不变）。 |
||
|---|---|---|
| .gitea/workflows | ||
| .workbuddy/memory | ||
| api | ||
| common | ||
| deploy | ||
| docs | ||
| hack | ||
| internal | ||
| manifest | ||
| resource | ||
| utility | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| Makefile | ||
| PROJECT_STRUCTURE.md | ||
| README.MD | ||
service.xpcool.com — 个人多客户端后端服务
GoFrame v2 单体应用，为 mini / h5 / app 多端提供后端服务，并附带完整的后台管理体系。
核心业务：用户认证（JWT）、看房数据（小区/房源/成交/预售证）、招聘考试聚合、 站内通知、服务器安全日志；后台管理（RBAC 菜单权限 + 操作审计）。
面向 AI 助手的项目上下文见
AGENTS.md；每次变更的结构化记录见docs/change-log/；目录树见PROJECT_STRUCTURE.md。
分层约定
调用链强制为 api → internal/controller → internal/service → internal/dao → internal/model(entity/do)。
controller只做 API 到 service 的适配，不碰 dao；- 跨层出入参走
internal/model/dto与internal/model/vo，API 类型与 entity 不得越界； - 数据库操作必须用 DO 对象（
internal/model/do），禁止g.Map； - 错误一律用
gerror（保留堆栈），响应统一走internal/library/response。
路由分组
三组路由在 internal/cmd/cmd.go 中注册：
| 前缀 | 用途 | 鉴权 |
|---|---|---|
/api/service/open |
开放接口（前端直接调用） | 公开，无鉴权 |
/api/service/user |
用户端接口 | 登录公开，其余走 UserAuth |
/api/service/admin |
管理端接口 | AdminAuth + 按「方法+路径」自动匹配权限码 |
管理端权限由后端从 admin_menu（type=2 行，path 存 "METHOD /路径"）反查，
前端无需传 X-Permission；未配置映射的接口一律拒绝。
数据库模型生成
先在 MySQL 上执行 manifest/sql/ 下的迁移脚本，再设置 DB_DSN，然后运行：
gf gen dao -p internal -g default -gt -c
该命令是 internal/dao、internal/model/do、internal/model/entity 的唯一来源，生成物禁止手改。
注意：部分模块（招聘、通知、自动任务、服务器安全日志）的表结构为手写 entity/do/dao，
未走 gf gen，改动时请勿用生成命令覆盖。
本地启动
环境变量按 GF_GCFG_FILE 切换配置文件（config.dev.yaml / config.test.yaml / config.prod.yaml）。
- 终端：
source .env.dev && go run main.go（.env.dev不入库，保存本地 DSN 与密钥）。 - GoLand：运行配置
.run/service-dev.run.xml（项目级，重载项目后自动识别） 已注入GF_GCFG_FILE/DB_DSN/JWT_SECRET，在运行下拉框中选择即可。 该文件含数据库口令，已加入.gitignore。
开发环境下，若 ${DB_DSN} / ${RECRUITMENT_DB_DSN} / ${JWT_SECRET} 占位符未被环境变量注入，
injectEnv 会回填本地默认值，保证「零配置可启动」；生产（GF_GCFG_ENV=prod）不兜底，配置缺失显性报错。
构建与测试
go build ./...
go test ./...