# n8n Workflow 说明（Phase 3–6 — 待实施）

> n8n 运行在现有 auto.hoelee.com（`bridge_hoelee` 网络）。它是同步器，不是 SOT。

## 依赖的 AList API（已源码验证，见 API_INTEGRATION.md）

- 登录换 token：`POST http://alist-serve-resource:5244/api/auth/login`
- User：`/api/admin/user/{list,get,create,update,delete,cancel_2fa}`
- Role：`/api/admin/role/{list,get,create,update,delete}`

## 需要的 Workflow

### WF1 — Customer Create（trigger: Customers 新记录）
1. 校验 customer。
2. 查重 username → 建/改 AList user（`base_path=/Class`，`role=[专属role]`，`permission=16384`）。
3. 建专属 role（`name=customer-<username>`，空 scopes）。
4. 用 `/api/admin/user/update` 把 user 绑定到新 role（显式传 role ID，勿留空）。
5. 回填 `alist_user_id` / `alist_role_id` 到 NocoDB。
6. `sync_status=synced`。

### WF2 — AccessGrant Create/Update（trigger: AccessGrants 记录变更）
1. 找 customer + resource path。
2. 判断当前日期 vs start_at/expires_at。
3. 若 active → 把该 path 并入该客专属 role 的 `permission_scopes`（permission=0）。
4. 若非 active → 不加入。
5. 整体 `post /api/admin/role/update` 重写 scopes（幂等）。
6. 记录 `sync_status` / `last_sync_at` / `last_sync_error`。

### WF3 — Expiry Sync（schedule: every 5 min）
1. 查所有 active/scheduled grants。
2. 计算 desired scopes（NocoDB 有效 grants 并集）。
3. 对比 AList 实际 scopes（`role/get`）。
4. 移除过期 scope、加入新生效 scope。
5. 若无剩余 active grant 且政策启用 → disable 该 customer（`user/update disabled=true`）。
6. 记录结果；失败发通知。

### WF4 — Full Reconciliation（schedule: daily）
- desired(NocoDB) vs actual(AList) 全量 diff，修复 AList，记录 reconciliation。

### WF5 — Customer Suspension（trigger: status=suspended）
- `user/update disabled=true` + 清空 role scopes；恢复时重算。

### WF6 — Customer Delete（soft delete）
- NocoDB `status=deleted`；AList 禁用用户 + 清空 scopes，不物理删除。

## 幂等规则（规格 §28）

所有操作 = get current → compare → apply diff。重跑不产生重复 user/role/scope。
更新 scope 一律「整体重写该 role 的 `permission_scopes`」。

## 待定项（实施时确认）

- n8n 内网访问 AList 的 host 名（预期 `http://alist-serve-resource:5244`）。
- 登录 token 缓存 / 刷新策略（JWT_EXPIRE=2h → 建议每次 workflow 起手先 login）。