Merge pull request #3 from d0zingcat/feature/better_readme

README.md

@@ -1,136 +1,97 @@
 # Alert Message Center
 
-这是一个基于 **Bun**, **Hono**, **Drizzle ORM (SQLite)** 和 **React (Vite + Tailwind)** 构建的企业级告警管理系统。
+[![Tech Stack](https://img.shields.io/badge/Stack-Bun%20%7C%20Hono%20%7C%20React-blue)](https://bun.sh)
+[![Database](https://img.shields.io/badge/Database-PostgreSQL-blue)](https://www.postgresql.org/)
 
-它采用 **Topic (主题)** 订阅模型，类似于 Sentry 的告警分发机制。告警发送到特定的 Topic，系统根据订阅关系，通过 **飞书机器人私聊 (Private Message)** 将告警精准推送给订阅该 Topic 的用户。
+**Alert Message Center** 是一个现代化、企业级的告警路由与分发中心。它旨在将纷繁复杂的告警源（Prometheus, Grafana, 自建脚本等）与最终接收人解耦，通过 **飞书机器人私聊** 实现告警的精准触达。
 
-## 核心理念
+---
 
--   **Topic (主题)**: 业务逻辑上的告警分类，例如 `payment-service-error`, `frontend-performance`, `daily-report`。
--   **User (用户)**: 接收告警的实体，绑定飞书 User ID。
--   **Subscription (订阅)**: 用户订阅感兴趣的 Topic。
--   **Private Message (私聊)**: 告警不再发送到嘈杂的群组，而是直接私聊发送给相关负责人，确保触达。
+## 📸 界面预览
 
-## 功能特性
+### 1. 话题管理与个人信箱
+支持通过 **Topic (主题)** 订阅模式分发告警，同时也提供 **Personal Inbox (个人信箱)** 功能，无需创建话题即可快速给自己推送消息。
+![Topics View](docs/images/topics_view.png)
 
--   **精准分发**: 告警只发给订阅的人，避免群消息轰炸。
--   **集中管理**: 统一管理所有告警入口和订阅关系，无需维护大量硬编码的 Webhook URL。
--   **飞书集成**: 使用飞书开放平台 API，支持发送富文本和卡片消息。
--   **全局监控**: 提供 Grafana 风格的系统负载看板，实时追踪告警接收数、应发消息数及发送成功率。
--   **现代化技术栈**: 全栈 TypeScript，高性能 Bun 运行时。
+### 2. 管理员看板 (Live Stats)
+实时追踪全系统的告警负载、分发成功率以及各话题的热度。
+![Admin Dashboard](docs/images/admin_dashboard.png)
 
-## 快速开始
+---
 
-### 1. 前置准备
+## 🔥 核心特性
 
-你需要创建一个飞书企业自建应用 (Custom App)：
-1.  访问 [飞书开发者后台](https://open.feishu.cn/app)。
-2.  创建企业自建应用。
-3.  **启用机器人能力**: 在 "添加应用能力" -> "机器人" 中启用。
-4.  **申请权限**: 在 "权限管理" 中申请以下权限：
-    -   `im:message` (获取与发送单聊、群组消息)
-    -   `im:message:send_as_bot` (以应用身份发送消息)
-    -   (可选) `contact:user.id:readonly` (通过手机号或邮箱获取用户 ID)
-5.  **发布版本**: 创建版本并发布，等待管理员审核通过。
-6.  获取 **App ID** and **App Secret**。
+- **🚀 极简推送 (Personal Inbox)**: 每个用户拥有专属的 Webhook Token，直接向 `/dm` 接口发送即可在飞书收到私聊，零配置成本。
+- **📢 主题订阅 (Topic Model)**: 灵活的“发布-订阅”机制。告警发送至 Topic，系统自动分发给所有订阅成员，避免群聊骚扰。
+- **🛡️ 权限与审计**: 
+    - 话题创建需经过管理员审批。
+    - 记录完整的 `Alert Task` 日志，包含发送者、时间、审批人及分发成功率。
+- **📊 实时看板**: Grafana 风格的监控界面，直观展示系统运行健壮性。
+- **⚡ 高性能架构**: 基于 Bun + Hono 的全异步架构，毫秒级分发延迟。
 
-### 2. 安装依赖
+---
 
-确保你已经安装了 [Bun](https://bun.sh/)。
+## 🛠️ 技术栈
 
+- **Runtime**: [Bun](https://bun.sh/) (高性能 TS 运行时)
+- **Backend**: [Hono](https://hono.dev/) (Web Standards Based)
+- **Frontend**: [React](https://react.dev/) + [Vite](https://vitejs.dev/) + [Tailwind CSS](https://tailwindcss.com/)
+- **Database**: [PostgreSQL](https://www.postgresql.org/) + [Drizzle ORM](https://orm.drizzle.team/)
+- **Messaging**: [Feishu (Lark) Open Platform](https://open.feishu.cn/)
+
+---
+
+## 🚀 快速开始
+
+### 1. 飞书应用配置
+1.  登录 [飞书开放平台](https://open.feishu.cn/) 创建一个 **企业自建应用**。
+2.  在“应用能力”中开启 **机器人**。
+3.  在“权限管理”中申请 `im:message:send_as_bot` (以应用身份发送消息)。
+4.  获取 `App ID` 和 `App Secret`。
+
+### 2. 部署运行
 ```bash
-# 在根目录运行
+# 安装依赖
 bun install
-```
 
-### 3. 配置环境变量
+# 配置环境变量 (apps/server/.env)
+DATABASE_URL="postgresql://user:pass@localhost:5432/db"
+FEISHU_APP_ID="cli_xxx"
+FEISHU_APP_SECRET="xxx"
+ADMIN_EMAILS="user1@example.com,user2@example.com" # 管理员列表
 
-在 `apps/server` 目录下 (或者在启动命令中) 配置环境变量：
+# 数据库推送
+cd apps/server && bun run db:push
 
-```bash
-export FEISHU_APP_ID="你的AppID"
-export FEISHU_APP_SECRET="你的AppSecret"
-```
-
-### 4. 启动开发环境
-
-这将同时启动后端 API (端口 3000) 和前端界面 (端口 5173)。
-
-```bash
+# 启动开发环境
 bun run dev
 ```
 
-访问前端界面: [http://localhost:5173](http://localhost:5173)
+---
 
-### 5. 使用指南
+## 📡 Webhook 使用指南
 
-#### 第一步：配置 Topic
-1.  进入 **Topics** 页面，点击 "Add Topic"。
-2.  填写 Name (显示名) 和 Slug (唯一标识，用于 URL)。
-    *   例如: Name: "支付服务异常", Slug: `payment-error`。
-
-#### 第二步：添加用户
-1.  进入 **Users** 页面，添加用户。
-2.  必须填入用户的 **飞书 User ID** (Open ID 或 User ID)。
-    *   *提示: 可以在飞书管理后台查看用户的 User ID，或者通过 API 获取。*
-
-#### 第三步：订阅告警
-1.  回到 **Topics** 页面。
-2.  点击 Topic 卡片上的 **订阅图标** (用户组图标)。
-3.  勾选需要接收该 Topic 告警的用户。
-
-#### 第四步：发送告警
-使用你的程序或脚本向系统发送 POST 请求：
-
-**POST** `http://localhost:3000/api/webhook/:slug`
-
-示例 (curl):
-
-```bash
-curl -X POST http://localhost:3000/api/webhook/payment-error \
-  -H "Content-Type: application/json" \
-  -d '{
-    "msg_type": "text",
-    "content": {
-      "text": "支付接口响应超时 (500ms)"
-    }
-  }'
-```
-
-系统会查找订阅了 `payment-error` 的所有用户，并通过飞书机器人给他们分别发送私聊消息。
-
-## API 参考
-
-### 发送告警
-
-`POST /api/webhook/:slug`
-
-**Parameters:**
-- `slug`: Topic 的唯一标识符。
-
-**Body:**
-直接透传给飞书消息 API 的 `content` 和 `msg_type`。
-
-1. **文本消息**:
+### 1. 发送给个人 (Personal Inbox)
+**URL**: `POST /api/webhook/:your_token/dm`
+**Body**: 
 ```json
 {
   "msg_type": "text",
-  "content": {
-    "text": "告警内容..."
-  }
+  "content": { "text": "这是一条私有告警" }
 }
 ```
 
-2. **富文本/卡片消息**:
-请参考 [飞书发送消息 API 文档](https://open.feishu.cn/document/server-docs/im-v1/message/create) 构建 `content`。
+### 2. 发送到主题 (Topic)
+**URL**: `POST /api/webhook/:your_token/topic/:topic_slug`
+**Body**: 同上。系统会自动根据该 Topic 的订阅列表进行广播。
 
-## 项目结构
+---
 
-*   `apps/server`: 后端服务 (Hono + Drizzle)
-    *   `src/index.ts`: 入口文件
-    *   `src/feishu.ts`: 飞书 API 客户端
-    *   `src/webhook.ts`: 告警处理与分发逻辑
-    *   `src/db`: 数据库 Schema (Topics, Users, Subscriptions)
-*   `apps/web`: 前端界面 (React + Vite)
-    *   `src/views/SystemLoadView.tsx`: 实时监控仪表盘
-    *   `src/views/AdminView.tsx`: 后台管理与仪表盘集成
+## 📂 项目结构
+
+- `apps/server`: 核心 API 服务，处理 OAuth、Webhook 解析与飞书分发。
+- `apps/web`: 响应式管理后台。
+- `docs/copilot-context.md`: 为 AI 辅助编程提供的深层架构背景。
+
+---
+*Created with ❤️ by the Alert Message Center Team.*