# 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