# 日志 SDK

应用的「留痕」：**版本**（每个版本号的更新状态、发布记录、语义版本）、**反馈**、**操作记录**（Action 与数据写入）、**使用情况**、**错误**。它是自提升 SDK 的原料：反馈 → 改进提案 → 新版本 → 反馈标记为已处理。

```js
import { log } from "/developer/sdk/v1/aidc.js";
```

## 平台自动记的

| 记录 | 什么时候 | 内容 |
| --- | --- | --- |
| `usage/open` | 每次打开应用（含公开链接） | 访客、版本、通道、经不经分享 |
| `action/<Action>` | 每次执行 Action | 参数、改前改后、一句话摘要；与对象的变化记录互相关联 |
| `action/data.*` | 开发者直接改数据、批量导入 | 改了什么、导入多少行 |
| `share/*` | 分享、撤销 | 对象、角色 |
| 版本与发布 | 部署 / 测试 / 发布 / 回滚 | 每个版本号的状态：已上线 / 测试中 / 已测未发 / 已被替换 / 已回滚 / 未测试 |

应用、版本、访客都从票据来，应用自己伪造不了。

## 应用自己记的

```js
log.track("filter", { line: "TJ01" });                         // 使用（不等结果、失败不打扰用户）
await log.feedback({ topic: "wording", rating: 3, message: "「累计合格」是当班还是当天？", object: { type: "production.order_line", pk } });
log.error(err, { where: "render" });                            // 前端错误
log.captureErrors();                                            // 自动上报没接住的错误（每类最多 10 条）
```

不要在 `data` 里放个人敏感信息（身份证、手机、银行卡、薪资…）；单条附加信息 ≤ 4 KB，每个访客每分钟 ≤ 120 条。使用与错误保留 180 天；反馈、操作、分享长期保留。

## 开发者：看

```js
const s = await log.summary({ days: 7 });          // 缺省当前应用
// s.counts / s.visitors / s.top（常用操作）/ s.usageByDay / s.openFeedback / s.recentErrors
// s.versions（每个版本号的状态）/ s.releases（发布记录）/ s.semantic（语义版本）
const open = await log.events({ kind: "feedback", status: "open" });
await log.setFeedbackStatus(open[0].id, "planned");            // open → planned → done / dismissed
```

```bash
aidc log summary tj8100-live --days 7
aidc log events --app tj8100-live --kind feedback --status open
aidc log feedback <记录 id> --status done
aidc app status tj8100-live     # 各版本号的更新状态
aidc app history tj8100-live    # 发布记录
```

## API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/v1/developer/log/{命名空间}/events` | 记 usage / feedback / error |
| GET | `/api/v1/developer/log/{命名空间}/events` | 查记录（开发者） |
| PATCH | `/api/v1/developer/log/{命名空间}/events/{id}` | 反馈处理状态 |
| GET | `/api/v1/developer/log/{命名空间}/summary` | 概况 + 版本状态 + 发布记录 + 语义版本 |