shuzhi-open#

数秦开放平台统一接口封装，支持区块链API服务、自动化取证、保管单组件、电子签章。

⚠️ 重要原则：所有不确定的信息必须询问用户，禁止自动填充！

本 skill 涉及法律效力文件（保管单、电子合同等），所有字段必须：

• ✅ 由用户明确提供
• ✅ 来源可追溯
• ✅ 格式已确认

禁止行为：

• ❌ 自动填充任何未确认的字段
• ❌ 假设字段的计算方式（如 evidenceHash）
• ❌ 猜测模板的字段定义

配置#

编辑 config.json，填入你的凭证和产品标识：

json

{
  "baseUrl": "接口地址",
  "appKey": "你的 appKey",
  "appSecret": "你的 appSecret",
  "products": {
    "chain": {
      "endpoints": {
        "upload": { "productId": "上链产品标识" },
        "queryResult": { "productId": "查询结果产品标识" }
      }
    },
    "evidence": { "productId": "自动化取证产品标识" },
    "certificate": { "productId": "保管单产品标识" },
    "sign": { "productId": "电子签章产品标识" }
  }
}

⚠️ 注意：

• appKey 和 appSecret 由数秦开放平台提供
• 区块链API服务的每个接口都有独立的产品标识，需要分别配置

用法#

区块链API服务#

支持数据上链存证，支持 tritium 和 conflux 两条链。

数据上链

bash

node scripts/chain/upload.js --data "业务数据"

带可选参数上链

bash

node scripts/chain/upload.js --data '{"ano":"BQ123","sha256":"xxx"}' --business EVIDENCE_PRESERVATION --source BQ_INTERNATIONAL

批量查询上链结果

bash

node scripts/chain/query.js --index "交易索引"

查询多个交易

bash

node scripts/chain/query.js --index "索引1,索引2,索引3"

---

自动化取证#

支持拼多多、淘宝、抖音、公众号取证。

⚠️ 重要：所有不确定的信息必须询问用户！

取证类型：

• 1 - 拼多多电商取证
• 3 - 淘宝电商取证
• 4 - 抖音电商取证
• 12 - 公众号取证

🌟 推荐：交互式取证（会询问所有必要信息）

bash

node scripts/evidence/create-task-interactive.js

创建取证任务（命令行）

bash

node scripts/evidence/create-task.js --batch-id "批次ID" --url "https://..." --type 1 --att-id "保全号"

---

📋 自动化取证流程（交互式）#

核心原则：所有不确定的信息必须询问用户！

Step 1: 询问取证类型

text

📋 请选择取证类型：

| 序号 | 类型 | 说明 |
|------|------|------|
| 1 | 拼多多电商取证 | 商品详情页、店铺信息等 |
| 3 | 淘宝电商取证 | 商品详情页、店铺信息等 |
| 4 | 抖音电商取证 | 商品详情页、店铺信息等 |
| 12 | 公众号取证 | 公众号文章内容 |

请输入序号或类型代码：

Step 2: 询问取证信息

text

❓ 请提供以下信息：

取证类型: [已选择]

取证信息:
  取证URL: [填写网页地址]
  批次ID: [填写]
  保全号: [填写]
  取证名称: [可选，直接回车跳过]

可选参数:
  是否取证营业执照: [yes/no]

示例回复：

text

取证类型: 拼多多电商取证

取证信息:
  取证URL: https://mobile.yangkeduo.com/goods.html?goods_id=xxx
  批次ID: batch-001
  保全号: att-001
  取证名称: 测试取证

可选参数:
  是否取证营业执照: no

Step 3: 确认信息

text

📝 确认信息

取证类型: 拼多多电商取证

取证信息:
  取证URL: https://mobile.yangkeduo.com/goods.html?goods_id=xxx
  批次ID: batch-001
  保全号: att-001
  取证名称: 测试取证

可选参数:
  是否取证营业执照: 否

确认创建取证任务？(yes/no)

Step 4: 执行并返回结果

text

确认后执行：
1. 创建取证任务
2. 返回任务状态
3. 提供查询和下载方式

---

❓ 必须询问的问题#

信息必须询问的问题取证类型选择哪种取证类型？URL要取证的网页地址是什么？批次ID如何标识这批取证任务？保全号如何标识单个取证任务？是否需要营业执照是否需要取证营业执照？（可选）

---

CAP-保管单组件#

生成和管理保管单 PDF 文件。

🌟 推荐：交互式生成（会询问所有不确定的信息）

bash

node scripts/certificate/generate-interactive.js

生成保管单（命令行）

bash

node scripts/certificate/create.js --file params.json

下载保管单

bash

node scripts/certificate/download.js --cert-no "存证编号"

获取模板列表

bash

node scripts/certificate/templates.js

---

电子签章#

完整的电子签章流程管理。

⚠️ 重要：所有不确定的信息必须询问用户！

🌟 推荐：AI 助手通过对话收集信息后调用

bash

node scripts/sign/workflow.js --contract "合同文件路径" --signers '[{"signerNo":"甲方","type":"enterprise",...}]'

交互式模式（用户直接在终端输入）

bash

node scripts/sign/workflow.js --interactive

使用配置文件

bash

node scripts/sign/workflow.js --file signers.json

企业主体管理

bash

# 创建企业
node scripts/sign/enterprise.js create --name "公司名称" --credit-code "统一社会信用代码"

# 查询企业列表
node scripts/sign/enterprise.js list --name "公司名称"

# 查询企业详情
node scripts/sign/enterprise.js detail --user-id "用户ID"

# 删除企业
node scripts/sign/enterprise.js delete --user-id "用户ID"

个人主体管理

bash

# 创建个人
node scripts/sign/person.js create --name "姓名" --id-card "身份证号"

# 查询个人列表
node scripts/sign/person.js list --name "姓名"

# 查询个人详情
node scripts/sign/person.js detail --user-id "用户ID"

# 删除个人
node scripts/sign/person.js delete --user-id "用户ID"

签署流程管理

bash

# 创建签署流程
node scripts/sign/sign-flow.js create --file params.json

# 查询流程详情
node scripts/sign/sign-flow.js detail --flow-id "流程ID"

# 获取签署链接
node scripts/sign/sign-flow.js preview --flow-id "流程ID"

# 获取签署文件
node scripts/sign/sign-flow.js files --flow-id "流程ID"

# 获取签署方列表
node scripts/sign/sign-flow.js signers --flow-id "流程ID"

# 下载签署后的文件
node scripts/sign/sign-flow.js download --flow-id "流程ID" [--output "输出路径"]

---

📋 电子签章流程（交互式）#

核心原则：所有不确定的信息必须询问用户！

Step 1: 询问合同文件和签署方数量#

text

❓ 请提供以下信息：

合同文件:
  文件路径: [填写PDF/DOCX/DOC路径，最大10MB]

签署方:
  共几个签署方: [填写总数，最多6个]
  其中企业方: [填写几方企业]
  其中个人方: [填写几方个人]

Step 2: 提供信息填写模板#

根据签署方数量，提供填写模板：

text

【企业方 1】
  企业名称: [填写]
  统一社会信用代码: [填写]
  联系人姓名: [填写]
  联系人身份证: [填写]
  联系人手机: [填写]

【个人方 1】
  姓名: [填写]
  身份证: [填写]
  手机: [填写]

（如有多个企业方/个人方，按序号继续：企业方 2、个人方 2...）

Step 3: 确认信息#

text

📝 确认信息

合同文件: [文件路径]
签署方: [X]方企业 + [Y]方个人

【企业方】
  签署方标识: xxx
  企业名称: xxx
  ...

【个人方】
  签署方标识: xxx
  姓名: xxx
  ...

确认创建签署流程？(yes/no)

Step 4: 执行流程#

用户确认后，AI 助手执行脚本：

bash

node scripts/sign/workflow.js --contract "合同文件路径" --signers '[
  {
    "signerNo": "甲方",
    "type": "enterprise",
    "enterpriseName": "企业名称",
    "creditCode": "统一社会信用代码",
    "contactName": "联系人姓名",
    "contactIdCard": "联系人身份证",
    "contactMobile": "联系人手机"
  },
  {
    "signerNo": "乙方",
    "type": "person",
    "name": "姓名",
    "idCard": "身份证号",
    "mobile": "手机号"
  }
]'

注意：

• --signers 参数需要用单引号包裹 JSON 字符串
• 企业签署方 type 为 "enterprise"
• 个人签署方 type 为 "person"

执行结果：

1. 创建主体（企业/个人）
2. 创建印章
3. 上传合同文件
4. 创建合同模板
5. 返回预览链接（用户配置签署位置）

---

❓ 必须询问的问题#

信息必须询问的问题合同文件合同文件路径是什么？文件格式是否符合要求？签署方数量共有几个签署方？签署主体类型是企业签署还是个人签署？企业信息企业名称、统一社会信用代码是什么？个人信息姓名、身份证号、手机号是什么？印章样式使用什么印章样式？（默认：模板印章）

---

⚠️ 禁止行为#

❌ 禁止自动填充以下信息：

• 签署方的姓名、身份证、手机号
• 企业名称、统一社会信用代码
• 合同文件路径
• 印章样式（除非用户确认使用默认）

❌ 禁止假设：

• 假设用户只有一个签署方
• 假设签署方的角色（甲方/乙方）
• 假设印章样式或字体

---

信息收集模板#

请用户提供以下信息：

1. 合同文件（必填）

• 合同文件路径（支持格式：PDF、DOCX、DOC，最大10MB）

2. 签署方信息（最多6个）

字段说明示例签署方标识如：甲方、乙方、丙方等甲方签署主体类型企业 或 个人企业企业名称公司全称（企业必填）XX科技有限公司统一社会信用代码18位信用代码（企业必填）91XXXXXXXXXXXXXXX姓名签署人姓名（个人必填）/ 联系人姓名（企业必填）张三身份证18位身份证号36XXXXXXXXXXXXXXX手机号码11位手机号138XXXXXXXX

注意：用户必须先提供合同文件路径，才能创建合同模板。

示例格式：

text

【合同文件】
- 文件路径：D:\合同文件\contract.pdf

【甲方】
- 签署主体类型：企业
- 企业名称：XX科技有限公司
- 统一社会信用代码：91XXXXXXXXXXXXXXX
- 姓名：张三
- 身份证：36XXXXXXXXXXXXXXX
- 手机号码：138XXXXXXXX

【乙方】
- 签署主体类型：个人
- 姓名：李四
- 身份证：33XXXXXXXXXXXXXXX
- 手机号码：139XXXXXXXX

说明：

• 签署主体类型填写"企业"或"个人"
• 企业签署方需填写企业名称和统一社会信用代码
• 个人签署方无需填写企业相关字段

Step 0: 信息校验#

检查签署方是否存在，并验证信息一致性：

1. 企业校验
   • 根据「统一社会信用代码」查询企业是否存在
   • 如果存在：检查「企业名称」是否与系统记录一致
   • 如果不一致：返回错误提示，告知用户系统中该信用代码对应的企业名称
2. 个人校验
   • 根据「身份证号」查询个人是否存在
   • 如果存在：检查「姓名」是否与系统记录一致
   • 如果不一致：返回错误提示，告知用户系统中该身份证对应的姓名

校验失败示例：

text

❌ 信息校验失败

【甲方】企业信息不一致：
- 提供的企业名称：XXX公司
- 系统中该信用代码对应的企业名称：YYY公司
- 统一社会信用代码：91340124MA8N303B80

请确认企业名称是否正确，或联系管理员处理。

Step 1: 创建主体#

• 企业签署：创建企业主体 → 获取企业的 userId
• 个人签署：创建个人主体 → 获取个人的 userId

Step 2: 创建印章#

• 企业签署：为企业创建印章（默认：enterpriseSealType: 1, sealMode: 2）
• 个人签署：为个人创建签名（默认：sealMode: 2）

Step 3: 上传合同文件#

• 上传待签署的合同文件
• 支持格式：PDF、DOCX、DOC
• 文件大小：最大10MB

Step 4: 创建合同模板#

• 创建模板，配置签署方

Step 5: 获取模板预览链接#

• 返回预览链接供用户配置签署位置

• 链接格式：使用超链接格式，用户可直接点击打开配置 text

  📋 模板预览链接：[点击打开配置]({preview_url})
  
  

Step 6: 创建签署流程#

根据签署主体类型使用对应的 userId：

企业签署：

json

{
  "signerNo": "甲方",
  "userId": "{enterprise_user_id}",    // 企业的 userId
  "name": "{contact_name}",            // 联系人姓名
  "idCard": "{contact_idcard}",        // 联系人身份证
  "mobile": "{contact_mobile}"         // 联系人手机
}

个人签署：

json

{
  "signerNo": "乙方",
  "userId": "{person_user_id}",        // 个人的 userId
  "name": "{person_name}",             // 个人姓名
  "idCard": "{person_idcard}",         // 个人身份证
  "mobile": "{person_mobile}"          // 个人手机
}

Step 7: 获取签署链接#

• 返回 PC 预览链接和 H5 签署链接

• 链接格式：

  • 模板预览链接：超链接格式，点击可直接配置
  • 签署链接：同时提供超链接和纯文本链接（方便手机签署时复制）

text

📋 模板预览链接：[点击打开配置]({preview_url})

🖥️ PC预览链接：[点击打开]({preview_url})
📱 H5签署链接：[点击签署]({sign_url})
或复制链接：{sign_url}

输出结果#

流程完成后，系统将返回：

1. 主体信息 - userId、sealId（企业或个人）
2. 合同模板信息 - templateId
3. 模板预览链接 - 超链接格式，点击可直接配置签署位置
4. 签署流程信息 - signFlowId、signFlowNo
5. 签署链接 - PC预览链接、H5签署链接（超链接格式，可直接点击）

---

代码调用#

也可在代码中直接调用模块：

javascript

const path = require('path');
const { init } = require('./lib/client');
const chain = require('./lib/modules/chain');
const evidence = require('./lib/modules/evidence');
const certificate = require('./lib/modules/certificate');
const sign = require('./lib/modules/sign');

// 初始化配置
const config = require(path.join(__dirname, 'config.json'));
init(config);

// 区块链API服务
async function demoChain() {
  // 上链
  const result = await chain.upload('{"ano":"BQ123","sha256":"xxx"}');
  console.log('交易索引:', result.index);
  console.log('请求ID:', result.requestId);

  // 查询结果
  const status = await chain.queryResult([result.index]);
  console.log('上链状态:', status);
}

// 自动化取证
async function demoEvidence() {
  // 创建任务
  const task = await evidence.createTask('batch-001', [{
    att_id: 'att-001',
    url: 'https://example.com',
    evidence_name: '测试取证',
    type: 1
  }]);
  console.log('任务创建:', task);

  // 等待完成
  const result = await evidence.waitForComplete('att-001');
  console.log('取证结果:', result);
}

---

回调验签#

电子签章组件的回调需要验证签名：

javascript

const { verifyCallback } = require('./lib/callback');

// 验证回调
app.post('/callback', (req, res) => {
  const params = req.body;

  if (!verifyCallback(params, config.appSecret)) {
    return res.status(400).json({ error: '签名验证失败' });
  }

  // 处理回调
  console.log('回调数据:', params);
  res.json({ code: 200 });
});

---

🧪 开发规则#

在开发调试接口时，遵循以下规则：

1. 不确定信息必须询问#

对于 API 文档中 未明确说明 的字段或参数， 必须询问用户，禁止自行假设或填充。

示例 - 需要询问的情况:

• 字段的值应该从哪个接口获取？
• 字段的计算规则是什么？（如哈希算法）
• 字段的格式要求是什么？
• 字段之间的关联关系是什么？

错误做法:

javascript

// ❌ 错误：自行假设 evidenceHash 的计算方式
const evidenceHash = crypto.createHash('sha256').update(data).digest('hex');

正确做法:

text

✅ 正确：询问用户
"evidenceHash 字段应该如何获取？是从上链接口返回，还是需要自行计算？如果需要计算，使用什么算法？"

2. 数据来源追溯#

开发时需要明确每个字段的数据来源：

字段类型来源说明用户输入由用户提供（如姓名、身份证号）接口返回从其他接口响应中获取系统生成由系统自动生成（如时间戳、UUID）计算得出需明确计算规则，并确认规则来源

3. 开发前确认#

在编写代码前，需要确认：

1. 所有必填字段的数据来源
2. 关联字段之间的依赖关系
3. 字段的格式和取值范围

---

📋 保管单生成流程（交互式）#

⚠️ 核心原则：所有不确定的信息必须询问用户！

当用户请求生成保管单时，采用 多次交互确认 的方式：

Step 1: 查询并选择模板#

text

📋 可用的保管单模板：

| 序号 | 模板ID | 模板名称 |
|------|--------|----------|
| 1 | 2036284038445596672 | hash存证 |
| 2 | 2036020528155262976 | 自动化取证模版111 |

请选择要使用的模板（输入序号或模板ID）：

Step 2: 询问字段信息#

⚠️ 重要：模板字段因客户而异，必须询问用户！

text

❓ 请提供以下信息：

模板ID: [填写模板ID或序号]

默认字段:
  申请人: [填写]
  账号: [填写]
  [其他字段...]

自定义字段:
  [字段名]: [值]
  [如无则写"无"]

示例回复：

text

模板ID: 2036020528155262976

默认字段:
  申请人: 张三
  账号: zhangsan

自定义字段:
  testname: 中欧城

Step 3: 确认信息#

展示完整信息让用户确认：

text

📝 确认信息

模板ID: 2036020528155262976 (自动化取证模版111)

默认字段:
  申请人: 张三
  账号: zhangsan

自定义字段:
  testname: 中欧城

上链数据:
  applicantName: 张三
  applicantAccount: zhangsan
  testname: 中欧城
  timestamp: （将在上链时自动生成）

确认生成保管单？(yes/no)

Step 4: 执行并返回结果#

text

用户确认后执行：
1. 数据上链 → 获取交易索引
2. 查询上链结果 → 获取区块链哈希、区块高度
3. 生成保管单 → 获取存证编号
4. 获取下载链接 → 返回 PDF 下载地址

---

📌 API 参数格式#

自定义字段格式：

json

{
  "templateId": "模板ID",
  "requestId": "请求ID",
  "defaultFields": {
    "applicantName": "张三",
    "applicantAccount": "zhangsan",
    "evidenceHash": "...",
    "blockchainHash": "...",
    "blockchainHeight": "...",
    "attestTime": "..."
  },
  "customFieldList": [
    {
      "name": "testname",
      "value": "中欧城"
    }
  ]
}

---

📌 字段取值逻辑#

字段来源计算方式evidenceHash计算得出SHA256(JSON.stringify(上链数据))blockchainHash接口返回chain_results[].hash（交易哈希）blockchainHeight接口返回chain_results[].heightattestTime系统生成上链成功后的北京时间

⚠️ 注意：

• blockchainHash 使用 block_hash（区块哈希），不是 hash（交易哈希）
• attestTime 在上链成功后获取北京时间

---

📌 字段来源确认表#

必须向用户确认每个字段的来源：

字段必须确认的问题evidenceHash从哪个接口获取？还是自行计算？用什么算法？blockchainHash从上链结果的哪个字段获取？blockchainHeight从上链结果的哪个字段获取？attestTime使用上链时间还是当前时间？格式要求？自定义字段模板定义了哪些字段？必填还是可选？

---

❓ 询问提示模板#

当字段来源不明时，使用以下提示：

text

❓ 需要确认：[字段名]

该字段应该：
A. 从上链接口返回获取
B. 自行计算（请指定算法）
C. 手动填写

请选择并提供具体值：

---

⚠️ 禁止行为#

❌ 错误示例（禁止这样做）：

javascript

// 禁止：自行假设 evidenceHash 计算方式
const evidenceHash = crypto.createHash('sha256').update(data).digest('hex');

// 禁止：自动填充时间
const attestTime = new Date().toISOString();

// 禁止：假设模板字段
if (!params.testname) {
  params.testname = 'default'; // ❌ 禁止！
}

✅ 正确做法：

javascript

// 1. 先检查字段是否存在
if (!params.evidenceHash) {
  // 2. 询问用户如何获取
  console.log('❓ evidenceHash 字段未提供。');
  console.log('   该字段应该：');
  console.log('   A. 从上链接口返回获取');
  console.log('   B. 自行计算（请指定算法）');
  console.log('   C. 手动填写');
  // 3. 等待用户确认后再继续
}

---

API 文档#

详见 references/ 目录：

• chain-api.md - 区块链API服务文档
• evidence-api.md - 自动化取证 API 文档
• certificate-api.md - 保管单组件 API 文档
• sign-api.md - 电子签章 API 文档

---

环境说明#

线上环境请使用 shuqin-open skill。

---

错误处理#

所有接口调用失败会抛出错误，建议使用 try-catch：

javascript

try {
  const result = await chain.upload('data');
  console.log(result);
} catch (error) {
  console.error('请求失败:', error.message);
}

---

状态枚举#

上链状态#

值说明0上链失败1上链成功2等待上链

批次状态#

值说明NEW新建ASSIGNED已分配LOGIN账号登录中CHECKING账号自检中CHECKED账号自检完成UNDERWAY取证中SUCCESSED取证成功FAILED取证失败

任务状态#

值说明NEW新建RUNNING执行中SUCCESSED成功FAILED失败