# 微信小程序技术沟通文档：灵活用工与用工税筹模块

## 1. 项目背景

本项目面向中小微企业建设一个整体智能体。`灵活用工与用工税筹`只是其中一个业务子模块，不是整个产品。

当企业用户提出用工、临时工、合规用工、用工成本、结算、保险、发票等相关问题时，主智能体会调用该子模块。该子模块负责理解用户意图、生成办理草稿、做成本对比、识别风险、生成提交前数据，并在用户确认后交给后端流程继续处理。

当前计划增加一个微信小程序，作为企业主和临时工使用的轻量前台。

## 2. 产品核心原则

### 2.1 草稿优先

中小微企业用户通常不希望先回答大量问题。产品体验应当是：

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

默认逻辑：

- 能从企业画像推断的字段，不要重复问用户。
- 能从历史偏好推断的字段，优先复用。
- 能使用合理默认值的字段，先生成草稿，再允许修改。
- 只有关键缺失信息或高风险信息，才主动追问。

例如企业已有一批临时工时，不应一开始要求企业主逐个填写名单。更好的方式是先生成登记批次和二维码，让临时工扫码自行登记。

### 2.2 弱化第三方平台存在感

前台用户体验中，不应频繁出现“第三方 API”“连接器 payload”“某某平台接口返回”等技术表达。

用户看到的是：

```text
我已帮你生成这批临时工规范办理草稿。
确认后，将继续进入登记、保险、打卡、结算等流程。
```

内部系统可以记录：

```text
provider = partner_platform
action = create_requirement
audit_required = true
```

只有在用户授权、合同、保险、结算、发票、支付、法律合规或用户明确询问时，才需要披露外部服务方或第三方处理信息。

### 2.3 成本对比优先

企业主最关心的不是复杂费率，而是三个结果：

```text
企业总支出
平均每人成本
员工到手金额
```

灵活用工模块需要展示：

- 当前处理方式的大致支出
- 方案一
- 方案二
- 方案三

三种方案的真实名称、费率、适用条件后续应从正式方案目录中配置。当前测试阶段可以使用测试默认值，但必须清楚标注为测试数据。

## 3. 小程序定位

微信小程序只作为轻前台，不承载核心智能体逻辑。

小程序负责：

- 企业主登录和企业绑定
- 企业主对话入口
- 展示智能体生成的用工草稿
- 展示成本对比
- 让用户确认、修改、选择方案
- 生成或展示临时工扫码登记入口
- 临时工扫码填写个人资料
- 企业主查看登记进度和办理状态

小程序不负责：

- 直接调用大模型
- 直接调用合作平台 API
- 保存模型密钥或平台密钥
- 执行复杂风控判断
- 执行核心成本测算逻辑
- 保存不可控的敏感业务规则

## 4. 建议系统架构

```mermaid
flowchart LR
    A["微信小程序"] --> B["业务后端 API"]
    B --> C["主智能体 / LangGraph"]
    C --> D["灵活用工与用工税筹子模块"]
    D --> E["模块私有 RAG"]
    D --> F["成本测算服务"]
    D --> G["审计与确认模块"]
    D --> H["第三方连接器模块"]
    H --> I["合作平台 API"]

    J["临时工扫码登记页"] --> B
    B --> K["业务数据库"]
    B --> L["文件/图片/附件存储"]
```

## 5. 端到端业务流程

### 5.1 企业已有临时工，想规范处理

```mermaid
sequenceDiagram
    participant U as 企业主
    participant MP as 微信小程序
    participant API as 业务后端
    participant Agent as 主智能体
    participant FE as 灵活用工子模块
    participant Worker as 临时工
    participant Conn as 连接器模块

    U->>MP: 我现在有一批临时工，想规范一下
    MP->>API: 提交用户消息
    API->>Agent: 请求意图识别和处理
    Agent->>FE: 调用灵活用工子模块
    FE->>FE: 生成登记草稿和默认字段
    FE->>FE: 生成成本对比
    FE-->>API: 返回草稿、成本方案、待确认项
    API-->>MP: 展示草稿和成本对比
    U->>MP: 确认或修改，选择方案
    MP->>API: 提交确认结果
    API->>FE: 生成临时工登记批次
    API-->>MP: 返回二维码/登记链接
    Worker->>MP: 扫码填写个人信息
    MP->>API: 提交临时工登记资料
    API-->>MP: 企业主查看登记进度
    U->>MP: 确认提交
    API->>Conn: 内部提交办理请求
```

### 5.2 企业新增用工需求

```text
企业主输入自然语言需求
-> 智能体生成用工需求草稿
-> 展示成本对比和风险提示
-> 企业主确认或修改
-> 进入审计与确认
-> 后端提交办理
-> 小程序展示状态进度
```

## 6. 页面建议

第一版小程序建议只做最小闭环。

### 6.1 企业主端

1. 首页 / 对话页
   - 企业主自然语言输入需求
   - 展示智能体回复
   - 支持继续补充信息

2. 用工草稿页
   - 展示用工类型、工种、地点、结算方式、保险、打卡、二维码有效期等
   - 字段可修改
   - 明确显示哪些是默认生成

3. 成本对比页
   - 当前方式
   - 方案一
   - 方案二
   - 方案三
   - 核心列：企业总支出、平均每人成本、员工到手

4. 确认提交页
   - 展示最终确认信息
   - 用户确认后才继续办理
   - 高风险或授权类动作必须留下确认记录

5. 登记进度页
   - 已登记人数
   - 待登记人数
   - 资料异常人数
   - 可提醒临时工继续填写

### 6.2 临时工端

临时工通过二维码进入轻量登记页。

需要支持：

- 手机号验证
- 身份信息填写
- 银行卡信息填写
- 工种或任务确认
- 协议/授权确认
- 提交结果提示

临时工端不需要看到企业主的成本测算和方案选择。

## 7. 后端模块边界

### 7.1 主智能体

负责：

- 用户意图识别
- 判断是否进入灵活用工子模块
- 跨模块编排
- 汇总不同子模块返回结果

建议技术：

- LangGraph
- Pydantic
- OpenAI Responses API

### 7.2 灵活用工与用工税筹子模块

负责：

- 用工意图识别
- 用工场景分类
- 风险诊断
- 成本测算
- 三方案对比
- 用工草稿生成
- 平台提交前数据准备
- 平台状态解释

当前已规划技术：

- FastAPI
- Pydantic
- LangGraph 子图
- Python deterministic rules
- PostgreSQL + pgvector
- LlamaIndex
- pytest

### 7.3 第三方连接器模块

负责：

- 对接合作平台 API
- 处理鉴权、提交、查询、回调
- 保存原始请求和响应
- 把技术状态转成业务状态

注意：连接器细节不直接暴露给用户。

### 7.4 审计与确认模块

负责：

- 用户确认记录
- 关键字段变更记录
- 授权确认
- 外部提交前确认
- 高风险动作留痕

## 8. 接口设计原则

所有模块必须有接收层和输出层。

```text
外部上下文
-> 接收层转换为模块内部标准格式
-> 模块内部处理
-> 输出层转换为目标方需要的格式
```

小程序不直接适配灵活用工模块内部结构。推荐路径是：

```text
小程序
-> 业务后端 API
-> 主智能体
-> 灵活用工子模块
-> 输出给业务后端
-> 小程序展示
```

## 9. 第一版 API 草案

这些接口用于技术沟通，不是最终定稿。

### 9.1 企业主发送消息

```http
POST /api/v1/agent/messages
```

请求：

```json
{
  "enterprise_id": "ent_001",
  "conversation_id": "conv_001",
  "message": "我现在有一批临时工，想规范一下"
}
```

返回：

```json
{
  "reply": "我先帮你生成一份临时工规范办理草稿。",
  "next_action": "show_employment_draft",
  "draft_id": "draft_001"
}
```

### 9.2 获取用工草稿

```http
GET /api/v1/flexible-employment/drafts/{draft_id}
```

返回：

```json
{
  "draft_id": "draft_001",
  "scenario": "existing_worker_regularization",
  "work_location": {
    "value": "企业注册地址",
    "source": "enterprise_registered_address",
    "editable": true
  },
  "insurance_required": true,
  "check_in_required": true,
  "qr_valid_days": 7,
  "missing_fields": ["主要工作内容"],
  "risk_prompts": []
}
```

### 9.3 获取成本对比

```http
GET /api/v1/flexible-employment/drafts/{draft_id}/cost-comparison
```

返回：

```json
{
  "rows": [
    {
      "plan_id": "current",
      "plan_name": "当前处理方式",
      "employer_total_outflow": 48000,
      "employer_average_cost_per_worker": 6000,
      "worker_take_home_per_worker": 6000
    },
    {
      "plan_id": "plan_1",
      "plan_name": "测试方案一",
      "employer_total_outflow": 51705.6,
      "employer_average_cost_per_worker": 6463.2,
      "worker_take_home_per_worker": 6000,
      "status": "test_only"
    }
  ],
  "notice": "当前方案数据为测试默认值，正式费率以后端方案目录为准。"
}
```

### 9.4 企业主确认方案

```http
POST /api/v1/flexible-employment/drafts/{draft_id}/confirm
```

请求：

```json
{
  "selected_plan_id": "plan_1",
  "confirmed_fields": {
    "work_location": "某某工业园 3 号仓",
    "work_content": "仓库搬运"
  }
}
```

返回：

```json
{
  "batch_id": "batch_001",
  "registration_url": "https://example.com/register/batch_001",
  "qr_code_url": "https://example.com/qrcode/batch_001.png"
}
```

### 9.5 临时工扫码登记

```http
POST /api/v1/worker-registration/{batch_id}/submit
```

请求：

```json
{
  "name": "张三",
  "mobile": "13800000000",
  "id_card_no": "encrypted_value",
  "bank_account": "encrypted_value",
  "confirmed_work_type": "仓库搬运"
}
```

返回：

```json
{
  "status": "submitted",
  "message": "登记已提交，请等待企业确认。"
}
```

## 10. 数据安全和合规注意点

第一版就需要重视：

- AppSecret 只放后端，不放小程序前端。
- OpenAI API Key 只放后端。
- 合作平台 API Key 只放后端。
- 身份证号、银行卡号、手机号等敏感信息需要加密存储或脱敏存储。
- 临时工扫码链接需要有有效期。
- 企业主确认、临时工授权、外部提交动作需要留痕。
- 小程序前端不要保存敏感字段明文缓存。
- 重要操作需要服务端权限校验，不能只依赖前端按钮隐藏。

## 11. 推荐技术栈

### 11.1 小程序前端

- 微信原生小程序
- TypeScript
- TDesign WeChat 或 Vant Weapp
- 微信登录能力
- 后端 Session / Token 鉴权

第一版不建议上复杂跨端框架，先验证核心业务闭环。

### 11.2 后端

- Python
- FastAPI
- Pydantic
- LangGraph
- PostgreSQL
- Redis
- pgvector
- LlamaIndex
- pytest

### 11.3 模型层

建议使用后端模型路由：

- 轻量分类、字段抽取：低成本模型
- 普通对话、草稿生成：主力模型
- 高风险解释、合规提示、复杂总结：更强模型

模型调用必须放在后端，不在小程序前端直连。

## 12. 第一阶段交付建议

第一阶段目标是做最小闭环 Demo，而不是一次性做完整系统。

建议范围：

1. 企业主登录和企业选择
2. 企业主输入一句用工需求
3. 后端返回用工草稿
4. 展示成本对比
5. 企业主选择方案并确认
6. 生成模拟二维码
7. 临时工扫码填写模拟登记信息
8. 企业主查看登记进度

暂不做：

- 正式合作平台 API 调用
- 正式支付
- 正式电子合同
- 正式发票流程
- 完整企业画像系统
- 完整 GraphRAG

## 13. 当前未确认事项

需要后续确认：

- 小程序主体类型和 AppID
- 企业认证方式
- 三种方案的正式名称、费率、适用条件
- 合作平台正式 API 文档
- 临时工登记所需的法定字段
- 是否需要微信支付
- 是否需要短信服务
- 是否需要电子签
- 敏感信息加密方案
- 小程序类目和合规审核要求

## 14. 技术结论

推荐路线：

```text
微信小程序做轻前台
FastAPI 做业务后端
LangGraph 做主智能体和模块编排
Pydantic 做模块间标准数据契约
灵活用工模块负责草稿、成本、风险、结构化
连接器模块负责合作平台 API
审计确认模块负责用户确认和留痕
```

核心体验不是让企业主填写复杂系统，而是：

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

