Initial commit

rules/backend-guidelines.md

@@ -0,0 +1,59 @@
+---
+description: InsightReply 后端 Go/API 编码规范与架构设计
+globs: *.go, *.sql
+---
+# InsightReply 后端 Go 编码与 API 设计规范
+
+本文档定义了 InsightReply 后端服务（Golang）的架构风格、代码组织模式及统一的 API 响应标准。
+
+## 一、 整体架构模式
+
+后端服务采用 **清晰架构 (Clean Architecture / Domain-Driven Design 简化版)** 进行分层，严禁跨层调用：
+
+*   **`cmd/server/`**: 应用入口，加载配置、初始化路由与数据库连接。
+*   **`internal/handler/`** (或 `controller/`): 负责接收 HTTP 请求，解析参数，并将其转化为业务层需要的结构。
+*   **`internal/service/`**: 存放核心业务逻辑（如调用 LLM 生成评论的策略代码、热度计算公式的落地）。
+*   **`internal/repository/`** (或 `model/`): 负责与 PostgreSQL 数据库交互（封装所有的 SQL / ORM 逻辑）。
+
+## 二、 统一接口标准 (RESTful)
+
+所有对外部浏览器和前端暴露的 HTTP JSON 接口，必须严格遵守统一的包装格式。
+
+### 1. 成功响应
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "replies": [...] // 具体的业务数据
+  }
+}
+```
+
+### 2. 失败响应（业务报错）
+*   `code`: > 200 的自定义业务状态码（例如 `4001` 表示参数错误，`4003` 表示权限不足）。
+*   `message`: 面向前端的友好提示。
+```json
+{
+  "code": 4001,
+  "message": "推文链接解析失败",
+  "data": null
+}
+```
+*注：HTTP Status Code 应依然使用 `400 Bad Request` 或 `500 Internal Server Error` 匹配网络层的状态语义。*
+
+## 三、 Go 代码风格与规范
+
+*   **错误处理 (Error Handling)**:
+    *   坚决避免到处写 `err != nil` 却只做透明抛出的行为，当错误发生时，使用 `fmt.Errorf("doSomething failed: %w", err)` 包装上游错误信息，以便追踪。
+*   **命名规范**:
+    *   包名 (`package`): 保持简短、全部小写、无下划线，不使用复数形式（如用 `user` 而非 `users`）。
+    *   接口类型名 (`interface`): 通常以 `-er` 结尾（如 `Reader`, `TweetFetcher`）。
+*   **日志打印**:
+    *   关键的业务路径（如调用第三方 LLM API 失败）、恐慌恢复 (Panic Recovery)、定时任务失败必须有结构化的日志记录。
+
+## 四、 数据库 (PostgreSQL) 规范
+
+*   对于本项目的初步开发，推荐使用如 **`gorm`** 或 **`sqlx`** 进行快速的数据交互操作。
+*   所有表名、字段名在 Go 结构体 (`struct`) 的 tag 中必须显式定义为下划线 (snake_case)。
+*   UUID 作为主键，禁止前端或外部服务自行生成传入，一律由 PostgreSQL `gen_random_uuid()` 或者服务端生成。

rules/frontend-guidelines.md

@@ -0,0 +1,83 @@
+---
+description: InsightReply 前端 UI/UX 编码规范与实现方案
+globs: *.ts, *.tsx, *.vue, *.css, *.html
+---
+# InsightReply 前端 UI/UX 编码规范与实现方案
+
+本文档基于 `ui-ux-pro-max` 高级设计理念以及现代前端工程化标准，定义了 InsightReply 浏览器插件和 Web 后台的开发规范。
+
+## 一、 核心视觉原则 (ui-ux-pro-max 特性)
+
+### 1. 极致暗黑与毛玻璃 (Premium Dark Mode & Glassmorphism)
+我们致力于打造充满极客感、空间感和现代感的界面。
+
+*   **色彩体系**：
+    *   主背景色：采用深度黑或深炭灰（例如 `#0A0A0A` 到 `#171717`），坚决避免使用死板的纯黑 (`#000000`)。
+    *   次级面板：使用比背景稍亮的一级的灰色区分层级。
+    *   强调文字：避免纯白，使用柔和的高反差灰色（如 `#E5E5E5` 或 `#D4D4D4`）减轻视觉疲劳。
+*   **毛玻璃效果 (Glassmorphism)**：
+    *   重点应用场景：浏览器插件悬浮弹窗、侧边通知、下拉菜单。
+    *   CSS 标准：`background-color: rgba(23, 23, 23, 0.7); backdrop-filter: blur(12px); border: 1px solid rgba(255, 255, 255, 0.1);`。
+
+### 2. 动态交互与微动画 (Micro-Interactions)
+所有交互必须平滑且具有生命力。
+
+*   **过渡动画 (Transitions)**：
+    *   所有按钮悬停 (Hover)、面板展开 (Expand) 等状态变化必须带有过渡。
+    *   标准推荐：`transition-all duration-200 ease-in-out`。
+*   **状态反馈 (Feedback)**：
+    *   点击事件触发时提供细微的尺寸缩小反馈 (如 `active:scale-95`)。
+    *   Loading 或 Success 状态需辅以平滑的 SVG 骨架或打勾动画。
+
+### 3. 排版体系与强调色 (Typography & Accent)
+
+*   **现代无衬线字体**：
+    *   优先字体栈：`Inter`, `Geist`, 或 Apple 原生 `SF Pro`。确保字母间距 (Tracking) 在小号字时适当放宽，大标题时适当收紧。
+*   **品牌强调色 (Accent Colors)**：
+    *   主推 AI 科技质感的渐变色。例如：紫蓝渐变 `from-violet-500 to-blue-500`。
+    *   应用于：核心 Call To Action (CTA) 按钮、选中的 Tab 下划线、高亮的重要标签。
+
+---
+
+## 二、 技术栈实现规范 (Tailwind CSS 最佳实践)
+
+我们将使用 **Tailwind CSS (v3 / v4)**，结合以下工程化工具链，系统化落地 `ui-ux-pro-max`：
+
+### 1. 原子化运用与 Design Tokens
+*   **禁止硬编码魔法值**。所有的自定义颜色（如品牌色紫蓝）、特殊间距，尽其所能都在 `tailwind.config.ts` (或 js) 的 `theme.extend` 中被转换为 Tokens。
+*   例子：`bg-brand-primary` 替代 `bg-[#8B5CF6]`。
+
+### 2. 动态类名管理的终极方案
+所有复用性高、含动态计算逻辑的 UI 组件，必须引入 `clsx` 和 `tailwind-merge` 这个组合包（通常约定以 `cn` 函数导出）。
+
+*   **原因**：避免你在子组件传参时（例如 `class="bg-red-500"`），因为和组件内部默认的 `bg-blue-500` 发成 Tailwind 权重冲突导致样式失效。
+*   **`lib/utils.ts` 工具函数标准写法**：
+    ```typescript
+    import { clsx, type ClassValue } from "clsx"
+    import { twMerge } from "tailwind-merge"
+
+    export function cn(...inputs: ClassValue[]) {
+      return twMerge(clsx(inputs))
+    }
+    ```
+
+### 3. 组件化结构
+高频 UI 实体必须封装。以 Vue 3 + Tailwind 为例：
+*   所有属性 (Props) 变化带来的 UI 变化，结合上述的 `cn` 在 `<script setup>` 顶部计算完毕。
+*   如非极其生僻或庞大的样式块，尽量不要使用 `<style>` 块里的 `@apply`，坚持 Inline Tailwind classes，保证组件的可移植性。
+
+---
+
+## 三、 浏览器插件 (Chrome Extension) 特定架构规范
+
+由于 InsightReply 需要在强敌环伺的第三方页面（如 X / Twitter）上运行，前端注入策略尤为关键。
+
+### 1. UI 隔离：必须采用 Shadow DOM
+*   **痛点**：Twitter 原生大量的 CSS 选择器极易破坏我们插件的排版（例如它的 `div`, `span` 默认样式），同时我们的样式如果泄漏也可能打乱 Twitter。
+*   **规范强制**：
+    所有注入到宿主页面的 Content Scripts 最终挂载点 (Mount Root) 必须被包装在 `ShadowRoot` 之内。所有的 Tailwind 打包产物 CSS 将局部单向注入到该 ShadowTree 内。
+
+### 2. 轻量化与按需加载
+*   插件端对体积非常敏感。
+*   绝不全量引入极其庞大的组件库包（如不按需加载全量导入 Element Plus）。
+*   页面侧边栏组件与 Background Service Worker (Go 通讯代理层) 通过标准 `chrome.runtime.sendMessage` 保持极简高效的通讯。