Phase 1-3: AList stock deployment, NocoDB 7-table schema, W1/W2 n8n workflows + docs

docs/API_INTEGRATION.md

@@ -0,0 +1,259 @@
+# AList API 集成说明（源码级验证）
+
+> 规格文档 §11/§47 要求：不猜 API，不发明 endpoint。本文所有端点均已从
+> AList 上游源码（`AlistGo/alist`，`v3.63.0`）验证，而非仅凭文档目录猜测。
+
+## 1. 版本
+
+- 目标版本：`xhofe/alist:v3.63.0`（2026-08 最新稳定 release）
+- Role-scoped path aggregation + Check path limit 自 v3.53.0 起支持（规格 §48 要求已满足）。
+
+## 2. 认证
+
+```
+POST /api/auth/login
+Body: { "username": "admin", "password": "***" }
+响应: { "code": 200, "data": { "token": "<JWT>" } }
+```
+
+后续所有 Admin 请求带 header：
+
+```
+Authorization: <token>
+```
+
+## 3. 已验证的 Admin API
+
+源码位置：`server/router.go`（`admin(g *gin.RouterGroup)`）、`server/handles/user.go`、`server/handles/role.go`。
+
+### 3.1 User API
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/api/admin/user/list` | GET | 分页列出用户（`?page=&per_page=`） |
+| `/api/admin/user/get` | GET | `?id=` 取单个用户 |
+| `/api/admin/user/create` | POST | 建用户 |
+| `/api/admin/user/update` | POST | 改用户 |
+| `/api/admin/user/delete` | POST | `?id=` 删用户 |
+| `/api/admin/user/cancel_2fa` | POST | 撤销某用户 2FA |
+
+### 3.2 Role API（关键 —— 完整 CRUD 存在）
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/api/admin/role/list` | GET | 分页列出 role |
+| `/api/admin/role/get` | GET | `?id=` 取单个 role |
+| `/api/admin/role/create` | POST | 建 role |
+| `/api/admin/role/update` | POST | 改 role（含 `permission_scopes`） |
+| `/api/admin/role/delete` | POST | `?id=` 删 role |
+
+> ✅ 结论：Role scope 的增删改**可通过官方 API 完整实现**，无需 fork、无需
+> integration service（规格 §12 的 Option C 不需要走）。
+
+## 4. 数据结构（源码 `internal/model/`）
+
+### 4.1 Role
+
+```go
+type Role struct {
+    ID               uint              `json:"id"`
+    Name             string            `json:"name"`          // 唯一
+    Description      string            `json:"description"`
+    Default          bool              `json:"default"`
+    PermissionScopes []PermissionEntry `json:"permission_scopes"`
+}
+
+type PermissionEntry struct {
+    Path       string `json:"path"`        // 路径前缀，如 "/Class/A/1"
+    Permission int32  `json:"permission"`  // bitmask
+}
+```
+
+JSON 示例：
+
+```json
+{
+  "id": 5,
+  "name": "customer-alice",
+  "description": "Alice customer role",
+  "default": false,
+  "permission_scopes": [
+    { "path": "/Class/A/1", "permission": 0 },
+    { "path": "/Class/A/2", "permission": 0 }
+  ]
+}
+```
+
+### 4.2 User
+
+```go
+type User struct {
+    ID       uint   `json:"id"`
+    Username string `json:"username"`
+    Password string `json:"password"`      // create/update 时传入明文
+    BasePath string `json:"base_path"`
+    Role     Roles  `json:"role"`          // role-ID 数组
+    Permission int32 `json:"permission"`   // bitmask
+    Disabled bool   `json:"disabled"`
+}
+```
+
+JSON 示例（只读客户）：
+
+```json
+{
+  "id": 10,
+  "username": "alice",
+  "password": "***",
+  "base_path": "/Class",
+  "role": [5],
+  "permission": 16384,
+  "disabled": false
+}
+```
+
+## 5. Permission bitmask（源码 `internal/model/user.go`）
+
+| bit | 含义 | 对应 |
+|---|---|---|
+| 0 | 查看隐藏文件 | 1 |
+| 1 | 免密访问 | 2 |
+| 2 | 离线下载任务 | 4 |
+| 3 | mkdir / upload | 8 |
+| 4 | rename | 16 |
+| 5 | move | 32 |
+| 6 | copy | 64 |
+| 7 | remove / delete | 128 |
+| 8 | WebDAV read | 256 |
+| 9 | WebDAV write | 512 |
+| 10 | FTP login/read | 1024 |
+| 11 | FTP write | 2048 |
+| 12 | 读压缩包 | 4096 |
+| 13 | 解压 | 8192 |
+| **14** | **Check path limit** | **16384** |
+| 15 | MCP read | 32768 |
+| 16 | MCP write | 65536 |
+
+**本项目默认：**
+- `read-only` = bitmask **`0`**（不设 bit 3–7/9/11/13 等任何写权限）
+- `Check path limit ON` = 设 bit 14 → **`16384`**
+
+即客户 user 的 `permission` 字段 = `16384`（只读 + 路径限制），所有写位为 0。
+
+## 6. Role scope + Check path limit 的权限判定逻辑
+
+源码 `JoinPath()`（`internal/model/user.go`）证实：
+
+1. 用户 base path 只是登录后的默认落点，**不是 ACL**（规格 §2/§30）。
+2. 若用户 `CheckPathLimit()` 为真（bit 14 置位），请求路径必须落在该用户**任一 role
+   的任一 permission scope 的 path 之内**（前缀匹配），否则返回 `PermissionDenied`。
+3. 因此「Alice 只能进 /Class/A/1 与 /Class/A/2，进不了 /Class/A/3 与 /Class/B」
+   的正确实现 = Alice 专属 role 的 `permission_scopes` 只含这两个 path，且 user
+   `permission` bit 14 置位。
+
+## 7. 保护性约束（源码确认）
+
+- `admin` / `guest` role 受保护：`update`（改 admin 名/默认属性）与 `delete` 会被
+  `ErrChangeDefaultRole` 拒绝。客户 role 不受此限。
+- `CreateUser` 时若 `role` 空数组，会回填默认 role ID（`op.GetDefaultRoleID()`）。
+  **因此建客户时必须显式传其专属 role ID，不能留空。**
+- `UpdateUser` 若试图把用户 role 改成 admin/guest role，会被拒绝。
+- 至少保留 1 个 enabled admin，否则禁用最后一个 admin 会失败。
+
+## 8. 给 n8n 的实现要点（幂等，规格 §10/§28）
+
+- 建用户：先 `GET /api/admin/user/list` 按 `username` 查重，存在则 `update`，否则 `create`。
+- 建 role：先 `GET /api/admin/role/list` 按 `name` 查重，存在则 `update`（重写 `permission_scopes`），否则 `create`。
+- 更新 scope：`POST /api/admin/role/update`，整体重写该 role 的 `permission_scopes`
+  （desired state = NocoDB 当前有效 grants 的并集），天然幂等。
+- 到期撤销：从 desired scopes 里移除过期 path，再整体 `update` 该 role。
+- 禁用客户：`POST /api/admin/user/update` 设 `disabled: true`。
+- 删除客户：soft delete（NocoDB 侧 `status=deleted`），AList 侧禁用用户 + 清空 role scopes，不物理删除（保留审计）。
+
+## 9. Phase 3 实测验证（2026-08-22，对真实 v3.63.0 实例）
+
+> 以下为对 DSM 上运行中的 `alist-serve-resource`（v3.63.0，端口 5244）实际 curl 验证结果，
+> 修正/确认了上文的若干推断。
+
+### 9.1 认证 —— 登录带 2FA 时的字段
+
+源码 `server/handles/auth.go` 的 `LoginReq` 结构：
+
+```go
+type LoginReq struct {
+    Username string `json:"username" binding:"required"`
+    Password string `json:"password"`
+    OtpCode  string `json:"otp_code"`   // 2FA 开启时必填（TOTP 6 位）
+}
+```
+
+- 账户开启 2FA（`otp_secret` 非空）时，单次 `POST /api/auth/login` 不带 `otp_code`
+  直接返回 `{"code":402,"message":"Invalid 2FA code"}`。**是一步登录**，不是两步 challenge。
+- 登录成功返回：`{"code":200,"data":{"token":"<JWT>","device_key":"<md5>"}}`。
+- `GET /api/admin/user/list` 返回的员工 `password` 字段恒为 `""`（脱敏），`otp` 状态不在此端点，
+  需 `GET /api/me` 才见 `otp: true/false`。
+
+### 9.2 Role CRUD 实测返回值（修正 §3）
+
+| 端点 | 实测返回 | 备注 |
+|---|---|---|
+| `role/list` | `{"code":200,"data":{"content":[...],"total":N}}` | `PageResp` 包裹，非顶层数组 |
+| `role/create` | `{"code":200,"data":null}` | **不返回新建 role 对象**；需再 `role/list` 按 `name` 取 id |
+| `role/update` | `{"code":200,"data":null}` | 成功即 null；`role/get?id=` 可回读确认 |
+| `role/get?id=` | `{"code":200,"data":{...}}` | 返回完整 role 含 `permission_scopes` |
+| `role/delete` | **`POST /api/admin/role/delete?id=4`（id 走 query param）** | 用 JSON body 传 id 会 `400 strconv.Atoi: parsing "": invalid syntax` |
+
+- `role/delete` 与 `user/delete` **都必须 `?id=` query param**，不是 body。
+- `user/create`、`user/delete` 同样实测成功（返回 `data:null`）。
+
+### 9.3 admin 账户（当前实例）
+
+- 用户名 `hoelee`，角色 `admin`（role id 2，`permission 65535`，`permission_scopes` = `[{"/", 65535}]`）。
+- `guest` role（id 1）`disabled`，`permission 0`。
+- admin 登录曾开 2FA（已由用户关闭）；本系统若需 n8n 无人值守，**建议 admin 账户保持 2FA 关闭
+  或用独立 service token**——否则 n8n 每次登录都要算 TOTP。
+
+### 9.4 网络可达性（关键部署事实）
+
+- AList 容器名 `alist-serve-resource` 仅 Docker **网络内部**可解析。
+  **DSM host shell 无法解析该名字**（`Could not resolve host`），须用 `localhost:5244`。
+- n8n 容器在 `bridge_hoelee` 网络内，访问 AList 用 **`http://alist-serve-resource:5244`**（✅）。
+- 旧 `alist` 容器（v3.54.0）现在映射 host 端口 5243，新容器占 5244，无冲突。
+
+### 9.5 ⚠ JWT secret 不一致（待修复，否则 token 会失效）
+
+- 容器 env `JWT_SECRET=<redacted>=`（.env 传入），但 AList 初始化时写入 `data/config.json`
+  的 `jwt_secret` 是另一个值 `<redacted>`（首次启动自动生成）。
+- **env `JWT_SECRET` 只影响首次初始化**；服务运行后以 `config.json` 为准（当前生效的是
+  `<redacted>`）。两者不一致是正常的（env 在初次 init 时可能被 config 覆盖）。
+- 影响：若将来重建数据目录（清空 `data/`），.env 里的 `JWT_SECRET` 会生效；否则一直用 config.json 上的值。
+  **n8n 不关心这个**（每次 `login` 换 token），但需知悉「改 env 不会改已运行实例的 JWT」。
+- 若要统一：改 `data/config.json` 的 `jwt_secret` 并重启，或接受 config.json 为准。
+
+### 9.6 n8n 集成结论（Phase 3 通过 ✅）
+
+- admin 登录 token 可用，Role/User 全 CRUD 可用，scope 读写可用。
+- n8n workflow 实现要点（§8）全部成立，唯一补充：**delete 走 `?id=`**，**create/update 返回 null
+  需回查**（用 `list` 按 `name` 定位 id）。
+
+### 9.7 ⚠ `user/create` 空 role 会失败（Phase 4/W1 debug 实测，源码级确认）
+
+- **症状**：`POST /api/admin/user/create` 传 `"role": []` 时返回
+  `{"code":400,"message":"admin or guest user can not be created"}`，且与 username 无关（任意名字都失败）。
+- **根因**（`server/handles/user.go` `CreateUser`）：
+  1. `if len(req.Role) == 0 { req.Role = model.Roles{op.GetDefaultRoleID()} }` —— 空 role 被自动填为
+     **默认 role（guest，id=1）**。
+  2. 紧接着 `if req.IsAdmin() || req.IsGuest() { ... 400 ... }`，其中
+     `IsGuest()` = `Role.Contains(GUEST)`（`GUEST=1`）、`IsAdmin()` = `Role.Contains(ADMIN)`（`ADMIN=2`）。
+     role 现在是 `[1]`（guest）→ 判定为 guest → 拒绝。
+- **关键认知**：`IsGuest/IsAdmin` 判断的是 **role ID**，不是 username。错误信息里的 "admin or guest
+  user" 会误导向「用户名保留了」，实际是「role 里含 guest/admin ID」。
+- **正确顺序（必须）**：
+  1. `role/create`（name=`customer-<username>`，空 `permission_scopes`）→ 返回 200 但 `data:null`；
+  2. `role/list` 按 name 找到新建 role 的自增 id（3、4、5…）；
+  3. `user/create` 传 `"role": [<该 role id>]`（**非空、非 1/2**）→ 成功，`base_path` 正确。
+  - 实测：`role:[5]` 创建用户 `code 200`，`base_path:/Class`、`permission 16384` 均落地。
+- **适用**：W1 的「新建用户」路径必须先建 role；更新路径 `user/update` 里 `role:[]` 同样会触发
+  `GetDefaultRoleID` 回填（见 `UpdateUser` 同款逻辑），若客户已有 role id 应显式传入。
+- 相关常量：`GENERAL=0, GUEST=1, ADMIN=2, NEWGENERAL=3`（`internal/model/user.go`）；`permission`
+  bitmask 定义同文件注释（bit 14 = "check path limit" = 16384）。

docs/BACKUP_RESTORE.md

@@ -0,0 +1,27 @@
+# 备份 / 恢复
+
+> 重要区分（规格 §35）：AList 的 data/config 与 NAS 真实文件 `/volume1/Class` 是两回事。
+> 备份 AList ≠ 备份客户文件。
+
+## 需要备份
+
+| 对象 | 说明 |
+|---|---|
+| AList data/config | `/volume1/docker/alist-serve-resource/data`（含数据库、用户、role） |
+| `.env` | 加密备份，不落 Git 明文 |
+| docker-compose.yml + docs | 已入 Git（gitea） |
+| NocoDB 数据库 | 现成 DB 已有自动备份（你说过不用重复做） |
+| n8n 数据 | 现有 n8n 已有备份策略 |
+
+## 备份脚本占位
+
+`scripts/backup.sh` / `restore.sh` 在 Phase 9 补全。当前 AList 数据目录可直接
+tar 备份：
+
+```bash
+tar czf alist-serve-resource-data-$(date +%F).tar.gz -C /volume1/docker alist-serve-resource
+```
+
+## 恢复
+
+Phase 9 补充完整步骤（停止容器 → 还原目录 → 启动 → 跑 reconciliation）。

docs/CONFIGURATION.md

@@ -0,0 +1,27 @@
+# 配置说明
+
+## 环境变量
+
+全部见 `.env.example`。核心变量：
+
+| 变量 | 用途 |
+|---|---|
+| `JWT_SECRET` | AList 会话签名密钥（生产必换） |
+| `ALIST_URL` | n8n 访问 AList 的内网地址 |
+| `ALIST_ADMIN_USERNAME/PASSWORD` | admin 登录（换 token） |
+| `NOCODB_URL` / `NOCODB_TOKEN` | 业务 SOT |
+| `N8N_ENCRYPTION_KEY` | n8n credential 加密 |
+
+## AList 关键配置
+
+- `JWT_EXPIRE=2h`：session 有效期。
+- 不设 `ALIST_CUSTOM_CSS/JS`（stock）。
+- 端口映射 `5247:5244`（host → container）。
+
+## NocoDB / n8n
+
+- 复用现有运行中的 NocoDB（`https://nocodb.hoelee.com`）与 n8n（`https://auto.hoelee.com`），
+  本 compose **不重复部署**它们。
+- 只需在 NocoDB 建表（见 DATABASE_SCHEMA.md）、在 n8n 建 workflow（见 N8N_WORKFLOWS.md）。
+
+## 具体参数在实施 Phase 2/3 时补充。

docs/DATABASE_SCHEMA.md

@@ -0,0 +1,152 @@
+# NocoDB 数据结构（Phase 2b — 重建，7 表最终模型）
+
+> Source of Truth = NocoDB。AList 只做 enforcement，不存业务授权数据。
+> 本 schema 按《Hermes 调整指导》最终业务模型重建（2026-08-22）。
+> 通过 NocoDB API 自动建表，无需手动点 UI。
+
+- **Base**: `AlistAccess`（id `p3lzkresswyowqg`），独立新 base，与旧 `accessDB` 隔离。
+- **MySQL source**: mysql-server 上的 `alistaccess` schema（由 NocoDB 自动管理）。
+- **API token**: workspace token（`nc_api_tokens` 表内 `n8n` token），`xc-token` header。
+
+## 表 model_id（n8n v2 API 硬编码用）
+
+| 表 | model_id |
+|---|---|
+| Customers | `maqb9zgvza2te3k` |
+| Products | `molyb3pxv81l75g` |
+| Resources | `m6cm7tkxzd8m18c` |
+| CustomerProducts | `mvyqbv8ao7u6bct` |
+| AccessGrants | `mxdx3yhfcyej3ao` |
+| AccessLogs | `ml12zcyzlehgi21` |
+| Purchases | `mwp12z9lcohhsuk` |
+
+> ⚠ ID 是本次重建生成的。若再次删库重建，ID 会变，需同步更新 n8n 节点 + 本文档。
+
+## 关系（LinkToAnotherRecord）
+
+| 子表 | 字段 | 方向 | 指向 | 说明 |
+|---|---|---|---|---|
+| CustomerProducts | `customer` | bt | Customers | |
+| CustomerProducts | `product` | bt | Products | |
+| Products | `Resources` | **mm** | Resources | M2M link，列 id `c4ko4x8kwi16swg` |
+| Resources | `Products` | mm (reverse) | Products | 列 id `cfxi44n9ixkimqc` |
+| AccessGrants | `customer` | bt | Customers | |
+| AccessGrants | `resource` | bt | Resources | |
+| AccessLogs | `customer` | bt | Customers | |
+| Purchases | `customer` | bt | Customers | |
+| Purchases | `product` | bt | Products | |
+
+> M2M 读写方式（已实测）：`GET/POST /api/v2/tables/{products}/links/c4ko4x8kwi16swg/records/{productId}`，
+> POST body `{"Id": <resourceId>}`。反向用 Resources 的 `cfxi44n9ixkimqc`。
+
+## 表结构
+
+### 1. Customers
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| Id | number (PK) | |
+| username | SingleLineText | AList 登录名（唯一） |
+| password | SingleLineText | **plaintext**（规格 §2 已确认，勿 hash） |
+| display_name | SingleLineText | |
+| email | Email | |
+| notes | LongText | |
+| alist_user_id | Number | AList 用户 ID（n8n 回填） |
+| alist_role_id | Number | AList role ID（n8n 回填） |
+| status | SingleSelect | pending/active/suspended/expired/disabled/deleted |
+| sync_status | SingleSelect | pending/syncing/synced/error/unknown |
+| sync_required | Checkbox | 系统维护，管理员勿手改 |
+| last_sync | DateTime | |
+| last_sync_error | LongText | |
+
+### 2. Products
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| Id | number (PK) | |
+| name | SingleLineText | 如 "Python Basic" |
+| description | LongText | |
+| default_duration_days | Number | 默认有效期天数 |
+| status | SingleSelect | active/inactive |
+| Resources | link (mm) | 该产品包含的 Resources |
+
+### 3. Resources
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| Id | number (PK) | |
+| name | SingleLineText | 如 "Python 01" |
+| alist_path | SingleLineText | 真实 AList path，如 "/Class/Python/01" |
+| description | LongText | |
+| status | SingleSelect | active/inactive |
+| Products | link (mm, reverse) | |
+
+### 4. CustomerProducts（核心新表）
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| Id | number (PK) | |
+| customer | link bt → Customers | |
+| product | link bt → Products | |
+| start_at | Date | |
+| expires_at | Date | 实际到期（可 override default_duration） |
+| status | SingleSelect | scheduled/active/expired/revoked/suspended |
+| sync_status | SingleSelect | pending/syncing/synced/error/unknown |
+| sync_required | Checkbox | |
+| last_sync | DateTime | |
+| last_sync_error | LongText | |
+
+### 5. AccessGrants（最终实际权限，n8n 计算维护）
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| Id | number (PK) | |
+| customer | link bt → Customers | |
+| resource | link bt → Resources | |
+| permission | SingleSelect | read/readwrite |
+| start_at | Date | |
+| expires_at | Date | effective expiry（多来源取 max） |
+| status | SingleSelect | pending/active/revoked/expired |
+| source | SingleSelect | product/manual |
+| sync_status | SingleSelect | pending/syncing/synced/error/unknown |
+| sync_required | Checkbox | |
+| last_sync | DateTime | |
+| last_sync_error | LongText | |
+| revoked_at | DateTime | |
+| revoke_reason | LongText | |
+
+### 6. AccessLogs（审计）
+| 字段 | 类型 |
+|---|---|
+| Id | number (PK) |
+| customer | link bt → Customers |
+| username | SingleLineText |
+| resource_path | SingleLineText |
+| file_path | SingleLineText |
+| action | SingleSelect (login/view/download/preview/logout) |
+| ip_address | SingleLineText |
+| user_agent | LongText |
+| result | SingleSelect (success/denied) |
+| bytes | Number |
+| timestamp | DateTime |
+
+### 7. Purchases（纯记录，不参与权限）
+| 字段 | 类型 |
+|---|---|
+| Id | number (PK) |
+| customer | link bt → Customers |
+| product | link bt → Products |
+| purchase_date | Date |
+| amount | Decimal |
+| payment_method | SingleLineText |
+| order_id | SingleLineText |
+| notes | LongText |
+
+## 建表 API recipe（实测 2026-08-22，复用见 nocodb-selfhosted skill）
+
+- 建 base：`POST /api/v2/meta/bases/ {"title"}`
+- 建表（内联非 select 列）：`POST /api/v2/meta/bases/{baseId}/tables {"title","table_name","type":"table","columns":[{"title","uidt"}]}`
+  - 可用 uidt：`SingleLineText`,`LongText`,`Number`,`Decimal`,`Date`,`DateTime`,`Email`,`Checkbox`
+- SingleSelect 两段式：
+  1. 建空列 `POST /api/v1/db/meta/tables/{tid}/columns {"title","uidt":"SingleSelect"}`
+  2. 设选项 **必须同时传 `dtxp`**（逗号枚举串）：
+     `PATCH /api/v1/db/meta/columns/{colid} {"colOptions":{"options":[{"title","order","color":null}]},"dtxp":"'opt1','opt2'"}`
+     ⚠ 只传 `colOptions` 不传 `dtxp` 会静默失败（options 空）。
+- Link：`POST /api/v1/db/meta/tables/{childTid}/columns {"title","uidt":"LinkToAnotherRecord","parentId","childId","type":"bt"}`
+- M2M：`type":"mm"`，然后走 `/api/v2/tables/{t}/links/{colId}/records/{rowId}` 读写。
+- 删记录：`DELETE /api/v2/tables/{tid}/records` body `[{"Id":N},...]`（不是 `/records/{id}`）。

docs/INSTALL.md

@@ -0,0 +1,86 @@
+# 安装文档（Phase 1：AList stock 部署）
+
+> 目标：在 DSM 上跑起全新的 stock AList，与旧 alist 并行，验证后再切换域名。
+
+## 0. 前置条件（你需独立操作）
+
+这些是你在 DSM / Portainer 上手动完成的部分，agent 无法代劳：
+
+1. **确认 NAS 目录存在且就绪**：
+   - `/volume1/Class`、`/volume1/Book`、`/volume1/Comic`、`/volume1/Template`
+   - 若目录名/路径不同，改 `docker-compose.yml` 的 volumes。
+
+2. **创建 AList 数据目录**（DSM File Station 或 SSH）：
+   ```
+   /volume1/docker/alist-serve-resource/data
+   /volume1/docker/alist-serve-resource/config
+   /volume1/docker/alist-serve-resource/storage
+   ```
+
+3. **确认外部网络 `bridge_hoelee` 存在**：
+   - 该网络由 n8n/nocodb 等其他 compose 创建（`external: true`）。
+   - 若不存在，在 DSM 上建：`docker network create bridge_hoelee`（或 Portainer → Networks → Add）。
+
+4. **准备 secrets**：
+   - 复制 `.env.example` → `.env`，填入真实 `JWT_SECRET`、`ALIST_ADMIN_PASSWORD` 等。
+   - 生成 JWT secret：`openssl rand -base64 32`
+
+## 1. 部署（Portainer）
+
+在 Portainer → Stacks → Add Stack：
+
+- Name: `alist-serve-resource`
+- 方式：上传 `docker-compose.yml` + 配置环境变量（或把 `.env` 内容填入 Environment variables 区）。
+- 网络 `bridge_hoelee` 是 external，Portainer 会复用现有网络，不会新建。
+
+> Portainer 与 `env_file`：Portainer Stack 使用内置 Environment variables 区而非 `.env` 文件。
+> 把 `.env` 里的键值对逐条填进 Portainer 的 Environment variables，或改用 Compose 里的
+> `${VAR}` 语法（Portainer 也支持 `env_file`，可上传 `.env` 作为 env_file）。
+
+部署后验证：
+
+```bash
+docker ps | grep alist-serve-resource
+docker logs alist-serve-resource
+```
+
+## 2. 首次初始化 AList admin
+
+1. 访问 `http://<DSM-IP>:5247`。
+2. 首次进入会引导设置 admin 账号密码（或 AList 会打印初始 admin 密码到日志：
+   `grep -i admin docker logs alist-serve-resource`）。
+3. 登录后台，确认版本 v3.63.0。
+
+## 3. 建立 Local Storage
+
+AList 后台 → 存储 → 添加 → 驱动选「本地存储 / Local」：
+
+```
+挂载路径: /Class      →  根文件夹路径: /mnt/Class
+挂载路径: /Book       →  根文件夹路径: /mnt/Book
+挂载路径: /Comic      →  根文件夹路径: /mnt/Comic
+挂载路径: /Template   →  根文件夹路径: /mnt/Template
+```
+
+> 客户看到的逻辑路径是 `/Class/...`，实际 host 是 `/volume1/Class/...`（规格 §31）。
+> 客户永远看不到 `/volume1` 或 `/mnt`。
+
+## 4. 验证健康检查
+
+```bash
+docker inspect --format '{{.State.Health.Status}}' alist-serve-resource
+# 应输出 healthy
+```
+
+## 5. 切换域名（后期，新旧并行验证通过后再做）
+
+1. 旧 alist（`nginx-limit-alist`/`traefik-update-alist`/`alist`）保持运行。
+2. DSM nginx 将 `access.hoelee.com` 新指到 `http://<DSM-IP>:5247`。
+3. 验证客户能正常登录/浏览/下载。
+4. 确认无误后，停掉旧 alist 三个 container（先 `docker stop`，观察，再 `docker rm`）。
+
+## 6. 后续 Phase
+
+- Phase 2：NocoDB schema（`docs/DATABASE_SCHEMA.md`）
+- Phase 3：n8n + AList API 连接（`docs/N8N_WORKFLOWS.md`）
+- Phase 4–10：客户建档、权限同步、到期同步、审计、监控、备份、文档

docs/N8N_WORKFLOWS.md

@@ -0,0 +1,54 @@
+# 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）。

docs/PROJECT_STATE.md

@@ -0,0 +1,93 @@
+# Project State (Handoff) — 2026-08-22
+
+> 交接文档：压缩/新会话后，按此文档续做。细节见各 doc。
+
+## 已完成 ✅
+
+### 1. AList stock 部署（Phase 1）— 运行中
+- Container `alist-serve-resource` (xhofe/alist v3.63.0)，DSM port **5244**，网络 `bridge_hoelee`
+- 挂载 `/volume1/Class` `/volume1/Book` `/volume1/Comic` `/volume1/Template`（只读 → /mnt/Class 等）
+- 旧 alist (v3.54.0) 仍运行在 5243，**暂不处理**
+- Admin: username `hoelee`，2FA 已关闭；compose 在项目根 `docker-compose.yml`
+- DSM 上从 host shell 访问内网容器要用 `localhost:5244`；n8n 容器内用 `http://alist-serve-resource:5244`
+
+### 2. NocoDB schema（Phase 2 重建）— 7 表最终模型
+Base: **`AlistAccess`**（`p3lzkresswyowqg`），与旧 `accessDB` 完全隔离。表 + model_id + 关键点：
+| 表 | model_id | 备注 |
+|---|---|---|
+| Customers | maqb9zgvza2te3k | plaintext password + **password_updated_at** |
+| Products | molyb3pxv81l75g | default_duration_days；M2M→Resources |
+| Resources | m6cm7tkxzd8m18c | alist_path |
+| CustomerProducts | mvyqbv8ao7u6bct | 核心表（customer+product+expiry） |
+| AccessGrants | mxdx3yhfcyej3ao | **物化状态表，不是 trigger**（禁止 loop） |
+| AccessLogs | ml12zcyzlehgi21 | 审计 |
+| Purchases | mwp12z9lcohhsuk | 纯记录 |
+
+- 建表脚本：`scripts/create_nocodb_schema.py`（幂等）
+- 表/字段/链接列 ID 全表：`docs/DATABASE_SCHEMA.md`（已更新为 7 表）
+- NocoDB API token（workspace 级，来自 nc_api_tokens 表 n8n 那行）：在 `docs/API_INTEGRATION.md` / SETUP.md 有记（或查 NocoDB UI）
+
+### 3. W1 客户开通 workflow — **已实测跑通** ✅
+- 文件：`n8n/W1-customer-provision.json`
+- 流程：Webhook → Extract customerId → **Load Env(step 2, 用 $env)** → Fetch 记录 → 判断 create/update → Create Role → Find Role Id → Create User(role:[roleId]) → Find User Id → Write Back
+- 关键：AList user/create 传 **空 role 数组会被拒**（自动填 guest→报 "admin or guest user can not be created"）。必须先 Create Role 拿自增 id，再 Create User 带 `role:[id]`
+- 已 import n8n；用户曾在 UI 微调 step 2（见下方「n8n env 访问结论」模板）
+
+### 4. W2 CustomerProduct 权限同步 — **已改好待测试** ⏳
+- 文件：`n8n/W2-customerproduct-sync.json`
+- 流程：Webhook → Extract customerProductId → Load Env → **Compute Effective Grants**(登录 AList→读 customer→读全部 active CP→读 Product 的 M2M Resources→**per-Resource MAX(expires_at)** 合并→读 AList role 现状→diff→算 newScopes) → AList Update Role Scopes → Write Back CP Sync Status
+- 已修：compute 节点 `***` 损坏行、所有 HTTP 表达式改引用 `$('Load Env').item.json.X`
+- ⚠️ 待用户 import + 测用例 2（1 Product 2 Resource）、用例 3（重叠取 max expiry）
+- **AccessGrants 表尚未在 W2 中被写入**（设计上它是物化结果，当前版本只更新 role scopes + CP sync 状态 —— 后续版本再物化进 AccessGrants？确认设计）
+
+## 🔴 下一步（按序）
+1. **用户测试 W2**（import 覆盖 → 用例 2、3 → AList 前端实测客户登录看目录）→ 报错贴 execution 错误
+2. 验证通过后：**expiry scheduler**（每 5 分钟对账：全量 diff NocoDB↔AList，到期的移除 scope）—— 规格 §26/§37
+3. 其余 workflow（W3-W6）：Product/Resource 变更 → 重算受影响 customer；手动 sync；日志；通知
+4. 本地 git 留档 → 验证稳定后推 Gitea（git.hoelee.com）
+
+## 🐛 已沉淀的坑（勿再踩）
+- **AList**：
+  - `user/create` 空 role 数组 → 400 "admin or guest"（源码 `req.Role==0 → 默认 guest` + `IsGuest()` 检查）；先建 role 拿 id
+  - `role/create`/`update` 返回 `data:null`；create 后要 **list 按 name 定位 id**
+  - delete 用 `?id=` query param，不是 body
+  - role/list 返回 `data.content[]` + `data.total`（PageResp）
+  - GUEST=1 / ADMIN=2 / GENERAL=0；用户级 bit14=16384 = Check path limit
+  - 源码位置：`internal/op/user.go` CreateUser / `server/handles/role.go` / `internal/model/roles.go`
+- **NocoDB**（`nocodb-selfhosted` skill 已更新）：
+  - SingleSelect 不能建表内联选项；要先建空列再 PATCH `{"colOptions":{options},"dtxp":"a,b,c"}`
+  - Link 字段用 `type:"bt"`（belongs-to）建，`hm` 会把列名搞乱
+  - base/table/column ID 全在 DATABASE_SCHEMA.md
+- **n8n env 访问（v1.123.72）**（memory 已记）：
+  - Code 节点内 `$env` ✅（**用户实测可用**，如 `$env.NOCODB_URL`）
+  - HTTP 节点表达式字段里 `$env` / `process.env` ❌ 都不行
+  - 模式：step 2 放 "Load Env" Code 节点输出全部 env **并透传 payload 字段**，下游 HTTP 用 `$('Load Env').item.json.VAR`
+  - step 2 已验证模板：
+    ```js
+    const prev = $input.item.json;
+    return { json: {
+      customerId: prev.customerId,
+      eventType: prev.eventType,
+      NOCODB_URL: $env.NOCODB_URL,
+      NOCODB_TOKEN: $env.NOCODB_TOKEN,
+      T_CUSTOMERS: $env.NOCODB_TABLE_CUSTOMERS,
+      ALIST_URL: $env.ALIST_URL,
+      ALIST_ADMIN_USERNAME: $env.ALIST_ADMIN_USERNAME,
+      ALIST_ADMIN_PASSWORD: $env.ALIST_ADMIN_PASSWORD,
+      ALIST_ADMIN_OTP: $env.ALIST_ADMIN_OTP || '',
+    } };
+    ```
+
+## 📁 项目结构
+```
+alist-serve-resource/
+├── docker-compose.yml / .env.example / .gitignore
+├── n8n/  W1-customer-provision.json · W2-customerproduct-sync.json · SETUP.md · W2-DESIGN.md · w2-compute.js
+├── scripts/  create_nocodb_schema.py · healthcheck.sh
+└── docs/  API_INTEGRATION.md · DATABASE_SCHEMA.md · INSTALL.md · CONFIGURATION.md · SECURITY.md · BACKUP_RESTORE.md · UPGRADE.md · TROUBLESHOOTING.md · PROJECT_STATE.md
+```
+
+## 待确认的设计点
+1. W2 当前不写 AccessGrants 表 —— 是否在验证后补物化写入？（避免 AccessGrant→n8n loop 的前提下，由 W2 单向写）
+2. 密码：客户可自改 AList 密码 → NocoDB plaintext 会失真；当前不强制回写（用户已选方案 C）
+3. 对账/到期只靠 n8n 定时扫描（AList 无 expiry 概念）—— 已确认

docs/SECURITY.md

@@ -0,0 +1,40 @@
+# 安全要求（规格 §29/§52）
+
+## Secrets 管理
+
+- **绝不**把 token/密码写死在 `docker-compose.yml`，全部走 `.env`（已 `.gitignore`）。
+- AList admin token、NocoDB token、n8n 加密密钥都只在 `.env`。
+- `.env` 加密备份（见 BACKUP_RESTORE.md），不提交 Git。
+
+## 双层防护（规格 §16/§52）
+
+1. **应用层**：AList role scope + Check path limit + read-only bitmask。
+2. **文件系统层**：NAS 目录以 `:ro` 只读挂载。
+
+即使 AList 权限配置出错，客户也无法通过 AList 改写 NAS 文件。
+
+## 网络暴露
+
+| 服务 | 公网 |
+|---|---|
+| AList 客户入口 | ✅ 经 DSM nginx（access.hoelee.com） |
+| AList Admin API | ❌ 仅内网（n8n 经 bridge_hoelee） |
+| NocoDB admin | ❌ 不直连公网 |
+| n8n editor | ❌ 不直连公网 |
+
+## 权限默认值（客户 user）
+
+- `permission` = `16384`（仅 Check path limit bit，所有写位=0）
+- 无 upload/mkdir/rename/move/copy/delete/webdav-write/ftp-write
+- 每客户专属 role，绝不共享（避免权限污染，规格 §7）
+
+## 路径安全（规格 §32）
+
+- 资源路径只允许 `/Class/...` 逻辑路径。
+- 拒绝 `../`、编码遍历、反斜杠、绝对 host 路径等。
+- NocoDB 中的 `alist_path` 需校验（n8n 侧或表单侧）。
+
+## 强密码 / 2FA
+
+- AList admin 强密码；支持 2FA 则启用（`/api/admin/user/cancel_2fa` 已确认存在，说明 2FA 可管理）。
+- 客户密码由你设定初值，首次交付后建议客户自行改。

docs/TROUBLESHOOTING.md

@@ -0,0 +1,4 @@
+# 故障排查
+
+> Phase 10 补全。当前已覆盖常见问题见 UPGRADE.md 的排查表。
+> 实施过程中遇到的真实问题会回填到这里。

docs/UPGRADE.md

@@ -0,0 +1,25 @@
+# 升级 / 故障排查
+
+## 升级（规格 §36）
+
+1. 备份 AList data/config。
+2. 读 release notes（github.com/AlistGo/alist/releases）。
+3. 固定新版本 tag（如 `v3.64.0`），改 `docker-compose.yml` 的 `image:`。
+4. Portainer → Recreate / `docker compose pull && up -d`。
+5. 跑 `scripts/healthcheck.sh`。
+6. 跑 n8n Full Reconciliation（WF4）。
+7. 验证 sample customer 权限。
+8. 异常则回滚 tag + 还原备份。
+
+## 故障排查
+
+| 症状 | 排查 |
+|---|---|
+| container unhealthy | `docker logs alist-serve-resource`；确认 `/ping` 返回 200 |
+| 挂载 MISS | 确认 NAS 目录名与 compose volumes 一致 |
+| 客户看不到路径 | 检查 role `permission_scopes`、user `permission` bit 14、storage mount path |
+| 客户能写文件 | 检查 user `permission` bitmask 是否误设 bit 3–7；确认挂载 `:ro` |
+| n8n 连不上 alist | 确认同 `bridge_hoelee` 网络、host 名 `alist-serve-resource` |
+| 到期未撤销 | 确认 WF3 每 5 min 触发；查 NocoDB `sync_status` |
+
+详细排查步骤 Phase 10 补全。