HMNL 直播讨论站

在线预览：https://hmnl3.20110208.xyz ｜设计系统：mdui 2 / Material Design 3

HMNL 直播讨论站是一个专注于直播讨论的在线社区平台。用户可以发布话题帖子（支持 Markdown），进行实时聊天交流，发表评论，并接收消息通知。

近期更新

UI 高优先级修复：设置页选主题不再整页重挂载；放送广场搜索改为客户端过滤（无转圈闪烁）；首页一言接口失败不再拖垮整页；首页/设置页按钮统一走 SPA 导航（不再整页刷新）；导航栏认证变更合并渲染；确认对话框 ESC/遮罩关闭不再泄漏 Promise。详见 docs/UI优化与安全修复.md。
安全加固：清除源码中硬编码的 AI 密钥，改由环境变量注入；.gitignore 补全本地凭据、备份与构建产物。
架构：原生 TypeScript SPA（无 React），36 个路由按需动态加载，AbortSignal 驱动的页面生命周期。

主要功能

用户系统：用户注册登录（带图形验证码），第一个注册用户自动成为超级管理员
数字ID：每个用户拥有唯一的数字ID，简洁易记
头像上传：用户可以上传个人头像（支持JPG、PNG，最大1MB）
修改密码：用户可以在个人中心修改密码（需要图形验证码验证）
多头衔系统：管理员可以为用户设置多个自定义头衔，支持添加/删除
入驻用户：管理员可以设置用户为入驻用户，入驻用户可获得专属RTMP推流地址（格式：rtmp://tv.20110208.xyz/live/数字ID），并在帖子和聊天中显示"入驻"标识
超级管理员：第一个注册本系统的用户自动成为超级管理员，可以指定其他用户为管理员；普通管理员只能管理头衔和入驻状态
举报系统：用户可以举报违规内容（帖子、消息、用户），管理员会收到通知并处理
发帖功能：支持Markdown格式编辑，实时预览
帖子管理：浏览、搜索（支持标题和内容搜索）、查看帖子详情
评论系统：针对帖子发表评论
即时聊天：实时聊天室功能，支持搜索消息内容和用户名
消息通知：新回复、系统通知等
管理后台：管理员可以管理用户角色、头衔和入驻状态，处理举报，支持搜索用户（用户名、ID、邮箱、头衔），点击用户头像可快速跳转到用户主页

设计特色

设计系统：mdui 2 / Material Design 3（Web Components）
主题：setColorScheme 种子色 + 深浅色模式（含跟随系统）
布局：桌面侧栏 mdui-navigation-drawer + 移动底栏
触控友好：关键操作区域对齐 Material 触控尺寸

详细迁移说明见：docs/MDUI-NATIVE-MIGRATION.md

技术栈

运行时：原生 TypeScript SPA（无 React）
构建工具：Vite 5
UI 组件：mdui 2 Web Components
样式方案：mdui design tokens + 自研 src/styles/app.css
路由管理：History API 自研路由器（动态 import + AbortSignal 生命周期）
后端服务：Supabase（数据库 + 认证）
Markdown：EasyMDE + marked + DOMPurify
直播播放：hls.js

目录结构

├── README.md
├── index.html
├── package.json
├── public/                    # 静态资源
├── android/                   # 原生 Android（Kotlin · Compose · M3）
├── _legacy_react/             # 旧 React 源码（对照，不参与构建）
├── WinUI3应用/                # Windows 桌面脚手架（参考）
├── docs/MDUI-NATIVE-MIGRATION.md
├── src/
│   ├── main.ts                # 入口
│   ├── app/                   # bootstrap / router / shell / stores
│   ├── features/              # 业务页面 mount 模块
│   ├── db/                    # Supabase 与 API
│   ├── services/
│   ├── styles/app.css         # 全局样式（mdui tokens）
│   └── types/
├── tsconfig*.json
└── vite.config.ts

Android 客户端

原生 Android App 位于 android/，技术栈为 Kotlin + Jetpack Compose + Material 3，直连同一 Supabase 后端，视觉对齐 mdui / MD3。

cd android
# 配置 local.properties：sdk.dir、SUPABASE_URL、SUPABASE_ANON_KEY
./gradlew :app:assembleDebug

详见：android/README.md

本地开发

环境要求

# Node.js ≥ 20
# npm ≥ 10
例如：
# node -v   # v20.18.3
# npm -v    # 10.8.2

在 Windows 上安装 Node.js

访问Node.js官网：https://nodejs.org/
下载并运行安装程序
按照安装向导完成安装
在命令提示符中验证：node -v 和 npm -v

在 macOS 上安装 Node.js

使用Homebrew安装（推荐）：

brew install node

或从官网下载.pkg安装包进行安装。

启动项目

# Step 1: 下载并解压代码包
# Step 2: 用IDE打开代码目录
# Step 3: 安装依赖
pnpm install

# Step 4: 启动开发服务器
pnpm dev

使用说明

首次使用

注册账号：访问登录页面，点击"注册"标签
填写信息：输入用户名和密码（至少6位）
验证码：输入图形验证码（不区分大小写，可点击刷新按钮更换）
第一个用户：第一个注册的用户将自动成为超级管理员
登录系统：使用注册的用户名和密码登录

超级管理员说明

重要提示：为方便二次开发和部署，本系统采用自动超管机制：

自动成为超管：第一个注册本系统的用户会自动获得超级管理员权限
超管权限：
- 可以指定其他用户为管理员
- 可以管理所有用户的头衔和入驻状态
- 可以处理所有举报
- 可以删除任何内容
普通管理员权限：
- 只能管理用户头衔和入驻状态
- 可以处理举报
- 可以删除内容
- 不能指定其他管理员
数据库实现：在 handle_new_user() 触发器中自动判断，当 profiles 表为空时（user_count = 0），新注册用户的 is_super_admin 字段自动设置为 TRUE

二次开发建议：

如需更改超管逻辑，请修改 supabase/migrations 中的 handle_new_user() 函数
如需手动指定超管，可直接在数据库中更新 profiles 表的 is_super_admin 字段
建议在生产环境部署前先注册超管账号，确保系统安全

功能使用

个人设置

进入个人中心页面
查看用户ID：在基本信息中查看你的唯一用户ID
上传头像：点击"选择头像"按钮，选择图片文件（JPG/PNG，最大1MB）
编辑简介：在简介区域输入个人介绍
查看头衔：如果管理员为你设置了头衔，会显示在基本信息中
入驻用户推流地址：如果你是入驻用户，会看到专属的RTMP推流地址卡片，可以一键复制地址用于直播推流

发布帖子

点击首页的"发布新帖"按钮或侧边栏的"发帖"
输入帖子标题
在编辑器中输入内容（支持Markdown格式）
可切换到"预览"标签查看渲染效果
点击"发布帖子"完成发布

浏览和搜索

在首页可以看到所有帖子列表
使用顶部搜索框搜索帖子标题或内容（实时搜索，支持清除）
点击帖子卡片进入详情页

评论互动

在帖子详情页底部可以发表评论
查看其他用户的评论
作者和管理员可以删除评论

即时聊天

点击侧边栏的"聊天室"进入
在底部输入框发送消息
消息每5秒自动刷新
搜索功能：
- 使用顶部搜索框搜索消息内容或用户名
- 实时显示匹配的消息数量
- 搜索时不会自动滚动，方便查看搜索结果
- 点击清除按钮恢复正常浏览

通知中心

侧边栏显示未读通知数量
点击"通知"查看所有通知
可标记为已读或删除通知

管理后台（仅管理员）

管理员可在侧边栏看到"管理后台"入口
用户搜索功能：
- 使用顶部搜索框快速查找用户
- 支持搜索用户名、数字ID、邮箱地址和头衔
- 实时过滤显示搜索结果
- 点击清除按钮恢复完整用户列表
快速跳转：点击用户头像可直接跳转到该用户的主页
查看所有用户列表（包含头像、用户ID、多个头衔和入驻状态）
超级管理员权限：第一个注册的用户为超级管理员，可以修改用户角色（普通用户/管理员）
普通管理员权限：只能管理用户头衔和入驻状态，不能指定其他管理员
设置多个用户头衔：
- 点击头衔旁边的编辑按钮进入编辑模式
- 输入新头衔（最多10个字符），按回车或点击"+"按钮添加
- 点击头衔上的"×"按钮删除该头衔
- 点击"✓"按钮保存所有更改
设置入驻用户：通过开关按钮设置用户为入驻用户，入驻用户可获得专属RTMP推流地址，并在帖子和聊天中显示"入驻"标识
处理举报：查看和处理用户举报的违规内容
查看用户统计数据（总用户数、管理员数、入驻用户数）

举报功能

在帖子、评论、聊天消息旁边可以看到举报按钮
点击举报按钮，填写详细的举报原因（至少5个字符）
提交后管理员会收到通知
可以在个人中心查看自己提交的举报状态
管理员可以在管理后台处理举报（通过/驳回）

特色功能说明

图形验证码

注册时需要输入图形验证码，防止恶意注册
验证码为4位随机字母和数字组合
支持点击刷新按钮更换验证码
验证不区分大小写

用户头像系统

用户可以在个人中心上传自定义头像
支持JPG、PNG格式，文件大小限制1MB
头像会在以下位置显示：
- 帖子列表和详情页
- 评论区
- 聊天室
- 管理后台用户列表
未上传头像时，显示用户名首字母作为默认头像

用户头衔系统

管理员可以为任何用户设置自定义头衔
头衔最多10个字符
头衔以橙色徽章形式显示在用户名旁边
头衔会在以下位置显示：
- 帖子列表和详情页
- 评论区
- 聊天室
- 个人中心
- 管理后台用户列表

入驻用户系统

管理员可以将用户设置为"入驻用户"
入驻用户会获得以下特权：
- 专属的RTMP推流地址：rtmp://tv.20110208.xyz/live/用户ID
- 在个人中心显示推流地址卡片，支持一键复制
- 绿色"入驻用户"徽章标识
入驻用户可以使用OBS等推流软件进行直播
管理后台可以查看入驻用户统计数量

用户ID系统

每个用户都有唯一的用户ID（UUID格式）
用户ID在个人中心完整显示（等宽字体）
管理后台显示用户ID前8位（节省空间）
用户ID用于生成入驻用户的专属推流地址

数据库结构

主要数据表

profiles：用户资料表
- 包含用户名、邮箱、角色、头像、简介等信息
- numeric_id：唯一的数字ID，用于生成推流地址
- titles：用户头衔数组，支持多个头衔
- is_verified：标识是否为入驻用户
- is_super_admin：标识是否为超级管理员（第一个注册的用户自动设置为TRUE）
posts：帖子表
comments：评论表
chat_messages：聊天消息表
notifications：通知表
reports：举报表
- 包含举报类型、被举报对象ID、举报原因、处理状态等
- 支持举报消息、帖子、用户

权限说明

普通用户：可以发帖、评论、聊天、举报
作者：可以编辑和删除自己的帖子和评论
普通管理员：可以管理用户头衔和入驻状态，删除任何内容，处理举报
超级管理员（第一个注册的用户）：拥有所有权限，可以指定其他用户为管理员

了解更多

您也可以查看帮助文档：源码导出，了解更多详细内容。

🔧 故障排除

遇到 "Home is not defined" 错误？

这是浏览器缓存问题，代码本身完全正确。

快速修复：

硬刷新浏览器（推荐）
- Windows/Linux: Ctrl + Shift + R 或 Ctrl + F5
- Mac: Cmd + Shift + R
清除浏览器缓存
- Chrome/Edge: F12 → 右键刷新按钮 → "清空缓存并硬性重新加载"
运行修复脚本
```
./fix-cache.sh
```

详细说明请查看：

CACHE_CLEAR_GUIDE.md - 缓存清除指南
ERROR_RESOLUTION.md - 错误解决报告

📚 相关文档

docs/UI优化与安全修复.md - UI 高优先级修复与安全加固记录
docs/MDUI-NATIVE-MIGRATION.md - mdui 原生化迁移说明
docs/MD3-REFACTOR-CHANGELOG.md - MD3 重构变更日志
docs/UI设计规范.md / docs/功能文档.md / docs/新手入门指南.md

彩蛋：徐诗二是一名优秀的初三化学教师。。。

Name		Name	Last commit message	Last commit date
.zcode/plans		.zcode/plans
WinUI3应用		WinUI3应用
_legacy_react		_legacy_react
android		android
docs		docs
public		public
scripts		scripts
server		server
sql		sql
src		src
supabase		supabase
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
ENV_LEAK_FIX_REPORT.md		ENV_LEAK_FIX_REPORT.md
HMNL-TOR-INTEGRATION-GUIDE.md		HMNL-TOR-INTEGRATION-GUIDE.md
README.md		README.md
TOR-DEPLOYMENT-REPORT.md		TOR-DEPLOYMENT-REPORT.md
biome.json		biome.json
deploy.bat		deploy.bat
deploy.ps1		deploy.ps1
deploy.sh		deploy.sh
ecosystem.config.cjs		ecosystem.config.cjs
fix-cache.sh		fix-cache.sh
guild1.db		guild1.db
guild1.db-shm		guild1.db-shm
guild1.db-wal		guild1.db-wal
index.html		index.html
miaoda-sc-plugin.d.ts		miaoda-sc-plugin.d.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
sgconfig.yml		sgconfig.yml
start-pm2.sh		start-pm2.sh
start.bat		start.bat
start.ps1		start.ps1
tsconfig.app.json		tsconfig.app.json
tsconfig.check.json		tsconfig.check.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.dev.ts		vite.config.dev.ts
vite.config.local.ts		vite.config.local.ts
vite.config.ts		vite.config.ts
图标.png		图标.png
幻霜论坛.md		幻霜论坛.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation