@@ -1,12 +1,11 @@
## 项目说明
本项目模板( Hair Keeper v1.2 .0) 是一个高度集成、深度定制、约定优于配置的全栈Web应用模板, 旨在保持灵活性的同时提供一套基于成熟架构的开发底座, 自带身份认证、权限控制、丰富前端组件、文件上传、后台任务、智能体开发等丰富功能, 提供AI开发辅助, 免于纠结功能如何实现, 可快速上手专注于业务逻辑。
本项目模板( Hair Keeper v1.1 .0) 是一个高度集成、深度定制、约定优于配置的全栈Web应用模板, 旨在保持灵活性的同时提供一套基于成熟架构的开发底座, 自带身份认证、权限控制、丰富前端组件、文件上传、后台任务、智能体开发等丰富功能, 提供AI开发辅助, 免于纠结功能如何实现, 可快速上手专注于业务逻辑。
Hair Keeper是个诙谐有趣的名称, 和项目内容毫无关系。
开发者直接在本项目模板的基础上进行开发,本项目源代码完全对开发者可见并可以随时修改、扩展功能、增加新的组件和模块,开发者尽量遵从如下文表述的约定和项目文件组织规则。
## 主要依赖库
本项目使用pnpm作为包管理器
- 基础: next + react + trpc + prisma
- UI基础框架: tailwindcss + radix-ui(基于shadcn/ui库添加组件) + lucide-react + sonner(toast)
- 图表等高级UI: recharts(图表) + xyflow/react(节点图 dagre自动布局) + embla-carousel-react + dnd-kit/sortable
@@ -46,43 +45,44 @@ Hair Keeper是个诙谐有趣的名称, 和项目内容毫无关系。
## 重要目录和文件
### 前端
- `src/ components/common/` : 进一步封装的高级通用控件, 例如下拉菜单、对话框表单、响应式tabs等控件
- `src/ components/features/` :进一步封装的控件,通常更重或者与业务关联强需要在不同的页面中复用
- `src/ components/ai-elements/` : ai对话相关的组件
- `src/ components/data-details/` : 专注于数据展示的可复用控件, 例如detail-badge-list、detail-copyable、detail-list、detail-timeline等控件
- `src/ components/data-table/` : 专注于数据表格的可复用控件, 本项目模板自带了基础的data-table、过滤器、排序、分页、列可见性切换等功能
- `src/ components/icons/` :项目的自定义图标可以写在这个文件夹
- `src/ components/layout/` :应用的完整布局框架和导航系统以及可复用的布局容器
- `src/ components/ui/` : 高度可定制可复用的基础UI组件, 通常源自第三方库
- `src/ app/(main)/` :开发者在这里自行实现的所有业务的页面
- `src/ app/(main)/dev/` :辅助开发的页面,本项目模板在其中实现了许多功能,代码在实现业务时也可以借鉴参考
- `src/ app/(main)/settings/` :全局设置,由开发者根据业务需求进行补充和实现
- `src/ app/(main)/users/` : 用户管理模块, 提供用户CRUD、角色管理、批量授权等完整的用户管理功能的页面和组件实现
- `src/ hooks/` : 可复用React Hooks库, 部分复杂的组件也通过hook实现Headless UI逻辑与样式分离, 组件中可复用的逻辑都可以放在这
- `src/ lib/trpc.ts` : 创建并导出tRPC React客户端实例, 用于前端与后端API通信
- `src/ lib/stores/` : 通过zustand管理的全局的状态
- `components/common/` : 进一步封装的高级通用控件, 例如下拉菜单、对话框表单、响应式tabs等控件
- `components/features/` :进一步封装的控件,通常更重或者与业务关联强需要在不同的页面中复用
- `components/ai-elements/` : ai对话相关的组件
- `components/data-details/` : 专注于数据展示的可复用控件, 例如detail-badge-list、detail-copyable、detail-list、detail-timeline等控件
- `components/data-table/` : 专注于数据表格的可复用控件, 本项目模板自带了基础的data-table、过滤器、排序、分页、列可见性切换等功能
- `components/icons/` :项目的自定义图标可以写在这个文件夹
- `components/layout/` :应用的完整布局框架和导航系统以及可复用的布局容器
- `components/ui/` : 高度可定制可复用的基础UI组件, 通常源自第三方库
- `app/(main)/` :开发者在这里自行实现的所有业务的页面
- `app/(main)/dev/` :辅助开发的页面,本项目模板在其中实现了许多功能,代码在实现业务时也可以借鉴参考
- `app/(main)/settings/` :全局设置,由开发者根据业务需求进行补充和实现
- `app/(main)/users/` : 用户管理模块, 提供用户CRUD、角色管理、批量授权等完整的用户管理功能的页面和组件实现
- `hooks/` : 可复用React Hooks库, 部分复杂的组件也通过hook实现Headless UI逻辑与样式分离, 组件中可复用的逻辑都可以放在这
- `lib/trpc.ts` : 创建并导出tRPC React客户端实例, 用于前端与后端API通信
- `lib/stores/` : 通过zustand管理的全局的状态
### 后端
- `src/ server/routers/` : 项目trpc api定义文件, 开发者主要在这里定义和实现业务的后端API
- `src/ server/routers/_app.ts` : `appRouter` 根路由定义,需要添加子路由时在此处注册
- `src/ server/routers/common.ts` :定义需要在多个模块中复用的通用业务接口路由
- `src/ server/routers/jobs.ts` : tRPC任务进度订阅路由
- `src/ server/routers/selection.ts` :用于记录用户选择的选项或者输入的内容,优化用户的输入体验
- `src/ server/routers/global.ts` : 系统全局和特定业务关联不大的一些api
- `src/ server/routers/dev/` : 开发模式下的辅助功能需要的trpc api
- `src/ server/queues/` : 消息队列和worker, 通过其中的index.ts统一导出, 任务状态更新采用trpc SSE subscription, 接口定义在`server/routers/jobs.ts` 中
- `src/ server/agents` : LLM的对接和使用
- `src/ server/service/` :服务层模块集合,封装后端业务逻辑和系统服务
- `src/ server/service/dev/` :开发模式下的辅助功能需要的后台服务
- `src/ server/utils/` :服务端专用工具函数库,为后端业务逻辑提供基础设施支持
- `src/ api/dev/` : 开发模式下的辅助功能需要的api
- `server/routers/` : 项目trpc api定义文件, 开发者主要在这里定义和实现业务的后端API
- `server/routers/_app.ts` : `appRouter` 根路由定义,需要添加子路由时在此处注册
- `server/routers/common.ts` :定义需要在多个模块中复用的通用业务接口路由
- `server/routers/jobs.ts` : tRPC任务进度订阅路由
- `server/routers/selection.ts` :用于记录用户选择的选项或者输入的内容,优化用户的输入体验
- `server/routers/global.ts` : 系统全局和特定业务关联不大的一些api
- `server/routers/dev/` : 开发模式下的辅助功能需要的trpc api
- `server/queues/` : 消息队列和worker, 通过其中的index.ts统一导出, 任务状态更新采用trpc SSE subscription, 接口定义在`server/routers/jobs.ts` 中
- `server/agents` : LLM的对接和使用
- `server/service/` :服务层模块集合,封装后端业务逻辑和系统服务
- `server/service/dev/` :开发模式下的辅助功能需要的后台服务
- `server/utils/` :服务端专用工具函数库,为后端业务逻辑提供基础设施支持
- `api/dev/` : 开发模式下的辅助功能需要的api
### 其他
- `src/ constants/` :项目全局常量管理
- `src/ constants/permissions.ts` :权限定义,支持前后端一致的权限控制,支持解析复杂的权限表达式(如"A&B|(C&D)")
- `src/lib/schema/` : 集中管理数据验证schema, 定义前后端统一的数据结构和验证规则, 前端对默认值等其他要求写在表单组件中, 后端对默认值等其他要求写在接口文件中, 使用z.input而不是z.infer来获取Schema的输入类型
- `src/lib/algorithom.ts` :通用计算机算法实现,例如拓扑排序
- `src/lib/format.ts` :数据格式化工具函数库
- `constants/` :项目全局常量管理
- `constants/permissions.ts` :权限定义,支持前后端一致的权限控制,支持解析复杂的权限表达式(如"A&B|(C&D)")
- `constants/menu.ts` : 菜单管理工具库,提供菜单项定义、查询、权限过滤等功能
- `lib/schema/` : 集中管理数据验证schema, 定义前后端统一的数据结构和验证规则, 前端对默认值等其他要求写在表单组件中, 后端对默认值等其他要求写在接口文件中, 使用z.input而不是z.infer来获取Schema的输入类型
- `lib/algorithom.ts` :通用计算机算法实现,例如拓扑排序
- `lib/format.ts` :数据格式化工具函数库
## 非标准命令
- `pnpm run dev:attach` : 这会使用tmux在名为nextdev的session中启动pnpm run dev, 便于在开发页面或其他地方与开发服务器交互