本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月13日备份/CSS清理计划-2026-08-12.md。
SoSite CSS 历史债清理计划（2026-08-12）
生成日期：2026-08-12 ｜ 依据：本次全量只读扫描（文件清单/同名类/内联样式/重复实现/死类）+ 历史审计（0806/0807）复核
结论：本次仅出计划，未修改任何代码。所有扫描均基于当前代码库实际状态。
说明：
[本次扫描]= 今日扫描实测数据；[已清理]= 已确认不再存在；[需执行时再查]= 动手前再确认一次。
〇、总体结论
- 架构底子好：
--mn-*CSS 变量令牌化 + 5 主题变体覆盖机制 +admin.css后台独立作用域——这些设计决策保留不动。 - 最重的一笔债已还：旧模板 CSS（
forum.css / pages.css / layout.css / blog.css / home.css）已全部不存在（本次 glob 确认），0807 整改中blog.css死文件等已清理。 - 剩余历史债集中在 4 类：同名类互覆（31 个）、死类候选（271 个）、内联样式滥用（207 处 + 硬编码色值 48 处）、重复实现（分页/按钮/卡片/徽章多套体系）。
- 清理原则：以
modern.css为前台唯一基座；admin.css后台保持作用域隔离；插件样式先收敛变量化、不重构组件；每阶段独立打包可回滚。
一、CSS 文件清单与引用关系 [本次扫描]
1.1 核心样式（assets/css/，6 个）
| 文件 | 引用方 | 状态 |
|---|---|---|
modern.css（1940 行） | 所有页面基座（layouts/main.php:28） | ✅ 保留（唯一基座） |
admin.css（804 行） | 仅后台（main.php:23） | ✅ 保留（已作用域化） |
components.css | 后台 + blog/detail + thread/show + post/create + profile/index 等（main.php:22 + 各视图 section('css')） | ⚠️ 与 admin.css 大量同名类，见 §二 |
style.css | 后台基础层（main.php:21） | 🟡 仅 4 个类定义，疑似残留，见 §五 |
fontawesome.css | 所有页面（main.php:40） | ✅ 保留 |
editor.css | needsEditor 时（main.php:42） | ✅ 保留 |
1.2 主题变体（assets/css/themes/，5 个）
modern-azure / crimson / jade / night / purple —— main.php:33 按主题热切换 ✅ 全部保留。
1.3 插件样式（plugins/*/assets/style.css，15 个）
15 个激活插件各有独立 style.css。✅ 保留（组件不动），但见 §三/§四 的变量化与内联收敛。
1.4 非程序文件（无需处理）
docs/style.css：文档站独立样式update/*/assets/**：部署包副本（勿改，部署时覆盖）
二、同名类多文件互覆（31 个）[本次扫描]
扫描方法：核心 4 文件（modern/components/admin/style）去注释后提取
.类名，统计跨文件出现 ≥2 的类。核心矛盾对：
components.css↔admin.css（后台页面两者同时加载，后加载者覆盖前者，顺序敏感）。
2.1 高优先（存在实际样式冲突风险，需人工甄别）
| 类 | 分布 | 说明 |
|---|---|---|
.active | components×5 / admin×5 | 导航高亮 vs 后台菜单高亮，语义不同 |
.stat-card | components×1 / admin×10 | 前台统计卡 vs 后台仪表盘（0807 已标无作用域前缀） |
.form-input | components×1 / admin×6 | 前台/后台表单控件 |
.btn-primary | components×2 / admin×6 | 两套按钮体系 |
.btn-secondary | components×3 / admin×3 | 同上 |
.btn-edit | components×2 / admin×8 | 编辑按钮 |
.alert / .alert-error / .alert-success / .alert-warning | components / admin | 两套提示配色（边框 3px/4px、不同色板） |
.text-center / .text-muted | components×3+2 / admin×2 | 工具类互覆 |
.c-666 / .c-999 / .c-333 | components / admin | 灰色文字工具类两套 |
2.2 低优先（同名但属通用工具类，可统一）
.btn-sm、.card、.checkbox-inline、.fs-12、.fs-13、.hidden、.link-primary、.lv-badge、.m-0、.mb-12、.mt-15、.mt-20、.tag、.auth-box、.color-swatch、.form-label（modern×1/components×1）
2.3 清理方向（等指令）
- 后台类统一加
.admin-content/.admin-container作用域前缀（0807 已对 badge/alert 做过，延续到其余全部） - 或后台独立改名（如
.a-btn/.a-alert），彻底切断顺序依赖 - 工具类（
.text-、.c-、.fs-*、间距类）收敛到单一文件唯一定义
三、内联样式滥用与硬编码色值 [本次扫描]
3.1 内联 style="..." 共 207 处（78 个视图文件）
Top 分布：
| 视图 | 处数 | 备注 |
|---|---|---|
plugins/medal/views/admin.php | 36 | 勋章后台弹窗/表单布局 |
plugins/content_review/views/admin.php | 17 | 审核后台 |
plugins/red_packet/views/index.php | 17 | 红包前台 |
plugins/friend_links/views/admin.php | 16 | 友链后台 |
plugins/announcements/views/admin.php | 13 | 公告后台 |
post/create.php / thread/edit.php | 各 6 | 发帖/编辑表单 |
| 其余 36 个视图 | 1-5 | 分散 |
插件后台视图（medal/content_review/friend_links/announcements）合计 82 处，占 40%。
3.2 硬编码色值（#hex）共 48 处
Top：red_packet/views/index.php×8、red_packet/views/detail.php×6、icon_generator/views/generator.php×5、content_review/views/admin.php×4、admin/groups.php×3、daily_checkin/views/_area.php×3、seo/views/admin.php×3 等。
3.3 清理方向（等指令）
- 插件后台布局类内联 → 收编为插件自身 style.css 的类（弹窗/表单行/间距）
- 硬编码色值 → 接入前台
--mn-*变量或插件局部变量（red_packet 红包色、daily_checkin 签到色等可留插件局部变量） - 一次性布局用的 1-2 处内联（如
margin:auto）可保留，不强行改造
四、重复实现（多套体系并存）[本次扫描]
| 体系 | modern.css | components.css | admin.css | 建议 |
|---|---|---|---|---|
| 分页 | 5 处（mn-pagination/mn-page-*） | 4 处（pagination/page-*） | 5 处（pagination/page-dots） | 前台收敛到 mn-pagination；后台独立保留 |
| 按钮 | 11 处（mn-btn-*） | 48 处（btn/btn-*） | 80 处（btn-* + admin 覆盖） | 前台以 mn-btn 为基座；后台保留 btn 但收敛重复定义 |
| 卡片 | 17 处（mn-section/mn-row 等） | 22 处（card/panel 等） | 11 处（admin-section/stat-card） | 前台收敛到 mn-；后台保留 admin- |
| 徽章 | 0 | 1 处 | 7 处 | 前台无徽章体系（已删 mn-level-badge），后台独立保留 |
0807 结论复核：分页 6 套→现 3 套、搜索表单 4 套→现 0 套（已统一），说明收敛工作已在推进，本次继续同一方向。
五、死类 / 未使用选择器 [本次扫描]
扫描方法：提取核心 CSS 的
.类名，与全部视图/插件视图/JS 中出现的class="..."对比。
| 文件 | 定义类数 | 视图命中 | 未命中候选 |
|---|---|---|---|
modern.css | 319 | 272 | 47（friend-link-* 前缀、home-sidebar-title、vote-btn-clean 等） |
components.css | 292 | 88 | 204（invite- 整体系、flex-/gap-/mt-/mb-* 间距类、c-green/c-orange 等） |
admin.css | 171 | 154 | 17（alert-warning-custom、tab-group、form-maxw 等） |
style.css | 4 | 1 | 3（text-success、hidden、page-theme-settings） |
⚠️ 注意：components.css 命中率低（292 类仅 88 命中）可能因为：a) 部分类由 JS 拼接/动态生成（className、classList）；b)
invite-*等是已停用插件 invite 的遗留样式（invite 插件 activated=false）；c) 旧模板残留类。删除前必须逐一人工核实，[需执行时再查]。
5.1 明显可处理项
style.css（4 类）：仅 1 个类命中 → 核实后基本可整体删除（后台基础层由 components/admin 覆盖）components.css的invite-*系列（invite-container/card/header/title/stats/form/input/btn/table 等约 30 类）：invite 插件已停用 → 确认无动态引用后可删modern.css的friend-link-*（friend-links-text/item/logo/img 等）：friend_links 插件有自己的 style.css → 核实 modern.css 中是否冗余
5.2 处理策略
分三批：A）有把握删除（停用插件样式、零命中且无 JS 引用）；B）需人工确认（命中率低但可能动态使用）；C）保留（工具类、主题变体依赖）。
六、分阶段清理计划
每阶段产出独立 update 包，可单独部署/回滚；每阶段前后跑前台+后台关键页面回归。
阶段 1：同名类收敛（高优先，消除顺序敏感）
- 后台互覆类加
.admin-content前缀或改名（.stat-card/.form-input/.btn-/.alert-/.active/.c-/.text-） - 工具类统一到 single 定义
- 风险：中（可能影响后台观感）｜验证：后台全部页面视觉对比
阶段 2：死类清理（低风险，先易后难）
- 批 A：invite-* 系列、style.css 整体、明确零引用类
- 批 B：components.css 204 候选逐个人工核实（含 JS 动态引用排查）
- 风险：低-中｜验证：前台页面 + JS 功能回归
阶段 3：内联样式收敛 + 色值变量化（中风险）
- 插件后台 82 处布局内联 → 插件 style.css 类
- 48 处硬编码色值 → CSS 变量（red_packet/daily_checkin 可定义插件局部变量）
- 风险：中（插件页面多）｜验证：逐个插件页面视觉对比
阶段 4：重复实现统一（最后，视觉变化最小化）
- 分页/按钮/卡片前台收敛到 mn- 基座，后台保留 admin-
- 风险：中-高（触及所有前台页面）｜验证：全页面截图对比
七、不动的东西（明确排除）
--mn-*变量令牌体系与 5 主题变体机制（架构资产，保留）admin.css后台独立体系（作用域隔离是特性，只收敛同名不推翻）fontawesome.css/editor.css/ 插件核心组件样式- 后续的 MD3 令牌化改造（另立项目，与本清理互不干扰）
八、待你决策的点
- 阶段顺序是否按 1→4，还是先做低风险的死类清理（阶段 2）热身？
- 同名类收敛：后台类加前缀还是改名？（加前缀改动小、改名更彻底）
- 插件样式是否允许改动？（涉及 medal/content_review/red_packet 等插件视图，建议允许、仅做类化不改视觉）
- 每阶段打包粒度：一个 update 包合并全部，还是 4 个包分开？
计划完成 — SoSite 2026-08-12。本轮未修改任何代码，所有结论基于只读扫描。
