# FF AI Workspace Frontend - Next.js 前端应用

## 技术栈

- **框架**: Next.js 14 (App Router)
- **语言**: TypeScript
- **样式**: Tailwind CSS
- **状态管理**: Zustand
- **数据获取**: Axios + TanStack React Query
- **表单**: React Hook Form + Zod
- **日期处理**: date-fns
- **图表**: Recharts

## 项目结构

```
frontend/
├── src/
│   ├── app/                    # Next.js 页面路由
│   │   ├── login/             # 登录/注册页面
│   │   ├── dashboard/         # 仪表盘
│   │   ├── expenses/          # 报销管理
│   │   ├── purchases/         # 采购管理
│   │   ├── contracts/         # 合同管理
│   │   ├── performance/       # 绩效管理（规划）
│   │   ├── users/             # 用户管理
│   │   ├── departments/       # 部门管理
│   │   ├── approvals/         # 审批中心
│   │   ├── notifications/     # 通知中心
│   │   ├── audit/             # 审计日志
│   │   ├── layout.tsx         # 根布局
│   │   ├── page.tsx           # 首页（自动跳转）
│   │   └── globals.css        # 全局样式
│   ├── components/            # React 组件
│   │   └── ui/                # UI 组件库
│   │       ├── button.tsx     # 按钮组件
│   │       ├── input.tsx      # 输入框组件
│   │       └── card.tsx       # 卡片组件
│   └── lib/                   # 工具库
│       ├── api.ts             # API 客户端
│       ├── auth.ts            # 认证状态管理
│       └── utils.ts           # 工具函数
├── package.json
├── tailwind.config.ts
├── next.config.mjs
└── tsconfig.json
```

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

#### 开发环境

创建 `.env.local` 或 `.env.development` 文件：

```bash
# API 地址（开发环境）
NEXT_PUBLIC_API_URL=http://localhost:3001/api/v1

# 应用配置
NEXT_PUBLIC_APP_NAME="FF AI Workspace"
NEXT_PUBLIC_APP_VERSION=1.0.0

# 功能开关
NEXT_PUBLIC_ENABLE_DEBUG=true
```

#### 生产环境

创建 `.env.production` 文件：

```bash
# API 地址（生产环境 - 使用相对路径，由 Nginx 反向代理）
NEXT_PUBLIC_API_URL=/api/v1

# 应用配置
NEXT_PUBLIC_APP_NAME="FF AI Workspace"
NEXT_PUBLIC_APP_VERSION=1.0.0

# 功能开关
NEXT_PUBLIC_ENABLE_DEBUG=false
```

**重要提示**：
- ✅ 所有浏览器访问的变量必须以 `NEXT_PUBLIC_` 开头
- ✅ 修改环境变量后需要重启开发服务器
- ⚠️ 不要提交 `.env.local`、`.env.development`、`.env.production` 到 Git

详细说明查看 [ENV_SETUP.md](./ENV_SETUP.md)

### 3. 启动开发服务器

```bash
npm run dev
```

应用将在 http://localhost:3001 启动

## 主要功能模块

### 1. 认证模块
- **登录**: 用户名/密码登录
- **注册**: 新用户注册
- **Token 管理**: JWT Token 自动刷新
- **权限控制**: 基于角色的访问控制

### 2. Dashboard（仪表盘）
- **统计卡片**: 展示关键指标
- **快速操作**: 常用功能快捷入口
- **功能导航**: 系统功能分类导航

### 3. 报销管理
- **报销单列表**: 查看我的报销单
- **创建报销单**: 创建新的报销申请
- **费用明细**: 多项费用明细管理
- **审批流程**: 提交审批、查看进度

### 4. 采购管理
- **采购单列表**: 查看我的采购单
- **创建采购单**: 创建新的采购申请
- **采购审批**: 采购审批流程
- **验收管理**: 采购验收记录

### 5. 合同管理
- **合同列表**: 查看我的合同
- **合同详情**: 查看合同详细信息
- **合同审批**: 合同审批流程
- **印章管理**: 合同用印申请

### 6. KPI 管理
- **KPI 记录**: 查看我的 KPI 记录
- **KPI 模板**: KPI 模板管理
- **自评打分**: KPI 自评功能
- **绩效统计**: 绩效数据统计

### 7. 用户管理
- **员工列表**: 查看所有员工
- **员工详情**: 查看员工详细信息
- **部门管理**: 部门组织架构
- **岗位管理**: 岗位信息管理

### 8. 审批中心
- **待审批列表**: 查看待我审批的事项
- **审批操作**: 通过/拒绝审批
- **审批记录**: 查看审批历史

### 9. 通知中心
- **通知列表**: 查看所有通知
- **未读标记**: 标记已读/未读
- **通知类型**: 审批通知、系统通知、消息通知

### 10. 审计日志
- **日志查询**: 按条件查询审计日志
- **操作记录**: 查看所有操作记录
- **日志筛选**: 按操作类型、时间筛选

## API 集成

所有 API 调用统一通过 `src/lib/api.ts` 管理：

```typescript
// 使用示例
import { expenseApi } from '@/lib/api';

// 获取报销单列表
const expenses = await expenseApi.getMyExpenses();

// 创建报销单
const newExpense = await expenseApi.createExpense({
  title: '差旅费报销',
  totalAmount: 1000,
  items: [...]
});
```

## 状态管理

使用 Zustand 进行全局状态管理：

```typescript
// 使用认证状态
import { useAuth } from '@/lib/auth';

function MyComponent() {
  const { user, isAuthenticated, login, logout } = useAuth();
  
  // ...
}
```

## 样式规范

使用 Tailwind CSS 进行样式开发：

```tsx
// 响应式设计
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {/* 内容 */}
</div>

// 使用预设的 UI 组件
import { Button } from '@/components/ui/button';

<Button variant="primary" size="lg">
  提交
</Button>
```

## 开发规范

### 1. 组件规范
- 使用函数组件和 Hooks
- 组件文件使用 PascalCase 命名
- 一个文件一个主要组件

### 2. 类型定义
- 优先使用 TypeScript 类型定义
- 接口定义使用 `interface`
- 类型别名使用 `type`

### 3. 代码风格
- 使用 ESLint 和 Prettier
- 遵循 Next.js 最佳实践
- 保持代码简洁易读

### 4. 性能优化
- 使用 React.memo 避免不必要的重渲染
- 图片使用 Next.js Image 组件
- 大列表使用虚拟滚动

## 构建部署

### 开发环境
```bash
npm run dev
```

### 生产构建
```bash
npm run build
npm run start
```

### Docker 部署
```bash
docker build -t ffoa-frontend .
docker run -p 3001:3001 ffoa-frontend
```

## 故障排查

### 常见问题

1. **API 请求失败**
   - 检查后端服务是否启动（`http://localhost:3001`）
   - 确认 `NEXT_PUBLIC_API_URL` 配置正确
   - 验证配置：在浏览器控制台运行 `console.log(process.env.NEXT_PUBLIC_API_URL)`

2. **认证失败**
   - 清除 localStorage 中的 token
   - 重新登录

3. **样式不生效**
   - 确认 Tailwind CSS 配置正确
   - 重启开发服务器

## 📚 相关文档

- **[功能清单](./docs/FEATURES.md)** - 所有前端页面和功能状态
- **[前端架构](../docs/standards/02-architecture/frontend-architecture.md)** - 架构设计和最佳实践
- **[导航架构](../docs/standards/02-architecture/app-navigation-architecture.md)** - 二级导航规范
- **[设计系统](../docs/standards/03-design-system/design-system.md)** - UI/UX 设计规范
- **[后端规范入口](../docs/standards/05-backend/README.md)** - API 请求响应规范
- **[国际化指南](../docs/standards/04-frontend/i18n-quick-start.md)** - i18n 使用说明

## 技术支持

如有问题，请联系开发团队或查看项目文档。

## License

MIT