# 审批中心（Approval Center）

> **负责人**: FFOA 开发团队  
> **状态**: 🟢 Active  
> **最后更新**: 2026-01-02

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2026-01-02 |
| [架构设计](./03-architecture.md) | ✅ | 2026-01-02 |
| [UI 交互规范](./05-ui-interaction-spec.md) | ✅ | 2026-01-02 |
| [数据模型](./06-data-model.md) | 🚧 | 2026-01-21 |
| [API 文档](./07-api.md) | 🚧 | 2026-01-21 |
| [测试场景](./09-test-scenarios.md) | 🚧 | 2026-01-20 |
| [E2E 测试规范](./10-e2e-test-spec.md) | ✅ | 2026-01-20 |
| [开发路线图](./10-roadmap.md) | ✅ | 2026-01-02 |
| [变更日志](./99-changelog.md) | ✅ | 2026-01-02 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 🔥 重要特性

### 审批流程时间线增强

**目标**: 显示完整的审批流程（包括未执行节点），符合业内规范（钉钉/飞书）

| 文档 | 内容 | 状态 |
|------|------|------|
| [特性概述](./features/timeline-enhancement/00-overview.md) | 背景、目标、实施状态 | ✅ |
| [业务分析](./features/timeline-enhancement/01-business-analysis.md) | 业内规范对比、问题分析 | ✅ |
| [逻辑规范](./features/timeline-enhancement/02-logic-specification.md) | 状态机制、数据流 | ✅ |
| [UI设计方案](./features/timeline-enhancement/03-ui-design.md) | 视觉设计、交互设计 | ✅ |
| [技术实施方案](./features/timeline-enhancement/04-implementation.md) | 实施步骤、代码示例 | ✅ |

**当前状态**: 🚧 设计方案已完成，待实施

---

## 📌 概述

审批中心是 FFOA 平台的**前端用户界面模块**，为用户提供统一的审批操作入口。采用**飞书/钉钉风格**的列表-详情分栏布局，整合了审批提交、待办处理、流程追踪等功能，为用户提供高效、流畅的审批体验。

> **⚠️ 重要区分**：
> - **审批引擎（Approval Engine）**: 后端核心业务逻辑、工作流编排、Temporal 集成
> - **审批中心（Approval Center）**: 前端用户界面、交互设计、用户体验

### 核心功能

1. **提交请求** - 选择表单模板，快速发起审批申请
2. **待我审批** - 查看并处理需要我审批的任务（通过/拒绝/转交）
3. **我提交的** - 追踪我发起的审批流程（含撤回功能）
4. **我审批的** - 查看我已经处理过的审批历史
5. **抄送我的** - 查看抄送给我的审批信息
6. **管理员处理** - 管理员专用的强制干预和审批管理功能

### 设计特点

- 🎨 **飞书风格设计** - 简洁、现代、高效的 UI
- 📱 **响应式布局** - 列表-详情分栏，适配不同屏幕
- 🚀 **实时更新** - 操作后即时刷新列表和数量
- 🔍 **快速筛选** - 支持表单类型筛选和关键字搜索
- ⚡ **流畅交互** - 加载状态、操作反馈、错误提示

### 业务价值

- 统一审批入口，提升用户效率
- 直观的流程追踪，透明化审批进度
- 便捷的操作体验，降低学习成本
- 符合国内用户习惯（参考飞书/钉钉）

---

## 🏗️ 技术信息

### 代码位置

- **主页面**: `frontend/src/app/(modules)/approval-center/page.tsx`
- **表单提交**: `frontend/src/app/(modules)/approval-center/submit/[formKey]/page.tsx`
- **旧路由转发**: `frontend/src/app/(engines)/approvals/page.tsx`
- **API 服务**: `frontend/src/services/api/approval.ts`
- **组件**:
  - `frontend/src/components/ApprovalTimeline.tsx` - 审批历史时间线
  - `frontend/src/components/FormRenderer.tsx` - 表单数据渲染
  - `frontend/src/components/UserSelector.tsx` - 用户选择器

### 路由结构

```
/approval-center              → 审批中心主页（列表-详情）
  ?tab=submit                 → 提交请求
  ?tab=pending                → 待我审批
  ?tab=initiated              → 我提交的
  ?tab=processed              → 我审批的
  ?tab=cc                     → 抄送我的
  ?tab=admin                  → 管理员处理（仅管理员）
  ?tab=pending&instanceId=xxx → 深度链接到特定审批项

/approval-center/submit/{formKey}  → 表单提交页面

/approvals                    → 旧路由（自动转发到 /approval-center）
```

### 技术栈

- **框架**: Next.js 16 (App Router) + TypeScript
- **UI 库**: Tailwind CSS + shadcn/ui
- **状态管理**: React Hooks (useState, useEffect, useCallback)
- **路由**: Next.js useRouter + useSearchParams
- **权限**: 集成 `useAuthGuard` 和 `useAuth`
- **国际化**: 支持中英文切换
- **通知**: sonner (toast 消息)

---

## 待实现功能

- 修复 forms/instances/[id]/page.tsx 的重复提交问题
- 管理员按表单导出（含子表单展开为多列、表头含 label+key）
- 提取防重复提交为通用 hook（useDebounceAction）
- 管理员批量审批、管理员转交、强制终止
- 审批中心性能优化（分页加载、虚拟滚动）
- 审批历史导出
- 审批统计报表

---

## 🔗 相关模块

### 依赖的模块

| 模块 | 依赖关系 | 说明 |
|------|---------|------|
| [审批引擎](../approval-engine/) | 强依赖 | 所有后端 API 调用 |
| [表单引擎](../form-engine/) | 强依赖 | 表单数据渲染（FormRenderer） |
| [表单管理](../form-management/) | 强依赖 | 获取表单定义和模板列表 |
| [组织架构](../organization/) | 强依赖 | 用户选择器、审批人信息 |
| [通知引擎](../notification-engine/) | 弱依赖 | 前端 toast 通知 |

### 被依赖的模块

| 模块 | 依赖关系 | 说明 |
|------|---------|------|
| [工作台](../../workspace/) | 弱依赖 | 工作台首页展示审批统计和快捷入口 |

---

## 🎯 功能完成度

| 功能模块 | 状态 | 说明 |
|---------|------|------|
| 提交请求（表单列表） | ✅ | 支持筛选、搜索、分类 |
| 待我审批（列表+详情） | ✅ | 支持通过、拒绝、转交、加签 |
| 我提交的（列表+详情） | ✅ | 支持撤回功能 |
| 我审批的（列表+详情） | ✅ | 历史记录查看 |
| 抄送我的（列表+详情） | ✅ | 只读查看 |
| 管理员处理 | ✅ | 强制终止、代审批、重新分配 |
| 审批历史时间线 | ✅ | 完整的审批流程展示 |
| 表单数据渲染 | ✅ | 使用通用 FormRenderer |
| 筛选和搜索 | ✅ | 按表单类型、关键字筛选 |
| 实时数量更新 | ✅ | Tab 标签显示数量 badge |
| 深度链接 | ✅ | 支持 instanceId 参数直接打开 |
| 旧路由兼容 | ✅ | /approvals 自动转发 |
| 响应式设计 | ⚠️ | 桌面端完善，移动端待优化 |
| 批量审批 | 📋 | 规划中 |
| 审批流程图可视化 | 📋 | 规划中 |

**整体完成度**: ~90%

---

## 🎨 设计规范

### 布局

- **标签栏高度**: `h-14` (56px)
- **列表宽度**: `400px`（固定）
- **详情面板**: `flex-1`（自适应）
- **间距**: `gap-3`, `gap-4`, `px-6`, `py-4`

### 颜色（飞书风格）

- **主色**: `#3370ff` (飞书蓝)
- **成功**: `#00b42a` (绿色)
- **警告**: `#ff7d00` (橙色)
- **紫色**: `#722ed1` (紫色)
- **红色**: `#f53f3f` (管理员操作)
- **边框**: `#e5e6eb`
- **背景**: `#f7f8fa`

### 圆角和阴影

- **按钮/卡片**: `rounded-lg` (8px)
- **无阴影**: 扁平化设计
- **Hover 阴影**: `hover:shadow-md`

### 图标

- 使用 `lucide-react` 图标库
- 统一大小: `w-4 h-4` 或 `w-5 h-5`

---

## 🚀 快速开始

### 1. 访问审批中心

```
浏览器访问: http://localhost:3000/approval-center
```

### 2. 发起审批

1. 点击"提交请求"标签
2. 选择表单模板（如"加班申请"）
3. 填写表单数据
4. 提交审批

### 3. 处理审批

1. 点击"待我审批"标签
2. 选择待处理的审批项
3. 查看表单数据和审批历史
4. 填写审批意见，点击"通过"或"拒绝"

### 4. 追踪审批

1. 点击"我提交的"标签
2. 查看审批进度和当前节点
3. 如需撤回，点击"撤回"按钮

---

## 📊 数据流

```
用户操作
  ↓
前端 API 调用 (approval.ts)
  ↓
审批引擎后端 (ApprovalService)
  ↓
Temporal 工作流
  ↓
数据库更新 (approval_instances, approval_tasks)
  ↓
前端刷新列表和详情
  ↓
Toast 通知用户
```

---

## 🧪 测试

### 手动测试

参考 [E2E 测试规范](./10-e2e-test-spec.md)

### 测试要点

1. **提交流程**: 选择表单 → 填写 → 提交 → 验证列表
2. **审批流程**: 待我审批 → 通过/拒绝 → 验证流转
3. **撤回流程**: 我提交的 → 撤回 → 验证状态
4. **转交流程**: 待我审批 → 转交 → 验证新审批人
5. **管理员操作**: 管理员处理 → 强制终止/代审批 → 验证结果

---

## 📚 参考资料

### 内部文档

- [PRD 文档](./01-prd.md) - 完整的产品需求
- [架构设计](./03-architecture.md) - 前端架构和数据流
- [UI 交互规范](./05-ui-interaction-spec.md) - 详细的交互设计
- [审批引擎 API](../approval-engine/07-api.md) - 后端 API 文档

### 外部资源

- [Next.js App Router](https://nextjs.org/docs/app)
- [Tailwind CSS](https://tailwindcss.com/docs)
- [shadcn/ui](https://ui.shadcn.com/)
- [Lucide Icons](https://lucide.dev/)

### 设计参考

- [飞书审批中心](https://www.feishu.cn)
- [钉钉审批](https://www.dingtalk.com)

---

## 📝 变更记录

查看 [变更日志](./99-changelog.md)

---

## 👥 贡献者

| 角色 | 说明 |
|------|------|
| 前端开发 | 审批中心 UI、交互逻辑、状态管理 |
| UI/UX 设计 | 飞书风格设计、交互优化 |
| 测试工程师 | E2E 测试、用户体验测试 |

---

**最后更新**: 2026-01-02  
**维护者**: FFOA 开发团队  
**文档版本**: v1.0（全新模块文档）