TurboHR/1-prd.md

劳动用工合规助手 — 产品需求文档 (PRD)

文档编号: 1-prd.md
版本: v1.0
日期: 2026-07-23
状态: 草案
依据: 0-req.md v3.0 需求规格说明书

---

1. 产品概述

1.1 产品定位

面向中小企业的极简用工合规 SaaS 工具，聚焦劳动仲裁三大高发领域（合同签订、工资加班费、解聘），辅以 AI 合规顾问，帮助企业事前预防、事中管控、事后追溯用工风险。

1.2 产品愿景

「让每个中小企业都有一个用得起的劳动法顾问」

1.3 核心价值主张

价值	说明
极简易用	三看三不用原则，不需要培训，打开就会用
自动合规	风险自动检测 + 人话提示，不用懂法也能合规
AI 顾问	通义千问驱动，随时问、自动查、提前预警
安全可靠	SaaS 云端存储，数据隔离，多设备访问

1.4 目标用户

用户角色	企业规模	使用频率	核心诉求
老板兼管 HR	10-30人	每周1-2次	快速了解风险，解聘时算钱
行政兼 HR	30-80人	每天5分钟	合同到期提醒，每月算加班费
初级 HR	80-200人	日常使用	合同管理，工资计算，解聘流程

---

2. 用户故事

2.1 认证与注册

编号	用户故事	验收标准
US-AUTH-01	作为企业管理者，我想注册账号，这样我就能开始使用系统管理用工合规	输入企业名称+手机号+密码 → 创建组织+管理员账号 → 自动登录跳转首页
US-AUTH-02	作为用户，我想用手机号和密码登录，这样我能安全访问我的数据	输入手机号+密码 → 校验通过 → 返回 JWT Token → 跳转首页
US-AUTH-03	作为管理员，我想添加 HR 用户，这样我的同事也能操作系统	设置页 → 用户管理 → 输入姓名+手机号+角色 → 创建成功
US-AUTH-04	作为用户，我想找回密码，这样我忘记密码时还能登录	忘记密码 → 输入手机号 → 验证码重置 → 重新登录

2.2 首页风险总览

编号	用户故事	验收标准
US-HOME-01	作为用户，我想打开首页就知道有没有风险，这样我不用到处翻找	顶部一句话：「今天有 X 件事需要处理」
US-HOME-02	作为用户，我想看到具体待办事项，这样我知道该先处理什么	待办列表：信号灯+一句话描述+「去处理」按钮
US-HOME-03	作为用户，我想看到风险分布，这样我知道哪类问题最多	进度条展示合同/工资/解聘三类风险数量
US-HOME-04	作为用户，当没有风险时我想看到安心提示，这样我知道一切正常	显示绿色「✅ 暂无风险，继续保持！」
US-HOME-05	作为用户，我想看到 AI 风险预测，这样我能提前防范	首页下方展示 AI 预测的未来30天风险卡片

2.3 合同管理

编号	用户故事	验收标准
US-CON-01	作为 HR，我想添加员工和合同信息，这样系统帮我管理合规	添加按钮 → 分步表单（基本信息→合同信息）→ 保存成功
US-CON-02	作为 HR，我想看到所有员工的合同状态，这样我一眼就知道谁有问题	列表5列：姓名/部门/入职日期/合同状态(信号灯)/操作
US-CON-03	作为 HR，当合同即将到期时我想收到提醒，这样我不会忘记续签	到期前30天列表出现「续签」按钮 + 首页待办提醒
US-CON-04	作为 HR，我想一键续签合同，这样我不用填一堆表单	点击「续签」→ 弹窗确认期限+签订方式 → 确认 → 状态变绿
US-CON-05	作为 HR，我想选择纸质或电子合同签订方式，这样符合实际操作	添加/续签时可选「纸质合同」或「电子合同」
US-CON-06	作为 HR，当员工入职很久没签合同时我想被提醒，这样避免双倍工资赔偿	入职超1个月未签 → 🔴 红色状态 + 首页待办
US-CON-07	作为 HR，我想搜索员工，这样快速找到某人的合同	搜索框输入姓名 → 实时筛选列表
US-CON-08	作为 HR，我想批量续签即将到期的合同，这样不用一个个点	全选 → 批量续签 → 弹窗确认 → 批量更新

2.4 钱的计算

编号	用户故事	验收标准
US-MONEY-01	作为 HR，我想计算加班费，这样我知道该付多少	输入月工资+加班小时数 → 实时显示各类加班费明细+合计
US-MONEY-02	作为 HR，当加班超过法定上限时我想被提醒，这样避免违法	月加班超36小时 → 结果区显示黄色警告
US-MONEY-03	作为 HR，我想计算未签合同的双倍工资，这样我知道风险金额	输入月工资+入职日期+签订状态 → 显示起止日期+赔偿金额
US-MONEY-04	作为 HR，我想计算经济补偿金，这样解聘时知道该赔多少	输入入职/离职日期+月工资+原因 → 显示工作年限+补偿金+赔偿金(×2)
US-MONEY-05	作为 HR，我想关联员工自动填入工资，这样不用手动输入	选择员工 → 月工资自动填入

2.5 解聘助手

编号	用户故事	验收标准
US-TERM-01	作为 HR，我想一步步完成解聘流程，这样不会漏掉步骤	5步向导：选原因→选员工→合规检查→算钱→确认
US-TERM-02	作为 HR，当解聘原因不同时我想看到对应的检查项，这样有针对性	Step 3 根据Step 1选择动态展示检查项
US-TERM-03	作为 HR，当员工属于禁止解聘情形时我想被警告，这样避免违法解聘	选员工后自动检查孕期/工伤/医疗期 → 红色警告弹窗
US-TERM-04	作为 HR，我想看到解聘历史记录，这样可以追溯	解聘助手页面底部展示历史记录列表
US-TERM-05	作为 HR，即使有未通过检查项我也想保存记录，这样尊重我的决策	Step 5 显示红色警告但不阻止保存

2.6 AI 合规顾问

编号	用户故事	验收标准
US-AI-01	作为用户，我想用大白话问劳动法问题，这样不用自己查法条	聊天界面输入问题 → AI 流式回答 + 法律依据 + 关联本企业数据
US-AI-02	作为用户，我想看到 AI 预测的未来风险，这样提前防范	首页 AI 风险预测卡片，展示未来30天预计风险
US-AI-03	作为 HR，我想让 AI 审查合同条款，这样知道有没有违法	粘贴/上传合同文本 → 逐条审查 + 红/黄/绿标注 + 合规评分
US-AI-04	作为 HR，我想匹配相似仲裁案例，这样评估败诉风险	输入争议情况 → 展示相似案例 + 败诉概率 + 赔偿预估
US-AI-05	作为用户，AI 回答时我想看到打字机效果，这样体验更好	SSE 流式输出，逐字显示

2.7 系统设置

编号	用户故事	验收标准
US-SET-01	作为管理员，我想设置企业地区，这样系统用对的最低工资标准	设置→企业信息→选择城市 → 自动填入最低工资/社平工资默认值
US-SET-02	作为管理员，我想管理用户和权限，这样控制谁能看谁能改	设置→用户管理→添加/移除用户→分配角色
US-SET-03	作为管理员，我想查看当前套餐和人数限制，这样知道是否需要升级	设置→套餐信息→显示当前套餐+已用人数+上限

2.8 员工端

编号	用户故事	验收标准
US-EMP-01	作为员工，我想用手机号+密码登录，这样不用等验证码	输入手机号+密码→登录成功→跳转工资条
US-EMP-02	作为员工，我想用手机号+验证码登录，这样不用记密码	输入手机号→获取验证码→输入验证码→登录成功→跳转工资条
US-EMP-03	作为员工，我想扫描 HR 发的二维码直接进入员工端，这样不用手动输入网址	扫码→打开员工端登录页→选择登录方式→登录
US-EMP-04	作为员工，我想查看月度工资条，这样知道工资明细	选择月份→显示基本工资+加班费拆分+应发合计
US-EMP-05	作为员工，我想确认已阅工资条，这样 HR 知道我看过了	点击「确认已阅」→记录时间+IP→HR端显示已确认
US-EMP-06	作为员工，我想查看我的合同信息，这样了解合同条款	我的合同页→显示合同类型/期限/试用期/工资/扫描件
US-EMP-07	作为员工，HR 发二维码让我填报入职信息，这样不用 HR 手动录入	扫码→填写姓名/身份证/银行卡等→提交→HR审核入库
US-EMP-08	作为员工，HR 发二维码让我确认电子合同，这样完成签署确认	扫码→查看合同内容→勾选确认→点击签署→记录时间+IP
US-EMP-09	作为 HR，我想生成入职填报二维码发给员工，这样通过微信即可发送	添加员工时选「生成填报二维码」→显示二维码+链接→保存图片/复制链接
US-EMP-10	作为 HR，我想生成合同确认二维码发给员工，这样完成电子合同签署	合同详情→生成确认二维码→微信发给员工→员工确认后状态自动更新
US-EMP-11	作为 HR，我想查看员工工资条确认状态，这样知道谁还没看	合同/工资管理→显示各员工确认状态（已确认/未确认）

---

3. 用户流程

3.1 新用户注册流程

访问网站 → 注册页
  │
  ├─ 输入企业名称
  ├─ 输入手机号
  ├─ 输入密码
  ├─ 点击注册
  │
  ├─ 创建 Organization + Admin User
  ├─ 自动登录，返回 JWT Token
  │
  └─ 跳转首页（空状态）
       │
       ├─ 显示新手引导弹窗（3步）
       └─ 显示「添加第一个员工」引导卡片

3.2 日常使用流程

登录 → 首页风险总览
  │
  ├─ 有待办？ → 点击「去处理」→ 跳转对应模块 → 处理 → 返回首页
  │
  ├─ 无待办？ → 查看AI风险预测 → 了解未来风险
  │
  └─ 日常操作：
       ├─ 合同管理 → 添加员工/续签/查看详情
       ├─ 钱的计算 → 切换Tab计算加班费/双倍工资/补偿金
       ├─ 解聘助手 → 5步向导完成解聘
       └─ AI顾问 → 问答/合同审查/案例匹配

3.3 合同到期续签流程

首页待办显示「🟡 XX合同还有20天到期」
  │
  └─ 点击「去续签」→ 合同管理页
       │
       └─ 点击「续签」→ 弹窗
            │
            ├─ 确认新期限（默认3年）
            ├─ 选择签订方式（默认沿用上次）
            ├─ 确认新到期日
            │
            └─ 点击「确认续签」
                 │
                 ├─ 更新合同记录
                 ├─ 状态变 🟢 正常
                 ├─ 风险项自动消除
                 └─ 首页待办减少

3.4 解聘流程

解聘助手 → Step 1: 选择解聘原因
  │
  └─ Step 2: 选择员工
       │
       ├─ 自动检查禁止解聘情形
       ├─ 触发？→ 红色警告 → 用户确认继续
       │
       └─ Step 3: 合规检查（根据原因动态展示）
            │
            └─ Step 4: 自动计算补偿金
                 │
                 └─ Step 5: 确认汇总
                      │
                      ├─ 有未通过项？→ 红色警告（不阻止）
                      ├─ 点击保存
                      │
                      └─ 生成解聘记录
                           ├─ 员工状态变更为离职
                           ├─ 记录存档
                           └─ 审计日志记录

3.5 AI 智能问答流程

AI顾问页 → 输入问题（或点击预设问题）
  │
  ├─ 前端构建上下文：
  │    ├─ 当前企业数据摘要（员工数/风险项/合同状态）
  │    └─ RAG 检索相关法律条文
  │
  ├─ 调用 DashScope API（qwen-plus）
  │
  ├─ SSE 流式返回
  │    ├─ 逐字显示回答
  │    └─ 显示完成后附法律依据（可折叠）
  │
  └─ 支持多轮对话（保留上下文）

3.6 员工入职填报流程

HR 管理端 → 添加员工 → 选择「生成填报二维码」
  │
  ├─ 生成一次性 token（24h 有效）
  ├─ 页面显示二维码图片 + 可复制链接
  │
  └─ HR 通过微信发送给员工（二维码图片或链接）
       │
       └─ 员工扫码/点击链接 → 填报页面
            │
            ├─ 填写姓名/手机号/身份证/银行卡等
            ├─ 提交
            │
            └─ 信息进入「待审核」状态
                 │
                 └─ HR 管理端收到通知
                      │
                      ├─ 审核 → 通过 → 正式入库
                      │          ├─ 创建 Employee 记录
                      │          └─ token 失效
                      │
                      └─ 审核 → 驳回 → 员工重新填报

3.7 电子合同签署确认流程

HR 管理端 → 录入电子合同 → 点击「生成确认二维码」
  │
  ├─ 生成一次性 token（7天有效）
  ├─ 页面显示二维码图片 + 可复制链接
  │
  └─ HR 通过微信发送给员工（二维码图片或链接）
       │
       └─ 员工扫码/点击链接 → 合同确认页面
            │
            ├─ 查看合同内容（类型/期限/试用期/工资）
            ├─ 查看合同文件（如有链接）
            ├─ 勾选「我已阅读，确认签署」
            ├─ 点击「确认签署」
            │
            └─ 系统记录：确认时间 + IP + 设备信息
                 │
                 └─ HR 端合同状态自动更新为「已确认签署」
                      ├─ token 失效
                      └─ 审计日志记录

---

4. 功能规格

4.1 认证模块

4.1.1 注册

• 页面: /register
• 输入: 企业名称、手机号、密码（8位以上）、确认密码
• 校验: 手机号格式、密码长度、手机号未被注册
• 处理: 创建 Organization（plan=free, maxEmployees=20）+ User（role=admin）+ bcrypt 加密密码
• 输出: JWT Token + 跳转首页
• 限流: 同一 IP 每小时最多 5 次注册

4.1.2 登录

• 页面: /login
• 输入: 手机号、密码
• 校验: 手机号存在、密码匹配
• 输出: Access Token（2h）+ Refresh Token（7d）
• 限流: 同一 IP 每分钟最多 5 次登录

4.1.3 Token 刷新

• 接口: POST /api/v1/auth/refresh
• 输入: Refresh Token
• 输出: 新 Access Token
• 逻辑: 校验 Refresh Token 有效性 → 签发新 Access Token

4.2 首页风险总览

4.2.1 数据聚合接口

• 接口: GET /api/v1/dashboard
• 返回数据:

{
  "success": true,
  "data": {
    "greeting": "早上好！今天有 3 件事需要处理",
    "stats": {
      "employeeCount": 12,
      "highRiskCount": 2,
      "todoCount": 3,
      "monthlyOvertimePay": 8000
    },
    "todos": [
      {
        "id": "risk_001",
        "level": "high",
        "title": "张三入职35天未签合同",
        "actionUrl": "/contracts?employee=张三"
      }
    ],
    "riskDistribution": {
      "contract": 5,
      "salary": 2,
      "termination": 1
    },
    "aiPrediction": {
      "risks": [...],
      "suggestion": "本周优先处理合同到期和未签问题"
    }
  }
}

4.2.2 风险检测引擎

• 触发时机: 数据变更时实时检测 + 每日凌晨定时全量扫描
• 检测规则: 见 0-req.md 4.3.3 / 4.4.4 合规检查规则
• 风险生命周期: pending → resolved（自动/手动）/ ignored（手动）

4.3 合同管理模块

4.3.1 API 规格

接口	方法	路径	说明
员工列表	GET	/api/v1/employees	支持分页、搜索、部门筛选
添加员工	POST	/api/v1/employees	含合同信息
员工详情	GET	/api/v1/employees/:id	含合同+风险信息
编辑员工	PUT	/api/v1/employees/:id	更新员工+合同信息
删除员工	DELETE	/api/v1/employees/:id	软删除（status=resigned）
批量续签	POST	/api/v1/contracts/batch-renew	批量续签合同
上传附件	POST	/api/v1/contracts/:id/attachment	上传纸质合同扫描件

4.3.2 合同状态自动计算

输入：signDate, startDate, endDate, contractType, renewalCount, hireDate
输出：status + statusText + riskLevel

逻辑：
  if signDate == null:
    daysSinceHire = today - hireDate
    if daysSinceHire > 365: → "已视为无固定期限" 🔴
    elif daysSinceHire > 30: → "未签合同(X天)" 🔴
    else: → "未签合同(X天)" 🟡
  elif endDate != null:
    daysToExpire = endDate - today
    if daysToExpire < 0: → "已到期未续签" 🔴
    elif daysToExpire <= 30: → "即将到期(X天)" 🟡
    else: → "正常" 🟢
  else:
    → "无固定期限" 🟢

4.3.3 试用期合法性校验

规则（劳动合同法第19条）：
  合同期 < 3个月 → 不能约定试用期
  合同期 3个月~1年 → 试用期 ≤ 1个月
  合同期 1年~3年 → 试用期 ≤ 2个月
  合同期 ≥ 3年 → 试用期 ≤ 6个月

校验时机：添加/编辑合同时实时校验
校验失败：红色提示「X年期合同试用期最多Y个月，当前Z个月不合法」

4.4 钱的计算模块

4.4.1 加班费计算

• 页面: /money Tab 1
• 输入: 月工资、工作日加班小时、休息日加班小时、节假日加班小时
• 计算: 纯前端实时计算，无需调后端
• 公式:

hourlyWage = monthlyWage / 21.75 / 8
weekdayPay = hourlyWage * 1.5 * weekdayHours
weekendPay = hourlyWage * 2.0 * weekendHours
holidayPay = hourlyWage * 3.0 * holidayHours
total = weekdayPay + weekendPay + holidayPay

• 预警: 总加班小时 > 36 → 黄色警告

4.4.2 双倍工资计算

• 页面: /money Tab 2
• 输入: 月工资、入职日期、合同签订日期（可选，默认未签订）
• 计算: 纯前端实时计算
• 公式:

if 未签订 or 签订日期 - 入职日期 > 30天:
  起算日 = 入职日 + 1个月
  截止日 = 入职日 + 1年（如未签订）或 签订日期
  月数 = min(截止日 - 起算日 的月数, 11)
  双倍工资差额 = 月工资 × 月数

4.4.3 经济补偿金计算

• 页面: /money Tab 3
• 输入: 入职日期、离职日期、月平均工资、离职原因、当地社平工资（选填）
• 计算: 纯前端实时计算
• 公式:

工作年限 = (离职日期 - 入职日期) 转换为年月
  满1年 → 1个月工资
  满6个月不满1年 → 1个月工资
  不满6个月 → 0.5个月工资
补偿月数 = 向上取整(工作年限月数 / 12) 或 半月

if 社平工资 > 0 and 月工资 > 社平工资 × 3:
  月工资 = 社平工资 × 3
  补偿月数 = min(补偿月数, 12)

经济补偿金 = 月工资 × 补偿月数
违法解除赔偿金 = 经济补偿金 × 2

4.5 解聘助手模块

4.5.1 解聘向导状态管理

interface TerminationWizardState {
  step: 1 | 2 | 3 | 4 | 5;
  reason: 'negotiated' | 'fault' | 'nonfault' | 'layoff' | 'expired' | null;
  employeeId: string | null;
  terminationDate: string | null;
  checklist: {
    item: string;
    passed: boolean;
    remark?: string;
  }[];
  compensation: number;
  riskLevel: 'safe' | 'warning' | 'danger';
}

4.5.2 动态检查项规则

解聘原因	检查项
协商解除	是否支付经济补偿金、是否签署协商解除协议
员工犯错	是否有规章制度依据、是否有证据材料、是否通知工会
员工没犯错但干不了	是否提前30天通知或支付代通知金、是否经过培训/调岗
公司裁员	是否提前30天向工会说明、是否听取职工意见、是否报劳动部门
合同到期不续签	是否提前通知、是否支付经济补偿金

4.5.3 禁止解聘情形检查

• 触发: Step 2 选择员工后自动检查
• 检查字段: employee.isPregnant / employee.isWorkInjured / employee.isInMedicalPeriod
• 交互: 弹出红色警告框 + 「我已了解风险，继续操作」确认按钮
• 不阻止流程: 用户确认后可继续

4.6 AI 合规顾问模块

4.6.1 智能问答

• 页面: /ai-assistant
• 接口: POST /api/v1/ai/chat（SSE 流式）
• 请求:

{
  "messages": [
    {"role": "user", "content": "试用期最长可以约定几个月？"}
  ],
  "context": {
    "orgId": "xxx",
    "employeeCount": 12,
    "riskItems": [...]
  }
}

• 后端处理:
  1. 构建系统 Prompt（劳动法专家角色 + 人话风格要求）
  2. RAG 检索相关法律条文（pgvector 语义搜索）
  3. 注入企业数据上下文
  4. 调用 DashScope API（qwen-plus）
  5. SSE 流式返回前端
• 响应: SSE 事件流

data: {"type": "chunk", "content": "根据"}
data: {"type": "chunk", "content": "《劳动合同法》"}
data: {"type": "chunk", "content": "第19条"}
...
data: {"type": "done", "legalBasis": "《劳动合同法》第19条"}

4.6.2 风险预测

• 触发: 每日凌晨定时任务 + 首页加载时读取缓存
• 接口: GET /api/v1/ai/prediction
• 逻辑:
  1. 查询未来30天将到期的合同
  2. 查询入职将满1年未签合同的员工
  3. 分析上月加班趋势变化
  4. 调用 LLM 生成优先级建议
• 缓存: 结果存 Redis / 内存缓存，24h 有效

4.6.3 合同审查

• 页面: /ai-assistant 子 Tab
• 接口: POST /api/v1/ai/contract-review
• 输入: 合同文本（粘贴或文件上传解析）
• 后端处理:
  1. 调用 qwen-max 分析合同条款
  2. 逐条标注红/黄/绿 + 修改建议
  3. 计算合规评分（0-100）
• 输出:

{
  "success": true,
  "data": {
    "score": 72,
    "items": [
      {"level": "red", "clause": "试用期6个月", "issue": "超过法定上限", "suggestion": "调整为2个月"},
      {"level": "yellow", "clause": "竞业限制", "issue": "未约定补偿标准", "suggestion": "约定月补偿不低于离职前12个月平均工资的30%"}
    ]
  }
}

4.6.4 案例匹配

• 页面: /ai-assistant 子 Tab
• 接口: POST /api/v1/ai/case-match
• 输入: 争议情况描述
• 后端处理:
  1. 将描述向量化（DashScope text-embedding-v2）
  2. pgvector 检索相似案例（top 5）
  3. 调用 qwen-max 分析败诉概率和赔偿预估
• 输出: 相似案例列表 + 败诉概率 + 赔偿预估 + 建议

4.6.5 使用次数限制

• 中间件: 每次 AI 请求前检查当月已用次数
• 计数: Redis / 数据库按 orgId + 月份 + 类型 统计
• 超限: 返回 429 Too Many Requests + 提示升级套餐

---

5. 页面规格

5.1 页面清单

管理端：

页面	路由	访问控制	布局
登录	/login	公开	居中卡片
注册	/register	公开	居中卡片
忘记密码	/forgot-password	公开	居中卡片
风险总览	/	登录	顶部导航 + 主内容
合同管理	/contracts	登录	顶部导航 + 主内容
钱的计算	/money	登录	顶部导航 + 主内容
解聘助手	/termination	登录	顶部导航 + 主内容
AI 合规顾问	/ai-assistant	登录	顶部导航 + 主内容
系统设置	/settings	登录(admin)	顶部导航 + 主内容

员工端：

页面	路由	访问控制	布局
员工登录	/portal/login	公开	居中卡片
工资条	/portal/payslip	员工Token	极简布局
我的合同	/portal/contract	员工Token	极简布局
入职填报	/portal/onboarding	Token链接	极简布局
合同确认	/portal/contract-confirm	Token链接	极简布局

5.2 响应式断点

断点	宽度	布局变化
桌面	≥1280px	顶部导航 + 960px 居中内容
平板	768-1279px	顶部导航 + 全宽内容
手机	375-767px	底部 Tab Bar + 全宽内容

5.3 空状态设计

场景	展示内容
首页无员工	插图 + 「添加第一个员工」按钮 + 示例截图
合同列表无数据	插图 + 「还没有员工，点这里添加」按钮
无风险	绿色大勾 + 「✅ 暂无风险，继续保持！」
AI 顾问无对话	欢迎语 + 预设问题快捷按钮
解聘无历史记录	插图 + 「还没有解聘记录」文字
员工端无工资条	插图 + 「暂无工资记录」文字
员工端无合同	插图 + 「暂无合同信息，请联系 HR」文字
入职填报链接失效	提示「链接已过期，请联系 HR 重新发送」
合同确认链接失效	提示「链接已过期，请联系 HR 重新发送」

---

6. API 规格

6.1 统一规范

• 前缀: /api/v1/
• 认证: Authorization: Bearer <access_token>
• 响应格式:

{
  "success": true,
  "data": {},
  "error": null
}

• 错误格式:

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "手机号格式不正确"
  }
}

• 分页: ?page=1&pageSize=20 → 返回 { items: [], total: 100, page: 1, pageSize: 20 }

6.2 API 清单

模块	方法	路径	说明
认证	POST	/auth/register	注册
认证	POST	/auth/login	登录
认证	POST	/auth/refresh	刷新 Token
认证	GET	/auth/me	获取当前用户
Dashboard	GET	/dashboard	首页数据聚合
员工	GET	/employees	员工列表
员工	POST	/employees	添加员工
员工	GET	/employees/:id	员工详情
员工	PUT	/employees/:id	编辑员工
员工	DELETE	/employees/:id	删除员工（软删除）
合同	POST	/contracts/batch-renew	批量续签
合同	POST	/contracts/:id/attachment	上传扫描件
加班	GET	/overtime	加班记录列表
加班	POST	/overtime	添加加班记录
解聘	GET	/termination	解聘记录列表
解聘	POST	/termination	创建解聘记录
风险	GET	/risks	风险列表
风险	PUT	/risks/:id	更新风险状态
AI	POST	/ai/chat	智能问答（SSE）
AI	GET	/ai/prediction	风险预测
AI	POST	/ai/contract-review	合同审查
AI	POST	/ai/case-match	案例匹配
设置	GET	/settings/org	企业信息
设置	PUT	/settings/org	更新企业信息
设置	GET	/settings/users	用户列表
设置	POST	/settings/users	添加用户
设置	PUT	/settings/users/:id	编辑用户
设置	DELETE	/settings/users/:id	移除用户
员工端	POST	/portal/auth/login	手机号+密码登录
员工端	POST	/portal/auth/send-code	发送验证码（v1.0 页面内显示）
员工端	POST	/portal/auth/verify	验证码登录
员工端	POST	/portal/auth/change-password	修改密码
员工端	GET	/portal/payslip	工资条列表
员工端	GET	/portal/payslip/:month	指定月工资明细
员工端	POST	/portal/payslip/:month/confirm	确认已阅工资条
员工端	GET	/portal/contract	我的合同信息
员工端	GET	/portal/onboarding/:token	获取入职填报信息
员工端	POST	/portal/onboarding/:token	提交入职填报
员工端	GET	/portal/contract-confirm/:token	获取合同确认信息
员工端	POST	/portal/contract-confirm/:token	确认签署合同
管理端	POST	/employees/:id/generate-onboarding-qr	生成入职填报二维码
管理端	POST	/contracts/:id/generate-confirm-qr	生成合同确认二维码
管理端	GET	/payslip/confirm-status	工资条确认状态

---

7. 数据库设计

7.1 Prisma Schema 概要

// 核心表
model Organization {
  id           String   @id @default(cuid())
  name         String
  plan         Plan     @default(FREE)
  maxEmployees Int      @default(20)
  city         String?
  createdAt    DateTime @default(now())
  users        User[]
  employees    Employee[]
  contracts    LaborContract[]
  overtimeRecords OvertimeRecord[]
  terminations TerminationRecord[]
  riskItems    RiskItem[]
  auditLogs    AuditLog[]
}

model User {
  id           String   @id @default(cuid())
  orgId        String
  org          Organization @relation(fields: [orgId], references: [id])
  phone        String   @unique
  email        String?
  passwordHash String
  name         String
  role         Role     @default(ADMIN)
  createdAt    DateTime @default(now())
  lastLoginAt  DateTime?
}

// 业务表
model Employee {
  id               String   @id @default(cuid())
  orgId            String
  org              Organization @relation(fields: [orgId], references: [id])
  name             String
  department       String
  hireDate         DateTime
  monthlySalary    String   // AES-256 加密存储
  status           EmployeeStatus @default(ACTIVE)
  gender           String?
  isPregnant       Boolean  @default(false)
  isInMedicalPeriod Boolean @default(false)
  isWorkInjured    Boolean  @default(false)
  phone            String?
  createdBy        String
  createdAt        DateTime @default(now())
  updatedAt        DateTime @updatedAt
  contracts        LaborContract[]
  overtimeRecords  OvertimeRecord[]
  terminations     TerminationRecord[]
}

model LaborContract {
  id                    String   @id @default(cuid())
  orgId                 String
  org                   Organization @relation(fields: [orgId], references: [id])
  employeeId            String
  employee              Employee @relation(fields: [employeeId], references: [id])
  signDate              DateTime?
  startDate             DateTime
  endDate               DateTime?
  contractType          ContractType
  signMethod            SignMethod @default(PAPER)
  contractYears         Int      @default(3)
  probationMonths       Int      @default(0)
  probationSalary       Int      @default(0)
  renewalCount          Int      @default(0)
  attachmentName        String?
  attachmentUrl         String?
  electronicContractNo  String?
  electronicContractUrl String?
  createdBy             String
  createdAt             DateTime @default(now())
  updatedAt             DateTime @updatedAt
}

// 其余表参考 0-req.md 第5章数据模型

7.2 枚举定义

enum Plan { FREE PRO ENTERPRISE }
enum Role { ADMIN HR VIEWER }
enum EmployeeStatus { ACTIVE RESIGNED }
enum ContractType { FIXED UNFIXED UNSIGNED }
enum SignMethod { PAPER ELECTRONIC }
enum RiskType { CONTRACT SALARY TERMINATION }
enum RiskLevel { HIGH MEDIUM LOW }
enum RiskStatus { PENDING RESOLVED IGNORED }
enum TerminationReason { NEGOTIATED FAULT NONFAULT LAYOFF EXPIRED }
enum RiskAssessment { SAFE WARNING DANGER }
enum OnboardingStatus { PENDING APPROVED REJECTED }
enum ContractConfirmStatus { UNCONFIRMED CONFIRMED EXPIRED }

// 员工端扩展表
model Payslip {
  id           String   @id @default(cuid())
  orgId        String
  employeeId   String
  employee     Employee @relation(fields: [employeeId], references: [id])
  month        String   // YYYY-MM
  baseSalary   Decimal  // 基本工资
  overtimePay  Decimal  // 加班费合计
  weekdayOvertimePay  Decimal
  weekendOvertimePay  Decimal
  holidayOvertimePay  Decimal
  totalPay     Decimal  // 应发合计
  confirmedAt  DateTime? // 员工确认时间
  confirmedIp  String?   // 确认 IP
  createdAt    DateTime @default(now())

  @@unique([employeeId, month])
}

model OnboardingLink {
  id           String   @id @default(cuid())
  orgId        String
  employeeId   String?  // 关联员工（审核通过后关联）
  token        String   @unique  // 一次性 token
  status       OnboardingStatus @default(PENDING)
  phone        String   // 员工手机号
  expiresAt    DateTime  // 24h 有效
  submittedAt  DateTime? // 员工提交时间
  submittedData Json?   // 员工填报数据
  reviewedBy   String?  // 审核人 userId
  reviewedAt   DateTime? // 审核时间
  createdAt    DateTime @default(now())
}

model ContractConfirmLink {
  id           String   @id @default(cuid())
  orgId        String
  contractId   String
  token        String   @unique  // 一次性 token
  status       ContractConfirmStatus @default(UNCONFIRMED)
  employeePhone String  // 员工手机号
  expiresAt    DateTime  // 7天有效
  confirmedAt  DateTime? // 员工确认时间
  confirmedIp  String?   // 确认 IP
  confirmedDevice String? // 设备信息
  createdAt    DateTime @default(now())
}

---

8. 前端架构

8.1 项目结构

frontend/
├── src/
│   ├── main.tsx                 # 入口
│   ├── App.tsx                  # 路由定义
│   ├── components/              # 通用组件
│   │   ├── layout/
│   │   │   ├── TopNav.tsx       # 顶部导航
│   │   │   ├── MobileTabBar.tsx # 移动端底部导航
│   │   │   └── PageContainer.tsx
│   │   ├── ui/
│   │   │   ├── Button.tsx
│   │   │   ├── Card.tsx
│   │   │   ├── Signal.tsx       # 信号灯组件
│   │   │   ├── Modal.tsx
│   │   │   ├── Input.tsx
│   │   │   ├── Select.tsx
│   │   │   ├── DatePicker.tsx
│   │   │   └── EmptyState.tsx
│   │   └── shared/
│   │       ├── RiskCard.tsx
│   │       ├── TodoList.tsx
│   │       └── ProgressBar.tsx
│   ├── pages/
│   │   ├── auth/
│   │   │   ├── Login.tsx
│   │   │   ├── Register.tsx
│   │   │   └── ForgotPassword.tsx
│   │   ├── Dashboard.tsx
│   │   ├── Contracts.tsx
│   │   ├── Money.tsx
│   │   ├── Termination.tsx
│   │   ├── AIAssistant.tsx
│   │   ├── Settings.tsx
│   │   └── portal/
│   │       ├── PortalLogin.tsx     # 员工端登录
│   │       ├── Payslip.tsx         # 工资条
│   │       ├── MyContract.tsx      # 我的合同
│   │       ├── Onboarding.tsx      # 入职填报
│   │       └── ContractConfirm.tsx # 合同确认
│   ├── hooks/
│   │   ├── useAuth.ts
│   │   ├── useApi.ts
│   │   └── useRiskEngine.ts
│   ├── lib/
│   │   ├── api.ts               # Axios 实例 + 拦截器
│   │   ├── calculator.ts        # 纯前端计算逻辑
│   │   ├── riskEngine.ts        # 风险检测引擎
│   │   └── utils.ts
│   ├── store/
│   │   └── authStore.ts         # Zustand 状态管理
│   └── types/
│       └── index.ts             # TypeScript 类型定义
├── package.json
├── vite.config.ts
├── tailwind.config.ts
└── tsconfig.json

8.2 状态管理

• 认证状态: Zustand（user, token, isAuthenticated）
• 服务端数据: TanStack Query（React Query）缓存 + 自动刷新
• 表单状态: React Hook Form + Zod 校验
• AI 对话: 本地 useState 管理消息列表 + SSE 流式追加

8.3 路由守卫

// ProtectedRoute：未登录 → 跳转 /login
// AdminRoute：非 admin → 跳转 /
// PublicRoute：已登录 → 跳转 /

---

9. 后端架构

9.1 项目结构

backend/
├── src/
│   ├── index.ts                 # 入口
│   ├── app.ts                   # Express 应用
│   ├── routes/
│   │   ├── auth.routes.ts
│   │   ├── employee.routes.ts
│   │   ├── contract.routes.ts
│   │   ├── overtime.routes.ts
│   │   ├── termination.routes.ts
│   │   ├── risk.routes.ts
│   │   ├── ai.routes.ts
│   │   ├── settings.routes.ts
│   │   └── portal.routes.ts        # 员工端路由
│   ├── middleware/
│   │   ├── auth.ts              # JWT 校验
│   │   ├── orgFilter.ts         # 多租户 orgId 注入
│   │   ├── rateLimit.ts         # 限流
│   │   ├── errorHandler.ts      # 统一错误处理
│   │   └── auditLog.ts          # 审计日志
│   ├── services/
│   │   ├── auth.service.ts
│   │   ├── employee.service.ts
│   │   ├── contract.service.ts
│   │   ├── risk.service.ts
│   │   ├── ai.service.ts        # DashScope 调用
│   │   ├── rag.service.ts       # RAG 检索
│   │   ├── portal.service.ts    # 员工端服务
│   │   └── qrcode.service.ts    # 二维码生成
│   ├── lib/
│   │   ├── prisma.ts            # Prisma 客户端
│   │   ├── jwt.ts               # JWT 工具
│   │   ├── crypto.ts            # AES-256 加解密
│   │   └── dashscope.ts         # 通义千问 SDK 封装
│   ├── validators/
│   │   ├── auth.validator.ts    # Zod schema
│   │   ├── employee.validator.ts
│   │   └── ...
│   └── jobs/
│       ├── riskScan.ts          # 定时风险扫描
│       └── aiPrediction.ts      # 定时 AI 预测
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── package.json
└── .env

9.2 环境变量

# 数据库
DATABASE_URL=postgresql://...

# JWT
JWT_SECRET=...
JWT_REFRESH_SECRET=...

# DashScope (通义千问)
DASHSCOPE_API_KEY=sk-xxx
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1

# 加密
ENCRYPTION_KEY=...  # AES-256 工资字段加密

# 存储
SUPABASE_URL=...
SUPABASE_KEY=...

# 二维码（前端生成，无需后端服务）
# 使用 qrcode.react 库在前端直接生成

# 部署
PORT=3000
CORS_ORIGIN=https://your-app.vercel.app

---

10. 验收标准

10.1 功能验收

模块	验收项	验收标准
注册	手机号注册	输入合法信息 → 创建成功 → 自动登录
登录	密码登录	正确密码 → 返回 Token；错误密码 → 提示错误
首页	数据聚合	登录后 → 显示员工数/风险数/待办/分布
合同	添加员工	4项必填 → 保存成功 → 列表显示
合同	信号灯状态	未签合同→🔴；即将到期→🟡；正常→🟢
合同	一键续签	点击续签→确认→状态变绿→风险消除
合同	纸质/电子	选择纸质→显示上传按钮；选择电子→显示编号/链接输入
钱的计算	加班费实时计算	输入数字→右侧结果实时更新
钱的计算	加班超时预警	总小时>36→黄色警告
解聘	5步向导	每步显示进度条→下一步→最终保存
解聘	禁止情形检查	选孕期员工→红色警告弹窗
AI	智能问答	输入问题→流式回答→附法律依据
AI	合同审查	粘贴合同→逐条标注→合规评分
AI	案例匹配	输入情况→相似案例→败诉概率
设置	用户管理	admin可添加用户→分配角色
员工端	密码登录	输入手机号+密码→登录成功
员工端	验证码登录	输入手机号→收到验证码→登录成功
员工端	扫码进入	HR 发二维码→员工扫码→打开员工端
员工端	工资条查看	选择月份→显示工资明细→确认已阅
员工端	合同查看	显示合同信息+扫描件+签署记录
员工端	入职填报	扫码→填写信息→提交→HR审核入库
员工端	合同确认	扫码→查看合同→勾选确认→记录时间IP
管理端	生成填报二维码	添加员工→选生成二维码→显示二维码+链接→微信发送
管理端	生成确认二维码	合同详情→生成确认二维码→微信发送→员工确认后状态更新

10.2 非功能验收

类别	验收标准
性能	首屏加载 < 2s，API 响应 < 500ms，AI 首 token < 3s
安全	密码 bcrypt 加密，工资 AES-256 加密，JWT 认证，orgId 隔离
响应式	桌面/平板/手机三端可用，导航自适应
兼容	Chrome/Edge/Safari 最新版正常
数据隔离	A 企业用户无法访问 B 企业数据
员工端隔离	员工只能查看自己的数据，不能查看他人
链接安全	入职/确认链接含一次性 token，过期失效

---

11. 发布计划

11.1 v1.0 发布范围

阶段	内容	���估工期
P0	项目搭建 + 路由骨架 + Prisma Schema	2天
P1	认证体系（注册/登录/JWT/路由守卫）	2天
P2	首页风险总览 + 风险检测引擎	2天
P3	合同管理（列表/添加/续签/纸质电子）	3天
P4	钱的计算（3 Tab 计算器）	2天
P5	解聘助手（5步向导 + 禁止检查）	2天
P6	AI 合规顾问（问答/预测/审查/案例 + RAG）	4天
P7	员工端（验证码登录 + 工资条 + 合同 + 入职填报 + 合同确认）	3天
P8	系统设置 + 新手引导 + 空状态	1天
P9	移动端适配 + 联调	2天
P10	部署上线 + 验证	1天
合计		~24天

11.2 后续版本

版本	内容	预估
v2.0	社保公积金模块	+2周
v3.0	人力成本分析 + 员工自助门户增强（考勤/请假）	+3周

---

12. 风险与对策

风险	影响	对策
通义千问 API 不稳定	AI 功能不可用	降级为规则引擎回答 + 重试机制
法律规则地区差异大	计算结果不准	提供城市选择 + 默认值 + 用户可修改
RAG 知识库构建耗时	P6 延期	先用 Prompt 内嵌法条，后续再建向量库
中小企业付费意愿低	商业化困难	free 套餐足够基础使用，AI 功能促付费
数据安全合规要求	法律风险	数据加密 + 身份证号加密存储 + 隐私协议
员工端使用率低	功能闲置	HR 主动生成二维码通过微信发给员工，降低使用门槛