# /mp/common/config 接口返回全部公开配置（合并 sys_frontend_config）

**日期**：2026-04-21
**PR**：#1114（Closes #1112）
**合并到 dev commit**：767e5cb4
**后端服务**：hl-user-service（已部署测试环境）
**影响前端**：小程序端「应用配置」接口字段扩展

---

## 为什么改

`/mp/common/config` 过去只返回 `version` / `minVersion` / `servicePhone` 三个 yml 硬编码字段，管理后台「前端配置」页面（`sys_frontend_config` 表）运营的所有配置（主题色、Logo、站点名、分页大小、页脚文本等）完全没在小程序端吐出。

改完后小程序端一个接口拿到全部公开配置。

---

## 接口签名变化

### `GET /mp/common/config`

**契约不变**：响应仍是 `Result<Map<String, Object>>`，`data` 字段类型保持 Map。

**data 内容扩展**：

| 字段来源 | 说明 |
|---------|------|
| yml 基础（固定存在） | `version` / `minVersion` / `servicePhone` |
| `sys_frontend_config` 表 | **所有启用（status=1）且非 SECRET、未软删除的配置项**，key = `config_key`，value 按 `config_type` 做类型转换 |

**类型转换规则**（后端已处理，前端直接使用）：

| config_type | JSON value 类型 | 示例 |
|------------|----------------|------|
| `NUMBER` | `number`（整数 Long / 小数 Double） | `"defaultPageSize": 20` |
| `BOOLEAN` | `boolean` | `"enableWatermark": false` |
| `JSON` | `object` / `array` | `"themeConfig": { ... }` |
| `TEXT` / `COLOR` / `IMAGE` | `string` | `"primaryColor": "#1890FF"` |
| 解析失败 | 原 `string`（降级兜底） | —— |

**过滤规则**：
- `config_type = 'SECRET'` 的不返回（第三方 API key 等敏感配置）
- `status = 0`（停用）的不返回
- `deleted_at IS NOT NULL`（软删除）的不返回

**冲突规则**：
- 若 `sys_frontend_config` 表存在 `config_key = 'version'`（或 `minVersion` / `servicePhone`），**DB 值覆盖 yml 默认值**
- 当前测试/正式环境 DB 不存在这三个 key，无实际冲突

---

## 测试环境实测响应

```bash
curl -sk "https://api.test.1814.love:9443/mp/common/config"
```

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "version": "1.0.0-dev",
    "minVersion": "1.0.0",
    "servicePhone": "400-000-0000",
    "primaryColor": "#1890FF",
    "accentColor": "#FF6B35",
    "backgroundColor": "#F5F7FA",
    "textColor": "#303133",
    "defaultPageSize": 20,
    "cacheExpireMinutes": 30,
    "enableWatermark": false,
    "siteName": "呼籁旅行",
    "logoUrl": "",
    "footerText": "呼籁旅行 版权所有",
    "copyrightYear": "2026",
    "customerServicePhone": ""
  }
}
```

---

## 前端影响

### 可以改（推荐）

**以前**：小程序端可能自己在代码里写死主题色、站点名、分页大小等默认值。
**现在**：这些配置直接从 `/mp/common/config` 读取，运营后台改完小程序端无需发版即可生效（缓存 30 分钟，运营端保存后自动失效）。

### 不需要改

- `version` / `minVersion` / `servicePhone` 三个原有字段**完全保留**，读取方式不变
- 响应结构 `{code, message, data, success}` 不变

### 前端建议

1. `data` 类型建议声明为 `Record<string, any>` 或按需定义强类型（已知 key 列表见上方实测响应）
2. 新 key 可能陆续增加（运营后台可以新增），前端按需解构即可，不要假设 data 只有固定字段
3. NUMBER 类型已转为 JS number，不用再 `parseInt(...)`；BOOLEAN 已转为 js boolean，不用再比较字符串 `"true"`

---

## 缓存行为

- 小程序端接口：`@MpCache(prefix="common:config", ttl=1800s)`，Redis key：`mp:common:config`
- 运营后台修改 `sys_frontend_config` 任一条 → `FrontendConfigService` 写路径触发 `depsManager.invalidateSource("table:sys_frontend_config")` → `MpCommonController` deps 命中该 source → 缓存被精准失效
- 首次部署本次 PR 后，旧缓存（ttl 未到期）会阻挡新数据，已在部署时主动清理一次：`redis-cli -n 0 del mp:common:config`

---

## 关联

- Issue：#1112
- 非目标：本 PR **不改** `/mp/config`（分组查询接口，`MpConfigController`）
- 历史遗留：`MpCacheEvict.categoryMap` 中 `config → table:frontend_config`（少 `sys_` 前缀）与实际 deps `table:sys_frontend_config` 不一致，本次不动，留后续清理工单