# สิทธิ์ของปลั๊กอิน (capabilities) — ให้ผู้ดูแลเลือกได้ว่าตำแหน่งไหนทำอะไรได้

> ประกาศสิทธิ์ของปลั๊กอินใน manifest แล้วผู้ดูแลติ๊กต่อตำแหน่งได้ที่ ผู้ใช้งาน → สิทธิ์การใช้งาน — ใช้กับ route, หน้าหลังบ้าน, action, ประเภทเนื้อหา และ user.can() ในโค้ด

ที่มา: https://anasaki.live/docs/developers/plugin-capabilities

ปลั๊กอินประกาศ **สิทธิ์ของตัวเอง** ได้ เช่น &#34;ดูสถิติ&#34;, &#34;เผยแพร่เอกสาร&#34;, &#34;แก้ API key&#34; แล้วผู้ดูแลเว็บเลือกเองว่าตำแหน่งไหนได้สิทธิ์อะไร ที่ **ผู้ใช้งาน → สิทธิ์การใช้งาน → 🔌 สิทธิ์ของปลั๊กอิน** โค้ดของปลั๊กอินไม่ต้องกำหนดชื่อตำแหน่งตายตัวอีก (ใช้ได้ตั้งแต่ Anasaki Studio 2.0.6 และใช้ได้กับปลั๊กอิน JavaScript, service และ WASM)

## 1. ประกาศใน manifest.json

```json
{
  &#34;id&#34;: &#34;page-translate&#34;,
  &#34;minCore&#34;: &#34;2.0.6&#34;,
  &#34;capabilities&#34;: [
    { &#34;id&#34;: &#34;manage&#34;,
      &#34;label&#34;: { &#34;th&#34;: &#34;ตั้งค่าการแปลภาษา&#34;, &#34;en&#34;: &#34;Manage page translation&#34; },
      &#34;description&#34;: { &#34;th&#34;: &#34;เปิดหน้า แปลภาษา (ตั้งค่า) และแก้โหมด&#34;, &#34;en&#34;: &#34;Open the settings page and change the mode&#34; },
      &#34;default&#34;: [&#34;administrator&#34;, &#34;editor&#34;] },
    { &#34;id&#34;: &#34;api_key&#34;,
      &#34;label&#34;: { &#34;th&#34;: &#34;แก้ Google API Key&#34;, &#34;en&#34;: &#34;Change the API key&#34; },
      &#34;default&#34;: [&#34;administrator&#34;] }
  ]
}
```

| ฟิลด์ | กฎ |
| --- | --- |
| `id` | `a-z` ตัวแรก ตามด้วย `a-z 0-9 _` ยาว 2–31 ตัว ไม่ซ้ำในปลั๊กอิน ชื่อเต็มของสิทธิ์คือ **`.`** เช่น `page-translate.manage` |
| `label` | `{th, en}` หรือข้อความ ไม่เกิน 80 ตัวอักษร แสดงในหน้าสิทธิ์และตอนติดตั้ง |
| `description` | ไม่บังคับ `{th, en}` ไม่เกิน 300 ตัวอักษร |
| `default` | ตำแหน่งที่ได้สิทธิ์นี้ตอนติดตั้งครั้งแรก (`administrator` `editor` `author` `contributor` `subscriber` หรือตำแหน่งที่สร้างเอง) ไม่เกิน 20 |

ประกาศได้ไม่เกิน 30 สิทธิ์ต่อปลั๊กอิน และ Store ตรวจกฎเดียวกันตอนอัปโหลด (Store 1.2.2 ขึ้นไป)

## 2. ใช้ในโค้ด

ปลั๊กอินอ้างได้เฉพาะ **สิทธิ์ของตัวเอง** (`.*`) และสิทธิ์ของระบบ ถ้าอ้างสิทธิ์ของปลั๊กอินอื่น ระบบจะ error ตอนลงทะเบียน

### รายการ `access`

ใส่ `'cap:'` ปนกับชื่อตำแหน่งได้ ทุกตำแหน่งที่มีสิทธิ์นั้นจะผ่าน

```ts
site.adminPage('settings', { label: { th: 'แปลภาษา (ตั้งค่า)', en: 'Page Translate' }, access: ['cap:page-translate.manage'], render });
site.action('saveApiKey', { access: ['cap:page-translate.api_key'], input: { apiKey: 'text?' }, run });
site.route('GET /reports/export', { access: ['cap:reports.export', 'administrator'] }, handler);
```

ใช้ได้กับ `site.route`, `site.page`, `site.collection`, `site.action`, `site.adminPage`, `site.dashboardWidget`, `site.adminNotice` และ `access.edit` ของประเภทเนื้อหา ผู้ดูแลยัง override ได้ที่ **โค้ดของเว็บไซต์ → สิทธิ์การเข้าถึง**

### ตรวจในโค้ด

```ts
run: ({ user }) => {
  if (!user?.can('page-translate.api_key')) return { message: 'ไม่มีสิทธิ์แก้ API key', errors: { form: 'forbidden' } };
  // …
}
site.can(user, 'reports.export');   // user เป็น null → false
user.caps;                          // สิทธิ์ของระบบ + สิทธิ์ของปลั๊กอินนี้ที่ผู้ใช้มี
```

ปุ่มหรือฟอร์มที่ซ่อนตาม `user.can()` มีไว้เพื่อหน้าตาเท่านั้น ต้องตรวจสิทธิ์ซ้ำใน `access` หรือใน `run` ของ action เสมอ

### ประเภทเนื้อหาของปลั๊กอิน

```ts
site.postType('docs_doc', {
  label: { th: 'เอกสาร', en: 'Docs' },
  caps: { edit: 'docs.edit', publish: 'docs.publish' },   // ใครเขียน/แก้ และใครเผยแพร่
});
```

- `caps.edit` แทนรายชื่อตำแหน่งเริ่มต้นของคนแก้ไข
- `caps.publish` จำกัดการเผยแพร่ (ถ้าไม่ใส่ คนที่แก้ได้จะเผยแพร่ได้ด้วย) บทความที่เผยแพร่แล้วแก้หรือลบได้เฉพาะคนที่มีสิทธิ์เผยแพร่
- REST `/api/v1/posts` และ `db.posts` บังคับตามนี้ และ `GET /api/v1/post-types` บอก `canEdit` / `canPublish` ของผู้ใช้ที่เรียก

### ปลั๊กอินแบบ service / WASM

- หน้าหลังบ้าน: ตั้ง `service.admin[].cap` เป็น `&#34;.&#34;`
- ข้อมูลผู้ใช้ที่ส่งมา (header `X-Anasaki-User` และ body ของ `plugins.call`) มี `user.caps` ซึ่งรวมสิทธิ์ของระบบและสิทธิ์ของปลั๊กอินนี้

## 3. รองรับ Anasaki Studio รุ่นเก่า

รุ่นก่อน 2.0.6 ไม่รู้จัก `capabilities` (ข้ามไปเฉยๆ) แต่จะไม่ยอมรับ `cap:` ใน `access` ให้ตรวจก่อนว่ามี `site.can` หรือไม่:

```ts
const CAPS = typeof (site as any).can === 'function';            // 2.0.6+
const ACCESS_MANAGE = CAPS ? ['cap:page-translate.manage'] : ['editor'];
site.adminPage('settings', { label: 'Page Translate', access: ACCESS_MANAGE, render });
```

ถ้าไม่ต้องรองรับรุ่นเก่า ให้ตั้ง `&#34;minCore&#34;: &#34;2.0.6&#34;` ขึ้นไปแล้วใช้ `cap:` ตรงๆ ได้เลย

## 4. ตอนติดตั้ง อัปเดต และถอนการติดตั้ง

- **ติดตั้งหรืออัปเดต:** สิทธิ์ที่เว็บไม่เคยเห็นมาก่อนจะให้ตำแหน่งใน `default` ส่วนสิทธิ์ที่เคยมีอยู่แล้วจะคงค่าที่ผู้ดูแลตั้งไว้ การอัปเดตจึงไม่คืนสิทธิ์ที่ผู้ดูแลเอาออกไปแล้ว
- **อัปเดตที่เอาสิทธิ์ออก หรือถอนการติดตั้ง:** สิทธิ์นั้นหายจากทุกตำแหน่ง สิทธิ์อื่นของตำแหน่งยังอยู่เหมือนเดิม ถ้าติดตั้งใหม่ จะได้ค่าเริ่มต้นเฉพาะสิทธิ์ที่ไม่เคยเห็นมาก่อน
- **ผู้ดูแลระบบ (administrator) มีทุกสิทธิ์เสมอ** และสิทธิ์ของปลั๊กอินมีผลเฉพาะตอนที่ปลั๊กอินนั้นติดตั้งอยู่
- หน้าติดตั้งแสดงรายการสิทธิ์ที่ปลั๊กอินจะเพิ่ม ผู้ดูแลจะได้เห็นก่อนกดติดตั้ง

## 5. ตั้งชื่อสิทธิ์ให้ใช้ง่าย

- แบ่งตามสิ่งที่คนทำ ไม่ใช่ตามหน้าจอ เช่น `view` (ดู), `edit` (แก้), `publish` (เผยแพร่), `manage` (ตั้งค่า), `export`
- แยกสิทธิ์ที่เสี่ยงออกมาต่างหาก เช่น การแก้ API key หรือการลบข้อมูลทั้งหมด แล้วตั้ง `default` เป็น `administrator` อย่างเดียว
- เขียน `label` และ `description` ให้ผู้ดูแลที่ไม่เขียนโค้ดเข้าใจ เพราะผู้ดูแลจะเห็นเฉพาะข้อความนี้ในหน้าสิทธิ์

ดูรายละเอียดทั้งหมดได้ที่ [Plugin API](/docs/developers/plugin-api) และปลั๊กอินทางการ **Docs** และ **Analytics** เป็นตัวอย่างที่ใช้สิทธิ์ของตัวเอง
