feat(docs): init docs

.gitignore

@@ -21,3 +21,5 @@ vite.config.ts.timestamp-*
 
 dist/
 app/
+
+/docs/.vitepress/cache

docs/.vitepress/config.mts

@@ -0,0 +1,52 @@
+import { defineConfig } from 'vitepress';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'docs.of.paste.then.ac',
+  lang: 'zh-CN',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '使用手册', link: '/usage' },
+      { text: 'API', link: '/api' },
+    ],
+
+    sidebar: {
+      '/usage/': [
+        {
+          text: '使用手册',
+          items: [
+            { text: '快速上手', link: '/usage/' },
+            { text: '常见问题', link: '/usage/faq' },
+            { text: '限制与约定', link: '/usage/limits' },
+          ],
+        },
+      ],
+      '/api/': [
+        {
+          text: 'API',
+          items: [
+            { text: '概述', link: '/api/' },
+            { text: 'Piece API', link: '/api/piece' },
+            { text: 'Statistics API', link: '/api/statistics' },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [{ icon: 'github', link: 'https://github.com/thenAC/paste' }],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2024 bLue',
+    },
+
+    externalLinkIcon: true,
+
+    outlineTitle: '目录',
+    docFooter: {
+      prev: '上一篇',
+      next: '下一篇',
+    },
+  },
+});

docs/api/index.md

@@ -0,0 +1,37 @@
+---
+outline: deep
+---
+
+# API 概述
+
+欢迎探索 API。本文档将介绍 then AC 系列 API 的通用规范和使用方式。
+
+## 接口端点地址
+
+当前 API 的地址前缀为 `https://paste.then.ac.api.algoux.cn/api`。
+
+## 请求格式
+
+根据具体请求的类型和参数决定。通常我们建议非浏览器场景下设置能标识你的应用或业务的自定义 `User-Agent` 请求头（如 `MyApp/1.0.0`），而非模拟主流浏览器的 User Agent。
+
+## 响应格式
+
+除特殊说明外，API 的响应格式为 JSON（`application/json`），包含以下字段：
+
+- `success: boolean`：请求是否成功
+- `code: number`：请求的返回码，当请求失败时其值不为 0，可用于匹配判断请求的错误类型
+- `msg: string`：请求的错误提示信息，仅当请求失败时存在
+- `data: any`：请求的返回数据
+
+请求成功时，通常状态码为 200，当有特定类型的响应时可能改变为 > 200, < 300 的状态码。
+
+### 常见错误
+
+- `code: -1`：系统错误。HTTP 状态码将被置为 `500`
+- `code: -2`：非法请求。通常仅在需要授权认证的接口中出现
+- `code: -3`：无效的请求参数。通常由于参数缺失、字段类型不匹配或参数校验未通过导致，HTTP 状态码将被置为 `422`
+- `code: -4`：请求频率超出限制。HTTP 状态码将被置为 `429`
+
+## 跨域支持
+
+所有接口默认开启 CORS 支持，响应头中包含 `Access-Control-Allow-Origin: *`。

docs/api/piece.md

@@ -0,0 +1,29 @@
+---
+outline: deep
+---
+
+# Piece API
+
+## 添加代码片段
+
+`POST /addPiece`
+
+### 请求参数
+
+| 参数名 | 类型   | 必填 | 描述         | 校验规则                                                                                     |
+| ------ | ------ | ---- | ------------ | -------------------------------------------------------------------------------------------- |
+| `code` | string | 是   | 代码片段内容 | 长度 1-1048576                                                                               |
+| `lang` | string | 是   | 代码语言     | [可用枚举值](https://github.com/thenAC/paste/blob/master/client/src/lib/configs/language.ts) |
+| `ttl`  | number | 是   | 有效期       | [可用枚举值](https://github.com/thenAC/paste/blob/master/common/configs/piece.json)          |
+| `rel`  | string | 否   | 相关链接     |                                                                                              |
+
+### 响应结构
+
+| 字段名 | 类型   | 字段存在 | 描述                 |
+| ------ | ------ | ------------ | -------------------- |
+| `key`  | string | 是           | 获得的代码片段 key   |
+| `url`  | string | 是           | 获得的代码片段短链接 |
+
+### 频率限制
+
+- IP 粒度：`10 次 / 分钟`

docs/api/statistics.md

@@ -0,0 +1,20 @@
+---
+outline: deep
+---
+
+# Statistics API
+
+## 获取统计信息
+
+`GET /getStatistics`
+
+### 请求参数
+
+无。
+
+### 响应结构
+
+| 字段名       | 类型                | 字段存在 | 描述             |
+| ------------ | ------------------- | -------- | ---------------- |
+| `totalCount` | string (from int64) | 是       | 代码片段总计数量 |
+| `totalBytes` | string (from int64) | 是       | 代码片段总计长度 |

docs/index.md

@@ -0,0 +1,24 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Paste then AC"
+  tagline: 文档手册
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /usage
+    - theme: alt
+      text: API 参考
+      link: /api
+
+features:
+  - title: 自由、开放的剪贴板
+    details: 无需登录，随贴随 A
+  - title: API 友好
+    details: 无限制、开放跨域的 API
+  - title: 适合算竞宝宝体质
+    details: 不断更新更多实用功能和工具集成
+---
+

docs/usage/faq.md

@@ -0,0 +1,23 @@
+# 常见问题
+
+Q：Paste then AC 是免费的吗？是否需要注册登录？
+
+A：它是免费的在线工具服务，无需注册登录即可使用。我们将始终保留游客使用的能力，日后或许会新增可选的账户功能，便于快速查找自己粘贴的过往代码。
+
+---
+
+Q：粘贴代码的有效期是多久？
+
+A：可以在粘贴前选定有效期。如果你需要稍后自动销毁代码，可以选择较短的有效期。
+
+---
+
+Q：是否有使用限制？
+
+A：对于游客身份的匿名粘贴，因服务器承载力所限及公平使用原则考量，目前存在较为宽松的频率限制：`10 次 / 分钟`。另外关于粘贴内容的限制，请参阅 [限制与约定](./limits.md)。
+
+---
+
+Q：我是否可以借助 Paste then AC 的接口构建上层应用或集成它到我自己的项目中？
+
+A：非常欢迎。我们的 API 支持跨域访问，你可以任意地程序化调用，例如使用它构建聊天机器人，或集成分享能力到 OJ 等项目中。关于 API 的使用方法，请参阅 [API 文档](/api.md)。

docs/usage/index.md

@@ -0,0 +1,26 @@
+# 快速上手
+
+欢迎来到 Paste then AC！这是一个超便捷粘贴与分享代码的工具。
+
+## 粘贴！
+
+Paste then AC 的界面十分简洁。
+
+![使用指引1](./assets/usage-1.png)
+
+除代码外，你可以额外配置更多属性：
+
+- `Language`：代码语言。默认自动侦测，如侦测不准确，你亦可手动选择语言
+- `Time to live`：此代码片段的有效期。你可以控制它在多久后被销毁
+
+![使用指引2](./assets/usage-2.png)
+
+填妥后，轻点 `Paste!` 按钮即可张贴这份伟大的代码。如无意外，你将获得一个随机生成的短链接，即刻复制并分享！
+
+## 打开分享！
+
+当打开一份分享的代码时，你可以快速浏览代码内容及其相关信息。
+
+![使用指引3](./assets/usage-3.png)
+
+轻点 `Copy!` 按钮即可快速复制代码到剪贴板。

docs/usage/limits.md

@@ -0,0 +1,31 @@
+# 限制与约定
+
+在使用 Paste then AC 前，请明确知晓适用范围与限制。
+
+## 适用场景
+
+此工具适用于分享代码片段，便于跨设备传输或分享内容给其他人。适用场景包括但不限于技术交流、学术研究、开发调试、临时中转、代码备份等。
+
+## 不适用场景
+
+1. 此工具并不对粘贴的内容提供 HTTP 托管服务，因此你不应该尝试将其用于发布博客、静态网页、媒体内容等
+2. 与适用场景相差较大的非技术场景通常是不建议的，如托管小说章节、文档等，但个人用途的信息和备忘并不在此范围
+3. 传播违法、违规、侵权、色情、暴力、诈骗等内容，尤其是违反中国大陆法律法规的内容
+4. 涉及隐私的敏感内容，如隐私数据、密码密钥、机密信息等，即便选择最短的有效期也不应该存储此类数据
+5. 营销、推广等内容
+
+## 限制与惩罚措施
+
+以下滥用或恶意行为将导致代码被删除，且 IP 或用户被限制或封禁：
+
+1. 发布违法、违规、侵权、色情、暴力、诈骗等内容
+2. 发布重复或垃圾的信息
+3. 发布营销推广信息
+4. 恶意发布大量内容、恶意爬取接口或其他对本工具及其依赖服务的攻击行为
+5. 利用本工具的 CDN 资源进行存储和二次分发
+6. 利用本工具的 CDN 资源为其他应用程序提供加速服务
+7. 加密、混淆代码文本或二进制，以用于资源分发、违规内容存储等
+
+## 安全性
+
+本工具并不对粘贴代码的私密性提供保障，亦暂无计划支持私有剪贴板，你发布的内容可能被其他爬虫或扫描程序暴力获取。如有安全性要求，请使用其他私有存储工具。

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "paste",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thenAC/paste.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/thenAC/paste/issues"
+  },
+  "homepage": "https://github.com/thenAC/paste#readme",
+  "devDependencies": {
+    "vitepress": "^1.3.4"
+  }
+}