# 企业内部工具系统 - 实现计划

## 项目概述

开发一个企业内部工具系统平台，以出差审批为首个功能模块，后续可持续扩展新功能。系统主要支持移动 H5，嵌入飞书应用中使用。

### 核心目标
- **H5 移动端优先**：专注于移动端体验，PC 端后期扩展
- 从工具台层面设计可扩展的页面结构
- **审批模块作为独立通用工具**：支持多样化审批场景，业务可复用
- 良好的飞书集成能力（多公司、多应用架构）

---

## 技术方案

### 技术架构

#### 前端技术栈（H5 移动端）
| 技术 | 用途 | 说明 |
|------|------|------|
| React 18 | 前端框架 | 配合 TypeScript |
| Ant Design Mobile | UI 组件库 | 移动端组件库 |
| Vant | 补充组件 | 必要时补充使用 |
| Vite | 构建工具 | 快速开发体验 |
| React Router | 路由管理 | 支持多页面应用 |
| Zustand / Jotai | 状态管理 | 轻量级方案 |
| React Query | 数据请求 | 服务端状态管理 |
| PostCSS + pxtorem | 移动端适配 | rem 转换 |
| VConsole | 调试工具 | 移动端调试 |

#### 后端技术栈
| 技术 | 用途 | 说明 |
|------|------|------|
| Webman | PHP 框架 | 高性能常驻内存框架 |
| MySQL | 数据库 | 关系型数据库 |
| Redis | 缓存 | 会话、缓存存储 |
| JWT | 认证 | Token 认证机制 |

### 多租户架构设计

**核心概念**：
- 系统**不按公司隔离用户**，用户全局唯一
- 用户关联所属公司，用于选择对应飞书应用配置
- 审批流程跨公司，只识别人员
- 飞书仅提供：系统入口 + 人员识别鉴权

**数据模型**：

```sql
-- 公司表（飞书应用配置）
CREATE TABLE company (
    id BIGINT PRIMARY KEY,
    name VARCHAR(100),
    feishu_app_id VARCHAR(100),
    feishu_app_secret VARCHAR(255),
    feishu_tenant_key VARCHAR(100),
    status TINYINT DEFAULT 1
);

-- 用户表（全局用户）
CREATE TABLE user (
    id BIGINT PRIMARY KEY,
    company_id BIGINT,           -- 所属公司
    feishu_user_id VARCHAR(100), -- 飞书用户ID
    feishu_union_id VARCHAR(100),-- 飞书UnionID（跨应用唯一）
    name VARCHAR(50),
    email VARCHAR(100),
    phone VARCHAR(20),
    avatar VARCHAR(255),
    status TINYINT DEFAULT 1
);

-- 用户与飞书应用关联（支持用户切换不同公司应用）
CREATE TABLE user_feishu_binding (
    id BIGINT PRIMARY KEY,
    user_id BIGINT,
    company_id BIGINT,
    feishu_open_id VARCHAR(100),
    created_at TIMESTAMP
);
```

### 项目目录结构（前后端分离）

```
x-server-mobile/                 # 项目根目录
├── frontend/                    # 前端项目（React + Vite）
│   ├── src/
│   │   ├── components/          # 通用组件
│   │   │   ├── approval/        # 审批组件（可复用）
│   │   │   ├── layout/          # 布局组件
│   │   │   └── common/          # 通用组件
│   │   ├── pages/               # 页面
│   │   │   ├── dashboard/       # 工具台首页
│   │   │   ├── business-trip/   # 出差审批
│   │   │   └── profile/         # 个人中心
│   │   ├── hooks/               # 自定义 Hooks
│   │   ├── services/            # API 服务
│   │   ├── stores/              # 状态管理
│   │   ├── utils/               # 工具函数
│   │   ├── types/               # TypeScript 类型
│   │   └── config/              # 配置文件
│   ├── public/
│   ├── package.json
│   └── vite.config.ts
│
└── backend/                     # 后端项目（Webman）
    ├── app/
    │   ├── controller/
    │   ├── model/
    │   ├── service/
    │   ├── middleware/
    │   └── util/
    ├── config/
    ├── routes/
    ├── support/
    ├── composer.json
    └── start.php
```

### 后端项目结构（Webman）
```
backend/
├── app/
│   ├── controller/
│   │   ├── ApprovalController.php    # 审批控制器
│   │   ├── BusinessTripController.php # 出差审批控制器
│   │   ├── UserController.php         # 用户控制器
│   │   ├── CompanyController.php      # 公司管理控制器
│   │   └── BaseController.php         # 基础控制器
│   ├── model/
│   │   ├── Approval.php               # 审批模型
│   │   ├── ApprovalNode.php           # 审批节点模型
│   │   ├── BusinessTrip.php           # 出差模型
│   │   ├── User.php                   # 用户模型
│   │   ├── Company.php                # 公司模型
│   │   └── UserFeishuBinding.php      # 用户飞书绑定模型
│   ├── service/
│   │   ├── ApprovalService.php        # 审批服务
│   │   ├── FeishuService.php          # 飞书服务（多应用）
│   │   ├── FeishuAppManager.php       # 飞书应用配置管理
│   │   ├── UserService.php            # 用户服务
│   │   └── CompanyService.php         # 公司服务
│   ├── middleware/
│   │   ├── AuthMiddleware.php         # 认证中间件
│   │   ├── CompanyResolveMiddleware.php # 公司识别中间件
│   │   └── CorsMiddleware.php         # 跨域中间件
│   └── util/
│       ├── JwtUtil.php                # JWT工具
│       └── Response.php               # 响应封装
├── config/
│   ├── route.php                      # 路由配置
│   ├── database.php                   # 数据库配置
│   ├── redis.php                      # Redis配置
│   └── feishu.php                     # 飞书应用配置模板
├── routes/
│   └── api.php                        # API路由定义
└── support/
    └── Bootstrap.php                  # 启动文件
```

### API 接口设计

#### 通用 API 规范
```
基础URL: /api/v1
响应格式:
{
  "code": 0,          // 0表示成功
  "message": "success",
  "data": {}
}
```

#### 审批相关接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /approval/list | 获取审批列表 |
| GET | /approval/detail/:id | 获取审批详情 |
| POST | /approval/submit | 提交审批申请 |
| POST | /approval/approve/:id | 审批通过 |
| POST | /approval/reject/:id | 审批拒绝 |
| POST | /approval/cancel/:id | 撤销申请 |
| GET | /approval/flow/:type | 获取审批流程配置 |

#### 出差审批接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /business-trip/list | 获取出差列表 |
| GET | /business-trip/detail/:id | 获取出差详情 |
| POST | /business-trip/apply | 提交出差申请 |
| PUT | /business-trip/:id | 更新出差申请（草稿状态） |

#### 用户认证接口（多飞书应用）
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | 用户登录 |
| POST | /auth/feishu-login | 飞书免登（自动识别公司应用） |
| GET | /user/info | 获取用户信息 |
| GET | /user/menu | 获取用户菜单权限 |
| GET | /user/companies | 获取用户可切换的公司列表 |
| POST | /user/switch-company | 切换当前公司 |

#### 飞书应用管理接口（管理端）
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /admin/company/list | 获取公司列表 |
| POST | /admin/company/add | 添加公司飞书应用配置 |
| PUT | /admin/company/:id | 更新公司飞书配置 |
| DELETE | /admin/company/:id | 删除公司配置 |

---

## 功能模块设计

### 1. 工具台架构（Dashboard - H5 移动端）

**设计理念**：工具台作为统一入口，支持模块化扩展，专注于移动端体验

```
工具台首页（H5）
├── 顶部导航栏
│   ├── Logo + 系统名称
│   ├── 搜索框（全局搜索）
│   ├── 通知图标
│   └── 用户头像
├── 主内容区
│   ├── 待办事项卡片（横向滚动）
│   ├── 快捷入口（九宫格/宫格）
│   ├── 数据统计卡片
│   └── 最新动态列表
└── 底部导航栏（TabBar）
    ├── 首页
    ├── 应用（宫格展开所有工具）
    ├── 消息
    └── 我的
```

**移动端适配要点**：
- 使用 TabBar 替代侧边栏（符合移动端习惯）
- 750px 设计稿 → rem 自适应转换
- 触摸手势支持（下拉刷新、上拉加载）
- 安全区域适配（刘海屏、底部横条）

**关键文件**：
- `src/pages/dashboard/index.tsx` - 工具台主页
- `src/components/layout/MobileLayout.tsx` - 移动端主布局
- `src/components/layout/TabBar.tsx` - 底部导航栏
- `src/components/layout/Header.tsx` - 顶部栏

### 2. 通用审批模块设计（独立工具）

**设计理念**：审批模块作为独立的通用工具，与具体业务解耦，支持多样化的审批场景

**核心特性**：
- ✅ 业务无关：不绑定特定业务表单和流程
- ✅ 流程灵活：支持单级、多级、会签、或签、抄送等任意组合
- ✅ 动态配置：审批流程可动态配置和调整
- ✅ 易于集成：任何业务都可快速接入审批模块

**核心数据模型**：

```typescript
// 审批流程节点类型
enum ApprovalNodeType {
  APPROVER = 'approver',      // 审批人（单人）
  AND_APPROVE = 'and_approve', // 会签（需所有人通过）
  OR_APPROVE = 'or_approve',   // 或签（任一人通过）
  NOTIFY = 'notify'            // 抄送（通知用）
}

// 审批单状态
enum ApprovalStatus {
  DRAFT = 'draft',           // 草稿
  PENDING = 'pending',       // 审批中
  APPROVED = 'approved',     // 已通过
  REJECTED = 'rejected',     // 已拒绝
  CANCELLED = 'cancelled'    // 已撤销
}

// 审批流程配置（业务无关）
interface ApprovalFlow {
  id: string;
  businessType: string;      // 业务类型标识（如：business-trip, purchase）
  name: string;
  nodes: ApprovalNode[];     // 流程节点
}

// 审批节点
interface ApprovalNode {
  id: string;
  type: ApprovalNodeType;
  approvers: User[];         // 审批人列表
  order: number;             // 节点顺序
  conditions?: any;          // 条件判断（可选，用于条件分支）
}

// 审批单（业务通用）
interface ApprovalOrder {
  id: string;
  businessType: string;      // 业务类型
  businessId: string;        // 业务单据ID
  title: string;             // 审批标题
  applicant: User;           // 申请人
  status: ApprovalStatus;
  currentNodes: string[];    // 当前待审批节点ID
  flowId: string;            // 使用的流程ID
  formData: any;             // 业务表单数据（JSON存储）
  attachments: Attachment[]; // 附件
  timeline: ApprovalTimeline[]; // 审批轨迹
}
```

**审批模块架构**：

```
src/modules/approval/                    # 审批模块（独立）
├── components/                          # UI组件
│   ├── ApprovalFlow.tsx                 # 流程可视化
│   ├── ApprovalDetail.tsx               # 审批详情
│   ├── ApprovalList.tsx                 # 审批列表
│   └── ApprovalAction.tsx               # 审批操作
├── hooks/                               # 自定义Hooks
│   ├── useApprovalSubmit.ts             # 提交审批
│   ├── useApprovalAction.ts             # 审批操作
│   └── useApprovalList.ts               # 获取列表
├── services/                            # API服务
│   └── approval.ts
├── types/                               # 类型定义
│   └── index.ts
└── utils/                               # 工具函数
    ├── flowParser.ts                    # 流程解析
    └── statusCalculator.ts              # 状态计算
```

**业务接入示例（出差审批）**：

```typescript
// 业务模块只需要调用审批模块的Hook
import { useApprovalSubmit } from '@/modules/approval/hooks'

function BusinessTripApply() {
  const { submitApproval } = useApprovalSubmit('business-trip')

  const handleSubmit = async (formData: BusinessTripFormData) => {
    // 1. 先保存业务数据
    const businessTripId = await saveBusinessTrip(formData)

    // 2. 提交审批（传入业务类型和业务ID）
    await submitApproval({
      businessId: businessTripId,
      title: `出差申请 - ${formData.destination}`,
      formData: formData,
      flowType: 'default' // 使用的流程模板
    })
  }
}
```

### 3. 出差审批模块

**页面结构**：
```
出差审批
├── 申请列表页
│   ├── 我发起的
│   ├── 待我审批
│   ├── 我已审批
│   └── 抄送我的
├── 申请表单页
│   ├── 基本信息（出差事由、时间、地点）
│   ├── 行程明细
│   ├── 费用预算
│   └── 附件上传
└── 审批详情页
    ├── 表单内容展示
    ├── 流程进度可视化
    ├── 审批历史
    └── 操作按钮
```

**关键文件**：
- `src/pages/business-trip/list.tsx` - 列表页
- `src/pages/business-trip/apply.tsx` - 申请表单
- `src/pages/business-trip/detail.tsx` - 详情页
- `src/pages/business-trip/types.ts` - 出差相关类型

### 4. 飞书集成（多应用架构）

**集成要点**：

#### 后端 - 多飞书应用管理
```php
// 飞书应用管理器
class FeishuAppManager
{
    // 根据飞书租户Key获取公司配置
    public function getCompanyByTenantKey(string $tenantKey): Company
    {
        // 从数据库查询对应的飞书应用配置
    }

    // 获取指定公司的飞书 access_token
    public function getAccessToken(int $companyId): string
    {
        // 缓存 access_token，过期自动刷新
    }

    // 根据用户ID获取其所属公司的飞书配置
    public function getUserFeishuConfig(int $userId): array
    {
        // 返回用户所属公司的飞书 AppID、AppSecret 等
    }
}
```

#### 前端 - 飞书 SDK 封装
```typescript
// src/utils/feishu.ts
export const FeishuSDK = {
  // 获取免登授权码
  getAuthCode: () => { /* ... */ },

  // 判断是否在飞书环境
  isFeishuEnv: () => { /* ... */ },

  // 获取当前租户信息（用于后端识别公司）
  getTenantContext: () => {
    // 从飞书容器获取 tenant_key 或其他标识
  }
}
```

#### 飞书免登流程（多应用）
```
1. 用户在飞书中打开应用
2. 前端获取 auth_code 和 tenant_key
3. 调用后端 /auth/feishu-login
4. 后端根据 tenant_key 查询对应公司配置
5. 使用该公司的 AppSecret 换取用户信息
6. 生成 JWT Token（包含 user_id 和 company_id）
7. 返回登录信息
```

---

## 实施步骤

### 阶段一：项目初始化
**前端：**
1. 初始化 Vite + React + TypeScript 项目
2. 安装 Ant Design 及相关依赖
3. 配置路由、状态管理、请求库（axios + React Query）
4. 配置 Tailwind CSS

**后端：**
1. 安装 Webman 框架
2. 配置 MySQL、Redis 连接
3. 配置 JWT 认证
4. 设置 CORS 中间件
5. **创建多租户数据表（company, user, user_feishu_binding）**

### 阶段二：工具台框架（H5）
**前端：**
1. 实现 MobileLayout 移动端布局组件
2. 实现 TabBar 底部导航栏
3. 实现 Header 组件
4. 创建工具台首页 Dashboard（H5 适配）
5. 配置 rem 移动端适配

**后端：**
1. 实现 /auth/login 登录接口
2. **实现 /auth/feishu-login 飞书免登（多应用识别）**
3. 实现 /user/info 用户信息接口
4. 实现 /user/menu 菜单权限接口
5. **实现 FeishuAppManager 服务（多应用配置管理）**
6. **实现 CompanyResolveMiddleware 中间件**

### 阶段三：独立审批模块（通用工具）
**前端：**
1. 创建 `src/modules/approval/` 独立模块目录
2. 定义审批相关 TypeScript 类型（业务无关）
3. 实现 ApprovalFlow 流程可视化组件
4. 实现 ApprovalDetail 详情页（通用）
5. 实现 ApprovalList 列表页（通用）
6. 实现 ApprovalAction 操作组件
7. **封装审批 Hooks（useApprovalSubmit, useApprovalAction）**
8. **提供业务接入示例**

**后端：**
1. 设计审批流程数据表（approval_flow, approval_node）
2. 设计审批单数据表（approval_order, approval_record）
3. 实现审批服务层逻辑（单级、多级、会签、或签）
4. **确保业务无关性，通过 businessType + businessId 关联业务**
5. 实现审批相关 API 接口

### 阶段四：出差审批业务（作为审批模块的使用示例）
**前端：**
1. 创建出差申请表单页面
2. **调用审批模块的 useApprovalSubmit Hook**
3. 创建出差审批列表（复用审批模块组件）
4. 创建出差审批详情（复用审批模块组件 + 业务表单展示）

**后端：**
1. 设计出差数据表（business_trip, business_trip_itinerary）
2. 实现出差业务逻辑（与审批解耦）
3. 实现出差相关 API 接口
4. **配置出差审批的默认流程模板**

### 阶段五：飞书集成与 H5 适配（多应用架构）
**前端：**
1. 集成飞书 JSAPI SDK
2. 实现飞书免登逻辑（获取 tenant_key）
3. **H5 移动端样式优化**
4. **配置 pxtorem（750px 设计稿适配）**
5. **安全区域适配（刘海屏、底部横条）**
6. 集成 VConsole 调试工具

**后端：**
1. **实现 FeishuService（支持多应用配置）**
2. **实现飞书应用配置管理接口（增删改查）**
3. **实现用户切换公司功能**
4. **实现飞书消息推送（根据用户所属公司推送）**

---

## 待确认问题

1. **飞书应用配置**：是否有飞书应用的 App ID、App Secret？
2. **权限设计**：是否需要 RBAC 权限系统？
3. **数据 Mock**：开发阶段是否需要 Mock 数据？
4. **部署环境**：开发/测试/生产环境配置？

---

## 关键文件清单

### 前端核心文件（H5）
| 文件路径 | 说明 |
|---------|------|
| `src/App.tsx` | 应用入口 |
| `src/main.tsx` | React 挂载点 |
| `src/router/index.tsx` | 路由配置 |
| `src/components/layout/MobileLayout.tsx` | 移动端主布局 |
| `src/components/layout/TabBar.tsx` | 底部导航栏 |
| `src/components/layout/Header.tsx` | 顶部栏 |
| `src/pages/dashboard/index.tsx` | 工具台首页 |
| `src/modules/approval/` | **审批模块（独立）** |
| `src/pages/business-trip/` | 出差审批业务 |
| `src/services/api.ts` | API 基础配置 |
| `src/utils/feishu.ts` | 飞书 SDK 封装 |
| `src/config/rem.ts` | rem 转换配置 |
| `package.json` | 项目依赖 |
| `vite.config.ts` | Vite 配置 |
| `tsconfig.json` | TypeScript 配置 |
| `postcss.config.js` | PostCSS 配置（pxtorem） |

### 后端核心文件
| 文件路径 | 说明 |
|---------|------|
| `app/controller/BaseController.php` | 基础控制器 |
| `app/controller/ApprovalController.php` | 审批控制器 |
| `app/controller/BusinessTripController.php` | 出差审批控制器 |
| `app/controller/UserController.php` | 用户控制器 |
| `app/model/Approval.php` | 审批模型 |
| `app/model/ApprovalNode.php` | 审批节点模型 |
| `app/service/ApprovalService.php` | 审批服务 |
| `app/service/FeishuService.php` | 飞书服务 |
| `app/middleware/AuthMiddleware.php` | 认证中间件 |
| `config/route.php` | 路由配置 |
| `config/database.php` | 数据库配置 |
| `routes/api.php` | API 路由定义 |

---

## 验证计划

### 前端验证（H5）
1. **运行项目**：`npm run dev` 确保项目启动
2. **路由测试**：访问各个页面确保路由正常
3. **审批模块测试**：验证审批组件的通用性和可复用性
4. **H5 适配测试**：
   - 测试不同屏幕尺寸（375px - 768px）
   - 测试刘海屏和底部横条适配
   - 测试触摸手势交互
5. **飞书环境测试**：
   - 在飞书中测试免登
   - 在飞书中测试 H5 适配
   - 测试多公司应用切换
6. **真机测试**：在真实移动设备上测试

### 后端验证
1. **启动 Webman**：`php start.php start` 确保服务启动
2. **API 测试**：使用 Postman/Apifox 测试各接口
3. **数据库测试**：验证数据表创建和 CRUD 操作
4. **认证测试**：验证 JWT 认证流程
5. **多租户测试**：
   - 测试多公司飞书应用配置
   - 测试跨公司审批流程
6. **飞书集成测试**：验证飞书免登和消息推送