独立操作日志与运维日志

适用平台版本：2.00.091。

操作日志与运维日志使用平台独立接口和管理页面，不再作为项目管理内部的数据结构维护，也不存入设备 app_attrs。项目或设备页面可以保留入口，查询、保存、标签和附件操作均调用对应的独立日志能力，不能建立第二套项目日志存储。

设备关联

需要关联设备时使用日志的 eui 字段。项目级日志可以关联代表项目的设备。平台允许 EUI 留空，业务自行决定是否关联；不能把“可为空”实现成自动绑定当前列表第一台设备，也不能将设备 ID 或项目 ID 填入 eui。

设备关联未准备好时保留明确状态。若业务要求关联，则在关联准备好后再提交；若业务允许不关联，则按已核对的接口空值约定提交。当前设备下无日志不代表项目下或所有设备均无日志。

接口接入边界

能力	接入与验证要求
查询与保存	使用操作日志、运维日志各自独立接口，保存后重新查询核对
设备关联	分别验证有关联与 EUI 留空；项目日志验证代表设备映射
标签	通过日志保存维护 tags，find-tags 查询已使用标签；核对增改、移除和查询结果
附件	使用配套附件接口，核对上传、关联、读取、删除及权限，不以本地文件名代替已上传附件
页面入口	项目或设备页面链接到同一份平台日志，不复制存储

已核对的 18 个接口

发布 c08e93f5 对应平台 2.00.091，包版本仍为 1.25.5。所有接口均为 POST，业务平台鉴权头为 token: <TOKEN>；两类日志只访问 token 当前租户，不合并 PUBLIC。下表路径中的 {kind} 分别替换为 operation-log、maintenance-log。

方法与路径	操作日志 operationId	运维日志 operationId	请求／响应要点
POST /thinklink/{kind}/find-page	operationLogFindPage	maintenanceLogFindPage	current/pageSize 默认 1/20；返回分页，total 可能为十进制字符串
POST /thinklink/{kind}/batch-save-update	operationLogBatchSaveUpdate	maintenanceLogBatchSaveUpdate	dataList 完整记录 UPSERT；返回 {result:true,data:[{id}]}
POST /thinklink/{kind}/batch-delete-by-ids	operationLogBatchDeleteByIds	maintenanceLogBatchDeleteByIds	必填非空 ids 数组；返回含 rowCount/rows 的结果
POST /thinklink/{kind}/find-tags	operationLogFindTags	maintenanceLogFindTags	{}；返回 {data:[{tag}]}
POST /thinklink/{kind}/attachment-quota	operationLogAttachmentQuota	maintenanceLogAttachmentQuota	{}；返回 used_bytes/max_bytes
POST /thinklink/{kind}/attachment-list	operationLogAttachmentList	maintenanceLogAttachmentList	必填 id；返回 attachments 及配额
POST /thinklink/{kind}/attachment-upload	operationLogAttachmentUpload	maintenanceLogAttachmentUpload	multipart 必填 id/file；可选 attachment_id 替换、filename 改名；返回附件及配额
POST /thinklink/{kind}/attachment-delete	operationLogAttachmentDelete	maintenanceLogAttachmentDelete	必填 id/attachment_id；返回剩余附件及配额
POST /thinklink/{kind}/attachment-download	operationLogAttachmentDownload	maintenanceLogAttachmentDownload	必填 id/attachment_id；返回二进制附件

查询按 id/eui/title 等精确匹配，tags 要包含全部指定标签；无 project_id 过滤。空白或 null 条件被忽略，不能用空 eui 查询“未关联设备”。默认 create_time DESC，无第二排序键或跨页一致快照保证。

保存是整记录 UPSERT，不是补丁。 更新前读回并保留完整记录；遗漏 title/content/remark/extra 会置 null，遗漏 tags 会置 []。无 id 生成新 ID，有 id 但不存在也会插入。标签 trim、去空、去重，通过日志保存增改／移除，find-tags 仅查询已使用标签，没有独立标签注册表。普通保存不能修改附件：新记录附件为空，更新保留已有附件元数据。按响应 ID 回读；丢失新增响应时先按关联标记核查，不能盲目重试造成重复日志。

新增操作日志示例（不关联设备；<BASE_URL> 是业务平台地址，不是 MCP URL）：

curl -X POST '<BASE_URL>/thinklink/operation-log/batch-save-update' \
  -H 'token: <TOKEN>' -H 'Content-Type: application/json' \
  --data '{"dataList":[{"eui":null,"title":"巡检记录","content":"示例正文","tags":["巡检"]}]}'

EUI 可省略、null 或空白，空白归一为 null；调用方应核对真实设备关联。获取返回的日志 ID 后，先查询附件配额，再上传文件：

curl -X POST '<BASE_URL>/thinklink/operation-log/attachment-upload' \
  -H 'token: <TOKEN>' \
  --form 'id=<LOG_ID>' --form 'file=@<FILE_PATH>'

单文件及当前租户当前日志类型的附件合计上限均为 50 MiB；操作和运维分别计额，不是每条日志各 50 MiB。MinIO 未就绪为 503，日志／附件不存在为 404，超限为 413。替换保留附件 ID/create_time。SQL 提交后的对象清理失败可能留下孤立对象，删除成功不证明对象已清理；异常后回读列表和配额。MCP 下载还受调用器响应体上限约束，超限明确失败而非截断。

旧 projectLog* 仅保留兼容与迁移用途，不作为新日志存储。MCP 可发现／可准备不代表日志或附件已写入业务平台。

历史迁移与验收

迁移前登记旧项目日志表、数组、JSON 或其他来源，记录所属对象、旧记录 ID、目标日志类型、目标设备 EUI（或明确不关联）、标签、附件及调用入口。保存旧记录到新记录的映射，重试前核对已迁入内容，防止重复日志或重复附件。

先备份，再迁移日志、标签与附件关系。核对记录数量、业务内容、原有时间与操作者信息、设备映射、标签集合、附件数量及实际可读性；若新版接口不能保留某项历史信息，记录差异并处理后再切换，不能静默丢弃。迁移期间仍有新增日志时需核对增量。

通过独立页面及项目／设备入口读取同一条记录，验证新增、编辑、设备关联、标签和附件操作。历史日志、附件和增量核对完成后，才停用旧存储与入口。

分别报告源码适配、数据库迁移、部署、浏览器验收和 MQTT 联调状态。日志独立管理不代表存在自动 MQTT 日志推送；未联调就标记未验证。

参见微应用参数协议与三维迁移。