项目技术栈

# 项目技术栈

> 本文档记录企业管理数字化中台的完整技术栈信息

---

## &#128203; 核心框架

| 技术 | 版本 | 用途 |
|------|------|------|
| **Next.js** | 16.1.1 | 全栈框架（App Router） |
| **React** | 19.2.3 | UI 库 |
| **TypeScript** | 5.9.3 | 类型安全 |
| **Node.js** | 24+ | 运行时环境 |

---

## &#128452;️ 数据库

| 技术 | 版本 | 用途 |
|------|------|------|
| **PostgreSQL** | 15+ | 主数据库（LIST 分区） |
| **Drizzle ORM** | 0.45.1 | 数据库 ORM |
| **pg** | 8.16.3 | PostgreSQL 驱动 |

---

## &#127912; UI 组件库

| 技术 | 版本 | 用途 |
|------|------|------|
| **shadcn/ui** | 基于 Radix UI | 主要 UI 组件 |
| **Ant Design** | 6.2.2 | 企业级组件 |
| **Tailwind CSS** | 4.x | 样式框架 |
| **Lucide React** | 0.468.0 | 图标库 |

### Radix UI 组件清单

- @radix-ui/react-accordion
- @radix-ui/react-alert-dialog
- @radix-ui/react-avatar
- @radix-ui/react-checkbox
- @radix-ui/react-dialog
- @radix-ui/react-dropdown-menu
- @radix-ui/react-popover
- @radix-ui/react-select
- @radix-ui/react-tabs
- @radix-ui/react-toast
- @radix-ui/react-tooltip
- 等共 20+ 组件

---

## &#128295; 状态管理 & 表单

| 技术 | 版本 | 用途 |
|------|------|------|
| **Zustand** | 5.0.10 | 状态管理 |
| **React Hook Form** | 7.70.0 | 表单处理 |
| **Zod** | 4.3.6 | 数据验证 |

---

## &#128272; 认证 & 安全

| 技术 | 版本 | 用途 |
|------|------|------|
| **JWT (jose)** | 6.1.3 | Token 认证 |
| **jsonwebtoken** | 9.0.3 | JWT 处理 |
| **bcrypt** | 6.0.0 | 密码加密 |
| **bcryptjs** | 3.0.3 | 密码加密（兼容层） |
| **next-themes** | 0.4.6 | 主题切换 |

---

## &#128193; 文件 & 数据处理

| 技术 | 版本 | 用途 |
|------|------|------|
| **xlsx** | 0.18.5 | Excel 处理（工资条导入导出） |
| **html2canvas** | 1.4.1 | 截图导出 |
| **jspdf** | 4.2.0 | PDF 生成 |
| **mammoth** | 1.12.0 | Word 文档解析 |
| **archiver** | 7.0.1 | 文件压缩 |
| **unzipper** | 0.12.3 | 文件解压 |
| **sharp** | 0.34.5 | 图片处理 |
| **image-size** | 2.0.2 | 图片尺寸获取 |

---

## ☁️ 云服务 & 存储

| 技术 | 版本 | 用途 |
|------|------|------|
| **七牛云 SDK (qiniu)** | 7.15.1 | 对象存储（主存储） |
| **AWS S3 SDK** | 3.958.0 | S3 兼容存储 |
| **阿里云 SMS SDK** | 4.4.0 | 短信服务 |
| **腾讯云 SDK** | 4.1.180 | 云服务 |
| **Nodemailer** | 7.0.13 | 邮件发送 |
| **FutureBirdAadminAi-coding-dev-sdk** | 0.7.15 | AI 能力集成 |

---

## ✍️ 富文本 & 编辑器

| 技术 | 版本 | 用途 |
|------|------|------|
| **TipTap** | 3.22.5 | 富文本编辑器 |
| **React Markdown** | 9.0.1 | Markdown 渲染 |
| **remark-gfm** | 4.0.0 | GitHub 风格 Markdown |

### TipTap 扩展

- @tiptap/extension-color - 颜色
- @tiptap/extension-image - 图片
- @tiptap/extension-link - 链接
- @tiptap/extension-text-align - 对齐
- @tiptap/extension-underline - 下划线

---

## &#128202; 图表 & 可视化

| 技术 | 版本 | 用途 |
|------|------|------|
| **Recharts** | 2.15.4 | 图表库（Dashboard 统计） |

---

## &#127919; 特殊功能

| 技术 | 版本 | 用途 |
|------|------|------|
| **lunar-javascript** | 1.7.7 | 农历转换（生日处理） |
| **QRCode** | 1.5.4 | 二维码生成 |
| **qrcode.react** | 4.2.0 | React 二维码组件 |
| **Handlebars** | 4.7.9 | 模板引擎（邮件模板） |
| **node-cron** | 4.2.1 | 定时任务 |
| **date-fns** | 4.1.0 | 日期处理 |
| **dayjs** | 1.11.19 | 日期处理 |
| **nanoid** | 5.1.6 | ID 生成 |
| **wechat-api** | 1.35.1 | 微信 API |

---

## &#129514; 开发工具

| 技术 | 版本 | 用途 |
|------|------|------|
| **pnpm** | 9.0.0+ | 包管理器（强制） |
| **ESLint** | 9.x | 代码检查 |
| **Prettier** | - | 代码格式化 |
| **Jest** | 30.2.0 | 单元测试 |
| **Playwright** | 1.58.2 | E2E 测试 |
| **tsx** | 4.21.0 | TypeScript 执行 |

---

## &#128260; 拖拽 & 交互

| 技术 | 版本 | 用途 |
|------|------|------|
| **@dnd-kit/core** | 6.3.1 | 拖拽核心 |
| **@dnd-kit/sortable** | 10.0.0 | 排序拖拽 |
| **@hello-pangea/dnd** | 18.0.1 | 拖拽备选方案 |

---

## &#128241; UI 辅助

| 技术 | 版本 | 用途 |
|------|------|------|
| **cmdk** | 1.1.1 | 命令面板 |
| **sonner** | 2.0.7 | Toast 通知 |
| **vaul** | 1.1.2 | Drawer 抽屉 |
| **input-otp** | 1.4.2 | OTP 输入 |
| **react-dropzone** | 14.4.0 | 文件上传 |
| **react-resizable-panels** | 4.2.0 | 可调整面板 |
| **embla-carousel-react** | 8.6.0 | 轮播图 |

---

## &#127959;️ 系统架构

```
├── src/app/
│   ├── admin/          # 主系统后台管理
│   ├── employee/       # 员工端（工资条查看）
│   ├── tenant/         # 企业端（企业管理）
│   ├── partner/        # 合作伙伴端
│   └── api/            # API 路由
├── src/services/       # 认证与权限服务
├── src/storage/        # Drizzle ORM 表结构
├── src/infrastructure/ # 数据库 Schema
├── src/lib/            # 工具库
├── src/components/     # React 组件
│   ├── ui/             # 基础 UI 组件（shadcn/ui）
│   └── ...             # 业务组件
├── src/stores/         # Zustand 状态管理
├── src/hooks/          # React Hooks
├── src/types/          # TypeScript 类型定义
└── docs/               # 项目文档
```

---

## ⚙️ 运行配置

### 端口

| 环境 | 端口 | 说明 |
|------|------|------|
| 开发环境 | 5000 | pnpm dev |
| 生产环境 | 5000 | 通过 Nginx 反向代理到 80/443 |

### 环境变量

| 变量 | 说明 |
|------|------|
| `DATABASE_URL` | PostgreSQL 连接字符串 |
| `NODE_ENV` | 运行环境（development/production） |
| `DEPLOY_RUN_PORT` | 服务端口（默认 5000） |
| `FutureBirdAadminAi_PROJECT_DOMAIN_DEFAULT` | 对外访问域名 |

---

## &#128230; 包管理器

**强制使用 pnpm**

```json
{
  "packageManager": "pnpm@9.0.0",
  "engines": {
    "pnpm": ">=9.0.0"
  }
}
```

已配置 `preinstall` 钩子，自动阻止使用 npm/yarn。

---

## &#128202; 数据库分区

**本项目主数据库采用 PostgreSQL LIST 分区**

| 基础表名 | 分区命名规则 |
|----------|--------------|
| `saas_users` | `saas_users_{company_id}` |
| `saas_orders` | `saas_orders_{company_id}` |
| `salary_slips` | `salary_slips_{company_id}` |

**分区表开发约束：**
1. 查询**必须**带 `company_id` 过滤（触发分区裁剪）
2. 插入**必须**包含 `company_id` 字段
3. 主键是复合主键：`(id, company_id)`

---

## &#128279; 数据库表清单

### 主系统（SaaS核心）

- `saas_tenants` - 租户表
- `saas_companies` - 企业表
- `saas_users` - 用户表（分区）
- `saas_orders` - 订单表（分区）
- `salary_slips` - 工资条表（分区）
- `salary_slip_details` - 工资条明细表
- `employees` - 员工信息表
- `unified_configs` - 统一配置表

### 身份权限体系

- `roles` - 角色表（9个预置角色）
- `user_roles` - 用户角色关联表
- `permissions` - 权限表（20个预置权限）
- `app_permissions` - 应用权限关联表

### 应用体系

- `apps` - 应用定义表（6个预置应用）
- `company_app_instances` - 企业应用实例表

---

## &#128221; 更新日志

| 日期 | 更新内容 |
|------|---------|
| 2025-01 | 初始版本，记录完整技术栈 |