update

docs/danxi/02-learn/advice.md

@@ -0,0 +1,15 @@
+# 忠告
+一些可能使你终身受用的代码建议。这不仅限于 Flutter，也适用于其他语言和框架。
+
+1. 世界上所有的代码风格指南都可以概括为：**四处看看，模仿，保持一致**。最坏的代码永远是**「我觉得我这么写更好」而风格完全不同的代码**；
+    - 如果你不确定一个功能怎么写，先看看已有的代码，「抄袭」它们调用的函数和使用的方法；
+    - 如果你不确定一个变量怎么命名，先看看已有的代码，「抄袭」它们的命名风格；
+    - 如果你不确定一个类怎么设计，先看看已有的代码，「抄袭」它们的结构；
+2. **仔细读注释，必要时自己写新的注释。**注释是代码的一部分，不要忽略它们；
+3. **能用和简洁比优雅更好**，不要为了追求优雅而写出难以理解的代码，这是在浪费时间。记住：**Make it work, make it correct, make it fast, then make it elegant**；
+4. **先看官方文档、库的源代码和问答社区，最后是博客**。别浪费时间在不靠谱的博客（说的就是你，CSDN）上，它们可能已经过时了；而源代码永远是你**最好的、100% 精确和无歧义的指南**，不要畏惧它们！
+5. **一次完成一件事**。这包括**不要在一个函数里做太多逻辑**，**不要在一个文件里写太多函数**，**不要在一次 Git 提交里改太多功能**。这样做的好处是：**一旦出错，你就知道是哪里出错了**；
+6. **警惕错误**。不要假设你的代码永远不会出错，如果有可能出错的地方，当时就写好错误处理代码。**尽可能考虑到所有可能的错误**；
+7. **做好测试**，至少要在发布前自己测试一遍程序。我已经遇到过太多次上线后才发现恶性 bug，然后紧急修复发布新版的经历，这会给用户非常糟糕的体验；
+8. **不要过早优化**。如果你的代码能在 1 秒内完成，那么不要花 1 小时优化它，因为你可能只能优化到 0.5 秒，这是不值得的。**优化应该在性能测试后进行**，而性能测试应该在功能完成后进行；
+9. **善用工具**。用工具组织好你的开发计划和待处理的问题（例如 Github Issues），要比你在纸上甚至脑子里记住要做的事情要好得多。

docs/danxi/03-architecture/feature.md

@@ -1 +1,52 @@
-# Feature
+# Feature
+
+一个 *Feature* 是指首页中显示的一个功能模块，或者称为一个「小部件」。此外，它还可以是一条首页顶部通知（例如「未连接到内网」的卡片）。
+
+## 结构
+### Feature
+`Feature` 抽象类定义了一个 *Feature* 的基本结构，包括标题、描述、图标、动作、布局等信息。
+
+如果需要创建一个新的 *Feature*，需要继承 `Feature` 类，并实现其方法。之后，还需要在 `FeatureMap` 中注册该 *Feature*。
+
+### FeatureMap
+`FeatureMap` 工具类用于管理所有的 *Feature*，并补充一些额外的信息，例如 *Feature* 的内部名称、构造方法、显示名称、用户组等。
+
+**内部名称**是指 *Feature* 的唯一标识符（如 `"fudan_daily_feature"`），用于渲染首页时，在 `FeatureMap` 中查找指定的 *Feature* 并创建。
+
+**显示名称**是指 *Feature* 在首页的自定义布局功能中显示的名称（如 `"复旦每日"`）。由于显示名称需要国际化，因此通常用一个 `(BuildContext) -> String` 的函数来表示。
+
+**用户组**是指 *Feature* 的用户组，用于控制 *Feature* 在不同账户登录时的显示情况。例如，「复旦每日」只在复旦用户登录时显示，用户组为默认值 `[UserGroup.FUDAN_UNDERGRADUATE_STUDENT, UserGroup.FUDAN_POSTGRADUATE_STUDENT, UserGroup.FUDAN_STAFF]`。
+
+:::tip
+用户组信息由首页在显示 *Features* 时用于判断是否需要显示，而不是由 *Feature* 自身来判断。这是因为 *Feature* 本身并不知道当前用户的信息。
+
+用户组也被用于
+:::
+
+::::tip
+`FeatureMap` 不管理特殊的 *Feature*，例如顶部通知和快捷方式（即 `CustomShortcutFeature`），因为它们的创建方式与普通 *Feature* 不同：是动态生成并插入到首页的。
+
+:::note
+`CustomShortcutFeature` 代表一个快捷方式卡片，用于跳转到某个 HTTP URL。
+:::
+
+`FeatureMap` 也不记录首次使用时默认的排序方式。这目前由在 `constant.dart` 中定义的 `DashboardCard` 数组来管理。
+::::
+
+
+### DashboardCard
+`DashboardCard` 是一个 *Feature* 卡片的序列化表示，用于表示在设置项中保存用户自定义的首页布局的一项。
+
+它目前有几个特殊字段，专用于表示快捷方式信息。
+
+:::tip
+`DashboardCard` 不可用于表示顶部通知类 *Feature*。
+
+为了表示首页布局，它的内部名称额外有两个可能的取值：`FEATURE_NEW_CARD` 和 `FEATURE_DIVIDER`。它们分别表示（接下来的内容会包含在）一个新的卡片和一个分隔线。
+:::
+
+## 如何做？
+### 创建新的 *Feature*
+1. 在 `feature` 目录下创建一个新的 Dart 文件，例如 `my_feature.dart`。
+2. 在 `my_feature.dart` 中，创建一个新的类，继承 `Feature` 类，并实现其方法。可参考 `dorm_electricity_feature.dart` 中的示例和注释；
+3. 依据 `base_feature.dart` 中的注释完成元信息的定义。

docs/writing-guideline.md

@@ -0,0 +1,34 @@
+# 文档写作规范
+
+本文档用于规范文档的写作，以便于文档的统一性。
+
+## 书写规范
+1. 文档一般使用 Markdown 语法进行书写，文件后缀为`.md`；
+2. 中文写作需遵守[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md)；
+3. 对于需要提示的内容，善用 Admonitions 语法，如下：
+    ```markdown
+    :::note
+    这是一个笔记，用于次要的补充说明，如提示读者此处的内容是可选或者不完整的
+    :::
+    :::tip
+    这是一个提示，用于补充一般的说明信息
+    :::
+    :::caution
+    这是一个警告，用于强调容易忽略的信息
+    :::
+    :::danger
+    这是一个危险，用于强调禁止行为
+    :::
+    ```
+    :::note
+    这是一个笔记，用于次要的补充说明，如提示读者此处的内容是可选或者不完整的
+    :::
+    :::tip
+    这是一个提示，用于补充一般的说明信息
+    :::
+    :::caution
+    这是一个警告，用于强调容易忽略的信息
+    :::
+    :::danger
+    这是一个危险，用于强调禁止行为
+    :::

sidebars.js

@@ -13,7 +13,7 @@
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  introSidebar: ["intro", {
+  introSidebar: ["intro", "writing-guideline", {
     "Document Basic": [
       {
         type: 'autogenerated',