huimv-employment/doc/第三方平台对接接口-mock.json

{
  "spec_version": "1.0.0",
  "title": "灵活用工 — 第三方人力资源/税筹平台对接接口契约（Mock）",
  "description": "政策法规、税务、合同、社保等知识类数据从第三方平台获取；实名、签约、临时工资源、结算、完税、开票等业务办理对接第三方人力资源平台。本文档供 fe-integration 模块 Mock 实现与二期正式联调共用同一契约。",
  "updated_at": "2026-07-07",
  "default_provider_code": "hr_platform_mock",
  "mock_config": {
    "enabled": true,
    "base_url": "http://127.0.0.1:19090/mock/hr-platform",
    "default_delay_ms": 150,
    "sign_algorithm": "HMAC-SHA256",
    "sign_header": "X-Platform-Signature",
    "timestamp_header": "X-Platform-Timestamp",
    "nonce_header": "X-Platform-Nonce",
    "callback_verify_sign": true
  },
  "providers": [
    {
      "provider_code": "hr_platform_mock",
      "provider_name": "合作人力资源平台（Mock）",
      "api_base_url": "http://127.0.0.1:19090/mock/hr-platform",
      "status": "active",
      "capabilities": [
        "knowledge_policy",
        "knowledge_tax",
        "knowledge_contract",
        "knowledge_social_security",
        "identity_verify",
        "contract_esign",
        "worker_resource",
        "requirement_submit",
        "settlement",
        "payment",
        "tax_withhold",
        "invoice",
        "insurance"
      ]
    }
  ],
  "biz_status_mapping": {
    "SUCCESS": "succeeded",
    "PROCESSING": "processing",
    "PENDING_AUDIT": "pending_audit",
    "PENDING_SIGN": "pending_sign",
    "REJECTED": "rejected",
    "FAILED": "failed",
    "NOT_FOUND": "not_found"
  },
  "categories": {
    "knowledge": {
      "name": "知识库（政策法规 / 税务 / 合同 / 社保）",
      "source": "第三方平台统一知识服务，本地 fe_policy_rule 可缓存热点条目；AI 检索优先调此类接口，不自行编造法规原文。",
      "endpoints": [
        "knowledge.policy.search",
        "knowledge.policy.get",
        "knowledge.tax.search",
        "knowledge.contract.search",
        "knowledge.social_security.search",
        "knowledge.sync.changelog"
      ]
    },
    "identity": {
      "name": "身份实名核验",
      "endpoints": ["identity.verify.two_factor", "identity.verify.face"]
    },
    "contract": {
      "name": "电子劳动合同",
      "endpoints": ["contract.create", "contract.sign_url", "contract.status", "contract.download"]
    },
    "worker_resource": {
      "name": "临时工资源与用工需求",
      "endpoints": [
        "worker.pool.search",
        "requirement.create",
        "requirement.status",
        "worker.registration.sync"
      ]
    },
    "settlement": {
      "name": "结算与支付",
      "endpoints": ["settlement.create", "settlement.status", "payment.batch", "payment.status"]
    },
    "tax_invoice": {
      "name": "个税代征与发票",
      "endpoints": ["tax.withhold.batch", "tax.withhold.status", "invoice.apply", "invoice.status"]
    },
    "insurance": {
      "name": "商业保险投保",
      "endpoints": ["insurance.enroll", "insurance.status"]
    },
    "callback": {
      "name": "平台异步回调（fe-server 接收）",
      "endpoints": [
        "callback.contract_signed",
        "callback.identity_verified",
        "callback.payment_result",
        "callback.tax_completed",
        "callback.invoice_issued"
      ]
    }
  },
  "endpoints": [
    {
      "id": "knowledge.policy.search",
      "category": "knowledge",
      "sub_category": "policy",
      "name": "政策法规检索",
      "method": "POST",
      "path": "/v1/knowledge/policy/search",
      "description": "按关键词、地区、用工场景检索灵活用工相关政策法规条文，供风险诊断与 AI 问答引用。",
      "fe_action": "knowledge_policy_search",
      "request": {
        "enterprise_id": "ent_001",
        "keyword": "灵活用工 劳务报酬",
        "region_code": "310000",
        "scene": "flexible_employment",
        "page": 1,
        "page_size": 10
      },
      "response_success": {
        "code": "SUCCESS",
        "message": "ok",
        "data": {
          "total": 2,
          "items": [
            {
              "doc_id": "POL-2024-001",
              "title": "关于规范灵活用工平台企业用工管理的指导意见",
              "issuer": "人力资源和社会保障部",
              "region_code": "CN",
              "effective_date": "2024-01-01",
              "category": "flexible_employment",
              "summary": "明确平台企业与灵活就业人员权利义务，强调实名、合同、报酬支付与社保缴纳合规要求。",
              "content_excerpt": "平台企业应当依法与灵活就业人员订立书面协议或劳动合同……",
              "source_url": "https://example.gov.cn/policy/2024/001",
              "risk_tags": ["contract_required", "real_name_required"]
            },
            {
              "doc_id": "POL-2023-088",
              "title": "上海市灵活用工合规指引（节选）",
              "issuer": "上海市人社局",
              "region_code": "310000",
              "effective_date": "2023-06-01",
              "category": "local_policy",
              "summary": "本地临时性、辅助性岗位用工备案与工资支付周期要求。",
              "content_excerpt": "临时性岗位用工期限一般不超过六个月……",
              "source_url": "https://example.sh.gov.cn/policy/088",
              "risk_tags": ["term_limit", "wage_cycle"]
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 120, "biz_status": "succeeded" }
    },
    {
      "id": "knowledge.policy.get",
      "category": "knowledge",
      "sub_category": "policy",
      "name": "政策法规详情",
      "method": "GET",
      "path": "/v1/knowledge/policy/{doc_id}",
      "description": "获取单条政策全文与结构化要点。",
      "fe_action": "knowledge_policy_get",
      "path_params": { "doc_id": "POL-2024-001" },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "doc_id": "POL-2024-001",
          "title": "关于规范灵活用工平台企业用工管理的指导意见",
          "full_text": "（Mock 全文）平台企业应当依法与灵活就业人员订立书面协议……",
          "key_points": [
            "实名登记是办理前提",
            "应订立书面劳动合同或书面协议",
            "报酬支付应通过合规通道并代扣代缴个税"
          ],
          "version": "1.0",
          "updated_at": "2024-01-01T00:00:00+08:00"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 80, "biz_status": "succeeded" }
    },
    {
      "id": "knowledge.tax.search",
      "category": "knowledge",
      "sub_category": "tax",
      "name": "税务政策检索",
      "method": "POST",
      "path": "/v1/knowledge/tax/search",
      "description": "检索劳务报酬个税、代征、发票开具相关税务政策与税率说明。",
      "fe_action": "knowledge_tax_search",
      "request": {
        "enterprise_id": "ent_001",
        "keyword": "劳务报酬 预扣预缴",
        "income_type": "labor_remuneration",
        "region_code": "310000"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "items": [
            {
              "doc_id": "TAX-2024-LABOR-01",
              "title": "居民个人劳务报酬所得预扣预缴规则（摘要）",
              "tax_type": "individual_income_tax",
              "summary": "按次或按月累计预扣；平台可依法代办申报。",
              "rate_table_ref": "IIT_LABOR_2024",
              "withholding_required": true,
              "invoice_type_hint": "增值税普通发票 / 代开发票"
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "knowledge.contract.search",
      "category": "knowledge",
      "sub_category": "contract",
      "name": "劳动合同法规与范本知识检索",
      "method": "POST",
      "path": "/v1/knowledge/contract/search",
      "description": "检索劳动合同签订、试用期、解除终止等法规要点及平台推荐范本说明（非直接生成合同正文）。",
      "fe_action": "knowledge_contract_search",
      "request": {
        "keyword": "非全日制 劳动合同",
        "work_type": "temporary",
        "contract_type": "labor_contract"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "items": [
            {
              "doc_id": "CTR-LAW-001",
              "title": "非全日制用工劳动合同签订要点",
              "summary": "可订立口头协议，但平台场景建议电子书面合同；工时与报酬结算周期不得超过十五日。",
              "mandatory_clauses": ["工作内容与地点", "报酬标准", "工时", "劳动保护"],
              "template_code": "TPL_LABOR_PART_TIME_V1",
              "esign_required": true
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "knowledge.social_security.search",
      "category": "knowledge",
      "sub_category": "social_security",
      "name": "社会保险政策检索",
      "method": "POST",
      "path": "/v1/knowledge/social-security/search",
      "description": "检索工伤保险、意外险、社保缴纳义务等地域性政策说明，辅助保险方案推荐。",
      "fe_action": "knowledge_social_security_search",
      "request": {
        "region_code": "310000",
        "keyword": "临时工 工伤保险",
        "industry": "logistics"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "items": [
            {
              "doc_id": "SS-2024-INJ-01",
              "title": "用工单位工伤保险责任说明",
              "summary": "平台场景下应通过商业意外险或雇主责任险补充保障；特定岗位须核实当地参保要求。",
              "insurance_recommendations": ["employer_liability", "accident_insurance"],
              "mandatory_enrollment": false,
              "region_code": "310000"
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "knowledge.sync.changelog",
      "category": "knowledge",
      "sub_category": "policy",
      "name": "知识库变更同步",
      "method": "GET",
      "path": "/v1/knowledge/changelog",
      "description": "拉取第三方知识库增量更新列表，供定时任务同步至 fe_policy_rule。",
      "fe_action": "knowledge_sync_changelog",
      "query": { "since": "2026-07-01T00:00:00+08:00" },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "changes": [
            {
              "doc_id": "POL-2024-001",
              "change_type": "update",
              "changed_at": "2026-07-05T10:00:00+08:00"
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 60, "biz_status": "succeeded" }
    },
    {
      "id": "identity.verify.two_factor",
      "category": "identity",
      "name": "实名二要素核验",
      "method": "POST",
      "path": "/v1/identity/verify/two-factor",
      "description": "姓名 + 身份证号核验，登记环节调用。",
      "fe_action": "identity_verify",
      "request": {
        "request_no": "IDV202607070001",
        "name": "张三",
        "id_card_no": "310101199001011234",
        "mobile": "13800138000"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "verify_id": "VER_mock_001",
          "status": "PASSED",
          "match_result": true,
          "verified_at": "2026-07-07T10:00:00+08:00"
        }
      },
      "response_fail": {
        "code": "REJECTED",
        "message": "身份信息不匹配",
        "data": { "verify_id": "VER_mock_002", "status": "FAILED", "match_result": false }
      },
      "mock": { "http_status": 200, "delay_ms": 300, "biz_status": "succeeded" }
    },
    {
      "id": "identity.verify.face",
      "category": "identity",
      "name": "人脸活体核验（可选）",
      "method": "POST",
      "path": "/v1/identity/verify/face",
      "description": "高风险场景人脸比对，二期启用。",
      "fe_action": "identity_verify_face",
      "request": {
        "verify_id": "VER_mock_001",
        "face_image_base64": "..."
      },
      "response_success": {
        "code": "SUCCESS",
        "data": { "status": "PASSED", "similarity": 0.98 }
      },
      "mock": { "http_status": 200, "delay_ms": 500, "biz_status": "succeeded" }
    },
    {
      "id": "contract.create",
      "category": "contract",
      "name": "创建电子劳动合同",
      "method": "POST",
      "path": "/v1/contracts",
      "description": "根据登记信息与用工草稿在第三方平台创建待签合同。",
      "fe_action": "contract_create",
      "request": {
        "request_no": "CTR202607070001",
        "order_no": "ORD202607070001",
        "enterprise": {
          "name": "上海某某物流有限公司",
          "credit_code": "91310000MA1K3XXXXX"
        },
        "worker": {
          "name": "张三",
          "id_card_mask": "310101********1234",
          "mobile_mask": "138****8000"
        },
        "contract_type": "labor_contract",
        "template_code": "TPL_LABOR_PART_TIME_V1",
        "work_content": "仓库分拣",
        "work_location": "上海市浦东新区",
        "wage_desc": "日薪280元",
        "start_date": "2026-07-10",
        "end_date": "2026-08-10"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_contract_id": "EXT_CTR_mock_001",
          "status": "PENDING_SIGN",
          "sign_deadline": "2026-07-09T23:59:59+08:00"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 200, "biz_status": "pending_sign" }
    },
    {
      "id": "contract.sign_url",
      "category": "contract",
      "name": "获取签署链接",
      "method": "POST",
      "path": "/v1/contracts/{external_contract_id}/sign-url",
      "description": "为临时工生成 H5/小程序签署链接。",
      "fe_action": "contract_sign_url",
      "path_params": { "external_contract_id": "EXT_CTR_mock_001" },
      "request": {
        "signer_role": "worker",
        "redirect_url": "https://mp.example.com/pages/contract/result"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "sign_url": "https://esign.mock.example.com/sign/abc123",
          "expires_at": "2026-07-08T12:00:00+08:00"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 150, "biz_status": "pending_sign" }
    },
    {
      "id": "contract.status",
      "category": "contract",
      "name": "合同状态查询",
      "method": "GET",
      "path": "/v1/contracts/{external_contract_id}",
      "description": "主动查询或补偿轮询合同签署状态。",
      "fe_action": "contract_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_contract_id": "EXT_CTR_mock_001",
          "status": "SIGNED",
          "signed_at": "2026-07-07T14:30:00+08:00",
          "pdf_url": "https://oss.mock.example.com/contracts/EXT_CTR_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "contract.download",
      "category": "contract",
      "name": "下载合同 PDF",
      "method": "GET",
      "path": "/v1/contracts/{external_contract_id}/download",
      "description": "已签署合同 PDF 下载地址。",
      "fe_action": "contract_download",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "pdf_url": "https://oss.mock.example.com/contracts/EXT_CTR_mock_001.pdf",
          "expire_seconds": 3600
        }
      },
      "mock": { "http_status": 200, "delay_ms": 80, "biz_status": "succeeded" }
    },
    {
      "id": "worker.pool.search",
      "category": "worker_resource",
      "name": "临时工资源池检索",
      "method": "POST",
      "path": "/v1/worker-pool/search",
      "description": "从第三方人力平台检索可匹配临时工资源（二期可选；一期 Mock 返回空或示例）。",
      "fe_action": "worker_pool_search",
      "request": {
        "region_code": "310000",
        "work_type": "warehouse_picker",
        "headcount": 20,
        "available_date": "2026-07-10"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "total": 1,
          "items": [
            {
              "pool_worker_id": "PW_mock_1001",
              "name_mask": "李*",
              "skills": ["分拣", "叉车证"],
              "available_from": "2026-07-10",
              "expected_daily_wage": 260,
              "verified": true
            }
          ]
        }
      },
      "mock": { "http_status": 200, "delay_ms": 200, "biz_status": "succeeded" }
    },
    {
      "id": "requirement.create",
      "category": "worker_resource",
      "name": "创建用工需求（正式提交平台）",
      "method": "POST",
      "path": "/v1/requirements",
      "description": "企业主确认方案后，将用工订单正式提交第三方人力资源平台办理。",
      "fe_action": "create_requirement",
      "request": {
        "request_no": "REQ202607070001",
        "order_no": "ORD202607070001",
        "batch_no": "BATCH202607070001",
        "enterprise_id": "ent_001",
        "plan_code": "plan_01",
        "work_summary": {
          "work_type": "warehouse_picker",
          "headcount": 15,
          "work_days": 30,
          "daily_wage": 280,
          "work_location": "上海市浦东新区"
        },
        "cost_snapshot_id": "COST_SNAP_001",
        "registration_url": "https://mp.example.com/register/batch_001"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_requirement_id": "EXT_REQ_mock_001",
          "status": "SUBMITTED",
          "platform_order_no": "PLT202607070001",
          "estimated_process_days": 3
        }
      },
      "mock": { "http_status": 200, "delay_ms": 250, "biz_status": "processing" }
    },
    {
      "id": "requirement.status",
      "category": "worker_resource",
      "name": "查询用工需求办理状态",
      "method": "GET",
      "path": "/v1/requirements/{external_requirement_id}",
      "description": "补偿轮询平台办理进度，映射至 fe_employment_order 状态机。",
      "fe_action": "query_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_requirement_id": "EXT_REQ_mock_001",
          "status": "IN_PROGRESS",
          "current_step": "registration",
          "steps": [
            { "code": "submitted", "name": "已提交", "done": true },
            { "code": "registration", "name": "人员登记中", "done": false },
            { "code": "contract", "name": "合同签署", "done": false },
            { "code": "settlement", "name": "待结算", "done": false }
          ],
          "registered_count": 5,
          "total_count": 15
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "processing" }
    },
    {
      "id": "worker.registration.sync",
      "category": "worker_resource",
      "name": "同步登记人员至平台",
      "method": "POST",
      "path": "/v1/requirements/{external_requirement_id}/workers",
      "description": "临时工在本系统完成登记后，将脱敏摘要同步至第三方平台。",
      "fe_action": "worker_registration_sync",
      "request": {
        "registration_id": "REG202607070001",
        "worker_ref": "WRK_mock_001",
        "name": "张三",
        "id_card_no_enc": "ENC_xxx",
        "mobile_enc": "ENC_yyy",
        "bank_card_enc": "ENC_zzz",
        "reg_status": "submitted"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_worker_id": "EXT_WRK_mock_001",
          "sync_status": "ACCEPTED"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 180, "biz_status": "succeeded" }
    },
    {
      "id": "settlement.create",
      "category": "settlement",
      "name": "创建结算单",
      "method": "POST",
      "path": "/v1/settlements",
      "description": "向平台提交结算批次与明细。",
      "fe_action": "settlement_create",
      "request": {
        "request_no": "STL202607070001",
        "order_no": "ORD202607070001",
        "settlement_period": "2026-07",
        "items": [
          {
            "worker_ref": "WRK_mock_001",
            "gross_amount": 8400.0,
            "tax_amount": 252.0,
            "net_amount": 8148.0,
            "work_days": 30
          }
        ],
        "total_enterprise_cost": 9200.0
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_settlement_id": "EXT_STL_mock_001",
          "status": "PENDING_CONFIRM"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 200, "biz_status": "pending_audit" }
    },
    {
      "id": "settlement.status",
      "category": "settlement",
      "name": "结算单状态查询",
      "method": "GET",
      "path": "/v1/settlements/{external_settlement_id}",
      "fe_action": "settlement_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_settlement_id": "EXT_STL_mock_001",
          "status": "CONFIRMED"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 80, "biz_status": "succeeded" }
    },
    {
      "id": "payment.batch",
      "category": "settlement",
      "name": "批量打款",
      "method": "POST",
      "path": "/v1/payments/batch",
      "description": "企业确认结算后发起批量代发。",
      "fe_action": "payment_batch",
      "request": {
        "request_no": "PAY202607070001",
        "external_settlement_id": "EXT_STL_mock_001",
        "payment_channel": "bank",
        "total_amount": 8148.0,
        "payee_count": 1
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_payment_id": "EXT_PAY_mock_001",
          "status": "PROCESSING"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 300, "biz_status": "processing" }
    },
    {
      "id": "payment.status",
      "category": "settlement",
      "name": "打款结果查询",
      "method": "GET",
      "path": "/v1/payments/{external_payment_id}",
      "fe_action": "payment_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_payment_id": "EXT_PAY_mock_001",
          "status": "SUCCESS",
          "paid_at": "2026-07-07T16:00:00+08:00",
          "external_trade_no": "BANK20260707160001"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "tax.withhold.batch",
      "category": "tax_invoice",
      "name": "个税代征批量申报",
      "method": "POST",
      "path": "/v1/tax/withhold/batch",
      "description": "打款成功后触发个税代扣代缴。",
      "fe_action": "tax_withhold",
      "request": {
        "request_no": "TAX202607070001",
        "external_payment_id": "EXT_PAY_mock_001",
        "tax_period": "2026-07",
        "items": [{ "worker_ref": "WRK_mock_001", "taxable_income": 8400.0, "tax_amount": 252.0 }]
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_tax_id": "EXT_TAX_mock_001",
          "status": "PROCESSING"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 250, "biz_status": "processing" }
    },
    {
      "id": "tax.withhold.status",
      "category": "tax_invoice",
      "name": "个税完税状态查询",
      "method": "GET",
      "path": "/v1/tax/withhold/{external_tax_id}",
      "fe_action": "tax_withhold_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_tax_id": "EXT_TAX_mock_001",
          "status": "COMPLETED",
          "certificate_url": "https://oss.mock.example.com/tax/EXT_TAX_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "invoice.apply",
      "category": "tax_invoice",
      "name": "发票开具申请",
      "method": "POST",
      "path": "/v1/invoices",
      "description": "完税后为企业开具服务费发票。",
      "fe_action": "invoice_apply",
      "request": {
        "request_no": "INV202607070001",
        "external_settlement_id": "EXT_STL_mock_001",
        "invoice_type": "vat_ordinary",
        "amount": 800.0,
        "title": "上海某某物流有限公司",
        "tax_no": "91310000MA1K3XXXXX"
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_invoice_id": "EXT_INV_mock_001",
          "status": "PROCESSING"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 200, "biz_status": "processing" }
    },
    {
      "id": "invoice.status",
      "category": "tax_invoice",
      "name": "发票状态查询",
      "method": "GET",
      "path": "/v1/invoices/{external_invoice_id}",
      "fe_action": "invoice_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_invoice_id": "EXT_INV_mock_001",
          "status": "ISSUED",
          "invoice_code": "031001900111",
          "invoice_no": "12345678",
          "pdf_url": "https://oss.mock.example.com/invoice/EXT_INV_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 100, "biz_status": "succeeded" }
    },
    {
      "id": "insurance.enroll",
      "category": "insurance",
      "name": "商业保险投保",
      "method": "POST",
      "path": "/v1/insurance/enroll",
      "description": "为登记人员批量投保意外险/雇主责任险。",
      "fe_action": "insurance_enroll",
      "request": {
        "request_no": "INS202607070001",
        "order_no": "ORD202607070001",
        "plan_code": "ACCIDENT_STD",
        "workers": [{ "worker_ref": "WRK_mock_001", "coverage_start": "2026-07-10" }]
      },
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_policy_id": "EXT_INS_mock_001",
          "status": "ACTIVE",
          "policy_no": "POLmock20260707001"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 200, "biz_status": "succeeded" }
    },
    {
      "id": "insurance.status",
      "category": "insurance",
      "name": "保单状态查询",
      "method": "GET",
      "path": "/v1/insurance/{external_policy_id}",
      "fe_action": "insurance_status",
      "response_success": {
        "code": "SUCCESS",
        "data": {
          "external_policy_id": "EXT_INS_mock_001",
          "status": "ACTIVE",
          "certificate_url": "https://oss.mock.example.com/ins/EXT_INS_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "delay_ms": 80, "biz_status": "succeeded" }
    }
  ],
  "callbacks": [
    {
      "id": "callback.identity_verified",
      "name": "实名核验结果回调",
      "direction": "platform_to_fe_server",
      "method": "POST",
      "path": "/api/v1/internal/callback/provider/identity-verified",
      "description": "第三方异步通知实名结果，fe-server 验签后更新 fe_worker_registration。",
      "payload_example": {
        "event_id": "EVT_IDV_001",
        "event_type": "identity.verified",
        "occurred_at": "2026-07-07T10:05:00+08:00",
        "data": {
          "verify_id": "VER_mock_001",
          "registration_id": "REG202607070001",
          "status": "PASSED"
        }
      },
      "mock": { "http_status": 200, "response": { "code": 200, "msg": "received" } }
    },
    {
      "id": "callback.contract_signed",
      "name": "合同签署完成回调",
      "direction": "platform_to_fe_server",
      "method": "POST",
      "path": "/api/v1/internal/callback/provider/contract-signed",
      "payload_example": {
        "event_id": "EVT_CTR_001",
        "event_type": "contract.signed",
        "data": {
          "external_contract_id": "EXT_CTR_mock_001",
          "signed_at": "2026-07-07T14:30:00+08:00",
          "pdf_url": "https://oss.mock.example.com/contracts/EXT_CTR_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "response": { "code": 200, "msg": "received" } }
    },
    {
      "id": "callback.payment_result",
      "name": "打款结果回调",
      "direction": "platform_to_fe_server",
      "method": "POST",
      "path": "/api/v1/internal/callback/provider/payment-result",
      "payload_example": {
        "event_id": "EVT_PAY_001",
        "event_type": "payment.completed",
        "data": {
          "external_payment_id": "EXT_PAY_mock_001",
          "status": "SUCCESS",
          "external_trade_no": "BANK20260707160001"
        }
      },
      "mock": { "http_status": 200, "response": { "code": 200, "msg": "received" } }
    },
    {
      "id": "callback.tax_completed",
      "name": "完税证明回调",
      "direction": "platform_to_fe_server",
      "method": "POST",
      "path": "/api/v1/internal/callback/provider/tax-completed",
      "payload_example": {
        "event_id": "EVT_TAX_001",
        "event_type": "tax.withhold.completed",
        "data": {
          "external_tax_id": "EXT_TAX_mock_001",
          "certificate_url": "https://oss.mock.example.com/tax/EXT_TAX_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "response": { "code": 200, "msg": "received" } }
    },
    {
      "id": "callback.invoice_issued",
      "name": "发票开具回调",
      "direction": "platform_to_fe_server",
      "method": "POST",
      "path": "/api/v1/internal/callback/provider/invoice-issued",
      "payload_example": {
        "event_id": "EVT_INV_001",
        "event_type": "invoice.issued",
        "data": {
          "external_invoice_id": "EXT_INV_mock_001",
          "invoice_no": "12345678",
          "pdf_url": "https://oss.mock.example.com/invoice/EXT_INV_mock_001.pdf"
        }
      },
      "mock": { "http_status": 200, "response": { "code": 200, "msg": "received" } }
    }
  ],
  "flow_bindings": [
    {
      "flow_step": "registration",
      "description": "临时工登记后实名核验",
      "endpoints": ["identity.verify.two_factor"],
      "callback": "callback.identity_verified"
    },
    {
      "flow_step": "contract_signing",
      "description": "创建并签署电子劳动合同",
      "endpoints": ["contract.create", "contract.sign_url", "contract.status"],
      "callback": "callback.contract_signed"
    },
    {
      "flow_step": "plan_confirmed",
      "description": "确认方案后提交用工需求至人力平台",
      "endpoints": ["requirement.create", "requirement.status"]
    },
    {
      "flow_step": "registration",
      "description": "登记人员同步至平台",
      "endpoints": ["worker.registration.sync"]
    },
    {
      "flow_step": "settlement_paid",
      "description": "结算打款与完税开票",
      "endpoints": [
        "settlement.create",
        "payment.batch",
        "tax.withhold.batch",
        "invoice.apply"
      ],
      "callbacks": [
        "callback.payment_result",
        "callback.tax_completed",
        "callback.invoice_issued"
      ]
    },
    {
      "flow_step": "ai_risk_diagnose",
      "description": "AI 风险诊断与政策问答（只读）",
      "endpoints": [
        "knowledge.policy.search",
        "knowledge.tax.search",
        "knowledge.contract.search",
        "knowledge.social_security.search"
      ]
    }
  ],
  "error_codes": [
    { "code": "SUCCESS", "http_status": 200, "biz_status": "succeeded", "message": "成功" },
    { "code": "PROCESSING", "http_status": 200, "biz_status": "processing", "message": "处理中" },
    { "code": "PENDING_AUDIT", "http_status": 200, "biz_status": "pending_audit", "message": "待审核" },
    { "code": "PENDING_SIGN", "http_status": 200, "biz_status": "pending_sign", "message": "待签署" },
    { "code": "REJECTED", "http_status": 200, "biz_status": "rejected", "message": "业务拒绝" },
    { "code": "INVALID_PARAM", "http_status": 400, "biz_status": "failed", "message": "参数错误" },
    { "code": "UNAUTHORIZED", "http_status": 401, "biz_status": "failed", "message": "鉴权失败" },
    { "code": "RATE_LIMITED", "http_status": 429, "biz_status": "failed", "message": "请求过于频繁" },
    { "code": "INTERNAL_ERROR", "http_status": 500, "biz_status": "failed", "message": "平台内部错误" }
  ],
  "fe_integration_notes": {
    "adapter_interface": "com.fe.integration.HrPlatformClient",
    "mock_impl": "MockHrPlatformClient（读取本 JSON 的 endpoints[].mock / response_success）",
    "log_table": "fe_provider_api_log",
    "log_fields_mapping": {
      "action": "endpoints[].fe_action",
      "request_payload": "实际请求 JSON",
      "response_payload": "response_success 或 response_fail",
      "biz_status": "mock.biz_status",
      "http_status": "mock.http_status"
    },
    "ai_knowledge_rule": "政策法规、税务、合同、社保知识禁止由大模型编造；必须通过 knowledge.* 接口获取或读取 fe_policy_rule 缓存。",
    "sensitive_data_rule": "调用第三方时传 enc 字段或平台侧 token；日志脱敏；小程序不展示 provider 技术细节。"
  }
}