discourse_theme_ran/README.md

# discourse_theme_ran（Horizon 主题源码）

> 该仓库是 Discourse `Horizon (beta)` 主题的源码副本。仓库内原 README 已标注该主题已并入 Discourse Core。

## 1. 项目作用

这是一个 Discourse 主题项目，核心目标是：
- 改造论坛整体视觉（卡片化主题列表、圆角、配色系统、侧边栏样式）
- 增强交互（侧边栏新建主题按钮、颜色方案切换、Composer Peek 模式）
- 调整不同页面体验（分类页、主题页、聊天页、登录页、移动端）
- 提供系统测试，验证主题关键行为

---

## 2. 目录结构与作用

### `.github/`
- `workflows/discourse-theme.yml`：CI 配置，复用 Discourse 官方主题工作流。

### `assets/`
- `.gitkeep`：占位目录，预留静态资源（当前无实际资源文件）。

### `common/`
- `common.scss`：公共样式入口，按模块聚合 `scss/` 下样式。
- `color_definitions.scss`：主题色变量定义（基于 tertiary 推导背景、链接、侧边栏等）。
- `head_tag.html`：注入浏览器兼容检测脚本，不支持 `hsl(from ...)` 时提示升级浏览器。

### `desktop/`
- `desktop.scss`：桌面端样式入口。
- `desktop-full-width.scss`：全宽布局与头部网格布局规则。
- `desktop-horizon-fixes.scss`：桌面端修复（如 bulk select 样式/布局修正）。

### `javascripts/`
- `.gitkeep`：占位。
- `discourse/api-initializers/`：通过 Discourse API 注入主题行为。
  - `horizon.gjs`：主题主初始化器；注册实验装饰层、配色选择器、站点设置覆盖、管理员弃用提示。
  - `sidebar-new-topic-button-connector.js`：把自定义“新建主题”按钮渲染到侧边栏。
  - `composer-peek-toggle-connector.js`：把 Peek 模式切换按钮挂到 composer 工具区。
  - `full-width-logo-behavior.js`：侧边栏展开时控制 Logo 最小化行为。
  - `reposition-bulk-select.js`：将批量选择入口放到导航控制区。
  - `hamburger-click-outside-transformer.js`：扩展汉堡菜单“点击外部关闭”例外元素。
- `discourse/components/`：Glimmer 组件。
  - `experimental-screen.gjs`：主内容四角/底部装饰层组件（根据容器位置实时计算）。
  - `sidebar-new-topic-button.gjs`：侧边栏新建主题按钮逻辑（权限、分类只读、草稿、关闭汉堡菜单）。
  - `composer-peek-mode-toggle.gjs`：Composer Peek 模式开关，偏好写入 `keyValueStore`。
  - `user-color-palette-selector.gjs`：用户配色切换主组件（支持匿名/登录、明暗配套、CSS 热替换）。
  - `user-color-palette-menu-item.gjs`：配色菜单项。
- `discourse/components/card/`：主题列表卡片列组件。
  - `topic-status-column.gjs`：Pinned/Hot 状态徽章。
  - `topic-category-column.gjs`：分类列。
  - `topic-creator-column.gjs`：主题创建者头像列。
  - `topic-replies-column.gjs`：回复数列。
  - `topic-likes-column.gjs`：点赞数列（当前主题列表布局中未启用展示）。
  - `topic-activity-column.gjs`：最近活动信息（回复/创建/更新与时间）。
- `discourse/initializers/topic-list-columns.gjs`：重排主题列表列、注入卡片列、改写点击行为与移动布局策略。

### `locales/`
- `en.yml`：主题文案与元数据（如 `topic_hot`、`topic_pinned`、描述文本）。

### `scss/`
按功能拆分的样式模块（由 `common/common.scss` 与 `desktop/desktop.scss` 聚合）：
- `variables.scss`：全局尺寸/圆角/间距变量。
- `main.scss`：页面主体容器网格与背景结构。
- `topic-cards.scss`：主题列表卡片化布局核心样式。
- `topic.scss`：主题阅读页、时间线、帖子流样式。
- `categories-view.scss`：分类页与分类+最新混合页样式。
- `sidebar.scss`：侧边栏容器/section/链接样式。
- `sidebar-new-topic-button.scss`：侧边栏新建主题按钮视觉与状态。
- `header.scss`：顶部栏、通知菜单、图标交互样式。
- `nav-pills.scss`：列表导航区（sticky、tab/下拉）样式。
- `buttons.scss`：按钮体系（默认/主按钮 hover、focus、active）。
- `composer.scss`：编辑器外观与工具条、翻译 composer 相关样式。
- `composer-peek-mode.scss`：Peek 模式下 composer 与主布局联动。
- `chat.scss`：聊天页/聊天抽屉适配。
- `welcome-banner.scss`：欢迎横幅和搜索区域样式。
- `mobile-stuff.scss`：移动端/小屏布局调整。
- `login.scss`：登录类页面布局样式。
- `misc.scss`：分散组件兼容/补丁样式。
- `hiddenstuff.scss`：隐藏部分原生 UI 元素。
- `color-choice.scss`：配色切换菜单样式。
- `color-exploration.scss`：侧边栏等颜色变量实验定义。
- `box-view.scss`：实验装饰层（四角遮罩）与聊天相关视觉细节。
- `desktop-full-width.scss`、`desktop-horizon-fixes.scss`：虽然在 `scss/` 目录下存在同名文件，实际桌面入口使用 `desktop/` 目录版本。

### `screenshots/`
- `light.png`、`dark.png`：主题明/暗模式截图，供主题元信息展示。

### `spec/`
系统测试（RSpec + Capybara）：
- `system/core_features_spec.rb`：主题与核心能力兼容性基础测试。
- `system/horizon_high_level_spec.rb`：高层端到端流程（主题列表、导航、配色切换）。
- `system/sidebar_topic_button_spec.rb`：侧边栏新建主题按钮行为测试。
- `system/composer_peek_spec.rb`：Peek 模式可见性与持久化测试。
- `system/user_color_palette_selector_spec.rb`：配色切换在匿名/登录/深色模式下的行为测试。
- `system/page_objects/components/user_color_palette_selector.rb`：配色选择器的 PageObject 封装。
- `.gitkeep`：占位。

### `test/`
- `acceptance/.gitkeep`：预留前端测试目录（当前无具体测试文件）。

---

## 3. 根目录文件作用

- `about.json`：主题元数据（名称、作者、链接、版本、颜色方案、截图、modifiers）。
- `settings.yml`：主题设置项（欢迎横幅开关、搜索体验模式）。
- `README.md`：项目说明文档（本文件）。
- `LICENSE`：MIT 许可证。
- `package.json`：前端开发依赖与 Node/pnpm 版本约束。
- `pnpm-lock.yaml`：前端依赖锁定文件。
- `Gemfile` / `Gemfile.lock`：Ruby 工具链依赖（rubocop-discourse、syntax_tree 等）。
- `.discourse-compatibility`：与 Discourse 版本兼容映射。
- `eslint.config.mjs`：ESLint 配置（继承 `@discourse/lint-configs`）。
- `stylelint.config.mjs`：Stylelint 配置。
- `.template-lintrc.cjs`：Ember Template Lint 配置。
- `.prettierrc.cjs`：Prettier 配置。
- `.rubocop.yml`：Rubocop 配置（Discourse 规则）。
- `.streerc`：Syntax Tree 格式化配置。
- `.npmrc`：npm 行为约束（严格引擎、禁自动 peer 安装）。
- `.gitignore`：Git 忽略规则。

---

## 4. 关键功能对应关系（便于快速定位）

- 主题配色切换：
  - 逻辑：`javascripts/discourse/components/user-color-palette-selector.gjs`
  - 菜单样式：`scss/color-choice.scss`
  - 颜色定义：`about.json` + `common/color_definitions.scss`

- 侧边栏新建主题按钮：
  - 逻辑：`javascripts/discourse/components/sidebar-new-topic-button.gjs`
  - 挂载：`javascripts/discourse/api-initializers/sidebar-new-topic-button-connector.js`
  - 样式：`scss/sidebar-new-topic-button.scss`

- 主题列表卡片化：
  - 列注册：`javascripts/discourse/initializers/topic-list-columns.gjs`
  - 各列组件：`javascripts/discourse/components/card/*.gjs`
  - 主样式：`scss/topic-cards.scss`

- Composer Peek 模式：
  - 逻辑：`javascripts/discourse/components/composer-peek-mode-toggle.gjs`
  - 挂载：`javascripts/discourse/api-initializers/composer-peek-toggle-connector.js`
  - 样式：`scss/composer-peek-mode.scss`

---

## 5. 说明

- 此仓库 README 原文已声明：该主题已并入 Discourse Core，生产环境优先使用 Core 内置 Horizon 主题。
- 当前仓库更适合作为学习/二次开发参考，用于理解 Discourse 主题的样式组织方式与前端扩展点。