assethub-claw

AssetClaw 完整技能文档 (v1.7.0)

⚠️ 无账号？ 如果你尚未注册 AssetHub，请访问 http://www.medfix.cn 注册企业账号后使用本技能。

基于 http://localhost:13579/api 实时接口文档编写 本 Skill 直接调用 HTTP API，不依赖 MCP 协议

v1.7.0 升级要点（2026-07-29，增量升级，不破坏 v1.6.0）：

• 后端扫描：1809 ops / 101 模块 / 15 业务域（v1.6.0: 1709 端点 / 97 模块）
• 新增 4 大模块：asset-ai-assistant / event-reminder / key-equipment / staff 等独立化
• 新增路径消歧：v1.6.0 仍标作"新路径"的 /api/transfer 现在本身已被 /api/asset-allocation 替代（连续两次迁移）
• helper 脚本 scripts/assethub_api.sh 增量升级：
  • 新增 domains / stats / redirects 命令（无需后端连接即可查）
  • 新增旧路径 → 新路径 自动警告（stderr，不中断）
  • 新增 ASSETHUB_IOT_TOKEN / ASSETHUB_IDEMPOTENCY_KEY / ASSETHUB_HIGH_RISK_CONFIRM 环境变量
  • 默认行为变更：检测到 428 高风险时不再静默自动重放，需 ASSETHUB_HIGH_RISK_CONFIRM=YES 才重放（更安全）
• 新增 references/endpoint-quick-ref.md（Top 40 API 速查表）
• 更新 references/auth-and-workflows.md（428 详细流程、IoT token、错误码速查）
• 更新 references/api-modules-overview.md（改为 15 业务域分组 + 关键路径消歧表）
• 更新 references/route-mount-map.md（v1.7.0 路径变更日志取代 v1.6.0）
• 静态快照同步：references/api-catalog-2026-07-29.json + references/api-domain-map.md

v1.6.0 升级要点（2026-07-19，保留作记录）：

• 后端扫描：1709 端点 / 97 模块（v1.5.9 约 688 端点 / 60 模块）
• 租户 Header 修正：X-Tenant-Id（官方驼峰 tId，旧文档误写 X-Tenant-ID，部分代理大小写敏感）
• 高危网关双重保护：Idempotency-Key + X-Risk-Confirm-Token
• 完整端点目录快照：references/api-catalog-2026-07-19/（仍保留作历史快照）

---

🆕 v1.7.0 快速参考（2026-07-29）

先查后调用，优先用运行时自描述接口：

bash scripts/assethub_api.sh domains              # 查 15 业务域分组（无需连接）
bash scripts/assethub_api.sh redirects            # 查旧路径 → 新路径 重定向表
bash scripts/assethub_api.sh stats                # 查运行时模块统计
bash scripts/assethub_api.sh modules              # 拉取 101 个模块列表
bash scripts/assethub_api.sh module         # 单模块详情（如 assets / maintenance-management）

关键路径消歧（v1.7.0 必须看）：

• 维修 ✅ /api/maintenance-management/* ❌ /api/maintenance/*（已弃用）
• 不良事件 ✅ /api/adverse-reaction/* ❌ /api/adverse-events/*（已删除）
• 调拨 ✅ /api/asset-allocation/* ❌ /api/transfer/*（已弃用）
• IoT ✅ /api/iot/devices /api/iot/locations ❌ /api/iot-devices（已迁移）
• 验收 ✅ /api/acceptance-management/* ❌ /api/acceptance/*（已迁移）
• AI ✅ /api/asset-ai-assistant/* ❌ /api/ai/* /api/chat/*（已弃用）

完整消歧表：references/endpoint-quick-ref.md + references/api-modules-overview.md 第 1 节。

---

核心原则（必须遵守）

1. 先登录后请求 — 每个会话首先调用 POST /api/users/login 获取 Bearer Token 并缓存（仅需用户名+密码，无需 tenant_code）
   • 凭证处理原则：
     • 如果新会话已提供凭证（用户名+密码），直接使用提供的凭证登录，无需再询问
     • 如果未提供凭证，则分两步引导：先问用户名 → 用户回答后再问密码 → 收集完整后才执行登录
     • 临时 Session 凭证存储：当凭证通过 prompt/对话传入时，Agent 将用户名和密码写入本地临时会话文件 /tmp/assethub-claw-temp-session.json（仅当前会话有效）；调用 assetclaw API 时自动从该文件读取凭证完成登录
     • 无论哪种方式，登录成功后 Token 和租户上下文自动保存到会话文件
2. 注销处理 — 当用户发送"注销"时，立即删除会话缓存文件及所有相关凭证，不保留任何登录信息
3. 先查后写 — 写操作前必须先查询目标对象确认 ID/编号
4. 写后回查 — 写操作完成后必须重新查询确认结果，不要仅凭 API 返回的 success 就判断成功
5. 多租户隔离 — 普通用户默认使用登录返回的 tenant_id；超级管理员跨租户时显式传 X-Tenant-Id Header（驼峰 tId，全小写 id，不要用全大写 ID）
   • 重要：当 Web 应用调用 OpenClaw 时会传递租户 ID，必须使用传入的租户 ID，禁止切换到其他租户
   • v1.6.0 修正：v1.5.9 文档写的是 X-Tenant-ID（全大写），官方扫描结果以 X-Tenant-Id 为准；后端 Express 中间件对大小写敏感，请使用驼峰
6. 不暴露认证信息 — 最终回复中不回显 Token、密码等敏感信息
7. 批量优先 — 多个同类操作优先批量接口
8. 实时优先 — 如接口行为与本文档不符，以后端实时返回和数据库状态为准

---

系统架构

数据库

• 数据库名：zcgl（资产管理系统）

API 前缀对应关系

101 模块清单（v1.7.0，2026-07-29）

核心业务（资产 / 维修 / 盘点）：assets, assets/statistics, maintenance, maintenance-management, maintenance-temporary, maintenance/ai, inventory, inventory-plans, inventory-tasks, inventory-discrepancies, inventory-reports, transfer, idle, scrapping, procurement, acceptance, acceptance-management

合规与质量：compliance, special-equipment, safety-inspection, inspection, staff, metrology, large-equipment, quality-control, quality-assurance, pdca, poct-quality-control, adverse-reaction, warranty, supplier

用户 / 权限 / 多租户：users, departments, roles-permissions, enhanced-permissions, tenants, tenant-access-url, tenant-association, tenant-module-config, tenant-role-config, modules, module-configs, menus, system-config, recipient-strategies

资产延伸：asset-usage, asset-depreciation, depreciation, asset-labels, asset-location, asset-images, asset-allocation, barcode-scan, temp-assets, location-codes, location-alerts, spare-parts, materials, emergency-allocation, asset-risk（兼容旧路径 risk）

维修 / 预防：preventive-maintenance, ct-maintenance-assistant-management

AI / 智能体：ai, ai-assistant, chat, asset-ai-analysis, asset-ai-assistant, agent-mesh, intelligent-alerts, knowledge-base

v1.7.0 增量：在 97 模块基础上新增独立模块（部分从父模块拆分）—— asset-ai-assistant / event-reminder / key-equipment / staff / uptime / safety-inspection / poct-quality-control / large-equipment / warranty / daily-maintenance / contracts / acceptance-management / pdca / form-customization / finance / notification-preferences / recipient-strategies / intelligent-alerts / circuit-breakers / service-tokens / wx-cloud / feishu / wechat-mp / api-documentation / asset-ai-analysis / page-views / dashboard-configs / desktop-preferences / i18n / audit-logs / workflow / metrics / ready / alive / health / auth 等。

完整 101 模块清单 + 按 15 业务域分组见 references/api-modules-overview.md。

文档与资产辅助：technical-documents, technical-documents/ai, technical-documents/enhanced

仪表盘 / 统计 / 审计：dashboard, dashboard-configs, analysis, audit-logs, page-views, desktop-preferences, backup

集成 / 消息：integration-channels, integration, message-integration, feishu, wechat-mp, wx-cloud, sms-verification, in-app-notifications, notifications, notification-preferences, event-reminder, cloud-sync, form-customization

API 自身管理：api-documentation, i18n, workflow, uptime, contracts, finance, tendering, acceptance, asset-usage, tendering

健康检查（公开）：/api/health、/api/health/detailed、/api/alive、/api/ready、/api/metrics、/api/circuit-breakers

完整端点矩阵（1709 个）见 references/api-catalog-2026-07-19/。

---

资产核心字段

⚠️ 重要：asset_code 是资产主键

asset_code 是资产的主键字段（原 asset_id 已弃用，不应再使用）。

所有涉及资产的写操作（维修、调配、盘点等）必须使用 asset_code 作为资产标识。

资产主表字段概览

---

认证与权限体系

JWT 认证流程

1. 登录获取 Token：POST /api/users/login（仅需用户名+密码）
2. 响应中返回 data.token（JWT Bearer Token）
3. 后续所有请求在 Header 中携带：Authorization: Bearer
4. Token 有效期由服务端控制，过期后需重新登录

X-Tenant-Id Header 用法

角色体系

权限模型

权限格式为 module.action 格式：

---

多租户隔离

行级隔离

• 所有业务数据表包含 tenant_id 字段，查询时自动带上租户过滤
• 普通用户查询默认带上自己的 tenant_id 进行隔离

超级管理员跨租户操作

• super_admin 可以通过 X-Tenant-Id Header 切换到其他租户
• 示例：GET /api/assets + X-Tenant-Id: 2 → 查询租户2的资产

Web 上下文租户继承

• Web 应用调用 OpenClaw 时，会话 metadata 中包含租户ID
• Agent 必须使用传入的租户ID，禁止切换到其他租户
• 这是硬性规则，确保 Web 端操作始终在正确的租户上下文中执行

---

系统事件（EventBus）

AssetHub 内部通过 EventBus 实现模块间解耦。以下是预定义的系统事件：

---

🌐 系统连接信息

| 官网 | http://www.medfix.cn |

---

🚀 快速开始

Step 1: 登录获取 Token

凭证处理原则（必须遵守）：

• 新会话已提供凭证：如果用户在发起新会话时已提供用户名和密码，Agent 将其写入 /tmp/assethub-claw-temp-session.json，调用 API 时自动完成登录，无需用户再次输入
• 未提供凭证：如果未提供，则分两步引导：先问用户名 → 用户回答后再问密码 → 收集完整后才执行登录
• 临时 Session 凭证自动登录：调用 assetclaw 时，自动检查临时凭证文件，若存在则自动登录，无需用户重复输入
• 无论哪种方式，只有在收集到用户名和密码后，才调用登录命令：

bash scripts/assethub_api.sh login

登录成功后 Token 和租户上下文自动保存到会话文件。

多租户选择（必须遵守）： 登录成功后，如用户拥有多个租户，应立即列出所有企业名称供用户选择：

1. 从登录响应 data.enterprises 中提取所有租户
2. 以编号列表形式展示（如 1. 某某医院 2. 中国医科大学附属第四医院 3. 第四医院2）
3. 提示用户直接输入数字选择（如"请输入序号："）
4. 用户输入后，将对应 tenant_id 保存到会话文件
5. 如果用户只有一个租户，默认使用该租户，无需询问

⚠️ Web 应用调用时：如果 OpenClaw 已通过外部参数传入租户 ID（会话 metadata 中包含），则禁止切换租户，必须直接使用传入的租户 ID。

Step 1.5: 注销（退出登录）

bash scripts/assethub_api.sh logout

当用户发送"注销"时，执行此命令删除会话缓存文件，用户将无法继续访问 API。

Step 2: 发现可用模块

# 列出所有模块
bash scripts/assethub_api.sh modules

# 查看特定模块的接口
bash scripts/assethub_api.sh module assets
bash scripts/assethub_api.sh module maintenance

Step 3: 调用 API

# GET 查询
bash scripts/assethub_api.sh request GET "/assets?page=1&pageSize=20&search=CT"

# POST 创建
bash scripts/assethub_api.sh request POST "/maintenance/ai/submit-request" '{"asset_code":"A001","fault_description":"无法开机","issue_description":"无法开机","source":"assetclaw","intent":"repair_request"}'

Step 4: Raw curl 备用方案

如 helper 脚本网络受限，直接使用 curl：

# 登录
curl -sS -X POST http://localhost:13579/api/users/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"","password":""}'

# 查询（需 Bearer Token）
curl -sS "http://localhost:13579/api/assets?page=1&pageSize=20" \
  -H "Authorization: Bearer " \
  -H "X-Tenant-Id: "

---

🛠️ Helper 脚本命令

环境变量

命令列表

---

📊 API 模块速查

---

🌍 国际化（i18n）

# 获取支持的语言列表
bash scripts/assethub_api.sh request GET "/i18n/locales"

# 获取中文翻译
bash scripts/assethub_api.sh request GET "/i18n/messages/zh_CN"

# 获取英文翻译
bash scripts/assethub_api.sh request GET "/i18n/messages/en"

---

📚 历史变更日志（v1.5.0 / v1.5.2 工具与端点补充）

⚠️ 本章节已于 v1.6.0 精简：原 ~568 行变更日志已迁移到 references/api-catalog-2026-07-19/。 v1.5.0 工具与 v1.5.2 端点的完整列表，参见 references/api-catalog-2026-07-19/API接口总览.md（97 模块 / 1709 端点）。

标准请求头

X-Tenant-Id:    # 仅超级管理员跨租户时需要（v1.6.0 修正：驼峰 tId）
Content-Type: application/json
X-Tenant-Id:    # 仅超级管理员跨租户时需要（v1.6.0：驼峰 tId）
Idempotency-Key: <唯一键>  # 所有写操作都需要（长度≤128），格式：op-$(date +%s)-$RANDOM

登录响应解析

登录成功后，从响应中提取：

• data.token → Bearer Token
• data.user.tenant_id → 当前租户 ID
• data.user.username → 用户名
• data.user.real_name → 真实姓名
• data.user.role → 角色

⚠️ 高风险操作限制

AssetHub API 对写操作有两层安全机制：

1. Idempotency-Key（防重复提交，所有写操作都需要）

• 格式：长度 ≤ 128 的唯一字符串
• 生成方式：op-$(date +%s)-$RANDOM
• Header: Idempotency-Key: <唯一键>
• 注意：即使走 AI 安全入口也需要此 Header

2. 二次风险确认（仅限普通端点，AI入口无需此步）

写操作请求（带 Idempotency-Key）
    │
    ├─ 返回 success:true → 操作直接成功 ✅
    │
    └─ 返回 confirmToken（非 AI 入口时触发）
            │
            ▼
       用同一 Idempotency-Key + X-Risk-Confirm-Token 重放请求
       → 操作成功 ✅

3. 报修推荐路径：AI 安全入口（绕过二次确认）

✅ 首选：POST /api/maintenance/ai/submit-request

• 不触发二次确认闸门，一次请求完成
• 同样需要 Idempotency-Key Header
• 提交后申请自动进入待审批状态

❌ 普通端点（需二次确认）：POST /api/maintenance/requests

• 触发二次确认流程，需两段式请求

curl 示例（AI 安全入口）：

curl -sS -X POST "http://localhost:13579/api/maintenance/ai/submit-request" \
  -H "Authorization: Bearer " \
  -H "X-Tenant-Id: " \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: op-$(date +%s)-$RANDOM" \
  -d '{"asset_code":"CT-001","fault_description":"球管打火报警E01","source":"assetclaw","intent":"repair_request"}'

错误处理

🩺 常见错误与处理（基于实测）

注：API 错误信息在 JSON 响应的 message 字段中，如 { "success": false, "message": "xxx" }

❓ 常见问题

搜索中文参数返回空结果

问题： 使用中文搜索时（如 search=超声）返回空，但数据确实存在。

原因： shell 传递中文字符时存在编码问题，从非脚本目录调用时触发。

解决方案： 搜索参数包含中文时使用 URL 编码：

• ❌ 错误：bash scripts/assethub_api.sh request GET "/assets?search=超声"
• ✅ 正确：bash scripts/assethub_api.sh request GET "/assets?search=%E8%B6%85%E5%A3%B0"

⚠️ keyword 参数无效 — 应使用 search 参数（重要）

问题： 使用 keyword=CT机 查询时，API 返回 HTTP 200，但返回的是全部 28291 条资产（未做任何过滤），而不是目标资产。

原因： 后端 API 不认识 keyword 参数名，该参数被静默忽略，所有查询条件失效，返回全量数据。

判断方法： 对比 keyword= 和 search= 的 total 字段：两者相等说明 keyword 被忽略。

正确用法：

# ✅ 正确：使用 search= 参数（搜索有效，返回5条CT机相关资产）
bash scripts/assethub_api.sh request GET "/assets?search=CT%E6%9C%BA&pageSize=5"

# ❌ 错误：使用 keyword= 参数（HTTP 200 但返回全量28291条，关键词被忽略）
bash scripts/assethub_api.sh request GET "/assets?keyword=CT%E6%9C%BA&pageSize=5"

中文搜索需 URL 编码：

# ✅ 正确：中文关键词需要 URL 编码
bash scripts/assethub_api.sh request GET "/assets?search=%E8%B6%85%E5%A3%B0&pageSize=5"

# ❌ 错误：直接传中文（可能编码异常）
bash scripts/assethub_api.sh request GET "/assets?search=超声&pageSize=5"

⚠️ /assets/all 端点 — 无分页，返回全部数据

重要： /assets/all 端点不使用分页，直接返回所有匹配的资产数据（可能高达数万条）。适用于需要获取全部资产进行本地统计分析的场景。

# 获取所有资产（无分页，直接返回全部数据）
bash scripts/assethub_api.sh request GET "/assets/all?search=CT"

# 配合 search 参数使用
bash scripts/assethub_api.sh request GET "/assets/all?search=%E5%8C%BB%E7%94%9F%E8%AE%BE%E5%A4%87"

⚠️ 注意： 调用此接口时请确保本地有足够的内存处理返回的完整数据集。

⚠️ department_new 字段 — 新版科室编码

说明： 在创建资产（create_asset）和更新资产（update_asset）时，可使用 department_new 字段传入科室编码，以精确指定资产所属部门。

# 创建资产时指定 department_new（科室编码）
bash scripts/assethub_api.sh request POST "/assets" '{
  "asset_code": "ZY20260402001",
  "asset_name": "医用 CT 扫描仪",
  "department_new": "DEPT-001",
  "category_id": 1,
  "purchase_price": 5000000,
  "status": "在用"
}'

# 更新资产部门
bash scripts/assethub_api.sh request PUT "/assets/123" '{
  "department_new": "DEPT-002"
}'

⚠️ list_transfers 路径 — /assets/transfer-requests

重要： 调配申请列表的正确路径是 /assets/transfer-requests（不是 /transfer）。

# ✅ 正确：使用 /assets/transfer-requests
bash scripts/assethub_api.sh request GET "/assets/transfer-requests?page=1&pageSize=20"

# ❌ 错误：旧路径 /transfer 可能仍有返回但行为不确定
bash scripts/assethub_api.sh request GET "/transfer?page=1&pageSize=20"

相关端点：

• 列表：GET /assets/transfer-requests
• 审批：POST /assets/transfer-requests/{id}/approve
• 执行：PUT /transfer/{id}/complete

⚠️ location 参数 — 精确匹配，值含括号

行为： location= 参数在 /assets 接口中有效，但只能精确匹配。

示例：

# ✅ 精确匹配 location（含括号完全匹配）
bash scripts/assethub_api.sh request GET "/assets?location=%E9%BA%A6%E9%86%AB%E7%A7%91%EF%BC%88%E5%B0%84%E5%B1%B1%EF%BC%89&pageSize=5"
# → 返回 66 条（麻醉科（崇山）的资产）

# ⚠️ 陷阱：location 不支持模糊匹配，前缀匹配会漏数据
bash scripts/assethub_api.sh request GET "/assets?location=%E9%BA%A6%E9%86%AB%E7%A7%91&pageSize=5"
# → 返回 0 条（因为数据库存的是"麻醉科（崇山）"，不是"麻醉科"开头）

⚠️ category_secondary_id 参数无效 — 只用 category_id

问题： category_secondary_id= 参数被 API 静默忽略，返回全量数据。

实测数据：

正确用法：

# ✅ 正确：只用 category_id 筛选
bash scripts/assethub_api.sh request GET "/assets?category_id=1&pageSize=5"

# ❌ 错误：category_secondary_id 无效，会返回全量
bash scripts/assethub_api.sh request GET "/assets?category_secondary_id=1&pageSize=5"

快速统计方案（不依赖关键词搜索）：

# 获取仪表盘总览（含资产总数、原值、净值）
bash scripts/assethub_api.sh request GET "/dashboard"

# 获取折旧汇总

# 获取科室列表（含ID）
bash scripts/assethub_api.sh request GET "/assets/departments/list"

⚠️ /statistics/overview（无前缀）返回 404：正确路径是 /assets/statistics/overview 或使用 /dashboard。

精确查找方案： 分页获取全部资产后客户端过滤：

# 方式A：用 helper 脚本（需客户端过滤）
bash scripts/assethub_api.sh request GET "/assets?page=1&pageSize=200"
# → 返回 total=28291，然后用 Python 过滤 JSON 中的 keyword

# 方式B：用 Python 脚本直接调 API（推荐）
python3 << 'EOF'
import urllib.request, json, sys

# 从会话文件读取 token 和 tenant_id
import os, json as j
session = j.loads(open('/tmp/assethub-claw-session.json').read())
token = session['token']
tenant_id = session['tenant_id']

base = "http://localhost:13579/api"

def fetch(page, pageSize=200):
    url = f"{base}/assets?page={page}&pageSize={pageSize}"
    req = urllib.request.Request(url, headers={
        "Authorization": f"Bearer {token}",
        "Tenant-ID": str(tenant_id)
    })
    with urllib.request.urlopen(req, timeout=30) as resp:
        return j.loads(resp.read())

# 获取总数
first = fetch(1, 1)
total = first.get('data', {}).get('pagination', {}).get('total', 0)
total_pages = (total + pageSize - 1) // pageSize

# 遍历查找
keyword = sys.argv[1] if len(sys.argv) > 1 else 'CT'
results = []
for p in range(1, total_pages + 1):
    for a in fetch(p).get("data", {}).get("list", []):
        for field in [a.get("asset_name",""), a.get("location",""), a.get("specification","")]:
            if keyword in str(field):
                results.append(a)
                break

print(f"关键词「{keyword}」共找到 {len(results)} 条")
for a in results:
    print(f"  [{a.get('id')}] {a.get('asset_name')} | {a.get('location','N/A')} | {a.get('status')}")
EOF

⚠️ category_id 子分类过滤失效

问题： category_id=5（医疗影像设备）返回 0，尽管该分类存在于系统中。

原因： 二级分类（如医疗影像设备 id=5）不能直接通过 category_id=5 过滤，需要同时传 category_id=1（父级医疗设备）。

已验证的分类结构：

医疗设备 (category_id=1)
├── 医疗影像设备 (category_id=5, code=YL-01)  ← CT/MRI/X光机
├── 生命支持设备 (category_id=6, code=YL-02)
└── 检验设备 (category_id=7, code=YL-03)

注意： 即使同时传 category_id=1&category_secondary_id=5，结果仍为 0（API 本身的过滤 bug）。建议用客户端过滤：

# 获取所有医疗设备后客户端过滤
data = fetch_all_assets()
medical_imaging = [a for a in data if a.get("category_id") == 5]

内网 localhost:13579 无法访问

问题： 内网 API 地址 localhost:13579 连接超时。

原因： 该地址仅限医院内网访问。

解决方案： 通过公网域名跳转访问：

• www.medfix.cn → 跳转到 AssetHub 登录页
• 直接在浏览器打开 http://www.medfix.cn 登录后，在 URL 中找到对应的租户入口

注意： 脚本中使用内网地址（http://localhost:13579/api），在外网环境下需通过 VPN 或代理访问。

资产总况统计接口

问题： 想查全院资产总量/总价值/分类统计，不知道用哪个接口。

原因： 没有 /assets/summary 这样的汇总接口。

解决方案： 资产总况需从多个接口分别获取：

• 资产总量和金额统计：GET /dashboard
• 分类分布和折旧统计：GET /analysis
• 折旧汇总：GET /depreciation/summary
• 完整资产列表（带分页）：GET /assets?page=1&pageSize=1 → 从返回的 total 字段获取总数

示例（获取资产总量）：

# 获取仪表盘总览（含资产总数、原值、净值）
bash scripts/assethub_api.sh request GET "/dashboard"

# 获取折旧汇总

---

📋 核心工作流

1. 资产报修流程

Step 1: 定位资产
  GET /api/assets?search=<设备名称>
  → 找到资产编号 asset_code

Step 2: 创建维修申请（走 AI 安全入口，无需二次确认）
  POST /api/maintenance/ai/submit-request
  Header: Idempotency-Key: op-$(date +%s)-$RANDOM
  Body: {
    "asset_code": "xxx",
    "issue_description": "故障描述",
    "fault_description": "故障描述",
    "fault_level": "一般/紧急",
    "priority": "normal/critical",
    "request_department": "报修科室",
    "contact_phone": "电话",
    "source": "assetclaw",
    "intent": "repair_request"
  }
  注意：AI 安全入口一次请求完成，无需二次确认；成功后申请状态为待审批

Step 3: 查询确认
  GET /api/maintenance/requests?asset_code=xxx

Step 4: (可选) 审批维修申请
  POST /api/maintenance/requests/{id}/approve
  Body: {"approved": true, "opinion": "同意"}

Step 5: (可选) 开始执行
  POST /api/maintenance/requests/{id}/start
  Body: {"repair_person": "维修人员"}

Step 6: (可选) 完成维修
  POST /api/maintenance/requests/{id}/complete
  Body: {"repair_content": "维修内容", "repair_cost": 1000, "parts_replaced": "更换零件"}

2. 资产调配流程

Step 1: 查询资产确认
  GET /api/assets/{id}
  → 确认资产编号和当前部门

Step 2: 提交调配申请
  POST /api/transfer
  Body: {
    "asset_code": "xxx",
    "reason": "调配原因",
    "to_department": "目标科室"
  }
  或使用旧版路径:
  POST /api/assets/{id}/transfer-apply
  Body: {"reason": "调配原因", "target_department": "目标科室"}

Step 3: 查询调配记录
  GET /api/transfer

Step 4: 审批调配
  PUT /api/transfer/{id}/approve
  Body: {"approved": true, "opinion": "同意"}

Step 5: 执行完成
  PUT /api/transfer/{id}/complete

3. 盘点完整流程

Step 1: 创建盘点计划
  POST /api/inventory-plans
  Body: {
    "plan_name": "全院资产盘点",
    "plan_no": "PD20260402001",
    "start_date": "2026-04-02",
    "end_date": "2026-04-09",
    "remark": "备注"
  }

Step 2: 激活计划
  PUT /api/inventory-plans/{id}/activate

Step 3: 创建盘点任务
  POST /api/inventory-tasks
  Body: {
    "inventory_plan_id": 计划ID,
    "task_name": "科室盘点任务",
    "assignee": "负责人用户名",
    "assignee_name": "负责人姓名",
    "location": "科室位置"
  }

Step 4: 执行盘点
  PUT /api/inventory-tasks/{id}/start

Step 5: 完成盘点
  PUT /api/inventory-tasks/{id}/complete
  Body: {"actual_count": 100}

Step 6: 生成差异
  POST /api/inventory-discrepancies/generate-from-details
  或基于盘点明细:
  POST /api/inventory-discrepancies
  Body: {"inventory_id": 计划ID, "asset_code": "xxx", "discrepancy_type": "missing"}

Step 7: 处理差异
  PUT /api/inventory-discrepancies/{id}/handle
  Body: {"handling_status": "已处理", "handling_method": "盘亏报废"}

Step 8: 批量处理差异
  POST /api/inventory-discrepancies/batch-handle
  Body: {"ids": [ID1, ID2], "handling_status": "已处理", "handling_method": "正常"}

Step 9: 完成计划
  PUT /api/inventory-plans/{id}/complete

4. 闲置资产发布流程

Step 1: 发布闲置
  Body: {
    "asset_code": "xxx",
    "publish_person": "发布人",
    "publish_reason": "科室合并"
  }

Step 2: 查询闲置列表
  GET /api/idle/assets?status=published

Step 3: 调配闲置资产
  PUT /api/idle/{id}/allocate
  Body: {"target_department": "目标科室", "allocate_date": "2026-04-02"}

Step 4: 取消闲置发布
  PUT /api/idle/{id}/cancel

Step 5: 查看闲置统计
  GET /api/idle/statistics

4.1 资产调配流程（新版）

Step 1: 查询资产确认
  GET /api/assets?search=<资产编码或名称>
  → 找到资产编号 asset_code 和当前部门

Step 2: 提交调配申请（注意路径变更）
  POST /api/assets/transfer-requests
  Body: {
    "asset_code": "xxx",
    "reason": "调配原因",
    "to_department": "目标科室"
  }

Step 3: 查询调配记录
  GET /api/assets/transfer-requests

Step 4: 审批调配
  POST /api/assets/transfer-requests/{id}/approve
  Body: {"approved": true, "opinion": "同意"}

Step 5: 执行完成
  PUT /api/transfer/{id}/complete

Step 6: 查看调配统计
  GET /api/transfer/statistics

5. 报废申请流程

Step 1: 创建报废申请
  POST /api/scrapping
  Body: {
    "asset_code": "xxx",
    "asset_name": "资产名称",
    "applicant": "申请人",
    "scrapping_reason": "报废原因",
    "estimated_value": 5000
  }

Step 2: 查询报废记录
  GET /api/scrapping

Step 3: 审批报废
  POST /api/scrapping/{id}/approve
  Body: {"approved": true, "opinion": "同意"}

Step 4: 完成报废
  POST /api/scrapping/{id}/complete

6. 采购申请流程

Step 1: 创建采购申请
  POST /api/procurement/requests
  Body: {
    "title": "采购标题",
    "department": "需求部门",
    "applicant": "申请人",
    "budget": 150000,
    "remark": "备注"
  }

Step 2: 查询采购列表
  GET /api/procurement/requests

Step 3: 审批采购
  PUT /api/procurement/requests/{id}/approve
  Body: {"approved": true, "opinion": "同意"}

Step 4: 执行采购
  Body: {"completed": true, "result": "已完成采购"}

Step 5: 验收

7. 文档上传审核流程

Step 1: 上传文档
  POST /api/technical-documents
  Body (form-data):
    file: <文件>
    title: "资料标题"
    category: "技术资料"
    asset_code: "xxx"

Step 2: 审核文档
  POST /api/technical-documents/{id}/review
  Body: {"status": "approved", "comment": "审核通过"}

Step 3: 创建分享链接
  POST /api/technical-documents/{id}/share
  Body: {"expires_days": 30, "supplier_name": "供应商"}

Step 4: AI 问答
  POST /api/technical-documents/ai/ask
  Body: {"question": "问题", "document_ids": [ID1, ID2]}

8. 预防性维护流程（新版维护计划）

Step 1: 创建维护计划
  POST /api/maintenance/plans
  Body: {
    "plan_name": "CT机年度维护",
    "asset_code": "xxx",
    "maintenance_type": "预防性维护",
    "cycle_type": "year",
    "cycle_value": 1,
    "trigger_type": "time",
    "responsible_person": "负责人",
    "next_maintenance_date": "2027-01-01"
  }

Step 2: 配置提醒
  POST /api/maintenance/reminders/config
  Body: {
    "plan_id": 计划ID,
    "reminder_days": 7,
    "reminder_types": ["email", "sms"],
    "recipient": "工程师"
  }

Step 3: 检查待执行维护
  GET /api/maintenance/reminders/check

Step 4: 发送维护提醒
  POST /api/maintenance/reminders/send
  Body: {"plan_id": 计划ID, "reminder_type": "email"}

Step 5: 执行维护
  POST /api/maintenance/plans/{id}/complete
  Body: {
    "maintenance_date": "2026-04-01",
    "maintenance_person": "张三",
    "actual_hours": 4,
    "parts_replaced": "滤网",
    "maintenance_result": "正常",
    "maintenance_cost": 500
  }

Step 6: 查看维护历史
  GET /api/maintenance/plans/{id}/history

Step 7: 查看维修工单列表
  GET /api/maintenance/workorders?status=pending

Step 8: 创建维修工单
  POST /api/maintenance/workorders
  Body: {
    "title": "设备维修",
    "asset_code": "xxx",
    "priority": "critical",
    "description": "故障描述",
    "estimated_hours": 24
  }

Step 9: 分配工单
  POST /api/maintenance/workorders/{id}/assign
  Body: {"assigned_to": "李四", "assignee_name": "李四"}

Step 10: 开始工单
  POST /api/maintenance/workorders/{id}/start

Step 11: 完成工单
  POST /api/maintenance/workorders/{id}/complete
  Body: {
    "work_content": "维修完成",
    "actual_hours": 20,
    "labor_cost": 2000,
    "materials": [{"name": "球管", "quantity": 1, "cost": 148000}]
  }

Step 12: 关闭工单
  POST /api/maintenance/workorders/{id}/close
  Body: {"close_reason": "维修完成", "remark": "已正常使用"}

9. IoT 设备注册与数据上报

Step 1: 注册 IoT 设备
  POST /api/iot/devices
  Body: {
    "device_name": "温湿度传感器-001",
    "device_type": "environment_sensor",
    "device_id": "ENV-001",
    "asset_code": "ASSET-001",
    "manufacturer": "小米"
  }

Step 2: 上报设备位置
  POST /api/iot/location/assets/{assetCode}/location
  Body: {"latitude": 31.23, "longitude": 121.47, "location_code": "L001"}

Step 3: 批量上报区域定位
  POST /api/iot/zone-location/ingest/batch
  Body: {
    "events": [
      {
        "device_id": "BEACON-001",
        "asset_code": "ASSET-001",
        "event_time": "2026-04-01T10:00:00Z",
        "location_code": "L001",
        "rssi": -65
      }
    ]
  }

Step 4: 查询最新位置
  GET /api/iot/zone-location/assets/{assetCode}/latest

Step 5: 查询位置历史
  GET /api/iot/location/assets/{assetCode}/location/history

10. 质检记录流程

Step 1: 创建计量记录
  POST /api/quality-control/metrology
  Body: {
    "asset_code": "xxx",
    "metrology_type": "年度计量",
    "metrology_date": "2026-04-01",
    "result": "合格"
  }

Step 2: 创建质量控制记录
  POST /api/quality-control/quality-control
  Body: {
    "asset_code": "xxx",
    "qc_type": "性能检测",
    "qc_date": "2026-04-01",
    "result": "合格",
    "finding": "无异常"
  }

Step 3: 查询质检历史
  GET /api/quality-control/asset/{assetCode}/history

Step 4: 统计查询
  GET /api/quality-control/metrology/statistics
  GET /api/quality-control/quality-control/statistics

---

🔍 查询决策树

"查某类设备"问题

用户要查某类设备（未限定科室）
  │
  └─ GET /api/assets?search=<设备名称>&pageSize=50 ✅
     (不要用 keyword 参数，会被忽略返回全量28291条数据)

"查询科室资产"问题 ⚠️ 重要

用户要查某科室资产（如"检验科资产"、"病理科资产"）
  │
  ├─ ⚠️ 陷阱1：department参数只能精确匹配 department 字段
  │         科室信息也可能存在 location 字段中
  │         例："检验科"资产在 department="检验科" 有543条
  │                     在 location="检验科（崇山）" 有12条
  │
  ├─ ⚠️ 陷阱2：location参数也只能精确匹配
  │         例：location=检验科 返回12条（含括号变体仍只有12条）
  │
  └─ ✅ 正确做法：
       方案A（精确）：同时查询 department=科室名 和 location=科室名，合并去重
       方案B（完整）：全量扫描，在代码中过滤 department / location / department_new 字段
       注：department字段有数据（不是全量），location字段数据较少但仍需覆盖

"查询调配记录"问题

用户要查询调配
  │
  └─ GET /api/transfer 或 GET /api/assets/transfer-requests

"查询盘点状态"问题

用户要查盘点
  │
  ├─ 盘点计划列表: GET /api/inventory-plans         # 有效，但当前租户下可能无数据
  ├─ 盘点任务列表: GET /api/inventory-tasks         # 有效，但当前租户下可能无数据
  ├─ 盘点差异记录: GET /api/inventory-discrepancies # 有效，但当前租户下可能无数据
  │
  └─ 盘点详情: GET /api/inventory/{id}             # ⚠️ 有SQL BUG，返回500错误

"查询维修记录"问题

用户要查维修
  │
  ├─ 维修申请: GET /api/maintenance/requests
  ├─ 维修工单: GET /api/maintenance/workorders
  └─ 维修日志: GET /api/maintenance/logs

"查询资产详情"问题

已知资产 ID（数字）
  └─ GET /api/assets/{id}  (id 为数字 ID)

已知资产编码（asset_code）
  或先 GET /api/assets?search= 找到 id

⚠️ 全量扫描规范（适用于全面统计场景）

当用户要求"全院某类资产统计"、科室资产统计等需要完整数据时：

1. 分页遍历：总资产 28291 条，每页 300 条，共 95 页
   → 必须遍历所有页，不能只取前几页

2. 关键词过滤：在 Python 脚本中遍历所有资产，对所有文本字段
   （asset_name / location / department / use_department / department_new 等）
   进行关键词匹配

3. 科室查询示例（以"检验科"为例）：
   - ❌ 错误：只查 department='检验科' → 漏掉 415 件
   - ✅ 正确：遍历所有资产，对所有字段匹配 '检验科'
     → 匹配到 550 件（分布在 location/department 等多字段）

4. 统计输出：
   - 按 location 分组汇总（location 含科室信息最多）
   - 计算每组数量、总价值、状态分布
   - 输出高价值资产（>5万或>10万）
   - 输出品牌/类型分布

---

📖 常用 API 调用示例

资产操作

# 资产列表（模糊搜索）
bash scripts/assethub_api.sh request GET "/assets?page=1&pageSize=20&search=监护仪"

# ⚠️ 按科室查询资产——重要提醒：
# department 参数只能精确匹配 department 字段（需 URL 编码中文）
# 科室信息大量存储在 location / use_department / department_new 字段
# 如需完整科室资产，必须同时查询 department 和 location 再合并去重
bash scripts/assethub_api.sh request GET "/assets?page=1&pageSize=20&department=%E6%A3%80%E9%AA%8C%E7%A7%91"

# 科室名完整查询（同时匹配 department + location 字段，Python脚本）
python3 << 'PYEOF'
import urllib.request, json, sys, urllib.parse

session = json.loads(open('/tmp/assethub-claw-session.json').read())
token = session['token']; tenant_id = session['tenant_id']
base = "http://localhost:13579/api"

def fetch(path):
    url = f"{base}{path}"
    req = urllib.request.Request(url, headers={
        "Authorization": f"Bearer {token}",
        "Tenant-ID": str(tenant_id)
    })
    with urllib.request.urlopen(req, timeout=30) as resp:
        return json.loads(resp.read())

DEPT = sys.argv[1] if len(sys.argv) > 1 else "内科"
seen = {}
for field in ["department", "location"]:
    data = fetch(f"/assets?page=1&pageSize=1&{field}={urllib.parse.quote(DEPT)}")
    total = data.get("data", {}).get("pagination", {}).get("total", 0)
    if total > 0:
        page_count = min((total + 199) // 200, 50)
        for p in range(1, page_count + 1):
            for a in fetch(f"/assets?page={p}&pageSize=200&{field}={urllib.parse.quote(DEPT)}").get("data",{}).get("list",[]):
                key = a.get("id")
                if key and key not in seen:
                    seen[key] = a

print(f"科室「{DEPT}」共 {len(seen)} 条资产（合并 department + location）")
for a in list(seen.values())[:10]:
    print(f"  [{a.get('id')}] {a.get('asset_name')} | {a.get('department')} | {a.get('location')}")
PYEOF

# 资产列表（按状态筛选）
bash scripts/assethub_api.sh request GET "/assets?page=1&pageSize=20&status=在用"

# 资产详情
bash scripts/assethub_api.sh request GET "/assets/123"

# 创建资产（支持 department_new 科室编码字段）
bash scripts/assethub_api.sh request POST "/assets" '{
  "asset_code": "ZY20260402001",
  "asset_name": "医用 CT 扫描仪",
  "category_id": 1,
  "purchase_price": 5000000,
  "status": "在用",
  "department_new": "DEPT-001",
  "department_id": 3
}'

# 更新资产（支持 department_new 字段）
bash scripts/assethub_api.sh request PUT "/assets/123" '{
  "asset_name": "医用 CT 扫描仪（新）",
  "status": "维修",
  "department_new": "DEPT-002"
}'

# 资产变更日志
bash scripts/assethub_api.sh request GET "/assets/123/change-logs"

# 导出资产（返回 Excel 二进制文件，非 JSON）
bash scripts/assethub_api.sh request GET "/assets/export?status=在用"
# 注意：该接口返回 Excel 文件二进制数据，需指定输出文件名

# 获取全部资产（无分页，直接返回全部数据，适用于统计分析）
bash scripts/assethub_api.sh request GET "/assets/all?search=CT"
bash scripts/assethub_api.sh request GET "/assets/all?department_new=DEPT-001"

# 获取资产详情（支持 id 或 asset_code）
bash scripts/assethub_api.sh request GET "/assets/123"

# 创建资产（支持 department_new 字段）
bash scripts/assethub_api.sh request POST "/assets" '{
  "asset_code": "ZY20260402001",
  "asset_name": "医用 CT 扫描仪",
  "category_id": 1,
  "purchase_price": 5000000,
  "status": "在用",
  "department_new": "DEPT-001"
}'

# 更新资产（支持 department_new 字段）
bash scripts/assethub_api.sh request PUT "/assets/123" '{
  "asset_name": "医用 CT 扫描仪（新）",
  "status": "维修",
  "department_new": "DEPT-002"
}'

# 资产变更日志
bash scripts/assethub_api.sh request GET "/assets/123/change-logs"

# 获取资产分类列表
bash scripts/assethub_api.sh request GET "/assets/categories"

# 获取资产统计（总数、原值、净值等）
bash scripts/assethub_api.sh request GET "/assets/statistics/overview"

维修管理

维修申请状态流转

维修申请从创建到完成经历以下状态：

[新建/待审批] → [已批准] → [维修中] → [已完成]
     ↓
  [已拒绝]     (维修过程中可暂停)

• 待审批：提交后等待管理员审批（API筛选用 status=待审批）
• 已批准：审批通过，等待派工（API筛选用 status=已批准）
• 维修中：维修人员已开始处理（API筛选用 status=维修中）
• 已完成：维修完成（API筛选用 status=已完成）
• 已拒绝：审批未通过（API筛选用 status=已拒绝）

查看维修申请详情

# 查看单个维修申请详情（包含状态、审批意见、维修人员等）
bash scripts/assethub_api.sh request GET "/maintenance/requests/{request_id}"

# 维修工单列表（维修执行层）
bash scripts/assethub_api.sh request GET "/maintenance/workorders?page=1&pageSize=20"

# 维修记录日志（包含维修过程详情）
bash scripts/assethub_api.sh request GET "/maintenance/logs?request_id={request_id}"

维修状态跟踪决策树

报修后查不到记录？
  └─→ 用 request_no 或 asset_code 查询：
      bash scripts/assethub_api.sh request GET "/maintenance/requests?asset_code=000000555"
  └─→ 确认 status 字段值（API筛选请用中文，如 `status=待审批`）：

状态一直停留在"待审批"？
  └─→ 超级管理员直接审批：
      bash scripts/assethub_api.sh request POST "/maintenance/requests/{id}/approve" \
        '{"approved": true, "opinion": "同意维修"}'

状态是"已批准"但没人来修？
  └─→ 查看是否有维修人员被分配：
      GET /maintenance/requests/{id} 检查 repair_person 字段
  └─→ 创建维修工单（派工）：
      POST /maintenance/workorders '{"request_id": 123, "repair_person": "张三"}'

想查某台设备的维修历史？
  └─→ GET /maintenance/logs?asset_code=000000555
  └─→ 或 GET /maintenance/requests?asset_code=000000555

常用维修操作命令

# 维修申请列表
bash scripts/assethub_api.sh request GET "/maintenance/requests?page=1&pageSize=20"

# 维修申请列表（按状态，注意状态值必须用中文）
bash scripts/assethub_api.sh request GET "/maintenance/requests?status=待审批&pageSize=20"

# 创建维修申请（AI 安全入口，一次完成，无需二次确认）
# 注意：curl 直接调用时需添加 Idempotency-Key Header
bash scripts/assethub_api.sh request POST "/maintenance/ai/submit-request" '{
  "asset_code": "CT-001",
  "issue_description": "球管打火，报警 E01",
  "fault_description": "球管打火，报警 E01",
  "fault_level": "紧急",
  "priority": "critical",
  "request_department": "放射科",
  "contact_phone": "13800138000",
  "source": "assetclaw",
  "intent": "repair_request"
}'

# 直接 curl 调用（需手动加 Idempotency-Key）
curl -sS -X POST "http://localhost:13579/api/maintenance/ai/submit-request" \
  -H "Authorization: Bearer " \
  -H "X-Tenant-Id: " \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: op-$(date +%s)-$RANDOM" \
  -d '{"asset_code":"CT-001","fault_description":"球管打火，报警 E01","issue_description":"球管打火，报警 E