# 灵活用工与用工税筹模块 — 技术方案

| 文档版本 | v1.2 |
|---------|------|
| 编写日期 | 2026-07-07 |
| 依据材料 | `wechat-mini-program-flexible-employment-plan.md`、`会议摘要`、`灵活用开发工会议.md`、`flexible-employment-demo.html`、`灵活用工-mysql.sql`、`灵活用工项目后端方案v1简化版本.docx` |

---

## 1. 项目背景与定位

### 1.1 背景

灵活用工与用工税筹是面向中小微企业的**独立业务产品**（与巴青平台**分仓库、分部署、分数据库**），通过智能体能力完成用工咨询、方案草稿、成本对比与登记办理。

当企业用户提出用工、临时工、合规用工、用工成本、结算、保险、发票等相关问题时，系统负责：

- 理解用工意图与场景分类
- 生成可确认的用工草稿
- 成本测算与三方案对比
- 风险诊断与合规提示
- 生成登记批次、结算数据等办理前结构化数据
- 用户确认后驱动后端流程继续办理

**一期仅提供微信小程序前台，不提供 Web 管理后台。**

### 1.2 产品定位

| 角色 | 定位 |
|------|------|
| 微信小程序 | 唯一前台：登录、对话、草稿/成本/进度、扫码登记 |
| 业务后端（fe-server） | Java 服务：鉴权、编排、持久化、规则/成本/状态机、第三方对接 |
| AI 服务（fe-ai） | Python 独立进程：对话、意图识别、草稿文案生成（不直连数据库） |
| 合作平台 | 身份校验、电子签、保险、支付、完税开票（经连接器对接，一期 Mock） |

### 1.3 核心产品原则

**（1）草稿优先**

```text
智能体先帮用户生成草稿 → 用户确认或修改 → 后端继续办理
```

- 能从企业画像推断的字段不重复追问
- 能从历史偏好推断的字段优先复用
- 能使用合理默认值的字段先生成草稿，再允许修改
- 仅对关键缺失信息或高风险信息主动追问
- 已有临时工场景：先生成登记批次与二维码，由临时工扫码自行登记

**（2）弱化第三方平台存在感**

用户侧不出现「第三方 API」「连接器」等技术表达；内部记录 `provider`、`action` 等。仅在授权、合同、结算、发票等场景说明外部服务方。

**（3）成本对比优先**

企业主关注：**企业总支出**、**平均每人成本**、**员工到手金额**。展示「当前方式 + 方案一/二/三」；测试费率标注 `test_only`。

**（4）后端说了算**

所有算数、改状态、提交正式数据、调用第三方，**100% 由 Java 后端执行**；AI 只通过工具接口查询与写草稿。

---

## 2. 总体架构

### 2.1 逻辑架构

```mermaid
flowchart TB
    subgraph client [客户端]
        MP[微信小程序]
        MP_ENT[企业主端]
        MP_WRK[临时工端]
        MP --> MP_ENT
        MP --> MP_WRK
    end

    subgraph gateway [接入层]
        NGX[Nginx HTTPS / 限流]
    end

    subgraph java [fe-server Java]
        SEC[Spring Security + JWT]
        ORCH[编排层 规则路由 / AI转发]
        PLATFORM[中台 画像 / 会话 / 权限]
        RULES[规则引擎 / 状态机]
        BIZ[登记 / 草稿 / 结算 / 成本]
        AIGW[AI 工具网关 /internal/fe]
        CONN[第三方连接器 Mock]
    end

    subgraph ai [fe-ai Python]
        AGENT[LangGraph 对话与草稿]
    end

    subgraph data [数据层]
        DB[(MySQL 5.7)]
        REDIS[(Redis)]
        LOCAL[本地文件 二维码等]
    end

    MP --> NGX --> SEC
    SEC --> ORCH
    ORCH -->|对话类| AGENT
    ORCH -->|确定性请求| BIZ
    AGENT --> AIGW
    AIGW --> PLATFORM
    AIGW --> BIZ
    AIGW --> RULES
    BIZ --> DB
    BIZ --> REDIS
    CONN --> DB
    AGENT -.->|禁止直连| DB
```

### 2.2 六层后端架构

| 层级 | 职责 | 一期实现 |
|------|------|----------|
| 接入网关 | Nginx、HTTPS、基础限流 | 是 |
| 统一编排层 | 规则路由（零 AI）+ AI 对话转发 + 结果组装 | 是 |
| 中台层 | 企业画像、身份权限、对话会话、草稿引擎 | 是（画像可简化） |
| 规则引擎 | 费率配置、政策规则、合规状态机 | 是（费率可测试数据） |
| 业务层 | 登记、人员、成本测算、结算（结算一期 Mock） | 是 |
| 集成层 | 第三方连接器 + Mock | Mock 为主 |

另设 **AI 工具接口网关**（`fe-server` 内独立包）：AI 调用后端能力的唯一入口，限流 + 鉴权 + 审计。

### 2.3 请求链路

**对话类（走 AI）：**

```text
小程序 → fe-server(/api/v1/mp/agent/messages)
      → fe-ai(Python)
      → fe-server(/internal/fe/* 工具接口)
      → MySQL / Redis
      → 组装卡片返回小程序
```

**确定性业务（不走 AI）：**

```text
小程序 → fe-server(/api/v1/mp/*)
      → 规则路由 → 业务 Service
      → MySQL / Redis
      → 返回
```

**禁止**：小程序直连大模型、直连合作平台、保存模型/平台密钥、在前端或 AI 侧执行成本测算与状态变更。

**模块间契约**：Java 侧统一 DTO + Bean Validation；`fe-server` 与 `fe-ai` 通过 **OpenAPI 3**（Knife4j 导出）对齐 JSON 结构。

---

## 3. 业务流程设计

### 3.1 主流程（企业已有临时工规范办理）

```mermaid
sequenceDiagram
    participant U as 企业主
    participant MP as 微信小程序
    participant API as fe-server
    participant AI as fe-ai
    participant Worker as 临时工
    participant Conn as 连接器

    U->>MP: 自然语言描述用工需求
    MP->>API: POST /api/v1/mp/agent/messages
    API->>AI: 转发对话
    AI->>API: /internal/fe/* 查画像、算成本
    AI-->>API: 草稿建议 + 回复文案
    API-->>MP: 对话卡片 + 弹窗草稿
    U->>MP: 确认方案 / 修改字段
    MP->>API: POST /api/v1/mp/drafts/{id}/confirm
    API->>API: 确认留痕、生成订单与登记批次
    API-->>MP: 二维码 / 登记链接
    Worker->>MP: 扫码登记
    MP->>API: POST /api/v1/mp/worker-registration/{batch_id}/submit
    API-->>MP: 登记进度
    API->>Conn: 内部提交（一期 Mock）
```

### 3.2 合规状态机（五流合一）

业务流程强制校验：**实名 → 合同 → 结算 → 完税 → 开票**。

| 步骤编码 | 步骤名称 | 说明 |
|----------|----------|------|
| `draft_created` | 草稿创建 | AI 生成草稿 |
| `plan_confirmed` | 方案确认 | 企业主选定方案并确认 |
| `registration` | 扫码登记 | 临时工扫码填写资料 |
| `enterprise_audit` | 企业审核 | 企业主审核登记资料 |
| `contract_signing` | 合同签署 | 电子劳动合同（一期 Mock） |
| `work_started` | 开始用工 | 实际用工 |
| `settlement_pending` | 待结算 | 生成结算单待确认 |
| `settlement_paid` | 已支付 | 打款完成（一期 Mock） |
| `completed` | 已完成 | 流程结束 |

状态变更写入 `fe_order_workflow_log`，与用户确认记录共同构成合规证据链。

### 3.3 数据隔离策略

- **AI 不直接连接 MySQL**，不持有数据库账号
- 草稿、订单、登记须经 Java **规则校验**后入库
- 敏感字段加密存储（`*_enc` + `*_mask`），列表仅展示脱敏值
- 业务查询默认带 `enterprise_id` 与 `del_flag = 0` 过滤

---

## 4. 前端方案（微信小程序）

### 4.1 技术选型

- 微信原生小程序 + TypeScript
- UI：TDesign WeChat 或 Vant Weapp
- 鉴权：微信 `wx.login` + 后端 **JWT**（`Authorization: Bearer <token>`）
- 第一版不上跨端框架，优先验证业务闭环

### 4.2 交互模式

- **主对话界面**为核心，草稿/成本/确认通过**底部弹窗（Bottom Sheet）**
- 底部 Tab：**发布需求 / 成本核算 / 进度总览 / 历史订单**
- AI 生成草稿后弹出确认弹窗，确认后生成**订单卡片**沉淀到对话流

### 4.3 企业主端 / 临时工端

与企业主端、临时工端页面清单同 v1.0（登录、对话、草稿弹窗、成本对比、登记进度、扫码登记等），临时工端不展示成本测算与企业财务明细。

### 4.4 敏感信息展示约束

- 严禁展示对公账户号、打款通道明细
- 仅展示支付渠道类型
- 前端不缓存身份证、银行卡明文；Token 存 `wx.setStorageSync`，登出清除

---

## 5. 后端模块设计

### 5.1 业务中心与表前缀

| 中心 | 表前缀 | 职责 |
|------|--------|------|
| 企业画像中心 | `fe_enterprise*` | 企业主体、财务、偏好配置 |
| 对话中心 | `fe_conversation*` | 会话、消息、智能体调用日志 |
| 草稿中心 | `fe_employment_draft*` | 草稿、字段来源、成本快照 |
| 方案与规则中心 | `fe_service_plan*`、`fe_policy_rule`、`fe_workflow_*` | 费率、政策、状态机 |
| 订单与登记中心 | `fe_employment_order`、`fe_registration_batch`、`fe_worker*` | 订单、批次、登记 |
| 结算中心 | `fe_settlement_*`、`fe_payment_record` | 结算单、支付（一期 Mock） |
| 审计确认 | `fe_user_confirmation`、`fe_field_change_log` | 确认留痕、字段变更 |
| 第三方连接器 | `fe_provider*` | 平台配置、API 调用日志 |

完整表结构见：**§7.6～§7.9**（源自 `灵活用工.sql`，生产执行 `灵活用工-mysql.sql`）。

### 5.2 工程结构（Maven 多模块）

```text
flexible-employment/                 # 独立 Git 仓库
├── fe-common/                         # 统一响应 R、异常、常量、工具类
├── fe-dao/                            # Entity、Mapper、MyBatis-Plus XML
├── fe-service/                        # 业务 Service、规则、状态机、成本引擎
├── fe-integration/                    # 第三方 Adapter（Mock / 正式）
├── fe-api/                            # Spring Boot 启动模块、Controller、Security
├── fe-miniapp/                        # 微信小程序源码
└── fe-ai/                             # Python FastAPI + LangGraph（独立部署）
```

**一期不建** `fe-admin`、`fe-ui` 等管理端模块。

### 5.3 fe-server（Java 主服务）

| 包路径 | 职责 |
|--------|------|
| `controller.mp` | 小程序 REST API（`/api/v1/mp/**`） |
| `controller.internal` | AI 工具网关（`/internal/fe/**`，内网 + 服务密钥） |
| `security` | Spring Security 过滤器链、JWT、小程序鉴权 |
| `service.draft` | 草稿 CRUD、版本号、提交校验 |
| `service.registration` | 批次、二维码、登记、进度 |
| `service.cost` | **成本测算（确定性 Java 计算，禁止 AI 算钱）** |
| `service.workflow` | 状态机流转与 `fe_order_workflow_log` |
| `service.rule` | 合规规则拦截 |
| `integration` | 第三方 Mock 实现 |

### 5.4 fe-ai（Python AI 服务）

**职责**：意图识别、多轮对话、草稿字段建议与自然语言回复。

**技术**：FastAPI + LangGraph + 国内大模型 API（通义 / 智谱 / DeepSeek 等）。

**约束**：

- 仅通过 HTTP 调用 `fe-server` 的 `/internal/fe/*`
- 权限：查询脱敏画像、读方案配置、创建/修改草稿、触发成本测算、查批次进度、检索知识库（一期可关键词）
- **禁止**：提交正式订单、改状态、打款、直连 MySQL

### 5.5 成本测算服务（Java）

**输入**：人数、天数、日薪/计件、方案编码  
**输出**：写入 `fe_draft_cost_snapshot`、`fe_draft_cost_detail`

**规则来源**：`fe_service_plan` + `fe_service_plan_fee_rule`；测试方案 `test_only = 1`。

### 5.6 第三方连接器

一期 **Mock 打桩**；接口契约在 `fe-integration` 定义，二期替换实现不改业务层。

| 能力 | 一期 | 二期 |
|------|------|------|
| 身份实名核验 | Mock | 正式 API |
| 电子签 | Mock | 正式 API |
| 保险投保 | Mock | 正式 API |
| 支付打款 | Mock | 微信/银行 |
| 完税开票 | 不做 | 正式对接 |

### 5.7 审计与确认（一期）

- 草稿确认、方案选择 → `fe_user_confirmation`
- 关键字段变更 → `fe_field_change_log`
- 临时工协议勾选 → `fe_worker_consent`
- 完整哈希链审计、按月分表 → 二期

---

## 6. 接口设计

### 6.1 设计原则

- RESTful，对外前缀 **`/api/v1/mp`**（小程序专用）
- 统一响应：`{ "code": 200, "msg": "success", "data": {} }`
- 接口文档：**Knife4j**（`springdoc-openapi`），仅内网或开发环境开放
- 敏感接口 HTTPS；登记类接口限流 + 幂等

### 6.2 核心 API（一期）

#### 认证（一期已实现）

> 文档入口：`http://{host}/doc.html`（Knife4j）。除 `password/set`、`password/status` 外，认证接口均为匿名访问。

```http
POST /api/v1/mp/auth/sms/send              # 发送登录验证码（60s 冷却）
POST /api/v1/mp/auth/sms/login             # 短信验证码登录/自动注册 → JWT
POST /api/v1/mp/auth/wechat/login          # 微信 code2session 登录/自动注册 → JWT
GET  /api/v1/mp/auth/password/public-key   # RSA 公钥（前端加密密码）
POST /api/v1/mp/auth/password/login        # 用户名/手机号 + 密码登录 → JWT
POST /api/v1/mp/auth/password/set          # 设置/修改密码（需 JWT）
POST /api/v1/mp/auth/password/reset        # 短信重置密码（须已设密）
GET  /api/v1/mp/auth/password/status       # 是否已设密（需 JWT）
GET  /api/v1/mp/getInfo                    # 当前用户登记状态（需 JWT）
GET  /api/v1/mp/health                     # 健康检查
```

**登录方式（一期）**：短信验证码（首选）、微信 code2session、可选账密（登录后在个人中心设置）。

**统一响应**：`{ "code": 200, "msg": "success", "data": { ... } }`；鉴权 Header：`Authorization: Bearer <token>`。

**身份规则**：

- `user_type`（`enterprise` / `worker`）**仅在首次创建用户时写入**，后续登录不可切换；错端登录返回 `40305`。
- 短信用户写 `mobile_enc`（AES/ECB 确定性加密，可等值查询）；微信用户写 `openid`；**一期未做**短信与微信账号合并（同一人可能有两个 `fe_user`）。
- 账密：前端 RSA 加密传输，库内 BCrypt；首次设密须填 `username`（全局唯一）。
- 退出登录：**一期无服务端 logout**，小程序本地清除 Token 即可；JWT 黑名单为二期。

**并发与唯一性**（应用层 + 数据库联合唯一索引 `(业务键, del_flag)`）：

| 场景 | 索引 / 机制 |
|------|-------------|
| 短信首次登录重复建号 | `uk_fe_user_mobile_enc` + insert 冲突重查 |
| 微信首次登录重复建号 | `uk_fe_user_openid` + insert 冲突重查 |
| 企业 `enterprise_code` / `credit_code` | `uk_fe_enterprise_code`、`uk_fe_enterprise_credit_code`；登记时 `FOR UPDATE` 锁 `fe_user` |
| 临时工 `worker_no` / 同用户重复登记 | `uk_fe_worker_worker_no`、`uk_fe_worker_user_id`；登记时 `FOR UPDATE` 锁 `fe_user` |

**JWT 鉴权（已实现）**：`JwtAuthFilter` 解析 Token 后**查库**校验 `status=active` 且未逻辑删除，并以**数据库 `user_type`** 写入请求上下文（非仅信任 Token 载荷）。

**错误码（认证相关）**：`40001` 验证码无效；`40010` 账密错误；`40011` 未设密；`40012` 用户名占用；`40301` 账号禁用；`40304` 账密锁定；`40305` 身份类型不匹配；`42901` 短信发送过频。

#### 企业 / 临时工登记（一期已实现）

```http
POST /api/v1/mp/enterprise/register        # 企业首次登记（需 JWT + enterprise）
POST /api/v1/mp/worker/register            # 临时工首次登记（需 JWT + worker）
```

#### 对话与智能体

```http
POST /api/v1/mp/agent/messages             # 封装对话，统一 R 格式（需 JWT，非流式）
GET  /api/v1/mp/ai/models                  # OpenAI 兼容模型列表（需 JWT）
POST /api/v1/mp/ai/chat/completions        # OpenAI 兼容对话；stream=true 时 SSE 流式
```

`POST /api/v1/mp/ai/chat/completions`：请求体与 OpenAI Chat Completions 一致；`"stream": true` 时响应 `text/event-stream`，透传上游 KB 网关；`stream=false` 或不传时为一次性 JSON。小程序流式需 `enableChunked` 等能力，否则建议使用 `/agent/messages`。

#### 对话与会话（规划中）

```http
GET  /api/v1/mp/conversations
GET  /api/v1/mp/conversations/{id}/messages
```

#### 用工草稿（规划中）

```http
GET  /api/v1/mp/drafts/{draft_id}
PUT  /api/v1/mp/drafts/{draft_id}
GET  /api/v1/mp/drafts/{draft_id}/cost-comparison
POST /api/v1/mp/drafts/{draft_id}/confirm
```

#### 登记与进度（规划中）

```http
GET  /api/v1/mp/registration-batches/{batch_id}
GET  /api/v1/mp/registration-batches/{batch_id}/workers
POST /api/v1/mp/registration-batches/{batch_id}/remind
GET  /api/v1/mp/register/scan?token=          # 扫码校验（临时工）
POST /api/v1/mp/worker-registration/{batch_id}/submit
```

#### 订单与进度（规划中）

```http
GET  /api/v1/mp/employment-orders
GET  /api/v1/mp/employment-orders/{order_id}/progress
```

#### 企业多租户（规划中）

```http
GET  /api/v1/mp/enterprises                # 当前用户企业列表
POST /api/v1/mp/enterprises/{id}/switch    # 切换默认企业
POST /api/v1/mp/auth/refresh               # 刷新 Token（可选）
```

结算确认类接口一期可仅预留路径，逻辑 Mock。

### 6.3 AI 工具接口（内网，`/internal/fe`）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/internal/fe/enterprise/profile` | 企业画像（脱敏） |
| GET | `/internal/fe/plans` | 方案与费率配置 |
| POST | `/internal/fe/drafts` | 创建草稿 |
| PUT | `/internal/fe/drafts/{id}` | 修改草稿 |
| GET | `/internal/fe/drafts/{id}` | 查询草稿 |
| POST | `/internal/fe/cost/calculate` | 触发成本测算 |
| GET | `/internal/fe/batches/{id}/progress` | 批次进度 |
| POST | `/internal/fe/rules/validate` | 规则合规校验 |
| GET | `/internal/fe/knowledge/search` | 知识检索（一期可简化） |

鉴权：内网 IP 白名单 + `X-Fe-Ai-Key` 服务密钥；Redisson 限流（按企业/会话）。

---

## 7. 数据设计

### 7.1 存储选型（一期定稿）

| 组件 | 选型 | 说明 |
|------|------|------|
| 业务库 | **MySQL 5.7** | InnoDB、utf8mb4；脚本 `灵活用工-mysql.sql` |
| 缓存 | **Redis** | 会话、验证码、扫码 token、限流、幂等、热点配置 |
| 文件 | **本地磁盘**（一期） | 登记二维码图片；合同 PDF 二期迁 OSS |
| 消息队列 | 不做（一期） | 异步任务用 `@Scheduled` 或二期 RocketMQ |

### 7.2 MySQL 5.7 开发规范

| 约束 | 应用层对策 |
|------|------------|
| JSON 列不能 `DEFAULT` | Insert/Update 时 Java 写入 `{}` / `[]` |
| 无部分唯一索引 | 使用 `(业务键, del_flag)` 联合唯一 |
| `DATETIME` 无时区 | 库与应用统一 `Asia/Shanghai` |
| JSON 查询性能有限 | 高频筛选字段用独立列，JSON 仅存扩展 |

**MyBatis-Plus 约定**：

- 全局逻辑删除字段 `del_flag`（`@TableLogic`）
- 乐观锁字段 `version`（草稿等关键表）
- JSON 字段使用 `JacksonTypeHandler` 或字符串序列化

### 7.3 Redis 使用规范

| 用途 | Key 示例 | TTL |
|------|----------|-----|
| 登录 JWT 黑名单 / 会话 | `fe:token:{jti}` | 与 Token 一致（**二期**） |
| 微信 session_key | `fe:wx:session:{openid}` | 按微信策略（可选） |
| 短信验证码 | `fe:sms:{mobileHash}` | 5 min（默认 300s） |
| 短信发送冷却 | `fe:sms:cd:{mobileHash}` | 60 s |
| 短信校验失败计数 | `fe:sms:attempts:{mobileHash}` | 与验证码 TTL 一致；默认 5 次失败后作废 |
| 账密登录失败计数 | `fe:login:fail:{accountKey}` | （可选，当前用 DB 字段） |
| 扫码登记 token | `fe:qr:{batchId}:{token}` | 与批次有效期一致 |
| 接口限流 | `fe:rl:{api}:{userId}` | 滑动窗口 |
| AI 调用配额 | `fe:ai:quota:{enterpriseId}` | 按日 |
| 幂等 | `fe:idempotent:{requestId}` | 24 h |
| 方案费率缓存 | `fe:plan:all` | 1 h |

> `mobileHash` 为手机号 SHA-256，Redis 中不存明文手机号。

建议使用 **Redisson** 实现分布式锁（草稿提交、登记幂等）。

### 7.4 核心实体关系

核心表 ER 关系见 **§7.7**；各表字段说明见 **§7.8**。

### 7.5 敏感数据处理

| 字段类型 | 存储策略 |
|----------|----------|
| 手机号、身份证、银行卡 | `*_enc` 密文 + `*_mask` 脱敏 |
| 微信 session_key、平台 API Key | 仅存后端；session_key 可放 Redis |
| 加密算法 | 手机号：AES/ECB/PKCS5Padding（确定性，支持 `mobile_enc` 等值查询）；密码：RSA 传输 + BCrypt 存储；密钥放环境变量 |

### 7.6 表清单总览

共 **35** 张业务表，统一前缀 `fe_`，引擎 InnoDB，字符集 utf8mb4。

- **全量 DDL**：`灵活用工-mysql.sql`（MySQL 5.7，一期生产）
- **设计稿**：`灵活用工.sql`（PostgreSQL 参考）
- **增量迁移**：`doc/migrations/V001`～`V006`（已有库按序执行）

| 版本 | 说明 |
|------|------|
| V001 | `fe_worker_consent.registration_id` 可空 |
| V002 | `fe_enterprise.contact_mobile_enc` |
| V003 | `fe_user`：`openid` 可空；账密字段；`uk_fe_user_username` |
| V004 | `fe_worker`：`uk_fe_worker_worker_no`、`uk_fe_worker_user_id` |
| V005 | `fe_enterprise`：`enterprise_code` 可空；`uk_fe_enterprise_credit_code` |
| V006 | `fe_user`：`uk_fe_user_mobile_enc` |

| 分组 | 表数量 | 表名 |
|------|--------|------|
| 身份与企业画像 | 5 | `fe_user`、`fe_enterprise`、`fe_enterprise_user`、`fe_enterprise_finance`、`fe_enterprise_preference` |
| 对话与智能体 | 3 | `fe_conversation`、`fe_conversation_message`、`fe_agent_action_log` |
| 方案、规则与状态机 | 5 | `fe_service_plan`、`fe_service_plan_fee_rule`、`fe_workflow_definition`、`fe_workflow_step`、`fe_policy_rule` |
| 草稿与成本 | 4 | `fe_employment_draft`、`fe_draft_field`、`fe_draft_cost_snapshot`、`fe_draft_cost_detail` |
| 订单、登记与人员 | 7 | `fe_employment_order`、`fe_registration_batch`、`fe_order_workflow_log`、`fe_worker`、`fe_worker_registration`、`fe_worker_consent`、`fe_contract` |
| 结算与支付 | 4 | `fe_settlement_order`、`fe_settlement_item`、`fe_settlement_fee`、`fe_payment_record` |
| 考勤（二期预留） | 2 | `fe_attendance_batch`、`fe_attendance_record` |
| 审计、第三方与消息 | 5 | `fe_user_confirmation`、`fe_field_change_log`、`fe_provider`、`fe_provider_api_log`、`fe_notification` |

### 7.7 表关系（核心链路）

```mermaid
erDiagram
    fe_enterprise ||--o{ fe_enterprise_user : binds
    fe_user ||--o{ fe_enterprise_user : binds
    fe_enterprise ||--o{ fe_conversation : owns
    fe_conversation ||--o{ fe_conversation_message : contains
    fe_enterprise ||--o{ fe_employment_draft : creates
    fe_employment_draft ||--o{ fe_draft_field : has
    fe_employment_draft ||--o{ fe_draft_cost_snapshot : calculates
    fe_draft_cost_snapshot ||--o{ fe_draft_cost_detail : contains
    fe_employment_draft ||--|| fe_employment_order : confirms_to
    fe_employment_order ||--o{ fe_registration_batch : has
    fe_registration_batch ||--o{ fe_worker_registration : registers
    fe_worker ||--o{ fe_worker_registration : profile
    fe_employment_order ||--o{ fe_settlement_order : settles
    fe_settlement_order ||--o{ fe_settlement_item : items
    fe_service_plan ||--o{ fe_service_plan_fee_rule : rules
```

### 7.8 分表字段说明

> 下列字段类型取自 `灵活用工.sql`（PostgreSQL）。MySQL 5.7 映射：`BIGSERIAL→BIGINT AUTO_INCREMENT`，`TIMESTAMPTZ→DATETIME`，`JSONB→JSON`，`BOOLEAN→TINYINT(1)`，`NUMERIC→DECIMAL`。

#### 身份与企业画像

##### `fe_user`

小程序用户主表，企业主与临时工共用账号体系，通过 `user_type` 区分身份。一期支持**短信验证码、微信 code2session、可选账密**登录；是 `fe_enterprise_user`、`fe_conversation`、`fe_worker` 等表的用户外键来源。敏感手机号仅存密文与脱敏值，密码仅存 BCrypt 哈希。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。 |
| `openid` | VARCHAR(64) | 否 | 微信 openid；**纯短信登录可为空**。唯一索引 `uk_fe_user_openid (openid, del_flag)`。 |
| `unionid` | VARCHAR(64) | 否 | 微信 unionid。 |
| `user_type` | VARCHAR(20) | 是 | `enterprise` / `worker`；**首次创建时写入，不可通过后续登录修改**。 |
| `nickname` | VARCHAR(64) | 否 | 昵称。 |
| `avatar_url` | VARCHAR(512) | 否 | 头像 URL。 |
| `mobile_enc` | TEXT | 否 | 手机号 AES 密文（确定性加密）。唯一索引 `uk_fe_user_mobile_enc (mobile_enc, del_flag)`（MySQL 对 TEXT 使用前缀长度 128）。 |
| `mobile_mask` | VARCHAR(20) | 否 | 手机号脱敏，如 `138****1234`。 |
| `username` | VARCHAR(64) | 否 | 登录用户名，**首次设密时写入**。唯一索引 `uk_fe_user_username (username, del_flag)`。 |
| `password_hash` | VARCHAR(128) | 否 | BCrypt 密码哈希；NULL 表示未设密。 |
| `pwd_failed_count` | INT | 是 | 账密连续失败次数，默认 0。 |
| `pwd_locked_until` | DATETIME | 否 | 账密锁定截止时间。 |
| `password_set_at` | DATETIME | 否 | 最近设密/改密时间。 |
| `session_key` | VARCHAR(128) | 否 | 微信 session_key，每次微信登录覆盖。 |
| `status` | VARCHAR(20) | 是 | `active` / `disabled`；禁用后 JWT 请求查库拒绝。 |
| `last_login_at` | DATETIME | 否 | 最近登录时间。 |
| `create_time` | DATETIME | 是 | 创建时间。 |
| `update_time` | DATETIME | 是 | 更新时间。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除；0=正常，1=删除。 |

##### `fe_enterprise`

企业主体表，灵活用工业务归属主体，承载企业认证信息与扩展画像。与 fe_enterprise_user（多管理员）、fe_employment_draft、fe_employment_order 等为一对多关系。注册地址 registered_address 供 AI 草稿默认推断工作地点。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。 |
| `enterprise_code` | VARCHAR(32) | 否 | 业务编码，格式 `ENT{年}{id}`；**insert 时可为空**，写入正式编号后非空。唯一索引 `uk_fe_enterprise_code (enterprise_code, del_flag)`。 |
| `name` | VARCHAR(200) | 是 | 企业全称。 |
| `credit_code` | VARCHAR(32) | 否 | 统一社会信用代码。唯一索引 `uk_fe_enterprise_credit_code (credit_code, del_flag)`。 |
| `legal_person` | VARCHAR(64) | 否 | 法定代表人姓名。认证材料解析或人工填写时写入。示例：王某某。可空；用于合同与开票信息核对。 |
| `registered_address` | VARCHAR(500) | 否 | 企业注册地址。认证或企业资料维护时写入；AI 生成草稿时优先作为 work_location 默认值来源。示例：上海市浦东新区张江路 88 号。可空；影响草稿地点推断。 |
| `contact_name` | VARCHAR(64) | 否 | 联系人姓名。 |
| `contact_mobile_enc` | TEXT | 否 | 联系人手机号密文。 |
| `contact_mobile_mask` | VARCHAR(20) | 否 | 联系人手机号脱敏。 |
| `industry` | VARCHAR(100) | 否 | 所属行业分类。企业资料维护或 AI 画像推断时写入。示例：仓储物流、制造业。可空；用于方案推荐与风险诊断。 |
| `scale` | VARCHAR(50) | 否 | 企业规模描述。企业资料维护时写入。示例：50-200人、小微企业。可空；辅助成本测算与合规判断。 |
| `auth_status` | VARCHAR(20) | 是 | 企业实名认证状态。提交认证置 pending，审核通过置 verified，驳回置 rejected。枚举：pending=待审核；verified=已认证；rejected=已驳回。非空，默认 pending；未认证企业功能受限。 |
| `auth_time` | TIMESTAMPTZ | 否 | 认证审核通过时间戳。运营或系统自动审核通过时写入。可空；仅 auth_status=verified 时有值。 |
| `profile_json` | JSONB | 否 | 企业扩展画像 JSON，承载行业标签、历史偏好摘要、风险标签等。AI 画像服务或运营标注时增量更新。示例：{"tags":["仓储","旺季用工"]}。可空，默认 {}；非敏感；结构由应用层约定。 |
| `create_time` | TIMESTAMPTZ | 是 | 企业记录创建时间。INSERT 时默认 NOW()。非空；审计字段。 |
| `update_time` | TIMESTAMPTZ | 是 | 企业资料最后更新时间。任意字段变更时由应用层刷新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。企业注销或管理员删除时置 1。枚举：0=正常；1=已删除。非空，默认 0；软删后释放 enterprise_code 唯一索引。 |

##### `fe_enterprise_user`

企业与微信用户的多对多绑定关系表，支持一企业多管理员、一用户管多企业。通过 is_default 标识用户登录后默认选中的企业上下文，关联 fe_enterprise 与 fe_user。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。绑定关系创建时生成。非空。 |
| `enterprise_id` | BIGINT | 是 | 关联企业主键，外键 REFERENCES fe_enterprise(id)。管理员邀请绑定或企业创建时写入。非空；级联查询企业下所有管理员。 |
| `user_id` | BIGINT | 是 | 关联微信用户主键，外键 REFERENCES fe_user(id)。被邀请用户接受绑定或企业创建者自动绑定时写入。非空；建立索引 idx_fe_enterprise_user_uid。 |
| `role` | VARCHAR(20) | 是 | 用户在该企业下的权限角色。绑定或角色调整时由企业主/管理员写入。枚举：owner=主账号（最高权限）；admin=管理员；viewer=只读。非空，默认 owner。 |
| `is_default` | BOOLEAN | 是 | 是否为用户登录后的默认选中企业。用户切换默认企业或首次绑定时由应用层更新，同一 user_id 仅一条为 true。非空，默认 FALSE；影响 API 请求默认 enterprise_id。 |
| `bind_time` | TIMESTAMPTZ | 是 | 绑定关系建立时间。绑定成功时写入，默认 NOW()。非空；用于审计。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。INSERT 时写入。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 记录更新时间。角色或默认企业变更时刷新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。解除绑定关系时置 1，非物理删除。枚举：0=正常；1=已解除。非空，默认 0；唯一索引 uk_fe_enterprise_user(enterprise_id,user_id) 在 del_flag=0 时生效。 |

##### `fe_enterprise_finance`

企业财务与开票信息表，与企业主体一对一（enterprise_id 唯一）。存储对公账户密文、开票抬头、打款渠道等；小程序端仅展示渠道类型，不展示账户明细等敏感金融信息。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。企业首次维护财务信息时生成。非空。 |
| `enterprise_id` | BIGINT | 是 | 关联企业主键，外键 REFERENCES fe_enterprise(id)。财务信息首次录入时写入。非空；一对一，唯一索引 uk_fe_enterprise_finance。 |
| `bank_name` | VARCHAR(100) | 否 | 对公账户开户银行名称。企业主在财务设置页填写时写入。示例：中国工商银行上海张江支行。可空。 |
| `bank_account_enc` | TEXT | 否 | 对公银行账号加密密文。企业提交账户信息时由应用层加密写入。高度敏感；禁止明文入库与前端回显；可空。 |
| `bank_account_mask` | VARCHAR(32) | 否 | 对公账号脱敏展示值。与 bank_account_enc 同时生成。示例：6222****1234。可空；供运营后台列表展示。 |
| `invoice_title` | VARCHAR(200) | 否 | 增值税发票开票抬头，通常与企业全称一致。财务设置时写入。示例：上海某某物流有限公司。可空；结算开票使用。 |
| `tax_no` | VARCHAR(32) | 否 | 纳税人识别号，用于开票与税务合规。财务设置或认证同步时写入。示例：91310000MA1K3XXXXX。可空；需与统一社会信用代码核对。 |
| `payment_channel` | VARCHAR(50) | 否 | 企业偏好打款渠道类型，小程序仅展示此枚举不展示账户号。财务设置时写入。枚举：wechat=微信支付；alipay=支付宝；bank=银行转账。可空。 |
| `balance_amount` | NUMERIC(14,2) | 否 | 企业在平台虚拟账户余额（元），NUMERIC(14,2)。充值、结算扣款时由账务服务更新。示例：50000.00。可空，默认 0；非敏感。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 财务信息变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_enterprise_preference`

企业智能偏好配置表，存储工种薪资基准、默认保险档次、发薪结算周期等结构化偏好。支持用户自然语言配置后由 AI 解析入库，供草稿生成引擎复用，关联 fe_enterprise。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。偏好项创建时生成。非空。 |
| `enterprise_id` | BIGINT | 是 | 关联企业主键，外键 REFERENCES fe_enterprise(id)。偏好配置时写入。非空；索引 idx_fe_enterprise_pref(enterprise_id,pref_type)。 |
| `pref_type` | VARCHAR(50) | 是 | 偏好大类。用户或 AI 配置时写入。枚举：work_type=工种薪资基准；insurance=默认保险配置；payment_cycle=发薪/结算周期偏好。非空。 |
| `pref_key` | VARCHAR(100) | 否 | 偏好子键，细分到具体工种或场景。示例：搬运工、仓库分拣。可空；同一 pref_type 下可有多条记录。 |
| `pref_value` | JSONB | 是 | 结构化偏好值 JSON，承载薪资区间、保险方案参数等。AI 解析或用户表单提交时写入。示例：{"daily_wage":280,"currency":"CNY"}。非空，默认 {}。 |
| `source` | VARCHAR(50) | 否 | 偏好数据来源，用于前端展示可信度标签。写入时由应用层标记。枚举：user_config=用户主动配置；ai_inferred=AI 从历史订单推断；default=系统默认。可空，默认 user_config。 |
| `raw_text` | TEXT | 否 | 用户自然语言配置原文，便于审计与重新解析。用户在对话或设置页输入时保存。示例：「搬运工日薪 280，要标准意外险」。可空。 |
| `confirmed` | BOOLEAN | 是 | 用户是否已明确确认该偏好项。用户点击确认后置 TRUE，未确认前草稿生成可提示复核。非空，默认 FALSE。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 偏好值变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

#### 对话与智能体

##### `fe_conversation`

AI 对话会话主表，企业主与智能体交互的容器。通过 chat_type 区分用工、知识库、订单、成本等专题对话；一对多关联 fe_conversation_message。enterprise_id 与 user_id 共同界定会话归属与权限。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。用户发起新对话时生成。非空；被消息表、草稿表外键引用。 |
| `conversation_no` | VARCHAR(32) | 是 | 会话对外业务编号，API 路径与日志中使用。创建会话时由编号生成器写入。示例：conv_001。非空；唯一索引 uk_fe_conversation_no。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。创建会话时从当前登录上下文写入。非空；索引 idx_fe_conversation_ent 用于侧边栏按企业筛选。 |
| `user_id` | BIGINT | 是 | 发起对话的企业主用户，外键 REFERENCES fe_user(id)。创建会话时写入。非空；须为 enterprise 类型用户。 |
| `title` | VARCHAR(200) | 否 | 会话标题，侧边栏展示用。可由首条用户消息摘要或 AI 自动生成，用户可重命名。示例：浦东仓库暑期用工。可空。 |
| `chat_type` | VARCHAR(30) | 是 | 对话专题类型，决定加载的子智能体与卡片模板。创建时根据入口或首条意图写入。枚举：employment=用工办理；knowledge=政策知识库；order=订单查询；cost=成本测算；attendance=考勤；emergency=... |
| `status` | VARCHAR(20) | 是 | 会话生命周期状态。用户归档或长期无消息时更新。枚举：active=进行中；archived=已归档（只读）。非空，默认 active。 |
| `last_message_at` | TIMESTAMPTZ | 否 | 最后一条消息时间，用于侧边栏按时间排序。每次 INSERT fe_conversation_message 后由应用层刷新。可空；索引排序字段。 |
| `create_time` | TIMESTAMPTZ | 是 | 会话创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 会话元数据变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_conversation_message`

对话消息明细表，存储用户与助手往返的文本及结构化卡片（草稿卡、成本卡、订单卡）。通过 next_action 驱动小程序路由跳转；关联 fe_conversation，可软链 fe_employment_draft。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。每条消息入库时生成。非空。 |
| `conversation_id` | BIGINT | 是 | 所属会话，外键 REFERENCES fe_conversation(id)。发送消息时写入。非空；索引 idx_fe_conv_msg(conversation_id,create_time)。 |
| `role` | VARCHAR(20) | 是 | 消息发送方角色。写入时由网关标记。枚举：user=企业主用户；assistant=AI 助手；system=系统提示（如流程引导）。非空。 |
| `content` | TEXT | 是 | 消息正文文本或卡片摘要说明，供聊天气泡展示。用户输入或 AI 生成时写入。非空；长文本需注意截断策略。 |
| `content_type` | VARCHAR(30) | 是 | 消息内容形态，决定前端渲染组件。写入时标记。枚举：text=纯文本；card_draft=用工草稿卡；card_cost=成本对比卡；card_order=订单进度卡。非空，默认 text。 |
| `card_payload` | JSONB | 否 | 卡片结构化数据 JSON，如草稿字段列表、成本行、订单摘要。AI 子模块返回卡片时写入。示例：{"draft_id":101,"fields":[...]}。可空；仅 content_type 为卡片类型时有值。 |
| `agent_module` | VARCHAR(50) | 否 | 处理该消息的子智能体模块名，用于排障与统计。路由层写入。示例：flexible_employment、cost_engine。可空。 |
| `next_action` | VARCHAR(50) | 否 | 建议前端执行的下一步动作编码，用于自动跳转或弹窗。助手回复卡片时写入。示例：show_employment_draft、open_cost_comparison。可空。 |
| `related_draft_id` | BIGINT | 否 | 关联的用工草稿 ID，软引用 fe_employment_draft(id)。生成或引用草稿卡时写入。可空；无外键约束，由应用层保证一致性。 |
| `token_usage` | JSONB | 否 | 大模型 token 消耗统计 JSON，含 prompt/completion 分项。AI 调用完成后写入，供成本核算。示例：{"prompt":1200,"completion":800}。可空；不展示给用户。 |
| `create_time` | TIMESTAMPTZ | 是 | 消息发送/入库时间，聊天气泡排序依据。非空，默认 NOW()。 |

##### `fe_agent_action_log`

智能体与子模块调用审计日志表，记录主智能体、灵活用工模块、成本引擎等的入参出参与耗时。用于技术排障与合规审计，不对小程序用户直接展示；可关联 fe_conversation。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。每次子模块调用时生成。非空。 |
| `conversation_id` | BIGINT | 否 | 关联会话，外键 REFERENCES fe_conversation(id)。对话内调用时写入；后台定时任务触发时可为空。可空。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。调用上下文中的企业 ID，必填以便按企业排障。非空；索引 idx_fe_agent_log。 |
| `module_name` | VARCHAR(50) | 是 | 被调用的模块名称。调用发起时写入。枚举示例：main_agent=主路由；flexible_employment=用工子模块；cost_engine=成本测算引擎。非空。 |
| `action` | VARCHAR(100) | 是 | 模块内具体动作编码。示例：generate_draft、calc_cost、parse_nl_preference。非空；与 module_name 组合定位代码路径。 |
| `request_json` | JSONB | 否 | 请求体 JSON 快照，含用户输入与上下文参数。调用前由中间件序列化写入。可空；可能含业务敏感字段，访问需授权。 |
| `response_json` | JSONB | 否 | 响应体 JSON 快照，含 AI 结构化输出。调用成功后写入。可空；失败时可能为空或部分写入。 |
| `status` | VARCHAR(20) | 是 | 调用结果状态。调用结束时写入。枚举：success=成功；failed=失败。非空，默认 success。 |
| `error_message` | TEXT | 否 | 失败时的错误堆栈或业务错误码说明。仅 status=failed 时写入。可空；供研发排障。 |
| `duration_ms` | INTEGER | 否 | 调用耗时（毫秒）。调用结束时计算写入。示例：2350。可空；用于性能监控。 |
| `create_time` | TIMESTAMPTZ | 是 | 调用发生时间。非空；按时间倒序查最近异常。 |

#### 方案、规则与状态机

##### `fe_service_plan`

用工方案目录表，成本对比页「当前方式 + 方案一二三」的配置数据源。正式环境费率以此表为准；test_only 状态方案仅供 Demo。一对多关联 fe_service_plan_fee_rule，被草稿与订单 selected_plan_id 引用。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。运营配置或初始化脚本插入时生成。非空。 |
| `plan_code` | VARCHAR(32) | 是 | 方案业务编码，全局唯一（软删条件下）。初始化或运营录入时写入。枚举：current=企业现有处理方式；plan_1/plan_2/plan_3=对比方案。示例：plan_1。非空；唯一索引 uk_fe_service_plan_code。 |
| `plan_name` | VARCHAR(100) | 是 | 前端展示名称。运营配置时写入。示例：合规优先 (A)、传统用工 (B)。非空。 |
| `plan_type` | VARCHAR(30) | 是 | 方案用工模式大类。配置时写入。枚举：flexible=灵活用工；traditional=传统用工；hybrid=混合模式。非空，默认 flexible。 |
| `description` | TEXT | 否 | 方案详细说明文案，成本对比页展开区展示。运营维护时写入。可空。 |
| `service_fee_rate` | NUMERIC(8,4) | 否 | 平台服务费率，NUMERIC(8,4)。示例：0.08 表示 8%。运营配置或费率调整时写入。可空；current 方案可为 NULL 表示按企业现状估算。 |
| `insurance_level` | VARCHAR(30) | 否 | 方案默认保险档次。枚举：basic=基础；standard=标准；premium=高级。可空；影响保险费用项测算。 |
| `tax_mode` | VARCHAR(50) | 否 | 税费代征模式编码，与地方税筹政策对应。运营配置时写入。示例：withhold_standard。可空。 |
| `applicable_scenarios` | JSONB | 否 | 适用场景 JSON 数组，供 AI 推荐方案时匹配。示例：["旺季临时工","仓储搬运"]。可空，默认 []。 |
| `compliance_tags` | JSONB | 否 | 合规能力标签 JSON 数组，前端展示勾选图标。示例：["业务真实","资金合规","个税申报"]。可空，默认 []。 |
| `sort_order` | INTEGER | 是 | 前端展示排序权重，越小越靠前。运营配置时写入。非空，默认 0。 |
| `status` | VARCHAR(20) | 是 | 方案生效状态。枚举：active=正式可用；test_only=测试演示默认；disabled=停用。非空，默认 active；生产环境应仅 active 参与正式测算。 |
| `effective_from` | DATE | 否 | 方案生效开始日期。费率版本管理时写入。可空。 |
| `effective_to` | DATE | 否 | 方案生效结束日期，到期后自动不参与测算。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 方案配置变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_service_plan_fee_rule`

方案费用项计算规则表，定义劳务费、服务费、保险、税费代征等分项的计算方式（固定额/比例/公式）。成本测算引擎读取本表与 fe_service_plan 联合计算；一对多归属 plan_id。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。运营为方案配置费用项时生成。非空。 |
| `plan_id` | BIGINT | 是 | 关联方案，外键 REFERENCES fe_service_plan(id)。配置费用规则时写入。非空；索引 idx_fe_plan_fee。 |
| `fee_code` | VARCHAR(50) | 是 | 费用项编码。枚举：labor_fee=劳务费；service_fee=平台服务费；insurance=保险费；tax_withhold=税费代征。非空。 |
| `fee_name` | VARCHAR(100) | 是 | 费用项中文展示名。示例：劳务费、服务费。非空。 |
| `calc_type` | VARCHAR(30) | 是 | 计算方式类型。枚举：fixed=固定金额；rate=按基数比例；formula=自定义公式（由 calc_expression 描述）。非空。 |
| `calc_expression` | TEXT | 否 | 计算公式或规则描述文本，供引擎解析或人工审计。运营配置时写入。示例：gross * service_fee_rate。可空；calc_type=formula 时建议必填。 |
| `default_rate` | NUMERIC(8,4) | 否 | 默认费率或系数，NUMERIC(8,4)。rate 类型费用项使用。示例：0.08。可空。 |
| `sort_order` | INTEGER | 是 | 成本明细展示顺序。非空，默认 0。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 规则变更时更新。非空。 |

##### `fe_workflow_definition`

合规流程定义表，描述「五流合一」整体状态机的版本化元数据。支持多版本并存，is_active 标识当前启用版本；一对多关联 fe_workflow_step 定义各步骤。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。初始化脚本或运营发布新版本时生成。非空。 |
| `workflow_code` | VARCHAR(50) | 是 | 流程业务编码，同一编码可有多个 version。示例：employment_compliance。非空；与 version 组成唯一索引 uk_fe_workflow_def。 |
| `workflow_name` | VARCHAR(100) | 是 | 流程中文名称。示例：用工合规办理流程。非空。 |
| `description` | TEXT | 否 | 流程整体说明，描述五流合一覆盖范围。可空。 |
| `version` | INTEGER | 是 | 流程版本号，递增整数。发布新流程时在上版基础上 +1。非空，默认 1；历史订单可能引用旧版步骤定义。 |
| `is_active` | BOOLEAN | 是 | 是否当前系统启用的流程版本。发布新版时旧版置 FALSE，新版置 TRUE。非空，默认 TRUE；同时仅应有一个 is_active=TRUE 的同 workflow_code。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 流程元数据变更时更新。非空。 |

##### `fe_workflow_step`

合规流程步骤定义表，订单 fe_employment_order.current_step_code 对应本表 step_code。强制校验实名、合同、结算、完税、开票等必经节点完整性；归属 fe_workflow_definition。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。流程版本初始化时批量插入。非空。 |
| `workflow_id` | BIGINT | 是 | 关联流程定义，外键 REFERENCES fe_workflow_definition(id)。步骤归属的流程版本。非空。 |
| `step_code` | VARCHAR(50) | 是 | 步骤唯一编码，订单 current_step_code 引用此值。枚举（九步）：draft_created=草稿创建；plan_confirmed=方案确认；registration=扫码登记；enterprise_audit=企业审... |
| `step_name` | VARCHAR(100) | 是 | 步骤中文展示名。示例：扫码登记、合同签署。非空。 |
| `step_order` | INTEGER | 是 | 步骤顺序号，从小到大推进。初始化时写入 1-9。非空。 |
| `required` | BOOLEAN | 是 | 是否必经步骤，FALSE 时可跳过（扩展流程用）。非空，默认 TRUE；MVP 九步均为必经。 |
| `auto_advance` | BOOLEAN | 是 | 满足系统条件后是否自动推进到下一步，无需人工点击。非空，默认 FALSE；如登记人数达标可自动推进。 |
| `create_time` | TIMESTAMPTZ | 是 | 步骤定义创建时间。非空。 |

##### `fe_policy_rule`

政策法规规则库表，供规则引擎与 RAG 知识库引用，支撑用工风险诊断、合规提示与智能问答。按 rule_category 分类，支持生效期与优先级排序。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。运营或法务录入规则时生成。非空。 |
| `rule_code` | VARCHAR(50) | 是 | 规则唯一业务编码。示例：TAX_WITHHOLD_001。非空；唯一索引 uk_fe_policy_rule。 |
| `rule_category` | VARCHAR(50) | 是 | 规则分类。枚举：tax=税务；labor=劳动用工；insurance=保险；invoice=发票开票。非空；用于检索过滤。 |
| `title` | VARCHAR(200) | 是 | 规则标题，知识库与对话引用时展示。非空。 |
| `content` | TEXT | 是 | 规则正文全文，可含法规条文摘要。非空；可能较长，注意全文检索索引。 |
| `effective_from` | DATE | 否 | 规则生效开始日期。可空；为空表示无开始限制。 |
| `effective_to` | DATE | 否 | 规则生效结束日期，过期规则不参与实时诊断。可空。 |
| `priority` | INTEGER | 是 | 匹配优先级，数值越大越优先。冲突时取高优先级规则。非空，默认 0。 |
| `status` | VARCHAR(20) | 是 | 规则启用状态。枚举：active=启用；disabled=停用。非空，默认 active。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 规则内容变更时更新。非空。 |

#### 草稿与成本

##### `fe_employment_draft`

用工草稿主表，体现「草稿优先」产品原则：AI 根据对话生成，用户确认前均为草稿状态。确认并选定方案后生成 fe_employment_order 与 fe_registration_batch；关联 fe_enterprise、fe_conversation、fe_service_plan。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。AI 子模块生成草稿时创建。非空；被 fe_draft_field、fe_draft_cost_snapshot 引用。 |
| `draft_no` | VARCHAR(32) | 是 | 草稿业务编号，对外 API 使用。生成时由编号器写入。示例：draft_001。非空；唯一索引 uk_fe_draft_no。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。从对话上下文写入。非空；索引 idx_fe_draft_ent。 |
| `conversation_id` | BIGINT | 否 | 来源 AI 对话，外键 REFERENCES fe_conversation(id)。对话触发生成时写入；后台批量生成可为空。可空。 |
| `scenario` | VARCHAR(50) | 是 | 用工业务场景类型。AI 识别用户意图时写入。枚举：existing_worker_regularization=已有非正规临时工规范转正；new_demand=全新用工需求。非空。 |
| `title` | VARCHAR(200) | 否 | 草稿标题，列表与卡片展示。AI 摘要或用户输入。示例：浦东仓库暑期搬运。可空。 |
| `status` | VARCHAR(20) | 是 | 草稿生命周期状态。枚举：pending=待用户确认；confirmed=已确认并转订单；cancelled=用户取消；expired=超时未确认自动过期。非空，默认 pending。 |
| `worker_count` | INTEGER | 否 | 计划用工人数。AI 提取或用户填写。示例：15。可空；确认前可为空触发 missing_fields 提示。 |
| `work_days` | INTEGER | 否 | 计划工作天数。示例：30。可空。 |
| `work_type` | VARCHAR(100) | 否 | 岗位/工种类型。示例：搬运工、分拣员。可空；影响薪资与保险测算。 |
| `work_content` | TEXT | 否 | 主要工作内容文字描述。AI 从对话归纳或用户补充。可空。 |
| `work_location` | VARCHAR(500) | 否 | 实际工作地点。可来自企业注册地址或用户指定。示例：上海市浦东新区XX路88号仓库。可空。 |
| `work_location_source` | VARCHAR(50) | 否 | 工作地点字段来源，前端可展示来源标签。枚举：enterprise_registered_address=取自 fe_enterprise.registered_address；user_input=用户明确输入；ai_inferred... |
| `settlement_mode` | VARCHAR(50) | 否 | 薪资结算方式。枚举：daily=日结；piece=计件；monthly=月结。可空；影响成本引擎计费基数。 |
| `daily_wage` | NUMERIC(12,2) | 否 | 日薪标准（元），NUMERIC(12,2)。示例：280.00。可空；piece/monthly 模式下可能为空。 |
| `insurance_required` | BOOLEAN | 是 | 是否强制购买商业保险。AI 默认或用户勾选。非空，默认 TRUE。 |
| `insurance_level` | VARCHAR(30) | 否 | 保险档次。枚举：basic/standard/premium。可空；与 fe_service_plan.insurance_level 对齐。 |
| `check_in_required` | BOOLEAN | 是 | 是否要求打卡考勤（二期功能预留）。非空，默认 FALSE。 |
| `qr_valid_days` | INTEGER | 否 | 登记二维码有效天数，确认后生成批次时使用。非空，默认 7。 |
| `work_start_date` | DATE | 否 | 计划开工日期，DATE 类型。示例：2026-08-01。可空。 |
| `work_end_date` | DATE | 否 | 计划结束日期。可空；应不早于 work_start_date。 |
| `job_requirements` | TEXT | 否 | 岗位要求（年龄、经验、证件等）自由文本。可空。 |
| `missing_fields` | JSONB | 否 | 待用户补充的字段名 JSON 数组。AI 检测信息不足时写入。示例：["work_location","daily_wage"]。可空，默认 []。 |
| `risk_prompts` | JSONB | 否 | 风险提示 JSON 数组，合规引擎输出。示例：["未签劳动合同存在用工风险"]。可空，默认 []。 |
| `estimated_total` | NUMERIC(14,2) | 否 | 预估企业总支出（元）。成本引擎测算后回写。可空。 |
| `estimated_per_capita` | NUMERIC(12,2) | 否 | 预估人均成本（元）。成本引擎测算后回写。可空。 |
| `selected_plan_id` | BIGINT | 否 | 用户选中的用工方案，外键 REFERENCES fe_service_plan(id)。用户在成本对比页确认方案时写入；确认草稿时必填。可空（待确认阶段）。 |
| `confirmed_at` | TIMESTAMPTZ | 否 | 用户点击确认草稿的时间戳。确认接口成功时写入。可空。 |
| `confirmed_by` | BIGINT | 否 | 确认操作用户，外键 REFERENCES fe_user(id)。确认接口写入。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 草稿创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 草稿字段或状态变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_draft_field`

草稿字段明细细表，逐字段记录值、数据来源与可编辑性，支撑前端「默认生成」角标（is_default=true）与字段级审计。一对多归属 fe_employment_draft。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。草稿生成或字段补全时插入。非空。 |
| `draft_id` | BIGINT | 是 | 关联草稿，外键 REFERENCES fe_employment_draft(id)。非空；与 field_key 组成唯一索引 uk_fe_draft_field。 |
| `field_key` | VARCHAR(100) | 是 | 字段键名，与草稿主表列名或扩展字段对应。示例：work_location、daily_wage。非空。 |
| `field_label` | VARCHAR(100) | 否 | 字段中文标签，表单展示用。示例：工作地点、日薪标准。可空。 |
| `field_value` | TEXT | 否 | 简单文本类型字段值。用户输入或 AI 填充时写入。可空；复杂结构用 value_json。 |
| `value_json` | JSONB | 否 | 复杂类型字段 JSON 值，如多选、地址对象。可空。 |
| `source` | VARCHAR(50) | 是 | 字段值来源，前端展示可信度。枚举：enterprise_profile=企业画像；history_preference=历史偏好；default=系统默认；user_input=用户输入；ai_inferred=AI 推断。非空，默认... |
| `editable` | BOOLEAN | 是 | 用户是否可在草稿编辑页修改该字段。非空，默认 TRUE；系统锁定字段置 FALSE。 |
| `is_default` | BOOLEAN | 是 | 是否 AI/系统默认生成未经用户修改，前端展示「默认」角标。非空，默认 FALSE。 |
| `create_time` | TIMESTAMPTZ | 是 | 字段记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 字段值变更时更新。非空。 |

##### `fe_draft_cost_snapshot`

草稿成本对比快照表，一次测算为同一草稿生成多行（current + plan_1/2/3）。核心指标：企业总支出、人均成本、员工到手；一对多关联 fe_draft_cost_detail。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。成本引擎每次全量测算时批量插入。非空。 |
| `draft_id` | BIGINT | 是 | 关联草稿，外键 REFERENCES fe_employment_draft(id)。非空；索引 idx_fe_cost_snapshot。 |
| `plan_id` | BIGINT | 否 | 关联方案目录，外键 REFERENCES fe_service_plan(id)。current 行可能为空（表示非平台方案）。可空。 |
| `plan_code` | VARCHAR(32) | 是 | 方案编码快照，防止方案后续改名影响历史展示。示例：plan_1。非空。 |
| `plan_name` | VARCHAR(100) | 是 | 方案名称快照。示例：合规优先 (A)。非空。 |
| `employer_total_outflow` | NUMERIC(14,2) | 是 | 企业总支出（元），含劳务+服务费+保险+税费等。成本引擎计算写入。非空。 |
| `employer_avg_cost_per_worker` | NUMERIC(12,2) | 是 | 企业平均每人成本（元）。非空。 |
| `worker_take_home_per_worker` | NUMERIC(12,2) | 否 | 员工每人预计到手（元），税后实发估算。可空。 |
| `is_recommended` | BOOLEAN | 是 | 是否 AI/规则推荐的优选方案，前端高亮展示。非空，默认 FALSE。 |
| `status_tag` | VARCHAR(30) | 否 | 快照数据性质标签。示例：test_only 表示使用测试费率，需向用户提示。可空。 |
| `compliance_tags` | JSONB | 否 | 合规标签 JSON 快照，与方案一致。可空，默认 []。 |
| `notice` | TEXT | 否 | 展示给用户的补充说明文案，如费率仅供参考。可空。 |
| `calc_version` | VARCHAR(20) | 否 | 测算引擎版本号，便于回放与排障。示例：v1.2.0。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 快照生成时间，同一 draft_id 下多条记录时间相近。非空。 |

##### `fe_draft_cost_detail`

成本对比费用明细细表，对应快照下劳务费、服务费、保险、税费代征等分项金额与费率。归属 fe_draft_cost_snapshot，供前端展开明细列表。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。生成快照时同步插入各费用项。非空。 |
| `snapshot_id` | BIGINT | 是 | 关联成本快照，外键 REFERENCES fe_draft_cost_snapshot(id)。非空；索引 idx_fe_cost_detail。 |
| `fee_code` | VARCHAR(50) | 是 | 费用项编码，与 fe_service_plan_fee_rule.fee_code 对齐。示例：labor_fee、service_fee。非空。 |
| `fee_name` | VARCHAR(100) | 是 | 费用项中文名。示例：劳务费、平台服务费。非空。 |
| `amount` | NUMERIC(14,2) | 是 | 该费用项金额（元），NUMERIC(14,2)。非空。 |
| `rate` | NUMERIC(8,4) | 否 | 适用费率或系数，NUMERIC(8,4)。可空；固定额费用项无费率。 |
| `sort_order` | INTEGER | 是 | 明细列表展示顺序。非空，默认 0。 |

#### 订单、登记与人员

##### `fe_employment_order`

用工订单主表，草稿确认并选定方案后生成，承载办理全流程业务状态与登记进度冗余统计。current_step_code 驱动合规状态机；关联 fe_enterprise、fe_employment_draft、fe_service_plan，一对多关联登记批次与结算单。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。草稿确认接口成功时创建。非空。 |
| `order_no` | VARCHAR(32) | 是 | 订单业务编号，企业主可见。示例：2024-001、ORD20260707001。非空；唯一索引 uk_fe_order_no。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。非空；索引 idx_fe_order_ent。 |
| `draft_id` | BIGINT | 否 | 来源草稿，外键 REFERENCES fe_employment_draft(id)。确认时写入，追溯对话与方案选择。可空（极少数后台直创订单）。 |
| `selected_plan_id` | BIGINT | 否 | 确认选用的用工方案，外键 REFERENCES fe_service_plan(id)。草稿确认时从 draft.selected_plan_id 复制。可空；应尽早补齐。 |
| `title` | VARCHAR(200) | 是 | 订单标题，通常继承草稿标题。非空。 |
| `worker_count` | INTEGER | 是 | 计划用工人数。非空；与登记批次 expected_count 对齐。 |
| `work_days` | INTEGER | 否 | 工作天数。可空。 |
| `work_type` | VARCHAR(100) | 否 | 岗位类型。可空。 |
| `work_location` | VARCHAR(500) | 否 | 工作地点。可空。 |
| `work_start_date` | DATE | 否 | 开工日期。可空。 |
| `work_end_date` | DATE | 否 | 结束日期。可空。 |
| `order_status` | VARCHAR(30) | 是 | 订单业务状态，与合规步骤联动但可更细粒度。示例：confirmed、in_progress、settling、completed。非空，默认 confirmed。 |
| `current_step_code` | VARCHAR(50) | 是 | 当前合规流程步骤编码，对应 fe_workflow_step.step_code。状态机推进时更新。非空，默认 plan_confirmed。 |
| `registered_count` | INTEGER | 是 | 已登记人数冗余统计，登记完成时由应用层累加。非空，默认 0；与 fe_worker_registration 定期校准。 |
| `pending_count` | INTEGER | 是 | 待登记人数冗余统计。非空，默认 0。 |
| `abnormal_count` | INTEGER | 是 | 资料异常/核验失败人数。非空，默认 0。 |
| `total_outflow` | NUMERIC(14,2) | 否 | 预计或实际企业总支出（元）。结算完成后更新为实际值。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 订单创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 订单状态或统计变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_registration_batch`

临时工扫码登记批次表，草稿确认方案后生成，含 H5/小程序登记链接、二维码图片与有效期。企业主在进度页查看登记统计；一对多关联 fe_worker_registration。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。订单进入登记步骤时由后端创建。非空。 |
| `batch_no` | VARCHAR(32) | 是 | 登记批次业务编号。示例：BATCH-001。非空；唯一索引 uk_fe_batch_no。 |
| `order_id` | BIGINT | 是 | 关联用工订单，外键 REFERENCES fe_employment_order(id)。非空；索引 idx_fe_batch_order。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。冗余便于按企业查批次。非空。 |
| `expected_count` | INTEGER | 是 | 本批次预期登记人数，通常等于订单 worker_count。非空。 |
| `registered_count` | INTEGER | 是 | 已登记总数（含进行中），冗余统计。非空，默认 0。 |
| `pending_count` | INTEGER | 是 | 尚未开始登记人数。非空，默认 0。 |
| `in_progress_count` | INTEGER | 是 | 登记进行中人数（已打开页面未提交）。非空，默认 0。 |
| `completed_count` | INTEGER | 是 | 登记已完成人数。非空，默认 0。 |
| `abnormal_count` | INTEGER | 是 | 登记异常人数（核验失败等）。非空，默认 0。 |
| `registration_url` | VARCHAR(512) | 否 | 临时工登记页链接（H5 或小程序 path）。批次创建时由链接服务生成。可空；需配合 qr_token 校验。 |
| `qr_code_url` | VARCHAR(512) | 否 | 登记二维码图片 CDN URL。批次创建时生成。可空。 |
| `qr_token` | VARCHAR(64) | 否 | 扫码登记安全 token，校验链接有效性与防篡改。创建时随机生成。可空；非空时唯一索引 uk_fe_batch_token。 |
| `valid_from` | TIMESTAMPTZ | 是 | 二维码/链接生效时间。非空，默认 NOW()。 |
| `valid_until` | TIMESTAMPTZ | 是 | 失效时间，过期后拒绝新登记（已登记记录保留）。创建时按 draft.qr_valid_days 计算。非空。 |
| `status` | VARCHAR(20) | 是 | 批次状态。枚举：active=有效可登记；expired=已过期；closed=企业主手动关闭。非空，默认 active。 |
| `create_time` | TIMESTAMPTZ | 是 | 批次创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 统计或状态变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_order_workflow_log`

订单合规流程状态变更日志表，记录状态机每一步推进的前后步骤、操作人与备注，构成五流合一合规证据链。关联 fe_employment_order，operator_id 可引用 fe_user。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。每次步骤推进时追加写入，不可修改。非空。 |
| `order_id` | BIGINT | 是 | 关联订单，外键 REFERENCES fe_employment_order(id)。非空；索引 idx_fe_order_wf_log。 |
| `from_step` | VARCHAR(50) | 否 | 变更前合规步骤编码。首次创建订单时可为空。可空。 |
| `to_step` | VARCHAR(50) | 是 | 变更后合规步骤编码，对应 fe_workflow_step.step_code。非空。 |
| `from_status` | VARCHAR(30) | 否 | 变更前订单业务状态 order_status。可空。 |
| `to_status` | VARCHAR(30) | 是 | 变更后订单业务状态。非空。 |
| `operator_id` | BIGINT | 否 | 操作人用户 ID，外键 REFERENCES fe_user(id)。系统自动推进时为 NULL。可空。 |
| `operator_type` | VARCHAR(20) | 是 | 操作方类型。枚举：system=系统自动；enterprise=企业主/管理员；worker=临时工；provider=第三方合作平台。非空，默认 system。 |
| `remark` | TEXT | 否 | 变更说明，如「登记人数已达预期，自动推进」。可空。 |
| `extra_json` | JSONB | 否 | 扩展上下文 JSON，如触发条件、关联合格人数。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 变更发生时间，审计时间轴依据。非空。 |

##### `fe_worker`

临时工自然人档案主表，跨登记批次复用，避免重复录入身份证与银行卡。身份证、银行卡、手机号均加密存储（*_enc），列表仅展示脱敏值（*_mask）；可关联 fe_user 实现微信绑定。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。首次登记提交且实名核验通过后创建或匹配已有档案。非空。 |
| `user_id` | BIGINT | 否 | 关联 `fe_user.id`。唯一索引 `uk_fe_worker_user_id (user_id, del_flag)`（同一用户仅一条有效档案）。 |
| `worker_no` | VARCHAR(32) | 否 | 业务编号，格式 `WK{年}{id}`；insert 后 update 写入。唯一索引 `uk_fe_worker_worker_no (worker_no, del_flag)`。 |
| `real_name` | VARCHAR(64) | 是 | 临时工真实姓名，与身份证一致。登记提交时写入。非空。 |
| `id_card_no_enc` | TEXT | 是 | 身份证号加密密文。登记页提交时应用层加密写入。非空；高度敏感，禁止明文。 |
| `id_card_no_mask` | VARCHAR(32) | 否 | 身份证号脱敏展示。示例：310***********1234。可空；列表与结算明细使用。 |
| `mobile_enc` | TEXT | 是 | 手机号加密密文。登记时写入。非空；高度敏感。 |
| `mobile_mask` | VARCHAR(20) | 否 | 手机号脱敏。示例：138****1234。可空。 |
| `bank_account_enc` | TEXT | 否 | 银行卡号加密密文，用于打款。登记时写入。可空；高度敏感。 |
| `bank_account_mask` | VARCHAR(32) | 否 | 银行卡号脱敏。示例：6222****5678。可空。 |
| `bank_name` | VARCHAR(100) | 否 | 开户银行名称。示例：中国工商银行。可空。 |
| `bank_branch` | VARCHAR(200) | 否 | 开户支行名称。可空。 |
| `verify_status` | VARCHAR(20) | 是 | 实名/人脸核验状态。枚举：pending=待核验；passed=通过；failed=失败。非空，默认 pending；failed 时登记流程阻断。 |
| `verify_message` | TEXT | 否 | 核验失败原因说明，展示给临时工重试。示例：光线不足导致人脸比对失败。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 档案创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 档案信息或核验状态变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_worker_registration`

批次登记记录表，记录每个临时工在某一 fe_registration_batch 下的一次登记全过程。reg_status 驱动进度页统计、催办与审核；关联 fe_worker 档案，敏感证件信息加密存储。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。临时工打开登记页或提交时创建。非空。 |
| `batch_id` | BIGINT | 是 | 所属登记批次，外键 REFERENCES fe_registration_batch(id)。非空；索引 idx_fe_worker_reg_batch。 |
| `order_id` | BIGINT | 是 | 关联订单，外键 REFERENCES fe_employment_order(id)。冗余便于按订单查登记列表。非空；索引 idx_fe_worker_reg_order。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。冗余。非空。 |
| `worker_id` | BIGINT | 否 | 关联临时工档案，外键 REFERENCES fe_worker(id)。提交成功且匹配/创建档案后绑定。可空（登记进行中）。 |
| `real_name` | VARCHAR(64) | 是 | 本次登记填写的姓名。非空；可能与 worker 档案后续同步。 |
| `mobile_enc` | TEXT | 否 | 登记手机号密文。提交时加密写入。可空；高度敏感。 |
| `mobile_mask` | VARCHAR(20) | 否 | 登记手机号脱敏。可空。 |
| `id_card_no_enc` | TEXT | 否 | 登记身份证密文。可空；高度敏感。 |
| `bank_account_enc` | TEXT | 否 | 登记银行卡密文。可空；高度敏感。 |
| `confirmed_work_type` | VARCHAR(100) | 否 | 临时工确认的工种或具体任务描述。提交时勾选或填写。可空。 |
| `reg_status` | VARCHAR(20) | 是 | 登记流程状态。枚举：pending=待登记（占位）；registering=填写中；completed=已完成；verify_failed=实名核验失败；under_review=待企业审核。非空，默认 pending。 |
| `fail_reason` | TEXT | 否 | 失败或企业驳回原因。可空。 |
| `submitted_at` | TIMESTAMPTZ | 否 | 临时工点击提交时间。可空。 |
| `reviewed_at` | TIMESTAMPTZ | 否 | 企业审核完成时间。可空。 |
| `reviewed_by` | BIGINT | 否 | 审核人，外键 REFERENCES fe_user(id)。可空。 |
| `remind_count` | INTEGER | 是 | 企业主催办次数，每次催办 +1。非空，默认 0。 |
| `last_remind_at` | TIMESTAMPTZ | 否 | 最近一次催办时间。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 登记记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 状态或资料变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_worker_consent`

临时工协议授权确认表，记录勾选电子劳动合同、隐私政策、信息授权等合规留痕。含同意时间、客户端 IP 与 UA，满足电子证据要求；关联 fe_worker_registration。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。临时工勾选协议并提交时插入。非空。 |
| `registration_id` | BIGINT | 是 | 关联登记记录，外键 REFERENCES fe_worker_registration(id)。非空；索引 idx_fe_worker_consent。 |
| `worker_id` | BIGINT | 否 | 关联临时工档案，外键 REFERENCES fe_worker(id)。档案绑定后写入。可空。 |
| `consent_type` | VARCHAR(50) | 是 | 协议类型。枚举：labor_contract=电子劳动合同；privacy_policy=隐私政策；authorization=个人信息处理授权。非空。 |
| `consent_version` | VARCHAR(20) | 否 | 协议版本号，对应法务发布的协议版本。示例：v2.1。可空。 |
| `consent_title` | VARCHAR(200) | 否 | 协议标题展示文案。示例：《灵活用工电子劳动合同》。可空。 |
| `agreed` | BOOLEAN | 是 | 是否勾选同意。非空，默认 FALSE；提交时须为 TRUE 否则阻断。 |
| `agreed_at` | TIMESTAMPTZ | 否 | 用户点击同意的时间戳。可空；提交成功时必填。 |
| `client_ip` | VARCHAR(64) | 否 | 客户端 IP 地址，合规取证。网关层提取写入。可空。 |
| `user_agent` | VARCHAR(500) | 否 | 客户端 User-Agent 字符串。可空；最长 500 字符。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录入库时间。非空。 |

##### `fe_contract`

电子劳动合同表，合规流程「合同签署」节点核心数据。一人一登记一条合同；MVP 阶段 sign_provider 可用 mock，对接电子签平台后替换。关联 fe_employment_order、fe_worker_registration、fe_worker。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。登记完成进入合同签署步骤时创建。非空。 |
| `contract_no` | VARCHAR(32) | 是 | 合同业务编号。示例：CT20260707001。非空；唯一索引 uk_fe_contract_no。 |
| `order_id` | BIGINT | 是 | 关联订单，外键 REFERENCES fe_employment_order(id)。非空；索引 idx_fe_contract_order。 |
| `registration_id` | BIGINT | 否 | 关联登记记录（一人一合同），外键 REFERENCES fe_worker_registration(id)。可空；建议必填。 |
| `worker_id` | BIGINT | 否 | 签约临时工，外键 REFERENCES fe_worker(id)。可空。 |
| `enterprise_id` | BIGINT | 是 | 签约企业，外键 REFERENCES fe_enterprise(id)。非空。 |
| `contract_type` | VARCHAR(50) | 是 | 合同类型编码。非空，默认 labor（劳动合同）。 |
| `contract_title` | VARCHAR(200) | 否 | 合同标题。示例：劳务派遣协议-张三。可空。 |
| `sign_status` | VARCHAR(20) | 是 | 签署状态。枚举：pending=待签署；signing=签署中；signed=已签署；rejected=拒签；expired=已过期。非空，默认 pending。 |
| `sign_provider` | VARCHAR(50) | 否 | 电子签服务商。枚举：mock=MVP 模拟；esign_partner=合作电子签平台。可空。 |
| `external_contract_id` | VARCHAR(100) | 否 | 第三方电子签平台返回的合同 ID。对接后写入。可空。 |
| `sign_url` | VARCHAR(512) | 否 | 临时工签署页面链接。创建合同时由签章服务返回。可空。 |
| `signed_at` | TIMESTAMPTZ | 否 | 双方签署完成时间。可空。 |
| `file_url` | VARCHAR(512) | 否 | 已签署合同 PDF 归档地址。签署完成后写入。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 合同记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 签署状态变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

#### 结算与支付

##### `fe_settlement_order`

结算确认单主表，用工结束后按考勤或约定生成，展示应发/扣款/实发、服务费、开票额与企业总支出。企业确认后进入支付环节；一对多关联 fe_settlement_item、fe_settlement_fee、fe_payment_record。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。结算引擎生成结算单时创建。非空。 |
| `settlement_no` | VARCHAR(32) | 是 | 结算单业务编号。示例：STL20260707001。非空；唯一索引 uk_fe_settlement_no。 |
| `order_id` | BIGINT | 是 | 关联用工订单，外键 REFERENCES fe_employment_order(id)。非空。 |
| `batch_id` | BIGINT | 否 | 关联登记批次，外键 REFERENCES fe_registration_batch(id)。可空；多批次订单可只关联主批次。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。非空；索引 idx_fe_settlement_ent。 |
| `worker_count` | INTEGER | 是 | 本次结算涵盖人数。非空。 |
| `gross_amount` | NUMERIC(14,2) | 是 | 应发总额（元），税前劳务合计。非空，默认 0。 |
| `deduction_amount` | NUMERIC(14,2) | 是 | 扣款及个税合计（元）。非空，默认 0。 |
| `net_amount` | NUMERIC(14,2) | 是 | 实发总额（元），临时工到手合计。非空，默认 0。 |
| `service_fee_amount` | NUMERIC(14,2) | 是 | 平台服务费（元）。非空，默认 0。 |
| `invoice_amount` | NUMERIC(14,2) | 是 | 预计开票额（元），供企业财务参考。非空，默认 0。 |
| `total_outflow` | NUMERIC(14,2) | 是 | 企业总支出（元）= 实发 + 服务费 + 税费等。非空，默认 0。 |
| `settlement_status` | VARCHAR(20) | 是 | 结算单状态。枚举：pending=待企业确认；confirmed=已确认待支付；paying=支付中；paid=已支付；cancelled=已取消。非空，默认 pending。 |
| `compliance_tags` | JSONB | 否 | 五流合一合规校验结果标签 JSON。示例：["个税已申报","发票合规"]。可空，默认 []。 |
| `compliance_remark` | TEXT | 否 | 合规说明文案。示例：可全额税前扣除。可空。 |
| `confirmed_at` | TIMESTAMPTZ | 否 | 企业主确认结算单时间。可空。 |
| `confirmed_by` | BIGINT | 否 | 确认人，外键 REFERENCES fe_user(id)。可空。 |
| `paid_at` | TIMESTAMPTZ | 否 | 支付完成时间，全部打款成功后写入。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 结算单生成时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 状态或金额变更时更新。非空。 |
| `del_flag` | SMALLINT | 是 | 逻辑删除标记。枚举：0=正常；1=已删除。非空，默认 0。 |

##### `fe_settlement_item`

结算单人明细表，按临时工拆分应发、个税、其他扣款与实发金额。支持按天、按小时、计件多种计量维度；关联 fe_settlement_order、fe_worker_registration、fe_worker。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。生成结算单时按登记记录逐人插入。非空。 |
| `settlement_id` | BIGINT | 是 | 关联结算单，外键 REFERENCES fe_settlement_order(id)。非空；索引 idx_fe_settlement_item。 |
| `registration_id` | BIGINT | 否 | 关联登记记录，外键 REFERENCES fe_worker_registration(id)。可空；建议必填以追溯人员。 |
| `worker_id` | BIGINT | 否 | 关联临时工档案，外键 REFERENCES fe_worker(id)。可空。 |
| `worker_name_mask` | VARCHAR(64) | 否 | 姓名脱敏展示，如张*三。可空；禁止存明文全名。 |
| `work_days` | NUMERIC(8,2) | 否 | 结算工作天数，NUMERIC(8,2)。可空。 |
| `work_hours` | NUMERIC(8,2) | 否 | 结算工作小时数。可空。 |
| `piece_count` | NUMERIC(12,2) | 否 | 计件数量。可空。 |
| `gross_amount` | NUMERIC(12,2) | 是 | 该人员应发金额（元）。非空，默认 0。 |
| `tax_amount` | NUMERIC(12,2) | 是 | 个税扣款（元）。非空，默认 0。 |
| `other_deduction` | NUMERIC(12,2) | 是 | 其他扣款（元），如工装赔偿。非空，默认 0。 |
| `net_amount` | NUMERIC(12,2) | 是 | 该人员实发金额（元）。非空，默认 0。 |
| `item_status` | VARCHAR(20) | 是 | 明细行状态。示例：pending、confirmed、paid。非空，默认 pending。 |
| `create_time` | TIMESTAMPTZ | 是 | 明细创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 明细金额调整时更新。非空。 |

##### `fe_settlement_fee`

结算单费用汇总项表，订单级劳务费、服务费、保险、税费等分项金额，对应小程序「资金总览」模块。归属 fe_settlement_order，结构与 fe_draft_cost_detail 类似但为实际结算数据。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。结算单生成时同步写入各费用分项。非空。 |
| `settlement_id` | BIGINT | 是 | 关联结算单，外键 REFERENCES fe_settlement_order(id)。非空；索引 idx_fe_settlement_fee。 |
| `fee_code` | VARCHAR(50) | 是 | 费用项编码。示例：labor_fee、service_fee、insurance、tax_withhold。非空。 |
| `fee_name` | VARCHAR(100) | 是 | 费用项中文名。非空。 |
| `amount` | NUMERIC(14,2) | 是 | 费用金额（元），NUMERIC(14,2)。非空。 |
| `rate` | NUMERIC(8,4) | 否 | 适用费率，NUMERIC(8,4)。可空。 |
| `sort_order` | INTEGER | 是 | 资金总览展示顺序。非空，默认 0。 |

##### `fe_payment_record`

支付/打款记录表，企业确认结算后发起付款，记录渠道、金额、第三方交易流水与凭证。小程序仅展示 payment_channel 渠道类型，不展示对公账户；关联 fe_settlement_order、fe_enterprise。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。发起支付时创建。非空。 |
| `payment_no` | VARCHAR(32) | 是 | 支付单业务编号。示例：PAY20260707001。非空；唯一索引 uk_fe_payment_no。 |
| `settlement_id` | BIGINT | 是 | 关联结算单，外键 REFERENCES fe_settlement_order(id)。非空；索引 idx_fe_payment_settlement。 |
| `enterprise_id` | BIGINT | 是 | 付款企业，外键 REFERENCES fe_enterprise(id)。非空。 |
| `payment_channel` | VARCHAR(50) | 是 | 支付渠道类型，前端仅展示此字段。枚举：wechat=微信支付；alipay=支付宝；bank=银行转账。非空。 |
| `payment_amount` | NUMERIC(14,2) | 是 | 支付金额（元）。非空。 |
| `payment_status` | VARCHAR(20) | 是 | 支付状态。枚举：pending=处理中；success=成功；failed=失败；refunded=已退款。非空，默认 pending。 |
| `external_trade_no` | VARCHAR(100) | 否 | 微信/支付宝/银行等第三方交易流水号。支付回调成功时写入。可空。 |
| `payer_user_id` | BIGINT | 否 | 发起付款的企业主用户，外键 REFERENCES fe_user(id)。可空。 |
| `paid_at` | TIMESTAMPTZ | 否 | 支付成功时间戳。可空。 |
| `receipt_url` | VARCHAR(512) | 否 | 支付凭证或回单下载地址。可空。 |
| `fail_reason` | TEXT | 否 | 支付失败原因。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 支付单创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 状态变更时更新。非空。 |

#### 考勤（二期预留）

##### `fe_attendance_batch`

考勤日报批次表（二期功能），按登记批次与日期汇总当日应考勤人数、出勤/加班/请假统计及预估费用。一期 MVP 可不实现业务逻辑，表结构先行预留；关联 fe_registration_batch、fe_employment_order。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。每日定时任务或企业主手动生成日报时创建。非空。 |
| `batch_id` | BIGINT | 是 | 关联登记批次，外键 REFERENCES fe_registration_batch(id)。非空；与 attendance_date 组成唯一索引 uk_fe_attendance_batch。 |
| `order_id` | BIGINT | 是 | 关联订单，外键 REFERENCES fe_employment_order(id)。冗余便于订单维度查考勤。非空。 |
| `attendance_date` | DATE | 是 | 考勤统计日期，DATE 类型。示例：2026-08-15。非空。 |
| `total_workers` | INTEGER | 是 | 当日应考勤人数。非空，默认 0。 |
| `normal_count` | INTEGER | 是 | 正常出勤人数。非空，默认 0。 |
| `overtime_count` | INTEGER | 是 | 加班人数。非空，默认 0。 |
| `leave_count` | INTEGER | 是 | 请假人数。非空，默认 0。 |
| `total_hours` | NUMERIC(10,2) | 否 | 当日总工时（小时）。可空，默认 0。 |
| `total_pieces` | NUMERIC(12,2) | 否 | 当日总计件数。可空，默认 0。 |
| `estimated_cost` | NUMERIC(14,2) | 否 | 当日预估劳务费用（元）。可空，默认 0。 |
| `status` | VARCHAR(20) | 是 | 日报状态。枚举：draft=草稿可编辑；confirmed=已确认锁定；archived=已归档。非空，默认 draft。 |
| `confirmed_by` | BIGINT | 否 | 确认人，外键 REFERENCES fe_user(id)。企业主确认日报时写入。可空。 |
| `confirmed_at` | TIMESTAMPTZ | 否 | 日报确认时间。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 日报创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 考勤数据变更时更新。非空。 |

##### `fe_attendance_record`

考勤明细表（二期），记录单人单日考勤类型（正常/加班/请假/计件）、工时与计件数。支持 manual/voice/import 多种录入来源；关联 fe_attendance_batch、fe_worker_registration、fe_worker。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。录入或导入单人考勤时插入。非空。 |
| `attendance_batch_id` | BIGINT | 是 | 关联考勤日报，外键 REFERENCES fe_attendance_batch(id)。非空；索引 idx_fe_attendance_rec。 |
| `registration_id` | BIGINT | 是 | 关联登记记录，外键 REFERENCES fe_worker_registration(id)。非空；确定考勤对象。 |
| `worker_id` | BIGINT | 否 | 关联临时工档案，外键 REFERENCES fe_worker(id)。可空；冗余加速查询。 |
| `attendance_type` | VARCHAR(20) | 是 | 考勤类型。枚举：normal=正常出勤；overtime=加班；leave=请假；piece=计件产量。非空，默认 normal。 |
| `work_hours` | NUMERIC(8,2) | 否 | 正常工作小时数，NUMERIC(8,2)。可空。 |
| `overtime_hours` | NUMERIC(8,2) | 否 | 加班小时数。可空。 |
| `piece_count` | NUMERIC(12,2) | 否 | 计件数量。可空。 |
| `remark` | TEXT | 否 | 考勤备注，如请假原因。可空。 |
| `source` | VARCHAR(30) | 否 | 录入来源。枚举：manual=手工录入；voice=语音录入（AI 解析）；import=批量导入。可空，默认 manual。 |
| `create_time` | TIMESTAMPTZ | 是 | 记录创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 考勤数据修改时更新。非空。 |

#### 审计、第三方与消息

##### `fe_user_confirmation`

用户确认与授权留痕表，草稿确认、方案选择、结算支付、外部平台提交等高风险操作必须写入，满足审计与合规举证。关联 fe_enterprise、fe_user，可引用 fe_service_plan。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。用户执行确认类操作时同步插入，不可篡改。非空。 |
| `enterprise_id` | BIGINT | 是 | 所属企业，外键 REFERENCES fe_enterprise(id)。非空；索引 idx_fe_user_confirm。 |
| `user_id` | BIGINT | 是 | 操作用户，外键 REFERENCES fe_user(id)。非空；须为 enterprise 类型企业主或管理员。 |
| `biz_type` | VARCHAR(50) | 是 | 业务场景类型。枚举：draft_confirm=确认用工草稿；plan_select=选定用工方案；settlement_pay=确认并支付结算；external_submit=授权提交第三方平台。非空。 |
| `biz_id` | BIGINT | 是 | 关联业务主键 ID，如 draft_id、settlement_id。非空；与 biz_type 组合解析。 |
| `biz_no` | VARCHAR(32) | 否 | 关联业务编号冗余，便于人工审计。示例：draft_001。可空。 |
| `action` | VARCHAR(50) | 是 | 用户动作类型。枚举：confirm=确认；modify=修改后确认；authorize=授权。非空。 |
| `confirmed_fields` | JSONB | 否 | 用户确认时的关键字段快照 JSON，固化确认瞬间数据。示例：{"worker_count":15,"daily_wage":280}。可空，默认 {}。 |
| `selected_plan_id` | BIGINT | 否 | 确认选用的方案，外键 REFERENCES fe_service_plan(id)。biz_type=plan_select 或 draft_confirm 时写入。可空。 |
| `client_ip` | VARCHAR(64) | 否 | 客户端 IP，合规取证。网关提取。可空。 |
| `user_agent` | VARCHAR(500) | 否 | 客户端 UA 字符串。可空。 |
| `remark` | TEXT | 否 | 用户填写的备注或系统附注。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 确认操作发生时间。非空。 |

##### `fe_field_change_log`

关键字段变更历史表，记录草稿、订单、登记等业务对象重要字段的修改前后值，区分用户手工编辑、自然语言修改、AI 重新生成与系统自动变更，支撑争议追溯。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。字段值发生变更时追加写入。非空。 |
| `biz_type` | VARCHAR(50) | 是 | 业务对象类型。枚举：draft=用工草稿；order=用工订单；registration=登记记录。非空。 |
| `biz_id` | BIGINT | 是 | 业务对象主键 ID。非空；与 biz_type 组合查询；索引 idx_fe_field_change。 |
| `field_key` | VARCHAR(100) | 是 | 被变更字段键名。示例：work_location、daily_wage。非空。 |
| `old_value` | TEXT | 否 | 变更前的文本值。可空；首次填入时 old_value 为空。 |
| `new_value` | TEXT | 否 | 变更后的文本值。可空。 |
| `change_source` | VARCHAR(30) | 是 | 变更来源。枚举：user_edit=用户表单编辑；nl_edit=自然语言对话修改；ai_regenerate=AI 重新生成草稿；system=系统自动（如状态联动）。非空。 |
| `operator_id` | BIGINT | 否 | 操作人，外键 REFERENCES fe_user(id)。系统自动变更时可为空。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 变更发生时间。非空。 |

##### `fe_provider`

第三方灵活用工/税筹合作平台连接器配置表，存储 API 根地址与加密鉴权信息。不对小程序用户暴露；被 fe_provider_api_log 引用，一期可采用 Mock 打桩。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。运营接入新合作平台时创建。非空。 |
| `provider_code` | VARCHAR(50) | 是 | 平台业务编码，全局唯一。示例：partner_platform、tax_partner_a。非空；唯一索引 uk_fe_provider_code。 |
| `provider_name` | VARCHAR(100) | 是 | 平台展示名称。非空。 |
| `api_base_url` | VARCHAR(512) | 否 | 第三方 API 根地址。示例：https://api.partner.com/v1。可空。 |
| `auth_config_enc` | TEXT | 否 | API Key、Secret 等鉴权配置 JSON 的加密密文。运营配置时加密写入。高度敏感；禁止明文与前端暴露。可空。 |
| `status` | VARCHAR(20) | 是 | 连接器启用状态。枚举：active=启用；disabled=停用。非空，默认 active。 |
| `create_time` | TIMESTAMPTZ | 是 | 配置创建时间。非空。 |
| `update_time` | TIMESTAMPTZ | 是 | 配置变更时更新。非空。 |

##### `fe_provider_api_log`

合作平台 API 调用日志表，保存原始 HTTP 请求响应、技术状态码与转换后的业务状态 biz_status。技术细节不对用户展示；audit_required 标识是否需用户确认后才能继续推进订单流程。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。每次调用第三方 API 时追加。非空。 |
| `provider_id` | BIGINT | 是 | 合作平台，外键 REFERENCES fe_provider(id)。非空；索引 idx_fe_provider_log。 |
| `enterprise_id` | BIGINT | 否 | 关联企业，外键 REFERENCES fe_enterprise(id)。调用上下文企业。可空。 |
| `order_id` | BIGINT | 否 | 关联订单，外键 REFERENCES fe_employment_order(id)。可空；索引 idx_fe_provider_log_order。 |
| `action` | VARCHAR(100) | 是 | API 动作编码。示例：create_requirement=创建用工需求；query_status=查询办理状态；callback=异步回调。非空。 |
| `request_payload` | JSONB | 否 | 请求体 JSON 快照。可空；可能含敏感业务数据，访问受控。 |
| `response_payload` | JSONB | 否 | 响应体 JSON 快照。可空。 |
| `http_status` | INTEGER | 否 | HTTP 响应状态码。示例：200、500。可空。 |
| `biz_status` | VARCHAR(50) | 否 | 将技术响应映射后的业务状态，供订单状态机消费。示例：submitted、approved、rejected。可空。 |
| `audit_required` | BOOLEAN | 是 | 是否需企业主在用户侧确认后才能继续流程。第三方返回待确认时置 TRUE。非空，默认 FALSE。 |
| `error_message` | TEXT | 否 | 调用失败错误信息。可空。 |
| `duration_ms` | INTEGER | 否 | 请求耗时（毫秒）。可空。 |
| `create_time` | TIMESTAMPTZ | 是 | 调用时间。非空。 |

##### `fe_notification`

消息与待办中心表，推送结算待确认、实名失败、登记进度、流程节点变更等通知。支持 action_url 跳转小程序对应页面/弹窗；关联 fe_enterprise、fe_user，通过 read_flag 与 handled_flag 区分已读与已办。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | BIGSERIAL | 是 | 表主键，自增。业务事件触发时由通知服务写入。非空。 |
| `enterprise_id` | BIGINT | 否 | 所属企业，外键 REFERENCES fe_enterprise(id)。企业维度消息筛选。可空；索引 idx_fe_notification_ent。 |
| `user_id` | BIGINT | 否 | 接收用户，外键 REFERENCES fe_user(id)。可空；索引 idx_fe_notification_user；与 enterprise_id 至少其一有值。 |
| `notify_type` | VARCHAR(30) | 是 | 通知展示样式。枚举：pending=待办（橙色）；error=异常（红色）；info=提示（蓝色）；success=成功（绿色）。非空。 |
| `category` | VARCHAR(50) | 是 | 业务分类。枚举：settlement=结算；registration=登记；verify=实名核验；workflow=流程进度。非空。 |
| `title` | VARCHAR(200) | 是 | 通知标题，列表主文案。非空。 |
| `content` | TEXT | 否 | 通知正文详细描述。可空。 |
| `biz_type` | VARCHAR(50) | 否 | 关联业务对象类型，如 settlement、registration、order。可空。 |
| `biz_id` | BIGINT | 否 | 关联业务主键 ID，用于跳转后加载详情。可空。 |
| `biz_no` | VARCHAR(32) | 否 | 关联业务编号冗余。示例：STL20260707001。可空。 |
| `action_url` | VARCHAR(512) | 否 | 小程序内跳转路径或 scheme。示例：/pages/settlement/detail?id=123。可空。 |
| `read_flag` | BOOLEAN | 是 | 是否已读。用户打开消息中心或点击后更新。非空，默认 FALSE。 |
| `handled_flag` | BOOLEAN | 是 | 待办是否已处理完成。用户完成对应操作后更新。非空，默认 FALSE。 |
| `create_time` | TIMESTAMPTZ | 是 | 通知创建时间。非空。 |
| `read_time` | TIMESTAMPTZ | 否 | 标记已读时间。可空。 |
| `handled_time` | TIMESTAMPTZ | 否 | 待办完成时间。可空。 |

### 7.9 索引与约束约定

| 约定 | 说明 |
|------|------|
| 主键 | 各表 `id BIGINT` 自增主键 |
| 逻辑删除 | 带 `del_flag` 的表，查询默认 `del_flag = 0` |
| 软删唯一索引 | PostgreSQL 部分唯一索引在 MySQL 版改为 `(业务键, del_flag)` 联合唯一 |
| 外键 | DDL 中声明 `REFERENCES`，应用层亦须校验企业归属 |
| 敏感字段 | `*_enc` 密文 + `*_mask` 脱敏，禁止明文入库 |
| JSON 字段 | MySQL 5.7 不设 DEFAULT，由应用层 Insert 时写入 `{}` |
| 乐观锁 | 草稿等关键表使用 `version` 字段防并发覆盖 |

---

## 8. 安全与合规

### 8.1 Spring Security + JWT + 小程序鉴权

**过滤器链（一期已实现）**：

```text
请求 → JwtAuthFilter → Controller
         ↓
    解析 JWT → 查 fe_user（status、del_flag、user_type）→ LoginUserHolder
```

| 路径模式 | 鉴权方式 |
|----------|----------|
| `/api/v1/mp/auth/sms/**`、`/auth/wechat/**` | 匿名 |
| `/api/v1/mp/auth/password/login`、`/reset`、`/public-key` | 匿名 |
| `/api/v1/mp/auth/password/set`、`/password/status` | JWT 必须 |
| `/api/v1/mp/health` | 匿名 |
| `/api/v1/mp/**` 其余 | JWT 必须；**每次请求查库**校验账号有效，身份以 DB `user_type` 为准 |
| `/internal/fe/**` | 内网 IP + `X-Fe-Ai-Key`（规划中） |
| `/doc.html`、`/v3/api-docs/**` | 开发环境开放 |

**JWT 载荷（已实现）**：`sub`(userId)、`userType`、`jti`、`exp`（默认 7200s）。`jti` 预留二期黑名单 `fe:token:{jti}`。

**登录流程**：

1. **短信**：发码 → 校验（一次性 + 失败次数上限）→ 找/建 `fe_user` → 校验 `user_type` 不可变 → 签发 JWT。
2. **微信**：`code2session` → 找/建 `fe_user`（写 openid）→ 同上。
3. **账密**：RSA 解密 → BCrypt 校验 → 失败计数与锁定 → 签发 JWT。
4. 小程序 Header：`Authorization: Bearer <token>`；登出仅清本地 Token（一期）。

**权限校验**：

- `user_type = enterprise`：企业登记、后续草稿/订单等（规划中）。
- `user_type = worker`：临时工登记、后续扫码登记等（规划中）。
- 写操作校验 `fe_enterprise_user` 绑定（企业多管理员为二期）。

**一期已知限制（二期）**：短信/微信账号合并；JWT 登出黑名单；改密后旧 Token 立即失效；RSA 密文防重放。

### 8.2 其他安全要求

- 小程序 AppSecret、大模型 API Key、第三方 Key **仅配置在后端**
- 登记二维码带 `qr_token` 与 `valid_until`，一次性或限时有效
- 重要操作（确认方案、提交登记）记录 `fe_user_confirmation`

### 8.3 日志与审计（一期）

- `fe_agent_action_log`：AI 工具调用链
- `fe_provider_api_log`：第三方 Mock 调用记录
- `fe_user_confirmation`：用户确认与授权

---

## 9. 技术栈汇总

### 9.1 一期定稿

| 层次 | 技术 | 版本建议 |
|------|------|----------|
| 业务后端 | **Spring Boot** | **2.7.18** |
| ORM | **MyBatis-Plus** | 3.5.x |
| 数据库 | **MySQL** | **5.7**（InnoDB / utf8mb4） |
| 连接池 | Druid | 1.2.x |
| 缓存 | **Redis** | 6.x / 7.x |
| 缓存客户端 | Redisson（推荐） | 3.23.x |
| 安全 | **Spring Security + JWT** | jjwt 0.11.x 或 spring-security-oauth2-resource-server |
| 小程序鉴权 | 自定义 Filter + `fe_user` 体系 | 见 §8.1 |
| 接口文档 | **Knife4j** | 4.x（OpenAPI 3） |
| 参数校验 | Hibernate Validator | 随 Boot 2.7 |
| 微信 SDK | WxJava | 4.6.x |
| 小程序 | 微信原生 + TypeScript + TDesign/Vant | — |
| AI 服务 | Python FastAPI + LangGraph | 独立部署 |
| 构建 | Maven 多模块 | JDK 8 或 17 |
| 反向代理 | Nginx | HTTPS |
| 测试 | JUnit 5 + Mockito | 成本/规则单测；接口 Postman/Apifox |

### 9.2 一期明确不采用

| 技术 | 原因 |
|------|------|
| 若依 / 管理后台 | 一期无 Web 管理界面 |
| PostgreSQL | 统一 MySQL 5.7 |
| Python 业务 API | 业务逻辑统一 Java |
| pgvector / 向量库 | 政策 RAG 一期简化 |
| 消息队列 | Redis + 定时任务够用 |

### 9.3 二期可选引入

- 运营后台（Vue3 + 若依或自研 `fe-admin`）
- RocketMQ、阿里云 OSS、XXL-Job
- 微信支付、订阅消息、正式第三方 Adapter
- MySQL 8.0 迁移（SQL 保持兼容写法）

---

## 10. 分期交付计划

### 10.1 一期 MVP

**目标**：可演示/内测闭环 —「AI 对话 → 草稿 → 成本对比 → 确认 → 扫码登记 → 进度查看」。

| 序号 | 交付项 | 说明 |
|------|--------|------|
| 1 | `fe-server` 工程骨架 | Spring Boot 2.7.18 多模块 + Knife4j |
| 2 | MySQL 落库 | 全量 `灵活用工-mysql.sql` 或增量 `doc/migrations/V001`～`V006` |
| 3 | 登录 + JWT | **已实现**：短信/微信/账密；Knife4j 文档；并发唯一约束；`user_type` 不可变 |
| 3a | 企业/临时工登记 | **已实现**：`POST /enterprise/register`、`/worker/register` |
| 3b | AI 对话代理 | **已实现**：`/agent/messages`；OpenAI 兼容 `/ai/chat/completions`（含 SSE） |
| 4 | 对话 + AI 联调 | fe-ai 调 `/internal/fe/*` |
| 5 | 草稿 + 成本对比 | Java 成本引擎 + 测试费率 |
| 6 | 确认 + 登记批次 + 二维码 | Redis 存 qr_token |
| 7 | 临时工扫码登记 | 短信验证码（Redis）+ 敏感字段加密 |
| 8 | 登记进度 | 统计 + 人员列表 |
| 9 | 确认留痕 | `fe_user_confirmation` |

**一期不做**：Web 管理后台、正式第三方 API、正式支付/电子签/发票、完整审计链、消息队列、OSS。

### 10.2 二期规划

- 运营后台、正式第三方联调、结算支付、微信订阅消息
- 审计哈希链、日志按月分表、监控告警
- 可选 MySQL 8.0 升级

### 10.3 里程碑建议

| 阶段 | 时间 | 产出 |
|------|------|------|
| 方案评审 | 第 1 周 | 本文档、库表、原型评审 |
| 骨架 + 登录 | 第 2 周 | fe-server 可启动；短信/微信/账密登录；登记接口；Knife4j |
| 体验版 | 第 3～4 周 | MVP 闭环可演示 |
| 内测 | 第 5 周起 | 缺陷修复、安全加固 |

---

## 11. 风险与待确认事项

### 11.1 待确认项

| 事项 | 影响 |
|------|------|
| 小程序 AppID 与主体类型 | 开发与审核 |
| 企业认证方式（一期可简化） | 企业画像与权限 |
| 三方案正式名称、费率 | 成本测算 |
| 敏感字段加密算法（AES / SM4） | 合规与实现 |
| 短信服务商 | 临时工验证码 |
| JDK 8 还是 17 | 工程初始化 |

### 11.2 技术风险

| 风险 | 应对 |
|------|------|
| MySQL 5.7 已 EOL | SQL 保持 8.0 可迁移；规划升级窗口 |
| AI 幻觉导致错误草稿 | Java 规则校验 + 用户确认门控 |
| JWT 泄露 | 短过期 + HTTPS + 敏感操作二次校验 |
| Redis 与 DB 不一致 | 以 MySQL 为准；Redis 仅缓存与锁 |
| 第三方 API 延期 | Mock 打桩，契约在 `fe-integration` 固化 |

---

## 12. 分工建议

| 角色 | 职责 |
|------|------|
| 李泽云 | 整体把控、AI 服务、方案文档 |
| 陆工 | Java 后端、库表、API、Security、成本引擎 |
| 夏工 | 微信小程序 |
| 周工 | 费率规则、第三方契约、测试 |

---

## 13. 附录

### 13.1 交付物清单

| 文件 | 说明 |
|------|------|
| `灵活用工项目技术方案.md` | 本文档（含 §7.8 全表字段说明） |
| `灵活用工.sql` | PostgreSQL 设计稿（35 表 DDL + COMMENT） |
| `灵活用工-mysql.sql` | MySQL 5.7 生产脚本 |
| `wechat-mini-program-flexible-employment-plan.md` | 小程序沟通文档 |
| `flexible-employment-demo.html` | 交互原型 |

### 13.2 参考核心体验一句话

```text
智能体先生成方案，企业主确认，临时工扫码补资料，Java 后端继续办理。
```

### 13.3 与后端方案 v1 对照说明

| 后端方案 v1 | 本方案一期 |
|-------------|------------|
| 六层架构 + AI 工具网关 | ✅ `fe-server` 分包实现 |
| 规则路由 vs AI 分流 | ✅ 确定性走 Service，对话走 fe-ai |
| MySQL + Redis | ✅ 定稿 |
| 成本后端计算 | ✅ Java `service.cost` |
| 完整审计哈希链 | ⏳ 二期 |
| 运营配置后台 | ⏳ 二期（费率一期 SQL/配置维护） |

---

*文档结束*