feat(portal): 门户左侧栏目导航+首页视觉升级+主题正名批次-PortalSideNav模型+attachCategoryNavigation注入doCategory/doArticle三件套categoryPath/navTopId/sideNav(站点快照树推导零新增查询,home/search不注入);7主题侧栏两栏markup+窄屏横滚+顶导航祖先高亮+二级下拉当前项高亮+面包屑全路径;cms_category.home_style全链路(news_grid 16条8x2日期前缀/media_focus形态)+PortalListData.Item补source来源徽标四处装配;Banner机制gallery展示位→galleryBanners四列大图轮播(自由字符串零DDL);页脚config 12新键(footer_addresses多校区/qr_*/social_*含URL校验,footerAddressLines由PortalSiteSnapshot.of拆行派生);新增展示型皮肤包campus-glow;fresh-mint2正名fresh-mint(theme.json/头注释同步);AttachmentService scene白名单加category(单页富文本贴图免清孤儿);新增PortalSideNavIT 8+PortalHomeBlocksIT 3,CategoryServiceIT/SiteServiceIT/PortalSsrIT/ThemeContractIT等单类独跑全绿;附sql/clear_cms_data.sql全量清库脚本(清cms_*六表留平台账号/主题包/上传文件,测试数据重走用)

2026-09-10 11:10:48 +08:00
parent f4b1749377
commit 98d640faba
77 changed files with 2564 additions and 175 deletions
@@ -0,0 +1,36 @@
+# fresh-mint 皮肤包
+
+由 blue-white 派生的清新薄荷风皮肤（**卡片封面版**，docs/10 契约 §5 工作流）。**升级随版本发布，不在站点间复制目录**。
+
+## 风格定位
+
+清爽、亲和，适合职业院校门户：主色薄荷青、圆角 12px、卡片纯白+柔和阴影、细线吸顶顶栏+居中 logo、列表卡片网格（一行 3 张）支持封面图、几何圆点装饰与大留白；无纹理、无通栏大图、无复杂动效。
+
+与 `fresh-mint`（同色系基础版）的差异：列表为带封面的卡片网格（`listLayout=grid`，`decoration=dots`），header 为 3 列网格（左：专业院系 / 中：品牌 / 右：搜索）；`fresh-mint` 采用 top-bar + brand-row 顶栏与纯文字列表卡片。
+
+## 数据契约（模板可取用的 model 属性全集，契约 §3）
+
+| 页面 | 属性 |
+| --- | --- |
+| 全部 | `site`（快照：config/分类树/轮播/友链组/院系子站）、`url`（PortalUrlHelper：home/category/article/upload/asset/search/siteHome）、`themeBase`（=`themes/fresh-mint`）、`navCategories`、`pageTitle`、`seoDescription`、`canonical`、`themeParams`（微调参数，仅 theme.json 声明过的 key）、`themeVarsCss`（服务端预构建 `:root{}` 覆盖串，无参数为空） |
+| home | `banners`（时间窗内 home 位）、`topArticles`（置顶+最新 6）、`categoryBlocks`（LIST 型根栏目块，各 top 8） |
+| list / search | `listData`（分页 + `items[].coverImage`）、`category`（list）、`q` + `searchMode`（search） |
+| detail | `article`、`prevArticle`、`nextArticle`、`currentCategoryId` |
+| single | `category`（含 `content`）、`currentCategoryId` |
+
+原则：皮肤不得假设"首页一定有轮播"、"列表一定有封面"，对空集合优雅降级。
+
+## 轮播图尺寸约定（bannerSize）
+
+1920x560（管理端上传端按此引导裁剪）。
+
+## 可调参数
+
+见 `theme.json` 的 `params`：
+
+- **color**（进 CSS 变量）：`primary` 主色 / `primaryDark` 主色加深（用于品牌文字、悬停加深）/ `primarySoft` 主色浅调（装饰、点缀背景）/ `bg` 页面底色 / `border` 边框色。
+- **select**：`listLayout` = `grid`（默认，卡片网格一行 3 张，支持封面）或 `list`（简约列表，封面靠左缩略）；`decoration` = `dots`（默认，背景几何圆点）或 `plain`（纯净无装饰）。
+
+换色建议：主色系三值同步调整（primary / primaryDark / primarySoft），bg 与 border、primarySoft 保持同族浅色调，避免底色与卡片对比失衡。
+
+优先级：`custom_css` > `themeVarsCss` > `main.css`。