Lixabeth20/Rule-Weaver
GitHub: Lixabeth20/Rule-Weaver
一款让风控分析师可视化创建欺诈检测规则并实时查看交易拦截/标记/放行结果的前后端一体化应用。
Stars: 0 | Forks: 0
## 概述
本项目使用以下技术栈：
- Vite
- Typescript
- React Router v7（所有导入均来自 `react-router` 而非 `react-router-dom`）
- React 19（用于前端组件）
- Tailwind v4（用于样式设计）
- Shadcn UI（用于 UI 组件库）
- Lucide Icons（用于图标）
- Convex（用于后端和数据库）
- Convex Auth（用于身份验证）
- Framer Motion（用于动画）
- Three js（用于 3D 模型）
所有相关文件均位于 'src' 目录中。
请使用 bun 作为包管理器。
## 设置
本项目已完成配置，不仅可以在云端环境中运行，也支持在沙盒中进行 Convex 开发。
## 环境变量
该项目在客户端配置了项目专属的 `CONVEX_DEPLOYMENT` 和 `VITE_CONVEX_URL` 环境变量。
Convex 服务器拥有一套独立的环境变量，可供 Convex 后端访问。
目前，这些变量包含与身份验证相关的密钥：JWKS、JWT_PRIVATE_KEY 和 SITE_URL。
# 使用身份验证（重要！）
在使用身份验证时，您必须遵循以下约定。
## 身份验证已设置完毕。
所有 Convex 身份验证功能均已配置完成。目前该身份验证支持邮箱 OTP 和匿名用户，并且可以扩展支持更多方式。
邮箱 OTP 的配置定义在 `src/convex/auth/emailOtp.ts` 中。请勿修改此文件。
此外，请勿修改以下身份验证文件：`src/convex/auth.config.ts` 和 `src/convex/auth.ts`。
## 在后端使用 Convex Auth
在 `src/convex/users.ts` 文件中，您可以使用 `getCurrentUser` 函数来获取当前用户的数据。
## 在前端使用 Convex Auth
`/auth` 页面已配置为支持身份验证。请导航至 `/auth` 以执行所有登录/注册流程。
您必须使用此 hook 来获取用户数据。切勿在没有此 hook 的情况下自行获取：
```
import { useAuth } from "@/hooks/use-auth";
const { isLoading, isAuthenticated, user, signIn, signOut } = useAuth();
```
## 受保护的路由
在保护页面时，请使用身份验证 hook 来检查用户的登录状态，并在需要时重定向到 `/auth`。
## 认证页面
认证页面定义在 `src/pages/Auth.tsx` 中。请将经过身份验证的页面以及登录/注册流程重定向到 `/auth`。
## 授权
您可以在前端和后端执行授权检查。
在前端，您可以使用 `useAuth` hook 来获取当前用户的数据和身份验证状态。
您还应该在基础层面对 queries、mutations 和 actions 进行保护，安全地执行授权检查。
## 在身份验证后添加重定向
在 `src/main.tsx` 中，您必须添加身份验证后的重定向 URL，以便在认证成功后跳转至正确的看板/个人资料/页面。
# 前端开发规范
您将使用结合了 React 19、Tailwind v4 和 Shadcn UI 的 Vite 前端。
通常，页面应放在 `src/pages` 目录中，而组件应放在 `src/components` 目录中。
Shadcn 原生组件位于 `src/components/ui` 目录中，默认情况下应直接使用它们。
## 页面路由
您的页面组件应当放在 `src/pages` 目录下。
添加新页面时，请务必更新 `src/main.tsx` 中的 React Router 配置，以包含您刚刚新增的路由。
## Shadcn UI 规范
使用 Shadcn 组件时请遵循以下规范，并且默认情况下您应当优先使用它们。
- 记得使用 "cursor-pointer" 让元素可点击
- 对于标题文本，请使用 "tracking-tight font-bold" 类名以提高可读性
- 务必确保应用程序具备良好的移动端响应式。这一点非常重要
- 避免嵌套卡片。尽量不要嵌套卡片、边框、组件等。嵌套卡片会增加视觉杂乱感，使应用显得混乱。
- 避免使用阴影。请勿为组件添加任何阴影，保持使用不带阴影的细边框即可。
- 避免使用骨架屏；相反，请使用 loader2 组件来在加载数据时展示旋转的加载状态。
## 落地页
您必须始终为应用程序创建外观精美且达到设计师水准的样式。
- 制作精良的动画并契合特定的“主题”（例如：新粗野主义、复古风、新拟态、玻璃拟态等）
请使用网络上广为人知的图片和 Emoji。
如果用户已经登录，请将“开始使用”按钮修改为显示“控制台”或“个人资料”，以便引导他们进入相应页面。
## 响应式与排版
确保使用容器包裹页面，以防止宽度在宽屏设备上过度拉伸。务必保证页面居中对齐，避免出现偏移。
务必确保您的设计具备良好的移动端响应式。请检查排版格式，以确保设置了正确的最大/最小宽度，并适配移动端响应。
- 务必为受保护的控制台页面创建侧边栏，并支持在各个页面之间进行导航
- 务必为落地页创建导航栏
- 在这些导航栏上，创建的 Logo 应当是可点击的，并且能重定向到首页（index 页面）
## 使用 Framer Motion 制作动画
您必须使用 Framer Motion 为组件添加动画效果。项目中已经安装并配置好了该库。
要使用它，请从 `framer-motion` 导入 `motion` 组件，并用它包裹您想要添加动画的组件。
### 其他需要添加动画的元素
- 淡入和淡出
- 滑入和滑出动画
- 渲染动画
- 按钮点击和其他 UI 元素
请为所有组件添加动画效果，包括落地页和应用内部页面。
## Three JS 图形
您的应用程序默认集成了 Three js。您可以使用它为落地页、游戏等创建 3D 图形。
## 颜色
您可以在以下文件中覆盖颜色配置：`src/index.css`
这里使用了适用于 Tailwind v4 的 oklch 颜色格式。
请始终使用这些颜色变量名。
确保所有 UI 组件都具备移动端响应式，并同时兼容浅色和深色模式。
请在父级的 className 中使用 `dark` 或 `light` 变量来设置主题。
## 样式与主题
更改主题时，请务必在 `src/components/ui` 中全局修改 Shadcn 组件的底层主题，并同时更新 `index.css` 文件中的颜色。
除非特定用例需要，否则请避免硬编码颜色，并确保通过底层的 Shadcn UI 组件来正确实现主题。
在进行样式设计时，请确保按钮和可点击元素具备 pointer-click 样式（默认情况下通常没有）。
请始终遵循设定的主题风格，并确保其符合用户的喜好。
## Toast 提示
您应当始终使用 Toast 提示来向用户展示操作结果，例如确认信息、执行结果、错误提示等。
请使用 Shadcn 的 Sonner 组件作为 Toaster（提示框）。例如：
```
import { toast } from "sonner"
import { Button } from "@/components/ui/button"
export function SonnerDemo() {
return (
)
}
```
请记得从 "sonner" 导入 `{ toast }`。用法：`toast("Event has been created.")`
## 对话框
请务必确保较大型的 Dialog（对话框）在其内容区域支持滚动，以保证内容能够适应屏幕大小。确保内容不会被屏幕截断。
理想情况下，请尽量使用 Dialog 而不是跳转到一个新页面。
# 使用 Convex 后端
您将负责实现 Convex 后端。请运用您对 Convex 的了解及相关文档来实现后端逻辑。
## Convex Schema
您必须严格遵循 Convex 的 Schema（模式）实现规范。
Schema 定义在 `src/convex/schema.ts` 文件中。
请勿在您的 queries 中包含 `_id` 和 `_creationTime` 字段（每张表默认已包含这些字段）。
请勿对 `_creationTime` 进行索引，因为它已由系统自动为您建立索引。绝不能出现重复的索引。
## Convex Actions：使用 CRUD 操作
在执行任何涉及外部连接的操作时，您必须在文件顶部带有 "use node" 声明的 Convex Action 中进行处理。
在声明了 "use node" 的 action 文件中，不能同时包含 queries 或 mutations。因此，您必须调用其他文件中已预构建好的 queries 和 mutations。
您还可以使用预装的内部 CRUD 函数来操作数据库：
```
// in convex/users.ts
import { crud } from "convex-helpers/server/crud";
import schema from "./schema.ts";
export const { create, read, update, destroy } = crud(schema, "users");
// in some file, in an action:
const user = await ctx.runQuery(internal.users.read, { id: userId });
await ctx.runMutation(internal.users.update, {
id: userId,
patch: {
status: "inactive",
},
});
```
## 使用 Convex 时需避免的常见错误
使用 Convex 时，请确保：
- 文档 ID 使用 `_id` 字段进行引用，而不是 `id`。
- 文档 ID 类型应表示为 `Id<"TableName">`，而不是 `string`。
- 文档对象类型应表示为 `Doc<"TableName">`。
- 在 schema 文件中将 schemaValidation 保持为 false。
- 必须正确地对您的代码进行类型定义，以便通过类型检查器。
- 必须妥善处理前端和后端 Convex queries 中可能出现的 null / undefined 情况，否则系统会抛出数据可能为 null 或 undefined 的错误。
- 始终使用 `@/folder` 路径，并遵循 `@/convex/folder/file.ts` 语法来导入 Convex 文件。
- 这包括导入生成的文件，如 `@/convex/_generated/server` 和 `@/convex/_generated/api`。
- 记得从 `convex/react` 导入 useQuery、useMutation、useAction 等函数。
- 绝对不要使用返回类型验证器。
标签：Convex, React, Syscall, Syscalls, TypeScript, Vite, Web开发, 安全插件, 自动化攻击, 风控规则引擎