TurboHR/系统功能分析报告.md

# TurboHR / 白话用工侠 系统功能详细分析报告

> 项目路径：`/Users/freedak/Documents/AIDashboard/UTMS/TurboHR/`
> 分析日期：2026-07-26
> 版本：v1.0

---

## 一、系统总体架构

### 1.1 技术栈

| 层级 | 技术选型 | 版本/说明 |
|------|---------|----------|
| 前端框架 | React 18 + TypeScript | Vite 构建，懒加载 + Suspense |
| 前端路由 | React Router v6 | 嵌套路由 + 认证守卫 |
| 状态管理 | Zustand + persist | localStorage 持久化 auth 状态 |
| 数据获取 | TanStack React Query | 缓存 + 自动刷新 + Mutation |
| UI 组件 | 自建组件库 | Card/Button/Input/Modal/Pagination/EmptyState/Skeleton/Signal/ConfirmDialog |
| 图标 | lucide-react | — |
| 图表 | recharts | 饼图等 |
| Markdown | react-markdown + remark-gfm + rehype-raw | AI 回复渲染 |
| 通知 | sonner | Toast 消息 |
| 后端框架 | Express 4 + TypeScript | tsx watch 热重载 |
| ORM | Prisma 5 | PostgreSQL |
| 数据库 | PostgreSQL | pgvector 扩展（RAG 向量检索） |
| 认证 | JWT（jsonwebtoken） | accessToken + refreshToken |
| 加密 | AES-256-CBC | 薪资/身份证/银行账号加密存储 |
| AI | OpenAI SDK → 阿里云 DashScope | qwen-plus / qwen-max 模型 |
| 文件上传 | multer | 内存/磁盘存储 |
| 数据导出 | ExcelJS + JSON | 支持 gzip 压缩 |
| 数据导入 | xlsx (SheetJS) | Excel 解析 + 身份证校验 |
| 安全 | helmet + cors + express-rate-limit | API 限流 |
| 日志 | morgan | HTTP 请求日志 |
| 压缩 | compression | SSE 流式响应排除压缩 |

### 1.2 项目目录结构

```
TurboHR/
├── backend/                    # 后端（Express + Prisma）
│   ├── prisma/
│   │   ├── schema.prisma       # 数据模型定义（879 行，30+ 表/模型）
│   │   ├── seed.ts             # 种子数据
│   │   ├── seed-wufang.ts      # 五方科技演示数据
│   │   └── migrations/         # 数据库迁移
│   ├── src/
│   │   ├── app.ts              # Express 应用配置 + 路由挂载
│   │   ├── index.ts            # 启动入口
│   │   ├── routes/             # 15 个路由模块
│   │   ├── services/           # 8 个业务服务
│   │   ├── middleware/         # 5 个中间件
│   │   ├── schemas/            # 4 个 Zod 校验 schema
│   │   └── lib/                # 5 个工具库
│   └── package.json
├── frontend/                   # 前端（React + Vite）
│   ├── src/
│   │   ├── App.tsx             # 路由定义 + 布局
│   │   ├── pages/              # 17 个页面组件
│   │   │   ├── auth/           # 认证页面（登录/注册/忘记密码）
│   │   │   └── portal/         # 员工端页面（5 个）
│   │   ├── components/         # 组件
│   │   │   ├── layout/         # 布局组件（TopNav/MobileTabBar/PageContainer）
│   │   │   └── ui/             # UI 基础组件（9 个）
│   │   ├── hooks/              # 自定义 Hooks（3 个）
│   │   ├── store/              # Zustand 状态管理
│   │   ├── lib/                # API 客户端
│   │   └── types/              # TypeScript 类型定义
│   └── package.json
├── docs/                       # 文档
├── 0-req.md                    # 需求文档
├── 1-prd.md                    # 产品需求文档
├── 2-task.md                   # 任务拆解
└── 白话用工侠_测试页面.html      # HTML 原型（6370 行）
```

### 1.3 系统角色

| 角色 | 端 | 说明 |
|------|-----|------|
| ADMIN | 管理端 | 系统管理员，全部权限 + 数据导出 |
| HR | 管理端 | HR 操作员，业务操作权限 |
| VIEWER | 管理端 | 只读查看者 |
| EMPLOYEE | 员工端 | 普通员工，查看工资条/合同/入职填报 |

### 1.4 套餐体系

| 套餐 | AI 问答 | 合同审查 | 案例匹配 | 最大员工数 |
|------|---------|---------|---------|-----------|
| FREE | 10 次/月 | 3 次/月 | 3 次/月 | 20 |
| PRO | 100 次/月 | 20 次/月 | 20 次/月 | 更多 |
| ENTERPRISE | 无限 | 无限 | 无限 | 无限 |

---

## 二、数据库模型详解（Prisma Schema）

### 2.1 枚举定义（15 个）

| 枚举 | 值 | 用途 |
|------|-----|------|
| `Plan` | FREE / PRO / ENTERPRISE | 组织套餐等级 |
| `Role` | ADMIN / HR / VIEWER | 管理端用户角色 |
| `EmployeeStatus` | ACTIVE / RESIGNED | 员工状态 |
| `FemaleWorkerType` | CADRE / WORKER | 女性岗位类型（影响退休年龄） |
| `ContractType` | FIXED / UNFIXED / UNSIGNED / LABOR / INTERNSHIP | 合同类型 |
| `SignMethod` | PAPER / ELECTRONIC | 签署方式 |
| `RiskType` | CONTRACT / SALARY / TERMINATION / MONTHLY / ONBOARDING | 风险类型 |
| `RiskLevel` | HIGH / MEDIUM / LOW | 风险等级 |
| `RiskStatus` | PENDING / RESOLVED / IGNORED | 风险处理状态 |
| `PayrollBatchType` | REGULAR / TERMINATION / BONUS / SEVERANCE | 工资批次类型 |
| `PayrollBatchStatus` | DRAFT / ARCHIVED | 批次状态 |
| `PayslipItemType` | INPUT / CALCULATED | 工资条项类型 |
| `PayslipStatus` | PENDING / PUBLISHED | 工资条发布状态 |
| `TerminationReason` | NEGOTIATED / FAULT / NONFAULT / LAYOFF / EXPIRED / RESIGNATION | 解聘原因 |
| `RiskAssessment` | SAFE / WARNING / DANGER | 风险评估结果 |
| `OnboardingStatus` | PENDING / APPROVED / REJECTED / CANCELLED | 入职链接状态 |
| `ContractConfirmStatus` | UNCONFIRMED / CONFIRMED / EXPIRED | 合同确认状态 |

### 2.2 数据模型总览（30+ 个模型）

```
核心组织
├── Organization          # 企业组织（套餐/城市/发薪频率/退休提醒）
├── User                  # 管理端用户（手机号/角色/禁用状态）
│
员工管理
├── Employee              # 员工（AES 加密薪资/身份证/银行账号）
├── LaborContract         # 劳动合同（类型/期限/试用期/续签/电子签）
├── OvertimeRecord        # 加班记录（工作日/休息日/节假日）
├── DisciplinaryRecord    # 违纪记录（类型/严重度/处理/签字确认）
├── AttendanceRecord      # 考勤记录（打卡/迟到/早退/缺勤/加班）
├── TrainingRecord        # 培训记录（制度培训/签收确认）
├── PerformanceRecord     # 绩效记录（考核周期/得分/等级/改进计划）
├── EmployeeAttachment    # 员工附件（身份证/银行卡/合同扫描件等）
├── SalaryChangeRecord    # 薪酬变更记录（版本化，effectiveMonth/endMonth）
├── EmployeeDepartmentRecord  # 部门变更记录（版本化）
│
薪税管理
├── PayrollBatch          # 工资批次（月/序号/类型/状态/汇总金额）
├── BatchEntry            # 批次明细（每员工薪酬项 + 自动计算项 + 风险提示）
├── Payslip               # 工资条（薪酬构成 + 累计预扣法 + 确认状态）
├── PayslipItem           # 工资条模版项（预置 + 自定义，公式计算）
├── OvertimeConfig        # 加班费配置（倍率/月计薪天数）
│
社保公积金
├── SocialInsuranceConfig     # 社保配置（版本化，按城市，比例/基数上下限）
├── HousingFundConfig         # 公积金配置（版本化，按城市）
├── EmployeeSocialInsRecord   # 员工社保记录（版本化，startMonth/endMonth）
├── EmployeeHousingFundRecord # 员工公积金记录（版本化）
├── SocialMonthlyProcess      # 月度社保/公积金办理记录（快照）
│
解聘管理
├── TerminationRecord     # 解聘/离职记录（状态机/补偿金明细/交接清单/审批）
│
风险管理
├── RiskItem              # 风险待办（自动检测 + 手动创建）
├── AuditLog              # 审计日志（操作/实体/详情/IP）
│
通知管理
├── NotificationSetting   # 通知设置（合同到期/未签/加班/工资条/月度提醒日）
├── NotificationLog       # 通知发送记录
│
员工端
├── OnboardingLink        # 入职填报链接（token/状态/表单数据/过期时间）
├── ContractConfirmLink   # 合同确认链接（token/验证码/签署证据链）
│
AI 能力
├── AIConversation        # AI 会话记录（标题/消息列表）
├── AIReviewRecord        # AI 审查/案例匹配记录
├── RagKnowledge          # RAG 知识库（pgvector 向量检索）
├── RetirementPolicy      # 退休政策版本管理（AI 解析/用户确认）
```

### 2.3 关键数据设计模式

| 模式 | 实现 | 涉及模型 |
|------|------|---------|
| **版本化快照** | `effectiveMonth` + `endMonth` + `isCurrent` | SocialInsuranceConfig, HousingFundConfig, SalaryChangeRecord, EmployeeSocialInsRecord, EmployeeHousingFundRecord, EmployeeDepartmentRecord |
| **敏感字段加密** | AES-256-CBC 对称加密 | Employee.monthlySalary, idCardNumber, bankAccount |
| **身份证哈希索引** | SHA-256 哈希用于去重查询 | Employee.idCardHash |
| **状态机** | status + currentStep 字段 | TerminationRecord (DRAFT→PENDING_APPROVAL→APPROVED→EXECUTING→COMPLETED) |
| **补偿金明细** | JSON 字段存储分项 + 调整记录 | TerminationRecord.compensationBreakdown |
| **合规检查覆盖** | JSON 字段记录人工覆盖原因 | TerminationRecord.checklistOverrides |
| **工作交接清单** | JSON 数组，每项含 done/remark | TerminationRecord.handoverItems |
| **月度办理快照** | JSON 存储办理时全量数据 | SocialMonthlyProcess.snapshot |
| **AI 消息历史** | JSON 数组 [{role, content}] | AIConversation.messages |
| **RAG 向量检索** | pgvector vector(1536) + ivfflat 索引 | RagKnowledge.embedding |

---

## 三、后端 API 详细分析

### 3.1 API 路由总览（15 个路由模块）

| 路由前缀 | 文件 | 行数 | 功能 |
|---------|------|------|------|
| `/api/v1/auth` | auth.routes.ts | 3445B | 注册/登录/刷新令牌 |
| `/api/v1/dashboard` | dashboard.routes.ts | 2865B | 仪表盘数据 + 待办操作 |
| `/api/v1/employees` | employee.routes.ts | 7334B | 员工 CRUD |
| `/api/v1/roster` | roster.routes.ts | 38878B | 花名册聚合 API（最大路由） |
| `/api/v1/termination` | termination.routes.ts | 10689B | 解聘/离职全流程 |
| `/api/v1/ai` | ai.routes.ts | 24384B | AI 问答/审查/案例/预测 |
| `/api/v1/portal` | portal.routes.ts | 16433B | 员工端全部接口 |
| `/api/v1/settings` | settings.routes.ts | 8574B | 企业/用户/退休政策 |
| `/api/v1/payroll` | payroll.routes.ts | 19655B | 加班费 + 工资条 |
| `/api/v1/payroll2` | payroll2.routes.ts | 26958B | 工资批次 + 薪酬模版 |
| `/api/v1/social` | social.routes.ts | 44930B | 社保公积金配置/记录/月度办理 |
| `/api/v1/notifications` | notification.routes.ts | 6436B | 通知设置/日志 |
| `/api/v1/attachments` | attachment.routes.ts | 1926B | 文件附件 |
| `/api/v1/export` | export.routes.ts | 10238B | 数据导出（JSON/Excel + 脱敏） |
| `/api/v1/import` | import.routes.ts | 34981B | Excel 批量导入 |

### 3.2 认证与安全

#### JWT 双 Token 机制
- **accessToken**：短期令牌，API 请求携带
- **refreshToken**：长期令牌，accessToken 过期后自动刷新
- **前端自动刷新**：axios 拦截器 401 → 用 refreshToken 换新 accessToken → 重放原请求

#### 加密体系
```
AES-256-CBC 对称加密
├── Employee.monthlySalary    → 月薪加密存储
├── Employee.idCardNumber     → 身份证号加密存储
├── Employee.bankAccount      → 银行账号加密存储
└── SHA-256 哈希
    └── Employee.idCardHash   → 身份证哈希（用于查重/匹配）
```

#### 中间件链
| 中间件 | 用途 |
|--------|------|
| `helmet` | 安全 HTTP 头 |
| `compression` | Gzip 压缩（排除 SSE） |
| `cors` | 跨域（credentials: true） |
| `express.json` | JSON 解析（10MB 限制） |
| `morgan` | HTTP 日志 |
| `apiLimiter` | API 限流 |
| `authMiddleware` | JWT 验证 |
| `requireAdmin` | ADMIN 角色校验 |
| `auditLog` | 操作审计日志 |

#### 员工端认证
- **密码登录**：手机号 + 密码（bcrypt 比对）
- **验证码登录**：手机号 + 验证码（60 秒频率限制，5 次错误锁定）
- **portalAuth 中间件**：验证 token role === 'EMPLOYEE'

### 3.3 核心业务服务（8 个 Service）

#### 3.3.1 risk.service.ts（568 行）— 风险自动检测引擎

| 函数 | 检测内容 |
|------|---------|
| `detectContractRisks()` | 合同风险：未签合同（>30天 HIGH / >365天 视为无固定期限）/ 即将到期（≤30天 MEDIUM）/ 已到期（HIGH）/ 试用期超限（MEDIUM） |
| `detectOnboardingRisks()` | 入职风险：入职未签合同（>30天 HIGH） |
| `detectTerminationRisks()` | 解聘风险：孕期/哺乳期（HIGH）/ 医疗期（MEDIUM）/ 工伤（HIGH） |
| `detectMonthlyTasks()` | 月度任务：发薪日/社保日/公积金日/个税日 + 工资条生成提醒 |
| `runRiskDetection()` | 执行全量检测 + 去重写入 RiskItem |
| `getDashboardData()` | 仪表盘聚合：员工数/风险数/待办/人力成本/合同/解聘/违纪/考勤等 |

**风险检测触发时机**：每次请求 `/dashboard` 时自动执行 `runRiskDetection()`

#### 3.3.2 termination.service.ts（811 行）— 解聘全流程

**6 步向导**：
1. 选择员工
2. 解聘方式（7 种原因）
3. 合规检查（按原因动态生成 checklist + 系统自动判断）
4. 费用结算（补偿金计算 + 分项明细 + 调整记录）
5. 工作交接（6 项默认清单）
6. 确认提交

**状态机**：
```
DRAFT → PENDING_APPROVAL → APPROVED → EXECUTING → COMPLETED
                ↓
            REJECTED
DRAFT/CANCELLED ← 撤回
```

**合规检查清单**（按解聘原因动态生成）：
| 原因 | 检查项 |
|------|--------|
| 协商解除 | 支付补偿金 / 签署协议 / 结清工资 |
| 过错辞退 | 规章制度依据 / 违纪证据 / 通知工会 / 书面通知 |
| 非过错解除 | 医疗期满（系统自动判断）/ 培训或调岗（系统查记录）/ 支付补偿金 / 提前30天通知 |
| 经济性裁员 | 提前30天说明 / 听取意见 / 报告劳动部门 / 支付补偿金 |
| 合同到期 | 支付补偿金 / 提前通知 |

**系统自动判断能力**：
- 医疗期状态 → 自动标记 `autoChecked: false`
- 培训记录 → 自动查 `trainingRecords` 判断是否经过培训
- 风险评估 → 孕期/工伤/医疗期 → DANGER 级别

**事务处理**：解聘创建在事务中执行 → 创建记录 + 关闭社保/公积金 + 更新员工状态 + 解决风险待办

#### 3.3.3 ai.service.ts（237 行）— AI 核心服务

| 函数 | 模型 | 用途 |
|------|------|------|
| `chat()` | qwen-plus | 普通对话（含 RAG 检索 + 企业上下文） |
| `chatStream()` | qwen-plus | SSE 流式对话 |
| `reviewContract()` | qwen-max | 合同审查（结构化解析风险项 + 合规评分） |
| `matchCase()` | qwen-max | 案例匹配（相似案例 + 败诉风险 + 建议） |
| `predictRisks()` | qwen-plus | 风险预测（未来30天 + 优先级建议） |
| `predictRisksStream()` | qwen-plus | SSE 流式风险预测（Markdown 表格输出） |

**AI 上下文注入**：
- `buildOrgContext()` 函数构建企业数据概览
- 包含：员工列表（姓名/部门/入职日期/工龄/合同状态/特殊状态）+ 当前风险项
- 支持按员工/部门/riskType 范围筛选

**RAG 知识库**：
- 15 条预置法律条文（劳动合同法/劳动法/社会保险法）
- pgvector 向量检索（cosine 距离，ivfflat 索引）
- `searchKnowledge()` 检索 top-K 相关条文注入 system prompt

**用量控制**：
- `checkUsageLimit()` 按套餐限制月度 AI 调用次数
- `recordUsage()` 写入 AuditLog 记录

#### 3.3.4 rag.service.ts（98 行）— RAG 知识库

- 启动时自动初始化（`seedKnowledgeBase()`）
- 自动建表 + 创建向量索引
- 首次启动注入 15 条法律条文种子数据
- 使用 `text-embedding-v2` 模型生成 1536 维向量

#### 3.3.5 retirement.service.ts（260 行）— 退休计算

- 从身份证号提取出生日期 + 性别
- 渐进式延迟退休算法（2025-01-01 起改革）
  - 男性：60→63 岁，每 4 个月延迟 1 个月
  - 女性干部：55→58 岁，每 4 个月延迟 1 个月
  - 女性工人：50→55 岁，每 2 个月延迟 1 个月
- AI 解析最新退休政策 + 用户确认 + 版本管理

#### 3.3.6 contract.service.ts（23861B）— 合同服务

- 合同状态计算（`getContractStatus`）
- 合同 CRUD + 续签

#### 3.3.7 payroll.service.ts（15131B）— 薪酬计算

- 薪酬模版管理
- 批次明细计算（`calcBatchEntry`）
- 社保/公积金/个税自动计算
- 工资条生成（`generatePayslipFromBatches`）
- 风险提示（`getPayrollRiskWarnings`）

#### 3.3.8 auth.service.ts（3012B）— 认证服务

- 注册（创建 Organization + User）
- 登录（bcrypt 验证 + JWT 签发）
- Token 刷新

### 3.4 员工端 API（portal.routes.ts）

| 端点 | 方法 | 功能 |
|------|------|------|
| `/portal/login` | POST | 密码登录 |
| `/portal/send-code` | POST | 发送验证码（60s 频率限制） |
| `/portal/verify-code` | POST | 验证码登录（5 次错误锁定） |
| `/portal/payslip` | GET | 查看当月工资条 |
| `/portal/payslip/history` | GET | 最近 6 个月工资条 |
| `/portal/payslip/:id/confirm` | POST | 工资条确认已阅（记录 IP） |
| `/portal/contract` | GET | 查看我的合同 |
| `/portal/onboarding/:token` | GET | 获取入职填报信息 |
| `/portal/onboarding` | POST | 入职填报提交 |
| `/portal/onboarding/:token/upload` | POST | 入职文件上传（JPG/PNG/PDF/BMP，10MB 限制） |
| `/portal/onboarding/:id/revoke` | POST | 撤回入职链接（HR 端） |
| `/portal/contract-confirm/:token` | GET | 获取合同确认信息 |
| `/portal/contract-confirm/send-code` | POST | 合同签署验证码 |
| `/portal/contract-confirm` | POST | 合同签署确认（验证码 + IP + UserAgent 证据链） |
| `/portal/contract-confirm/:id/resend` | POST | 重发合同确认链接（7 天有效期） |

### 3.5 数据导入导出

#### 导入（import.routes.ts，614 行）
- Excel 上传（multer memoryStorage，10MB 限制）
- 身份证号校验（18 位校验位算法 + 15 位自动升级 18 位）
- 社保基数范围校验（北京/上海/广州/深圳/杭州 上下限）
- 批量创建员工 + 合同 + 社保记录

#### 导出（export.routes.ts，246 行）
- 格式：JSON / Excel
- 模块选择：employees/contracts/terminations/payrollBatches/payslips/socialRecords/housingRecords/riskItems
- 敏感字段脱敏：身份证 `138****1234` / 银行账号 `****1234`
- 非 ADMIN 角色强制脱敏
- 支持 gzip 压缩

---

## 四、前端页面详细分析

### 4.1 路由结构

```
管理端（ProtectedRoute + AdminLayout）
├── /                 → Dashboard    （总览）
├── /roster           → Roster       （员工花名册）
├── /money            → Money        （薪税管理）
├── /social           → SocialInsurance（社保公积金）
├── /termination      → Termination  （解聘补偿）
├── /ai-assistant     → AIAssistant  （AI 顾问）
└── /settings         → Settings     （系统设置）

员工端（PortalLayout，无认证守卫）
├── /portal/login         → PortalLogin      （员工登录）
├── /portal/payslip       → Payslip          （工资条）
├── /portal/contract      → MyContract       （我的合同）
├── /portal/onboarding    → Onboarding       （入职填报）
└── /portal/contract-confirm → ContractConfirm（合同签署确认）

认证页（PublicRoute）
├── /login            → Login
├── /register         → Register
└── /forgot-password  → ForgotPassword
```

### 4.2 布局组件

#### TopNav.tsx（桌面端顶部导航）
- 6 个导航 Tab：总览 / 员工管理 / 薪税 / 社保公积金 / 解聘补偿 / AI 顾问
- React Query 拉取 `/dashboard` 数据，60 秒自动刷新
- 风险计数 Badge（总览 Tab + 通知铃铛）
- 用户下拉菜单（设置 / 退出）

#### MobileTabBar.tsx（移动端底部 Tab）
- 6 个 Tab：总览 / 员工 / 薪税 / 社保 / 解聘 / AI
- `md:hidden` 仅移动端显示
- 固定底部 `fixed bottom-0`

#### PageContainer.tsx
- 内容容器包装

#### OnboardingGuide.tsx
- 新手引导组件

### 4.3 各页面功能详解

---

#### 4.3.1 Dashboard.tsx（654 行）— 总览仪表盘

**4 个 Tab**：概览 / 风险提醒 / 月度任务 / 薪酬

**概览 Tab**：
- 4 统计卡片：在管员工数 / 高风险数 / 待办数 / 本月人力成本
- 当月人力成本卡片（应发/社保企业/公积金企业/实发）
- 年度人力成本卡片
- 合同到期预警列表
- 月度活动统计（合同签订/解聘/违纪/考勤/补偿金）
- 工资条明细

**风险提醒 Tab**：
- 风险待办列表（按类型图标 + 级别排序）
- 单条 resolve / ignore
- 批量 resolve / ignore
- 分页处理

**月度任务 Tab**：
- 月度任务列表（发薪/社保/公积金/个税/工资条）

**数据获取**：
- `useQuery(['dashboard'])` → `/dashboard`（含风险检测 + 全量聚合数据）
- `useQuery(['expiring-contracts'])` → `/roster/contracts/expiring`

---

#### 4.3.2 Roster.tsx（3840 行）— 员工花名册（最大页面）

**列表视图**：
- 搜索（防抖 `useDebouncedValue`）+ 状态筛选（在职/预入职/离职）+ 合同状态筛选
- 表格列：姓名/部门/状态/合同/工龄/月薪/操作
- 分页
- 未保存变更检测（`useUnsavedChanges`）

**详情面板（Tab 分组）**：
| Tab | 内容 |
|-----|------|
| 人事信息 | 基本信息 / 合同信息（类型/期限/试用期/签署方式/续签） |
| 薪酬 | 薪酬记录 / 社保公积金记录（版本化时间轴） |
| 考勤绩效 | 考勤记录 / 培训记录 / 绩效记录 |
| 风险合规 | 违纪记录（类型/严重度/处理/签字） / 离职解聘 |
| 变更历史 | 薪酬变更 / 部门变更 |

**关键功能**：
- 员工 CRUD + 身份证自动提取出生日期/性别
- 合同管理（签订/续签/电子签链接）
- 违纪记录管理
- 考勤记录管理
- 培训记录管理
- 绩效记录管理
- 附件上传
- 入职链接生成（token + 过期时间）
- 合同确认链接生成（token + 验证码签署）
- QR 码分享

---

#### 4.3.3 Money.tsx（1671 行）— 薪税管理

**4 个 Tab**：

| Tab | 组件 | 功能 |
|-----|------|------|
| 发薪批次 | BatchManager | 批次创建（常规/离职结算/奖金/补偿金）/ 复制上月 / 审批流 / 工资条明细 / 归档锁定 |
| 薪酬模版 | TemplateManager | 模版项管理（预置项 + 自定义项）/ 公式计算 / 排序 / 编辑 |
| 加班费计算 | OvertimeCalculator | 按月计算（工作日 1.5x / 休息日 2x / 节假日 3x）/ 关联批次 |
| 工资条管理 | PayslipManager | 从批次生成工资条 / 发布到员工端 / 确认状态追踪 |

**批次流程**：
```
创建批次（DRAFT）→ 添加员工 → 编辑薪酬项 → 自动计算社保/公积金/个税
→ 风险提示 → 审批 → 归档（ARCHIVED，锁定）→ 生成工资条 → 发布到员工端
```

---

#### 4.3.4 SocialInsurance.tsx（983 行）— 社保公积金

**3 个 Tab**：

| Tab | 功能 |
|-----|------|
| 月度办理 | 按月查看社保/公积金办理状态 + 增减员 + 在保人员 + 缴费明细 + 办理记录快照 |
| 社保配置 | 按城市配置社保比例 + 基数上下限 + 版本管理 + 基数调整 |
| 公积金配置 | 按城市配置公积金比例 + 基数上下限 + 版本管理 + 基数调整 |

**版本管理**：
- 新版本创建时旧版本自动 `isCurrent: false`
- 支持查看历史版本
- 基数调整（批量更新员工社保/公积金基数）

---

#### 4.3.5 Termination.tsx（1778 行）— 解聘补偿

**3 个视图**：

| 视图 | 功能 |
|------|------|
| 列表 | 解聘/离职记录列表 + 状态筛选 + 操作 |
| 向导 | 6 步解聘向导（选择员工 → 解聘方式 → 合规检查 → 费用结算 → 工作交接 → 确认提交） |
| 详情 | 解聘记录详情 + PDF 导出 |

**7 种解聘原因**：
- 协商解除（第 36 条）
- 过错辞退（第 39 条）
- 非过错解除（第 40 条）
- 经济性裁员（第 41 条）
- 合同到期不续签（第 44 条/第 46 条）
- 违法解除（赔偿金 ×2，第 87 条）
- 员工主动离职（第 37 条）

**合规检查**：
- 系统自动判断（医疗期/培训记录）
- 人工勾选 + 覆盖原因
- 风险评估（SAFE/WARNING/DANGER）

**费用结算**：
- 经济补偿金计算（N / N+1 / 2N）
- 补偿金分项明细（severance / noticePay / doublePay / other）
- 调整记录（field / from / to / reason）

**PDF 导出**：使用 jsPDF 生成解聘通知书

---

#### 4.3.6 AIAssistant.tsx（1149 行）— AI 顾问

**5 个 Tab**：

| Tab | 功能 | AI 模型 |
|-----|------|---------|
| 智能问答 | SSE 流式对话 + Markdown 渲染 + 快捷问题 + 历史会话 | qwen-plus |
| 风险预测 | 按员工/部门/风险类型筛选 + SSE 流式 + Markdown 表格输出 | qwen-plus |
| 合同审查 | 粘贴合同文本 → AI 逐条审查 + 风险分级 + 合规评分 | qwen-max |
| 案例匹配 | 输入争议情形 → AI 匹配相似案例 + 败诉风险 + 建议 | qwen-max |
| 知识库 | RAG 法律条文浏览 | — |

**通用功能**：
- `useAIHistory` Hook：历史记录 CRUD（`/ai/conversations`）
- `HistoryBar` 组件：历史记录加载/删除
- 流式渲染：SSE 逐 token 输出
- 快捷问题按钮

---

#### 4.3.7 Settings.tsx（1190 行）— 系统设置

**6 个 Section**：

| Section | 功能 |
|---------|------|
| 企业信息 | 企业名称/城市/联系人/发薪频率/退休提醒开关 |
| 用户管理 | 管理端用户 CRUD + 角色分配（ADMIN/HR/VIEWER） |
| 套餐 | 当前套餐 + 升级 |
| 通知设置 | 合同到期/未签/加班/工资条提醒 + 月度提醒日 + 微信 Webhook + 邮件 |
| 数据导入 | Excel 上传 + 身份证校验 + 社保基数校验 |
| 数据导出 | 模块选择 + 格式选择 + 脱敏选项 |

---

### 4.4 员工端页面（5 个）

| 页面 | 行数 | 功能 |
|------|------|------|
| PortalLogin.tsx | 5276B | 密码登录 + 验证码登录 |
| Payslip.tsx | 7714B | 当月工资条 + 6 个月历史 + 确认已阅 |
| MyContract.tsx | 5769B | 查看合同详情 + 电子签确认 |
| Onboarding.tsx | 8461B | 入职信息填报 + 文件上传（身份证/银行卡/学历等） |
| ContractConfirm.tsx | 6570B | 合同电子签署确认（验证码 + 证据链） |

### 4.5 自定义 Hooks

| Hook | 用途 |
|------|------|
| `useDebouncedValue` | 搜索防抖（300ms） |
| `useUnsavedChanges` | 未保存变更检测 + 离开提示 |
| `useConfirm` | 二次确认对话框 |

### 4.6 UI 组件库（9 个）

| 组件 | 说明 |
|------|------|
| Button | 按钮组件（variant: primary/secondary/danger/ghost） |
| Card | 卡片容器 |
| Input | 输入框 + Label + Select |
| Modal | 模态对话框 |
| Pagination | 分页组件 |
| EmptyState | 空状态占位 |
| Skeleton | 骨架屏加载 |
| Signal | 信号指示器 |
| ConfirmDialog | 确认对话框 |

---

## 五、已实现功能清单

### 5.1 核心业务功能

| 模块 | 功能点 | 实现状态 |
|------|--------|---------|
| **认证** | 手机号注册/登录/JWT 双 Token/自动刷新 | ✅ |
| **认证** | 员工端密码登录 + 验证码登录 | ✅ |
| **仪表盘** | 风险自动检测 + 待办列表 + 批量操作 | ✅ |
| **仪表盘** | 人力成本统计（月度/年度） | ✅ |
| **仪表盘** | 合同到期预警 | ✅ |
| **仪表盘** | 月度活动统计 | ✅ |
| **花名册** | 员工 CRUD + AES 加密敏感字段 | ✅ |
| **花名册** | 身份证号校验 + 自动提取出生日期/性别 | ✅ |
| **花名册** | 合同管理（签订/续签/电子签链接） | ✅ |
| **花名册** | 违纪记录 + 考勤记录 + 培训记录 + 绩效记录 | ✅ |
| **花名册** | 薪酬变更记录（版本化） | ✅ |
| **花名册** | 部门变更记录（版本化） | ✅ |
| **花名册** | 附件管理 | ✅ |
| **花名册** | 入职链接生成 + 员工自助填报 | ✅ |
| **花名册** | 合同确认链接 + 验证码签署 + 证据链 | ✅ |
| **薪税** | 工资批次管理（4 种类型） | ✅ |
| **薪税** | 批次复制上月 / 空白 / 指定批次 | ✅ |
| **薪税** | 薪酬模版（预置 + 自定义 + 公式计算） | ✅ |
| **薪税** | 加班费计算（3 种倍率） | ✅ |
| **薪税** | 社保/公积金/个税自动计算 | ✅ |
| **薪税** | 工资条生成 + 发布到员工端 | ✅ |
| **薪税** | 工资条确认追踪（IP + 时间戳） | ✅ |
| **薪税** | 累计预扣法个税计算 | ✅ |
| **薪税** | 批次归档锁定 | ✅ |
| **薪税** | 薪酬风险提示 | ✅ |
| **社保** | 社保配置（按城市 + 版本化） | ✅ |
| **社保** | 公积金配置（按城市 + 版本化） | ✅ |
| **社保** | 员工社保/公积金记录（版本化时间轴） | ✅ |
| **社保** | 月度办理（增减员 + 在保人员 + 缴费明细 + 快照） | ✅ |
| **社保** | 基数调整（批量更新） | ✅ |
| **解聘** | 6 步解聘向导 | ✅ |
| **解聘** | 7 种解聘原因 + 动态合规检查清单 | ✅ |
| **解聘** | 系统自动判断（医疗期/培训记录） | ✅ |
| **解聘** | 风险评估（孕期/工伤/医疗期） | ✅ |
| **解聘** | 补偿金计算（N/N+1/2N）+ 分项明细 | ✅ |
| **解聘** | 工作交接清单 | ✅ |
| **解聘** | 审批流（草稿→待审批→审批→执行→完成） | ✅ |
| **解聘** | 撤回（未到日期可撤回） | ✅ |
| **解聘** | PDF 解聘通知书导出 | ✅ |
| **解聘** | 员工主动离职流程 | ✅ |
| **AI** | 智能问答（SSE 流式 + RAG 检索 + 企业上下文） | ✅ |
| **AI** | 合同审查（结构化风险项 + 合规评分） | ✅ |
| **AI** | 案例匹配（相似案例 + 败诉风险） | ✅ |
| **AI** | 风险预测（SSE 流式 + Markdown 表格） | ✅ |
| **AI** | 历史会话管理 | ✅ |
| **AI** | 用量控制（按套餐限制） | ✅ |
| **AI** | 案例转待办 | ✅ |
| **设置** | 企业信息管理 | ✅ |
| **设置** | 用户管理（CRUD + 角色） | ✅ |
| **设置** | 通知设置（多渠道 + 月度提醒日） | ✅ |
| **设置** | 退休政策管理（AI 解析 + 用户确认 + 版本管理） | ✅ |
| **设置** | 退休提醒（渐进式延迟退休计算） | ✅ |
| **数据** | Excel 批量导入（身份证校验 + 社保基数校验） | ✅ |
| **数据** | 数据导出（JSON/Excel + 脱敏 + gzip） | ✅ |
| **员工端** | 工资条查看 + 确认 | ✅ |
| **员工端** | 合同查看 + 电子签确认 | ✅ |
| **员工端** | 入职自助填报 + 文件上传 | ✅ |

### 5.2 技术能力清单

| 能力 | 实现 |
|------|------|
| 多租户隔离 | orgId 贯穿所有查询 |
| JWT 双 Token | accessToken + refreshToken + 自动刷新 |
| AES-256 加密 | 薪资/身份证/银行账号 |
| SHA-256 哈希 | 身份证号查重 |
| API 限流 | express-rate-limit |
| 安全 HTTP 头 | helmet |
| SSE 流式 | AI 对话 + 风险预测 |
| RAG 向量检索 | pgvector + ivfflat + cosine 距离 |
| 审计日志 | AuditLog（操作/实体/详情/IP） |
| 操作确认 | useConfirm Hook + ConfirmDialog |
| 搜索防抖 | useDebouncedValue |
| 未保存检测 | useUnsavedChanges |
| 懒加载 | React.lazy + Suspense |
| 骨架屏 | Skeleton 组件 |
| 响应式 | md:hidden 移动端 Tab |
| 批量操作 | 待办批量 resolve/ignore |
| 版本化数据 | 社保/公积金/薪酬/部门变更 |
| 状态机 | 解聘流程 7 状态 |
| 事务处理 | 解聘创建事务 |
| 数据脱敏 | 导出时身份证/银行账号脱敏 |
| 身份证校验 | 18 位校验位算法 + 15 位升级 |
| 渐进式延迟退休 | 2025 改革算法 |

---

## 六、与 HTML 原型的功能差距分析

| 原型页面 | React 实现 | 差距说明 |
|---------|-----------|---------|
| 风险驾驶舱 | Dashboard.tsx | 原型有 SVG 环形评分 + AI 建议卡片流 + 业务流程入口，React 版偏重统计卡片 |
| 白小侠 AI 对话 | AIAssistant (chat) | ✅ 基本对应，原型有转专家/约律师功能未实现 |
| 判赔预测器 | AIAssistant (predict) | 原型有 12 场景选择 + 三档方案卡片，React 版为 AI 自由文本输出 |
| 文件 AI 审查 | AIAssistant (review) | 原型有左右分栏 + 原文高亮 + 一键采纳，React 版为文本输入 + AI 文本输出 |
| 全员风险地图 | Roster.tsx | ✅ 花名册已实现，但无 7 维仲裁风险评分 + 风险标签 |
| 个人风险档案 | Roster.tsx (详情) | ✅ 员工详情已实现，但无 7 维评分趋势图 + 修复路径 |
| 年度 AI 价值报告 | — | ❌ 未实现 |
| 合规中心 | — | ❌ 未独立实现（功能分散在各页面） |
| 电子签中心 | — | ❌ 未独立实现（合同确认链接已实现，但无独立管理页） |
| 申请草稿/已发申请 | — | ❌ 未实现 |
| 入职管理 | Roster.tsx | ✅ 通过入职链接实现 |
| 合同管理 | Roster.tsx (合同 Tab) | ✅ 集成在花名册 |
| 考勤确认 | Roster.tsx (考勤 Tab) | ✅ 考勤记录已实现，但无员工端确认流程 |
| 工资条发布 | Money.tsx (payslip) | ✅ 已实现 |
| 规章制度民主程序 | — | ❌ 未实现 |
| 企业文本库 | — | ❌ 未实现 |
| 用工文本模板库 | — | ❌ 未实现 |
| 用工体检诊断 | — | ❌ 未实现 |
| 背景调查 | — | ❌ 未实现 |
| 视频中心 | — | ❌ 未实现 |
| 五险一金计算器 | SocialInsurance.tsx | ✅ 社保配置已实现，但无独立计算器工具 |
| 医疗期计算器 | — | ❌ 未实现 |
| 通知管理 | Settings.tsx (通知设置) | ✅ 通知设置已实现，但无独立通知管理页 |
| 用户管理 | Settings.tsx (用户管理) | ✅ 已实现 |
| 系统日志 | — | ❌ 未实现（AuditLog 有数据但无前端页面） |

---

## 七、系统架构亮点与不足

### 7.1 亮点

1. **AI 深度集成**：RAG 知识库 + 企业上下文注入 + SSE 流式输出，AI 不是简单聊天而是结合企业实际数据
2. **风险自动检测引擎**：每次访问 Dashboard 自动检测合同/入职/解聘/月度任务风险，去重写入待办
3. **版本化数据设计**：社保/公积金/薪酬/部门变更全部版本化，支持时间轴追溯
4. **解联合规引擎**：7 种解聘原因 × 动态合规清单 × 系统自动判断 × 风险评估 × 状态机审批流
5. **敏感数据加密**：AES-256-CBC 加密薪资/身份证/银行账号 + SHA-256 哈希索引
6. **员工端自助**：入职填报 + 合同电子签 + 工资条查看，token 链接 + 验证码 + 证据链
7. **渐进式延迟退休**：精确实现 2025 年改革算法（男 60→63 / 女干部 55→58 / 女工人 50→55）

### 7.2 不足

1. **原型差距大**：26 个页面模块仅实现约 60%，合规中心/电子签中心/民主程序/文本库/背景调查/视频中心等未实现
2. **AI 审查交互弱**：原型有左右分栏 + 原文高亮 + 一键采纳，React 版仅为文本输入输出
3. **判赔预测简化**：原型有 12 场景选择 + 三档方案卡片 + 金额区间，React 版为 AI 自由文本
4. **无风险评分体系**：原型有 78 分健康度 + 5 维评分 + 7 维员工风险评分，React 版仅有高/中/低三级
5. **AuditLog 无前端**：有审计日志数据模型但无系统日志查看页面
6. **通知无独立管理**：通知设置已实现但通知列表/已读管理未独立建页
7. **Roster.tsx 过大**：3840 行单文件，应拆分为子组件
8. **验证码内存存储**：`codeStore = new Map()` 生产环境应使用 Redis