300 lines
10 KiB
Markdown
300 lines
10 KiB
Markdown
# FischerX
|
||
|
||
Fischer公司开发底座 — 适配国内运行环境的全栈Monorepo项目，理念对标John Rush的Mars Stack/Mars Foundation。
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
- **框架**: Next.js 14+ (App Router)
|
||
- **语言**: TypeScript (严格模式)
|
||
- **样式**: Tailwind CSS
|
||
- **UI组件**: Shadcn UI
|
||
- **状态管理**: Zustand + React Query
|
||
- **表单**: React Hook Form + Zod
|
||
- **测试**: Vitest + Playwright
|
||
|
||
### 后端
|
||
- **框架**: NestJS
|
||
- **ORM**: Prisma
|
||
- **数据库**: PostgreSQL
|
||
- **缓存**: Redis
|
||
- **认证**: JWT + Passport
|
||
- **测试**: Jest
|
||
|
||
### 基础设施
|
||
- **容器化**: Docker + Docker Compose
|
||
- **编排**: Kubernetes (阿里云ACK)
|
||
- **IaC**: Terraform
|
||
- **CI/CD**: GitHub Actions
|
||
- **监控**: Prometheus + Grafana + Loki + Jaeger
|
||
|
||
### 工具链
|
||
- **包管理**: pnpm
|
||
- **构建系统**: Turborepo
|
||
- **代码规范**: ESLint + Prettier
|
||
- **CLI工具**: @fischerx/cli
|
||
|
||
## 核心模块
|
||
|
||
| 模块 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| 用户管理 | 用户CRUD、头像上传 | ✅ 完成 |
|
||
| 认证授权 | JWT、Session、手机号登录、微信/支付宝OAuth、实名认证、MFA | ✅ 完成 |
|
||
| 权限控制 | RBAC模型、角色管理、权限分配、装饰器守卫 | ✅ 完成 |
|
||
| 文件存储 | 阿里云OSS、腾讯云COS、MinIO、图片处理、CDN | ✅ 完成 |
|
||
| 支付系统 | 支付宝、微信支付、银联适配器、退款、对账 | ✅ 完成 |
|
||
| 消息通知 | 邮件、短信、推送、站内信（适配器模式） | ✅ 完成 |
|
||
| 内容管理 | 文章、分类、标签、评论、版本控制 | ✅ 后端完成 |
|
||
| 监控告警 | Prometheus + Grafana + AlertManager + Loki + Jaeger | ✅ 完成 |
|
||
| CLI工具 | 项目初始化、代码生成、部署命令 | ✅ 完成 |
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
- Node.js >= 18.0.0
|
||
- pnpm >= 8.0.0
|
||
- Docker & Docker Compose
|
||
- PostgreSQL 15+
|
||
- Redis 7+
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone http://8.153.107.96/fischer/fischerX.git
|
||
cd fischerX
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
```
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 1. 启动基础设施（PostgreSQL + Redis）
|
||
docker-compose up -d postgres redis
|
||
|
||
# 2. 配置环境变量
|
||
cp services/api/.env.example services/api/.env
|
||
# 编辑 .env 填入数据库连接、Redis连接、JWT密钥等
|
||
|
||
# 3. 运行数据库迁移
|
||
cd services/api
|
||
npx prisma migrate dev
|
||
cd ../..
|
||
|
||
# 4. 启动后端API服务
|
||
cd services/api
|
||
pnpm start:dev
|
||
|
||
# 5. 启动前端Web应用
|
||
cd apps/web
|
||
pnpm dev
|
||
```
|
||
|
||
### 访问地址
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| 前端Web | http://localhost:3000 |
|
||
| 后端API | http://localhost:3001/api/v1/health |
|
||
| Grafana | http://localhost:3001 (admin/fischerx123) |
|
||
| Prometheus | http://localhost:9090 |
|
||
| Jaeger | http://localhost:16686 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
FischerX/
|
||
├── apps/ # 应用层
|
||
│ ├── web/ # Web应用 (Next.js)
|
||
│ └── admin/ # 管理后台 (占位)
|
||
├── packages/ # 共享包
|
||
│ ├── core/ # 核心业务逻辑 (@fischerx/core)
|
||
│ ├── ui/ # 共享UI组件 (@fischerx/ui)
|
||
│ ├── utils/ # 工具函数 (@fischerx/utils)
|
||
│ ├── types/ # 类型定义 (@fischerx/types)
|
||
│ ├── config/ # 配置管理 (@fischerx/config)
|
||
│ └── constants/ # 常量定义 (@fischerx/constants)
|
||
├── services/ # 后端服务
|
||
│ └── api/ # API服务 (NestJS)
|
||
│ ├── prisma/ # 数据库Schema
|
||
│ └── src/modules/ # 业务模块
|
||
│ ├── auth/ # 认证授权
|
||
│ ├── rbac/ # 权限控制
|
||
│ ├── user/ # 用户管理
|
||
│ ├── file/ # 文件存储
|
||
│ ├── payment/ # 支付系统
|
||
│ ├── notification/ # 消息通知
|
||
│ ├── content/ # 内容管理
|
||
│ ├── health/ # 健康检查
|
||
│ ├── cache/ # 缓存服务
|
||
│ └── monitoring/ # 监控集成
|
||
├── infra/ # 基础设施
|
||
│ ├── db/ # 数据库Docker配置
|
||
│ ├── k8s/ # Kubernetes配置
|
||
│ ├── monitoring/ # 监控栈 (Prometheus/Grafana/Loki/Jaeger)
|
||
│ ├── terraform/ # 阿里云资源管理
|
||
│ └── envs/ # 多环境配置 (dev/test/prod)
|
||
├── tools/ # 开发工具
|
||
│ └── cli/ # CLI工具 (@fischerx/cli)
|
||
├── docs/ # 文档
|
||
│ ├── architecture/ # 架构文档
|
||
│ ├── requirements/ # 需求文档
|
||
│ ├── design/ # 设计文档
|
||
│ ├── development/ # 开发文档
|
||
│ ├── api/ # API文档
|
||
│ ├── testing/ # 测试文档
|
||
│ ├── deployment/ # 部署文档
|
||
│ ├── operations/ # 运维文档
|
||
│ ├── user/ # 用户文档
|
||
│ └── templates/ # 文档模板
|
||
├── .github/workflows/ # CI/CD (8个Workflow)
|
||
├── docker-compose.yml # Docker Compose
|
||
├── turbo.json # Turborepo配置
|
||
├── pnpm-workspace.yaml # pnpm工作空间
|
||
└── package.json # 根package.json
|
||
```
|
||
|
||
## API端点
|
||
|
||
### 认证授权
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/auth/register | 用户注册 |
|
||
| POST | /api/v1/auth/login | 密码登录 |
|
||
| POST | /api/v1/auth/sms/send | 发送验证码 |
|
||
| POST | /api/v1/auth/sms/login | 验证码登录 |
|
||
| POST | /api/v1/auth/wechat/login | 微信OAuth登录 |
|
||
| POST | /api/v1/auth/alipay/login | 支付宝OAuth登录 |
|
||
| POST | /api/v1/auth/realname/verify | 实名认证 |
|
||
| POST | /api/v1/auth/mfa/enable | 启用MFA |
|
||
| POST | /api/v1/auth/mfa/verify | 验证MFA |
|
||
|
||
### 用户管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/v1/users/me | 当前用户信息 |
|
||
| PUT | /api/v1/users/me | 更新用户信息 |
|
||
| POST | /api/v1/users/me/avatar | 上传头像 |
|
||
| GET | /api/v1/users | 用户列表 (管理员) |
|
||
|
||
### 权限控制
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| CRUD | /api/v1/roles | 角色管理 |
|
||
| CRUD | /api/v1/permissions | 权限管理 |
|
||
| POST | /api/v1/roles/:id/permissions | 分配权限 |
|
||
| POST | /api/v1/users/:id/roles | 分配角色 |
|
||
|
||
### 支付系统
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/payment/orders | 创建支付订单 |
|
||
| GET | /api/v1/payment/orders/:id | 查询订单 |
|
||
| POST | /api/v1/payment/refunds | 申请退款 |
|
||
| POST | /api/v1/payment/callback/:channel | 支付回调 |
|
||
|
||
### 文件存储
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/files/upload | 上传文件 |
|
||
| GET | /api/v1/files | 文件列表 |
|
||
| GET | /api/v1/files/:id | 文件详情 |
|
||
| DELETE | /api/v1/files/:id | 删除文件 |
|
||
|
||
### 消息通知
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/v1/notifications | 发送通知 |
|
||
| GET | /api/v1/notifications | 通知列表 |
|
||
| PUT | /api/v1/notifications/:id/read | 标记已读 |
|
||
|
||
## 底座使用方式
|
||
|
||
### 方式一：Monorepo模式（推荐）
|
||
在FischerX Monorepo中创建新应用，自动继承共享包：
|
||
```bash
|
||
fischerx create-app my-crm --type=admin
|
||
```
|
||
|
||
### 方式二：独立项目模式
|
||
从FischerX模板创建独立项目：
|
||
```bash
|
||
fischerx init client-project --template=standalone
|
||
```
|
||
|
||
### 方式三：API服务模式
|
||
部署FischerX作为共享服务，通过API调用底座功能。
|
||
|
||
## CLI工具
|
||
|
||
```bash
|
||
# 安装
|
||
cd tools/cli && pnpm install && pnpm build
|
||
|
||
# 项目管理
|
||
fischerx init <project-name> # 初始化新项目
|
||
fischerx create-app <app-name> # 创建新应用
|
||
fischerx create-package <pkg-name> # 创建新共享包
|
||
|
||
# 代码生成
|
||
fischerx generate page <name> # 生成页面
|
||
fischerx generate component <name> # 生成组件
|
||
fischerx generate api <name> # 生成API
|
||
fischerx generate module <name> # 生成完整模块
|
||
|
||
# 部署
|
||
fischerx deploy --env dev # 部署到开发环境
|
||
fischerx deploy --env prod # 部署到生产环境
|
||
|
||
# 其他
|
||
fischerx doctor # 检查项目健康
|
||
fischerx info # 显示项目信息
|
||
```
|
||
|
||
## 国内环境适配
|
||
|
||
| 维度 | 适配方案 |
|
||
|------|---------|
|
||
| 云服务 | 阿里云（首选）、腾讯云（备选）、华为云（备选） |
|
||
| 认证 | 手机号验证码、微信OAuth、支付宝OAuth、实名认证 |
|
||
| 支付 | 微信支付、支付宝、银联 |
|
||
| 存储 | 阿里云OSS、腾讯云COS、MinIO私有化 |
|
||
| 短信 | 阿里云短信 |
|
||
| 邮件 | SMTP / 阿里云邮件 |
|
||
| 监控 | Prometheus + Grafana / 阿里云ARMS |
|
||
| 日志 | Loki / 阿里云SLS |
|
||
| 部署 | 阿里云ACK / 自建K8s |
|
||
| CDN | 阿里云CDN |
|
||
|
||
## 可用脚本
|
||
|
||
| 脚本 | 说明 |
|
||
|------|------|
|
||
| `pnpm install` | 安装所有依赖 |
|
||
| `pnpm build` | 构建所有包和应用 |
|
||
| `pnpm dev` | 启动开发服务器 |
|
||
| `pnpm lint` | 运行ESLint检查 |
|
||
| `pnpm test` | 运行所有测试 |
|
||
| `pnpm format` | 使用Prettier格式化代码 |
|
||
|
||
## 待完善功能
|
||
|
||
| 优先级 | 功能 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 订单系统模块 | 独立Order模块，订单状态机 |
|
||
| P0 | 企业微信通知 | WeComChannelService适配器 |
|
||
| P0 | 邮件真实发送 | 集成Nodemailer/阿里云邮件 |
|
||
| P0 | 短信真实发送 | 集成阿里云短信SDK |
|
||
| P1 | 用户管理前端页面 | 用户列表/编辑/删除 |
|
||
| P1 | 通知中心前端页面 | 通知列表/设置 |
|
||
| P1 | 订单前端页面 | 订单列表/详情 |
|
||
| P2 | 支付真实SDK集成 | 支付宝/微信支付真实SDK |
|
||
| P2 | 内容审核 | 阿里云绿网内容安全 |
|
||
| P2 | @fischerx/client-sdk | 客户端SDK包 |
|
||
|
||
## License
|
||
|
||
Private - Fischer Company
|