认证与鉴权

系统采用「组织 Key + 用户 JWT」两级凭证体系：组织 Key 标识接入方系统，用于用户管理与签发凭证；用户 JWT 承载日常业务调用，实现按用户的配额控制、数据隔离与操作审计。

凭证签发流程

sequenceDiagram
    autonumber
    participant Biz as 业务系统
    participant API as DJWork API
    participant DB as 平台数据库

    Biz->>API: POST /api/v1/token（组织 Key + user_id）
    API->>DB: 查找用户（组织 + external_user_id）
    alt 用户不存在且组织允许自动注册
        API->>DB: 自动注册 ext_组织code_用户ID
    else 用户存在
        API->>DB: 校验 is_active / is_frozen
    end
    API-->>Biz: { token, expires_in, registered, user }
    Note over Biz: 缓存 Token，到期前静默换证
      

凭证类型

签发用户 Token

POST/api/v1/token —— 用组织 Key 为终端用户签发 JWT：

curl -X POST https://<host>:8000/api/v1/token \
  -H "Authorization: Bearer djk_<api_id>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"10086","nickname":"张三","expires_in":86400}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400,
  "registered": false,
  "user": {
    "id": 42,
    "username": "ext_erpsap_10086",
    "external_user_id": "10086",
    "is_active": true,
    "is_frozen": false
  }
}

• registered=true 表示本次自动注册了新用户；组织关闭 auto_register 时需先调 POST /api/v1/users 预创建。
• 用户被冻结（is_frozen）后已签发的 JWT 即时失效，业务接口返回 403。

调用业务接口

import requests

BASE = "http://<host>:8000"

# 1. 组织 Key 换取用户 JWT（可缓存复用）
r = requests.post(f"{BASE}/api/v1/token",
    headers={"Authorization": "Bearer djk_<组织Key>"},
    json={"user_id": "10086"})
token = r.json()["token"]
H = {"Authorization": f"Bearer {token}"}

# 2. 用用户 JWT 调用业务接口（以查询合同类型为例）
types = requests.get(f"{BASE}/api/contract-types", headers=H).json()

用户生命周期管理

最佳实践

• 缓存 Token：同一用户在有效期内复用 JWT；收到 401 或临近过期时，用 POST /api/v1/token 静默换新，不要每次请求都签发。
• 最小 scope：纯后端集成只申请 api；需要嵌入页面才加 page。
• 短时效 + 换证：高安全场景给 expires_in=300，由后端定时换证，Token 泄露风险窗口最小。
• 区分 401 / 403：401 是凭证问题（换证重试一次），403 是权限 / 冻结 / 配额问题（提示用户，不要重试）。

SSO 免登集成

为用户签发含 page scope 的 Token 后，用一条 URL 即可让用户免登录进入 DJWork 的任意页面，也支持 iframe 嵌入第三方门户。落地后 Token 会被写入页面登录态（localStorage.jwt_token），后续走站内正常会话。

免登流程

sequenceDiagram
    autonumber
    participant Biz as 业务系统（门户/iframe）
    participant SSO as DJWork /sso/enter
    participant Page as 目标页面

    Biz->>Biz: POST /api/v1/token
（expires_in=300, scope=page）
    Biz->>SSO: GET /sso/enter?token=xxx&redirect=/tasks
    SSO->>SSO: 校验 scope 含 page
    SSO->>SSO: 校验 redirect 在白名单内
    SSO->>SSO: 校验 Referer 域名白名单（iframe 场景）
    SSO-->>Page: 写入登录态并 302 到 /tasks
      

跳转 URL

https://<host>:8000/sso/enter?token=<用户JWT>&redirect=/tasks

iframe 嵌入

<iframe
  src="https://<host>:8000/sso/enter?token=<JWT>&redirect=/tasks"
  style="width:100%;height:900px;border:0">
</iframe>

嵌入时 DJWork 会校验请求的 Referer 是否在组织的域名白名单内，白名单外的页面会被拒绝，请提前向管理员登记你的门户域名。

推荐落地页

安全约束

• redirect 只允许白名单内的站内路径，不能跳转外部网站。
• SSO 场景建议单独签发短时效 Token（expires_in: 300 + scope: page），页面加载完成即换取登录态，暴露窗口最小。
• 历史的一次性票据接口 POST /api/v1/ticket 已软弃用（返回 410），请统一使用 Token 直跳。

合同审核集成

最常用的集成能力。整体为「提交任务 → 轮询进度 → 拉取结果 → 下载批注文档」四步，全部使用用户 JWT。文件解析、OCR、多轮 LLM 审核都在后台异步执行。

交互时序

sequenceDiagram
    autonumber
    participant Biz as 业务系统
    participant API as DJWork API
    participant W as Celery Worker

    Biz->>API: POST /api/tasks/submit（文件 + 参数）
    API-->>Biz: { tasks: [{ task_id, file_id, file_name }] }
    loop 轮询（2~3 秒）
        Biz->>API: GET /api/tasks/{task_id}/status
        API-->>Biz: { status: running, progress: 60 }
    end
    Biz->>API: GET /api/tasks/{task_id}/detail
    API-->>Biz: { score, issues[], ... }
    Biz->>API: GET /api/tasks/{task_id}/download
    API-->>Biz: 文件流（带批注报告）
      

第一步：提交审核任务

POST/api/tasks/submit（multipart/form-data）

curl -X POST https://<host>:8000/api/tasks/submit \
  -H "Authorization: Bearer <用户JWT>" \
  -F "files=@合同.docx" \
  -F "contract_type_code=sale" \
  -F "stance=party_a" \
  -F "intensity=standard"

{
  "tasks": [
    { "task_id": "a1b2c3d4", "file_id": "f9e8d7c6", "file_name": "合同.docx" }
  ]
}

第二步：轮询进度

GET/api/tasks/{task_id}/status，建议每 2–3 秒一次：

{ "task_id": "a1b2c3d4", "status": "running", "progress": 60,
  "message": "AI 审核中" }

{ "task_id": "a1b2c3d4", "status": "completed", "progress": 100,
  "result": { "file_id": "f9e8d7c6", "score": 78, "total_issues": 6 } }

• status 状态机：pending → queued → running → completed | failed。
• 扫描版 / 图片型 PDF 会先 OCR 再审核，可能持续数分钟，轮询超时建议放宽到 10 分钟以上。
• 另有进度轮询 GET /api/tasks/{task_id}/progress?access_token=<JWT> 和日志 SSE GET /api/tasks/{task_id}/log/sse?access_token=<JWT> 可选（均需用户 JWT，进度端点仅限任务归属者）。

第三步：获取审核结果

GET/api/tasks/{task_id}/detail 返回完整结果：

• score：合同风险评分（AI 综合评定）。
• issues[]：逐条问题，含风险等级（高 / 中 / 低）、条款维度（如"违约责任条款"）、原文定位、问题说明与修改建议。
• extracted_fields：本次审核顺带抽取的关键要素。

第四步：下载批注文档

GET/api/tasks/{task_id}/download 返回把问题以批注形式写回原文的文件（优先带批注 PDF，其次 DOCX），可直接转存到你的业务附件里。

完整 Python 示例

import time
import requests

BASE = "http://<host>:8000"
H = {"Authorization": "Bearer <用户JWT>"}

# 1. 提交
r = requests.post(f"{BASE}/api/tasks/submit", headers=H,
    files={"files": open("合同.docx", "rb")},
    data={"contract_type_code": "sale", "stance": "party_a",
          "intensity": "standard"}).json()
task_id = r["tasks"][0]["task_id"]

# 2. 轮询（最长 10 分钟）
deadline = time.time() + 600
while time.time() < deadline:
    s = requests.get(f"{BASE}/api/tasks/{task_id}/status", headers=H).json()
    print(s["status"], s["progress"])
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if s["status"] != "completed":
    raise RuntimeError(s.get("error") or "审核超时")

# 3. 结果与批注文档
detail = requests.get(f"{BASE}/api/tasks/{task_id}/detail", headers=H).json()
print("评分:", detail["score"], "问题数:", detail["total_issues"])
pdf = requests.get(f"{BASE}/api/tasks/{task_id}/download", headers=H)
open("审核报告_带批注.pdf", "wb").write(pdf.content)

超出用户并发上限返回 429、配额不足返回 403——建议提交前先调 GET /api/v1/users/{user_id} 查配额，或在界面提前置灰提交按钮。

其他能力集成

除合同审核外，其余能力同样遵循「提交 → 轮询 → 取结果」模式，可以直接复用同一套任务轮询封装。本页给出各能力的关键步骤与参数；逐字段定义见「API 文档」。

要素提取

1. GET/api/extractions/templates 获取提取模板（内置合同模板含甲乙方、金额、期限、付款方式等字段 schema，管理员可自定义）。
2. POST/api/uploads/quick 上传文件（multipart 字段 file），得到 file_id。
3. POST/api/extractions/quick 提交 file_id + template_id，发起异步提取。
4. 轮询 GET/api/extractions/{file_id}/status，完成后 GET/api/extractions/{file_id}/detail 获取逐字段抽取结果（含字段值与依据位置）。

文档比对

flowchart LR
    U1[上传 source
POST /api/doc-compare/upload] --> U2[上传 target
role=target]
    U2 --> S[启动比对
POST /api/doc-compare/start]
    S --> P[进度轮询
GET .../progress]
    P --> R[差异清单
GET .../result
逐页 + 统计]
      

• 上传时用 role 区分 source（原稿）/ target（对照稿），两份文件类型需一致（PDF vs 图片 vs DOCX）。
• 结果 page_diffs[] 按页给出差异类型（added / deleted / modified）与前后内容，stat 汇总三类数量。

智能脱敏

1. POST/api/redact/upload 上传 PDF，得到 file_id。
2. POST/api/redact/scan 发起扫描：profile 选规则集（contract 合同 / case 案卷 / all），detect_seals 可选同时检测印章。任务进入 scanning → reviewing。
3. GET/api/redact/{task_id}/detail 拉取分组候选敏感项（字段、原文、页码、置信度），在你的界面呈现复核清单。
4. POST/api/redact/apply 提交复核结论：blacklist（抹除）/ whitelist（保留）、date_mode（日期涂至季度 / 整年 / 不处理）、replacements（替换值）、manual_rects（人工框选补涂）等。
5. 轮询 /status 至完成，检查 verify_result.remaining（残留数应为 0），再取 /result 脱敏副本与 /report 脱敏报告。

脱敏生成副本后系统会自动做残留自检（OCR 复扫），verify_result: {total, remaining} 可直接用于你侧的质量卡点。

印章核验与 NJCA 审核（双通道）

这两个模块提供 /api/v1 单接口通道：组织 Key 直接调用（请求中带 user_id），无需先签发用户 JWT；用用户 JWT 调用亦可。

import requests, time

BASE = "http://<host>:8000"
KH = {"Authorization": "Bearer djk_<组织Key>"}

# 1. 创建核验任务（组织 Key 通道必带 user_id）
r = requests.post(f"{BASE}/api/v1/seal-verifications",
    headers=KH, data={"user_id": "10086"},
    files={"file": open("盖章页.pdf", "rb")}).json()
task_id = r["data"]["task_id"]

# 2. 轮询结果
while True:
    s = requests.get(f"{BASE}/api/v1/seal-verifications/{task_id}",
                     headers=KH).json()
    if s["data"]["status"] in ("completed", "failed"):
        break
    time.sleep(3)

# 3. 逐页印章明细：文字 / 类型 / 坐标 / 匹配状态
for page in s["data"]["result"]["pages"]:
    for seal in page["seals"]:
        print(seal["text"], seal["seal_type"], seal["match_status"])

NJCA 审核把 files[] 批量上传到 POST /api/v1/njca-audits，轮询 GET /api/v1/njca-audits/{task_id} 后得到 conclusion（通过 / 不通过 / 无法判定）、fail_reasons 与要素抽取明细（被授权人、证件有效期、委托单位、印章匹配等）。

知识库与 LLM 网关

• 知识库：POST/api/kb 建库 → POST /api/kb/{kb_id}/documents 上传文档（自动解析、分片、向量化）→ POST /api/kb/search 问答（返回 answer + 引用 chunks），或用 /api/kb/search/stream 做 SSE 流式。
• OpenAI 兼容网关：POST /llm/v1/chat/completions 在标准 OpenAI 协议上扩展 kb_ids / kb_top_k / web_search，任何 OpenAI SDK 只改 base_url 即可获得「RAG + 联网搜索」。

from openai import OpenAI

client = OpenAI(base_url="http://<host>:8000/llm/v1",
                api_key="<用户JWT>")
resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "电子签章流程是怎么设置的？"}],
    extra_body={"kb_ids": [2], "kb_top_k": 5},   # DJWork 扩展参数
    stream=False)
print(resp.choices[0].message.content)

MCP 接入

DJWork 把内置能力以 MCP（Model Context Protocol）工具开放：已接入 AI Agent 的系统（Claude、Cursor、自研智能体）把 DJWork 挂为 MCP 工具源后，Agent 即可自动发现并调用合同审核、智能提取、文档比对、印章核验、NJCA 审核、知识库、OCR、LLM 等 18 个工具，无需逐个封装 REST 接口。

端点与认证

客户端一键配置

先在 DJWork 个人中心 → API 密钥 新建一个个人密钥（dkp_ 开头，长期有效），替换下方配置里的占位密钥即可。配置里其余内容已写好，点右上角「复制」直接粘贴到对应客户端的 MCP 配置文件：

Claude Desktop / Cursor / 通用 mcpServers

{
  "mcpServers": {
    "djwork": {
      "type": "http",
      "url": "https://djwork.njca.com.cn/mcp/djwork/",
      "headers": {
        "Authorization": "Bearer dkp_替换为你的个人API密钥"
      }
    }
  }
}

Claude Desktop 写入 claude_desktop_config.json；Cursor 写入 ~/.cursor/mcp.json（或设置 → MCP → Add server）；Cline / 其他兼容客户端同名结构。私有部署把 url 换成自己的域名即可。

仅支持 stdio 的客户端（mcp-remote 桥接）

客户端不支持 HTTP 传输时，用官方 mcp-remote 桥接（需本机 Node.js ≥ 18）：

{
  "mcpServers": {
    "djwork": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://djwork.njca.com.cn/mcp/djwork/",
        "--header",
        "Authorization: Bearer dkp_替换为你的个人API密钥"
      ]
    }
  }
}

JWT 也可用于 Authorization（短期令牌），但会过期；写进静态配置请用 dkp_ 个人密钥。密钥等同本人身份，请勿外传，泄露后在个人中心立即吊销。

知识库检索（kb_search）

知识库工具默认在密钥权限范围内自动检索（本人私有 + 组织共享 + 公开库），也可以按名称指定知识库让 AI 精确查找，并内置多轮 + 关联词句增强召回（自动查询扩展 → 多路并行召回 → 关键词精确补充 → 覆盖不足时二轮检索 → 统一重排），无需手工拆分查询：

不想写配置？个人中心「应用工具」页签可直接下载知识库检索 Skill 包（SKILL.md 标准格式，含 MCP 配置与零依赖检索脚本），下载时选择一个 API 密钥打包进去即可分发给外部 AI 使用。接口细节见API 文档 · MCP 服务。

文件输入约定

外部系统没有服务器路径，标准流程是先用 REST 上传文件换取 file_id，再在 MCP 工具里传 file_id：

sequenceDiagram
    participant E as 外部系统
    participant R as DJWork REST
    participant M as DJWork MCP
    E->>R: 1. POST /api/uploads/quick 上传文件（用户 JWT）
    R-->>E: 2. 返回 file_id
    E->>M: 3. call_tool（传 file_id）
    M-->>E: 4. task_id
    E->>M: 5. 轮询 *_status / *_get
      

工具清单

Python 客户端示例

import asyncio, json, time
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

DJWORK_URL = "http://<host>:8000/mcp/djwork/"
JWT = "<用户 JWT>"   # 组织 Key 经 /api/v1/token 换证获得

async def main():
    async with streamablehttp_client(
        DJWORK_URL, headers={"Authorization": f"Bearer {JWT}"}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()

            # 1) REST 上传拿到 file_id 后，提交印章核验
            res = await session.call_tool("seal_verify_start", {"file_id": "<file_id>"})
            task_id = json.loads(res.content[0].text)["task_id"]

            # 2) 轮询结果（扫描件通常 1~5 分钟）
            while True:
                r = await session.call_tool("seal_verify_status", {"task_id": task_id})
                task = json.loads(r.content[0].text)["task"]
                if task["status"] in ("completed", "failed", "cancelled"):
                    print(json.dumps(task, ensure_ascii=False, indent=2))
                    break
                time.sleep(10)

asyncio.run(main())

常见错误

每个工具的完整参数定义见「API 文档」页第十六章《MCP 服务》。

限流与配额

为保障多接入方共存时的服务稳定，系统按组织 Key 与用户两个维度做限流与配额控制。接入方应把下述控制项纳入错误处理与重试策略。

控制项一览

推荐的重试策略

import time, requests

def call_with_retry(fn, refresh_token, max_retry=4):
    for i in range(max_retry):
        r = fn()
        if r.status_code == 429:          # 限流：指数退避
            time.sleep(2 ** i)
            continue
        if r.status_code == 401:          # 凭证过期：换证后重试一次
            refresh_token()
            return fn()
        return r
    raise RuntimeError("重试次数耗尽")

• 上传前先本地校验大小（≤50MB）与扩展名，避免 413 / 400 无效请求占用限流额度。
• 任务轮询设置总超时（建议审核 ≥10 分钟），超时后仍应以最终轮询到的终态为准。
• 组织聚合用量可通过 GET /api/v1/usage 定期拉取，用于你侧的用量看板与预警。

错误处理

所有接口通过 HTTP 状态码 + 统一错误体返回失败原因，语义稳定，建议在你的 SDK / 后端里做一次统一封装。

统一错误码

{ "detail": "并发任务数已达上限（3），请等待进行中的任务完成" }

提交成功的任务即使后续处理失败也会进入 failed 终态并附 error 原因（如文件损坏、格式不支持）——请以轮询终态为准更新业务状态，而不是以提交是否成功为准。