📝 Migrate docs

2024-09-28 15:10:43 +08:00
parent fe0fffada2
commit 1ccb9e738e
11 changed files with 163 additions and 19 deletions
--- a/content/zh-CN/docs/solar-network.mdx
+++ b/content/zh-CN/docs/solar-network.mdx
@@ -0,0 +1,25 @@
+---
+icon: mdi-web
+title: Solar Network
+description: Solsynth LLC 的下一代社交网络
+---
+
+![Solar Archive Thumbnail](/thumbnails/docs/solar-network-user-manual.webp)
+
+Solar Network 是 Solsynth LLC 开发的社交网络，目标成为下一代社交网络。
+
+## 技术栈
+
+Solar Network 项目是经典的前后端分离项目，整体项目分为两部分：前端 (Solian)，后端 (Hydrogen.Dealer, Hydrogen.Passport, etc...)
+
+### 前端
+
+Solar Network 的前端是 Flutter 构建的全平台支持客户端，详情可以查看 [相关页面](solar-network/solian)
+
+### 后端
+
+Solar Network 的后端根据我们的定义是一个「中服务」架构，它相比微服务相比，单个服务负责的东西更多，体量更大，这可以帮我们更好地维护多个项目，
+但同时部分服务出现问题不会造成整体 Outage
+
+在这一切的中心是我们的核心服务 —— Hydrogen.Dealer，服务发现和中服务网关，同时是唯一一个 Solar Network 地外部接口，
+`api.sn.solsynth.dev` 就是 Hydrogen.Dealer 暴露出来的网关
--- a/content/zh-CN/docs/solar-network/creator.mdx
+++ b/content/zh-CN/docs/solar-network/creator.mdx
@@ -0,0 +1,9 @@
+---
+icon: mdi-palette
+title: 创作者计划
+description: 欢迎来到 Solar Network 创作者计划，在这里共创 Solar Network
+---
+
+创作者计划是 Solar Network 为了推动用户创作内容而诞生的一个企划，企划旨在帮助创作者更好的使用 Solar Network 产出更高质量的内容。
+
+加入创作者计划，获得更多官方支持，第一时间使用新功能，为未来的 Solar Network 提出宝贵的建议吧！
--- a/content/zh-CN/docs/solar-network/creator/stickers.mdx
+++ b/content/zh-CN/docs/solar-network/creator/stickers.mdx
@@ -0,0 +1,40 @@
+---
+icon: mdi-sticker-emoji
+title: 贴图及贴图包
+description: Stickers, Emotes 和 Emoji
+---
+
+贴图可以帮助用户通过 Solar Network 更好的表达他们的情绪，这篇文章将会向你介绍如何上传、使用一个贴图
+
+## 贴图包
+
+贴图必须跟随一个贴图包，要创建一个贴图包，你可以转到官网侧边栏的「Creator Hub」>「Stickers」来创建一个
+
+## 贴图
+
+贴图的创建，你首先需要准备内容。建议为一个 1024x1024 像素大小（最小为 128x128 的大小，否则可能造成效果不佳）的 PNG 或 GIF 图片，
+透明背景或内容背景均可，但请不要使用纯色填充。大面积的白色填充可能会给暗色模式的用户带来闪光弹。
+
+之后打开刚刚创建的贴图包，在「Actions」中点选加号标识来创建一个贴图。
+
+你可能需要上传一个附件来添加贴图的材质，并使用上传完成后界面的 Random ID (井号后面的一连串字符) 填写在 Attachment 字段里，
+能成功显示出内容即代表连接成功
+
+之后完成表单的填写即可。
+
+## 使用
+
+使用贴图，需要在你的内容中键入一个文字占位符，具体的组成为 `:<pack prefix><sticker alias>:`。
+例如一个贴图包的前缀（`prefix`）为 `solar`，一个该贴图包的的贴图别名（`alias`）为 `Hello`，组成出来的占位符为 `:solarHello:`
+
+不过不明白也别担心，大多数情况我们都有自动提示。只需在 Solian 内文本框键入一个英文冒号，再开始键入占位符的一部分即可。
+
+### 大小变化
+
+在 Solar Network 中，你可能看到大小不同的贴图，这是因为 Smart Resize 在背后发功。具体规则如下。
+
+1. 当仅有一个贴图，将使用 128x128 的大小
+2. 当有三个及一下的题图，将使用 32x32 的大小
+3. 当有三个以上的贴图，或贴图夹杂在文本内时，将使用 20x20 的大小
+
+这一系列的匹配都将发生在一个段落中。
--- a/content/zh-CN/docs/solar-network/index.mdx
+++ b/content/zh-CN/docs/solar-network/index.mdx
@@ -1,7 +0,0 @@
---
-icon: mdi-open-in-app
-title: Solar Network
-description: Solsynth LLC 的下一代社交网络
---
-
-Solar Network 是 Solsynth LLC 开发的社交网络，目标成为下一代社交网络。
--- a/content/zh-CN/docs/solar-network/open-project.mdx
+++ b/content/zh-CN/docs/solar-network/open-project.mdx
@@ -0,0 +1,10 @@
+---
+icon: mdi-oci
+title: 开放计划
+description: 欢迎来到 Solar Network 开放计划，让我们助力你的应用成长
+---
+
+开放计划是 Solar Network 一系列的开发者友好的 API 和小工具集合。
+我们坚持不为开发者添堵的规则，非必要不加密参数，永不混淆参数，人性化 API 接口，RESTful API 端点，尽可能的让开发者体验好。
+
+现在就开始浏览，看看你能用 Solar Network 做些什么吧！
--- a/content/zh-CN/docs/solar-network/open-project/api-standard.mdx
+++ b/content/zh-CN/docs/solar-network/open-project/api-standard.mdx
@@ -0,0 +1,70 @@
+---
+icon: mdi-pencil-ruler
+title: API 标准
+description: 在设计 Solar Network 服务 API 时惯用的准则
+---
+
+这篇文章是关于我们平时在设计 Solar Network API 时的范式是怎样的，能够帮助你更好的调用我们的 API 来进行第二次开发
+
+## 最小化
+
+我们的 API 一般追求极简，不像某些大平台的 API 一样除了数据之外的格式还有一大堆什么状态码、信息、请求 ID 什么的。这些信息我们都选择放在 HTTP 的 Header 部分。HTTP 的响应体就是纯粹的数据，无其他信息（需要分页的数据接口会额外返回一个数据总数）。
+
+## 增删查改
+
+我们的 API 基本上都是遵循 RESTful 设计范式的，如果你不知道什么是 RESTful，可以看以下我们理解的实践的 RESTful
+
+### 请求方法
+
+- `GET` 查询
+- `POST` 创建、进行某种操作
+- `PUT` 更新（虽在 RESTful 中也被定义为创建数据的行为，但是我们不使用）
+- `PATCH` 更新（不常用）
+- `DELETE` 删除
+
+### 路径映射
+
+假如你 POST 了一个地址来创建数据，那么用 GET 方法访问相同的地址大概就是列出数据的列表。
+在其后面加上 `/<id>` 就是单独读取某个数据，将请求方法改成 PUT 便是更新该条数据，改成 DELETE 就是删除该条数据。
+如果在 `/<id>` 再加上东西基本上就是 POST 方法来执行某个操作。
+例如以下是我们帖子的路径映射
+
+*注：`:id` 系路径参数*
+
+- `GET /posts` 获取帖子列表（分页）
+- `GET /posts/:id` 获取单个帖子
+- `GET /posts/:id/replies` 获取单个帖子的回复（分页）
+- `POST /posts` ~~创建帖子~~（于新版本因为引入帖子类型移除，需使用对应类型的创建接口）
+- `PUT /posts/:id` ~~更新帖子~~（于新版本因为引入帖子类型移除，需使用对应类型的更新接口）
+- `DELETE /posts/:id` 删除帖子
+- `POST /posts/:id/pin` 置顶帖子
+- `POST /posts/:id/react` 对帖子作出反应
+
+## 错误处理
+
+我们不理解为什么 HTTP 有给一套完善的状态码系统，其他大厂却仍选择自立门户。关于响应的 HTTP 状态码，以下是一些常用的含义代表。
+
+- `500` 服务器内部错误 —— 你不用管，如果多见记得抛 issue
+- `400` 请求参数错误 —— 看文档，核查请求体
+- `404` 数据不存在或是接口路径不对
+- `403` 没有权限
+- `401` 需要授权 —— 需要授权的 API 但你没有提供 API 令牌
+- `200` 成功
+- `204` 无内容 —— 常见于删除 *虽然后时候写 API 会忘记删除内容时改成这个*
+
+如果响应不是 `2xx` 的状态码，一般我们都不会返回 `application/json` 的数据，而是一个 `plain/text`，一行简单的文字来代表你犯了什么错。
+
+> 如果你是英语白痴，遇到报错别老来问我们，用用翻译好吗？不然我们写报错信息干嘛。
+
+## 超级网关
+
+超级网关指的是我们的 [Hydrogen.Dealer](https://git.solsynth.dev/Hydrogen/Dealer)，一般情况下你都不会直接访问我们的服务，都是走 Dealer 的网关转发的。虽然我们也不知道为什么写了个这个东西。
+
+我们 API 的地址为 `api.sn.solsynth.dev`，怎么用呢？很简单。访问 `/cgi/<service name>` 即可，这样的地址会被转发到对应服务的 `/api` 端点。新版本我们还给这些服务加了点别名，这样你的 URL 可以变得更好看点。
+
+- `/cgi/id` 或 `/cgi/auth` —— 授权服务 [Hydrogen.Passport](https://git.solsynth.dev/Hydrogen/Passport)
+- `/cgi/uc` 或 `/cgi/files` —— 附件服务 [Hydrogen.Paperclip](https://git.solsynth.dev/Hydrogen/Paperclip)
+- `/cgi/co` 或 `/cgi/interactive` —— 帖子服务 [Hydrogen.Interactive](https://git.solsynth.dev/Hydrogen/Interactive)
+- `/cgi/im` 或 `/cgi/messaging` —— 聊天服务 [Hydrogen.Messaging](https://git.solsynth.dev/Hydrogen/Messaging)
+
+> 冷知识：你可能注意到了我们新配置的别名其实就是之前没有超级网关时他们使用的子域名。