feat(theme): 皮肤包管理收敛与命名批次-兜底catch经wrapFailure先log.error记原始堆栈再包装(upload/derive/updateMeta三处,extractZip/deleteRecursively静默吞改warn/debug);内置包改显示名走.meta覆盖层(ThemeRegistry加载后覆写title/description,updateMeta放开内置:全空=恢复默认,params拒改);derive/upload支持表单命名(theme.json改写regex换ObjectMapper防误替换,upload落位前改staging失败不落位);resolveTheme回退warn补站点编码;ThemeVo.editable语义改为可编辑元数据;附内置包mint-breeze/fresh-mint2与R1学校主站编码迁移SQL;308/308全绿

2026-09-08 20:25:43 +08:00
parent 12a492fc55
commit a666e13f56
39 changed files with 2343 additions and 72 deletions
@@ -0,0 +1,36 @@
+# mint-breeze 皮肤包
+
+由 blue-white 派生的清新薄荷风皮肤（docs/10 契约 §5 工作流）。**升级随版本发布，不在站点间复制目录**。
+
+> 注：本包与 fresh-mint 为同源并存的两个车道产物（并发会话分道，2026-09-08），互不依赖；站点二选一即可。
+
+## 风格定位
+
+清爽、亲和，适合职业院校门户：薄荷青品牌色、圆角 12px、卡片纯白+柔和阴影、细线顶栏+居中 logo（桌面吸顶，移动端取消）、列表卡片网格（一行 3 张）、几何圆点装饰与大留白；无纹理、无通栏大图、无复杂动效。
+
+## 数据契约（模板可取用的 model 属性全集，契约 §3）
+
+| 页面 | 属性 |
+| --- | --- |
+| 全部 | `site`（快照：config/分类树/轮播/友链组/院系子站）、`url`（PortalUrlHelper：home/category/article/asset/search/siteHome）、`themeBase`（=`themes/mint-breeze`）、`navCategories`、`pageTitle`、`seoDescription`、`canonical`、`themeParams`（微调参数，仅 theme.json 声明过的 key）、`themeVarsCss`（服务端预构建 `:root{}` 覆盖串，无参数为空） |
+| home | `banners`（时间窗内 home 位）、`topArticles`（置顶+最新 6）、`categoryBlocks`（LIST 型根栏目块，各 top 8） |
+| list / search | `listData`（分页）、`category`（list）、`q` + `searchMode`（search） |
+| detail | `article`、`prevArticle`、`nextArticle`、`currentCategoryId` |
+| single | `category`（含 `content`）、`currentCategoryId` |
+
+原则：皮肤不得假设"首页一定有轮播"，对空集合优雅降级。
+
+## 轮播图尺寸约定（bannerSize）
+
+1920x560（管理端上传端按此引导裁剪，D2 决策点）。
+
+## 可调参数
+
+见 `theme.json` 的 `params`：
+
+- **color**（进 CSS 变量）：`primary` 主色 / `primaryDark` 主色加深（即强调色，用于品牌文字与悬停加深）/ `primaryLight` 主色提亮 / `bg` 页面底色 / `cardBg` 卡片底色 / `border` 边框色 / `text` 正文文字 / `textLight` 次要文字。
+- **select**：`listLayout` = `grid`（默认，卡片网格一行 3 张）或 `row`（传统行列表）。
+
+换色建议：主色系三值同步调整（primary / primaryDark / primaryLight），bg 与 border、primaryLight 保持同族浅色调，避免底色与卡片对比失衡。
+
+优先级：`custom_css` > `themeVarsCss` > `main.css`。