From 03af9df3e41b3cd2d96c6043cadbd41db46eb04f Mon Sep 17 00:00:00 2001 From: hoelee Date: Sun, 23 Aug 2026 07:41:45 +0800 Subject: [PATCH] docs(ADMIN_GUIDE): rewrite for non-technical admins - Remove all n8n/backend-logic mentions; NocoDB-only instructions. - Add required-field markers + fill order for each table. - Add Purchases table section (record customer purchase, expected fields). - Plain language, no jargon. Add status quick-reference table. --- docs/ADMIN_GUIDE.md | 179 ++++++++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 82 deletions(-) diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md index 40c7870..d40f2a7 100644 --- a/docs/ADMIN_GUIDE.md +++ b/docs/ADMIN_GUIDE.md @@ -1,93 +1,108 @@ # 管理员操作指南（ADMIN_GUIDE） -> 极简版。只讲你在 NocoDB 里怎么点，不讲技术细节。 +> 本指南只讲在 NocoDB 里怎么点。不需要懂技术，照着做即可。 +> 所有操作都在 NocoDB 的 `AlistAccess` 工作区里完成，系统会自动处理后续。 --- -## 第一部分：给顾客授权（Customers + CustomerProducts） +## 第一部分：给顾客开账号 + 授权（3 步） -### 目标 -让一个顾客能登录 AList，看到他买的产品对应的文件夹，并在他到期时自动失效。 +> 顺序：先建顾客 → 再建购买记录 → 再挂产品。 -### 步骤 +### 第 1 步 — 建顾客（Customers 表） -**第 1 步 — 建顾客（Customers 表）** +打开 `Customers` 表，点「＋新增记录」，**按顺序填**： -1. 打开 NocoDB 的 `AlistAccess` → `Customers` 表，点「＋新记录」。 -2. 填这两个字段（其余先留空）： - - `username`：顾客登录 AList 的账号（唯一，别重复） - - `password`：顾客的密码 -3. `status` 先选 **`active`**。 - -> **期待值**：保存后几秒，n8n 会自动在 AList 建好这个顾客的账号 + 专属角色， -> 并回填 `alist_user_id`、`alist_role_id`，`sync_status` 变成 `synced`。 -> 此时顾客还看不到任何文件夹（还没买产品，权限为空）。 - -**第 2 步 — 给顾客挂产品（CustomerProducts 表）** - -1. 打开 `CustomerProducts` 表，点「＋新记录」。 -2. 填： - - `customer`：选刚才那个顾客 - - `product`：选一个产品（比如「Test Product」） - - `start_at`：开始日期 - - `expires_at`：到期日期（**到期当天就失效**，要含当天请往后多填一天） - - `status`：选 **`active`** - -> **期待值**：保存后，n8n 会算出这个产品包含的文件夹路径，写进该顾客的 AList 权限。 -> 顾客登录后就能看到对应文件夹。`expires_at` 一过，权限自动移除。 - -**第 3 步 — 验证** - -- 用顾客的 `username` / `password` 登录 AList 前端，确认只看到该产品对应的文件夹。 -- 想看整体权限是否同步正确：该顾客记录的 `sync_status` 应为 `synced`。 - ---- - -## 第二部分：管理产品（Products + Resources） - -### 目标 -定义「产品」是什么，每个产品对应哪些文件夹，好让第一部分能直接选用。 - -### 概念对应 - -| NocoDB 表 | 是什么 | 例子 | -|---|---|---| -| `Resources` | 一个真实文件夹路径 | `alist_path = /Class/Forex` | -| `Products` | 一个可售产品 = 打包若干 Resources | 「Python 全套」含 `/Class/Python/01`、`/Class/Python/02` | - -### 步骤 - -**第 1 步 — 加资源（Resources 表）** - -1. 打开 `Resources` 表，点「＋新记录」。 -2. 填： - - `name`：给人看的名字（如「Forex 课程」） - - `alist_path`：AList 里的**绝对路径**（如 `/Class/Forex`，必须以 `/` 开头） - -> **期待值**：这个资源能被产品引用。路径必须真实存在于 AList 的挂载里，否则顾客会 403。 - -**第 2 步 — 建产品（Products 表）** - -1. 打开 `Products` 表，点「＋新记录」。 -2. 填： - - `name`：产品名（如「Python Basic」） - - `status`：选 **`active`** -3. 在 `Resources` 这一列（关联列）里，勾选这个产品**包含**的资源（一个产品可勾多个）。 - -> **期待值**：第一部分给顾客挂这个产品时，n8n 会把产品里勾选的所有资源的路径 -> 一次性算给顾客。 - ---- - -## 附：Customers.status 怎么配 - -| status | 含义 | 顾客能看到文件吗 | 何时用 | +| 顺序 | 栏位 | 必填 | 怎么填 | |---|---|---|---| -| `pending` | 未正式开通 | ❌（且还没建账号）| 刚建顾客、还没决定卖什么时 | -| `active` | 正常 | ✅（按已买产品）| 客户正在使用中 | -| `suspended` | 管理员封禁 | ❌ | 暂时停权（欠费/风控）| -| `expired` | 整户期满 | ❌ | 客户整体服务结束 | -| `deleted` | 软删除 | ❌（账号保留）| 停用但保留历史记录 | +| 1 | `username` | ✅ | 顾客登录用的账号名，**不能重复** | +| 2 | `password` | ✅ | 顾客的登录密码 | +| 3 | `display_name` | 选填 | 顾客显示名（顾客姓名等）| +| 4 | `email` | 选填 | 顾客邮箱 | +| 5 | `status` | ✅ | 先选 `active`（顾客马上能用）| -- 只要是非 `active`，顾客就登不进去、也看不到文件。 -- 改回 `active`，会自动按**当前还有效**的产品重新算权限（已过期的不会回来）。 +> **填完会看到**：保存后，下面几个栏位（`alist_user_id`、`alist_role_id`、`sync_status`） +> 会被系统自动填上，`sync_status` 变成 `synced`。这是正常的，不用管。 +> +> **注意**：如果 `status` 先选 `pending`（还没决定卖什么），系统不会建账号。 +> 等你后面改成 `active` 才会正式开账号。 + +### 第 2 步 — 记购买（Purchases 表） + +打开 `Purchases` 表，点「＋新增记录」，**期望填写**： + +| 栏位 | 必填 | 怎么填 | +|---|---|---| +| `customer` | ✅ | 选第 1 步那个顾客 | +| `product` | ✅ | 选顾客买的产品 | +| `purchase_date` | 选填 | 购买日期 | +| `amount` | 选填 | 金额 | +| `payment_method` | 选填 | 付款方式 | +| `order_id` | 选填 | 订单号 | +| `notes` | 选填 | 备注 | + +> 这份是**记账留档**用，填不填都不影响顾客能不能看文件。 + +### 第 3 步 — 挂产品（CustomerProducts 表） + +> **这步才是真正让顾客「看得到文件」的关键。** + +打开 `CustomerProducts` 表，点「＋新增记录」，**按顺序填**： + +| 顺序 | 栏位 | 必填 | 怎么填 | +|---|---|---|---| +| 1 | `customer` | ✅ | 选第 1 步那个顾客 | +| 2 | `product` | ✅ | 选他买的产品 | +| 3 | `start_at` | 选填 | 开始日期 | +| 4 | `expires_at` | ✅ | 到期日期（**到期当天就失效**）| +| 5 | `status` | ✅ | 选 `active` | + +> **填完会看到**：顾客登录后就能看到这个产品对应的文件夹。 +> 到了 `expires_at` 那天，权限自动失效。 +> +> **一个顾客可以有多条** CustomerProducts：买几个产品就建几条，权限会全加起来。 + +--- + +## 第二部分：准备产品（Products + Resources，2 步） + +> 顺序：先建资源（文件夹）→ 再建产品（打包）。 + +### 第 1 步 — 建资源（Resources 表） + +打开 `Resources` 表，点「＋新增记录」，**按顺序填**： + +| 顺序 | 栏位 | 必填 | 怎么填 | +|---|---|---|---| +| 1 | `name` | ✅ | 给人看的名字（如「Forex 课程」）| +| 2 | `alist_path` | ✅ | 文件夹路径，以 `/` 开头，如 `/Class/Forex` | + +> **注意**：`alist_path` 必须是真实存在的文件夹路径，填错顾客会打不开。 + +### 第 2 步 — 建产品（Products 表） + +打开 `Products` 表，点「＋新增记录」，**按顺序填**： + +| 顺序 | 栏位 | 必填 | 怎么填 | +|---|---|---|---| +| 1 | `name` | ✅ | 产品名（如「Python Basic」）| +| 2 | `status` | ✅ | 选 `active` | +| 3 | `Resources` | ✅ | 勾选这个产品**包含**的资源（可勾多个）| + +> **填完会看到**：以后在「第一部分第 3 步」给顾客挂这个产品时， +> 产品里勾选的资源路径会一次性算给顾客。 + +--- + +## 附：Customers 的 status 怎么选 + +| status | 意思 | 顾客能看文件吗 | 什么时候用 | +|---|---|---|---| +| `pending` | 还没正式开通 | ❌ | 刚建顾客、还没卖产品时 | +| `active` | 正常使用 | ✅ | 顾客在使用中 | +| `suspended` | 暂时停权 | ❌ | 欠费 / 有问题暂时停 | +| `expired` | 整户到期 | ❌ | 顾客服务整体结束 | +| `deleted` | 停用（保留记录）| ❌ | 不合作了但想留历史 | + +- 只要不是 `active`，顾客就登不进去、也看不到文件。 +- 改回 `active`，系统会自动算**现在还有效**的产品权限（已经过期的不会回来）。