odoo-forge-bundle 0.1.0

package/payload/skills/view-dev/references/search.md

@@ -0,0 +1,249 @@
+# 搜索
+
+> 来源：`docs/obsidian/07 知识库/odoo文档/03_开发者/03_参考/03_用户界面/02_视图架构.md`
+> 原文章节：`## 搜索`
+>
+> 本文件从原始文档中拆分而来，以下内容尽量保留原文，仅做拆分与轻量排版。
+
+搜索视图只用于筛选另一视图的记录（通常是列表或图表），自身不直接展示内容。它的根元素是 `search`，不接受任何属性，所有行为由内部的字段、过滤器、分组等元素决定。
+
+> [!note]
+> 原文包含搜索视图结构示意图（`search.svg`）。
+> ```xml
+> <search>
+>     ...
+> </search>
+> ```
+>
+## 目录
+
+- [搜索视图简介](#搜索视图简介)
+- [组件](#组件)
+- [field：基于字段值进行过滤](#field基于字段值进行过滤)
+- [filter：创建预定义过滤器](#filter创建预定义过滤器)
+- [separator：分隔过滤器组](#separator分隔过滤器组)
+- [group：分隔过滤器组](#group分隔过滤器组)
+- [searchpanel：显示搜索面板](#searchpanel显示搜索面板)
+- [searchpanel 字段属性](#searchpanel字段属性)
+- [搜索默认值](#搜索默认值)
+
+---
+
+## 搜索视图简介
+
+`search` 的子元素决定 UI 上展示的控件：是直接显示多个字段，还是把过滤器嵌套在下拉中。搜索视图常与 `actions` 中的默认 `domain`/`context`、`group_by` 以及 `search_default_*` 结合，形成打开界面时的默认筛选。
+
+## 组件
+
+搜索视图支持以下子元素，它们也会影响搜索面板或过滤器下拉的结构：
+
+- `field`：基于字段值构建过滤限定。
+- `filter`：预定义过滤器，支持默认启用、日期周期、分组等。
+- `separator`：在连续过滤器之间插入视觉断点。
+- `group`：为多个过滤器创建分组或复杂布局。
+- `searchpanel`：在多记录视图左侧展示快速筛选栏。
+
+### field：基于字段值进行过滤
+
+`field` 元素将用户输入转换为搜索域，默认形式为 `[(name, operator, value)]`，多个字段以 `AND` 组合。
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `name` | 要过滤的字段名称 | `string` | 必填 |  |
+| `string` | 字段标签 | `string` | 模型字段的 `string` 属性 |  |
+| `operator` | 覆盖默认运算符，如 `=`、`ilike`、`child_of` 等 | `string` | 取决于字段类型 |  |
+| `filter_domain` | 使用 `self` 构建的自定义域，优先级高于 `operator` | `Python 表达式` | `[]` | 适合跨字段或有特殊逻辑的筛选 |
+| `context` | 合并到目标视图的上下文，可用 `self` 读取输入值 | `Python 表达式` | `{}` |  |
+| `completion_domain` | 自动完成功能（如 Many2one）返回结果的额外域 | `Python 表达式` | `[]` |  |
+| `groups` | 以逗号分隔的用户组列表，支持 `!` 排除 | `string` | `''` | 例如 `groups="base.group_no_one,!base.group_multi_company"` |
+| `invisible` | 控制是否显示，`False` 为可见 | `Python 表达式` | `False` | 可用于提前加载字段供表达式引用 |
+
+> [!note]
+> `invisible` 有两个用途：
+>
+> - 提高可读性，避免视图过载；
+> - 提前在视图中定义字段，以便在表达式中使用。
+
+> [!example]
+> ```xml
+> <field name="fname_b" invisible="fname_c != 3 and fname_a == parent.fname_d"/>
+> <group invisible="fname_c != 4">
+>     <field name="fname_c"/>
+>     <field name="fname_d"/>
+> </group>
+> ```
+
+> [!note]
+> 原文包含 `field` 用法示意图（`search_field.svg`）。
+> ```xml
+> <search>
+>     <field name="name" string="My Custom Name"/>
+>     <field name="amount"/>
+>     <field name="currency_id"/>
+>     <field name="ref" filter_domain="[('name', 'like', self)]"/>
+> </search>
+> ```
+
+### filter：创建预定义过滤器
+
+`filter` 元素可以定义常用筛选、设置默认启用项，或为上下文/分组提供额外数据。
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `name` | 技术名称，可被 `search_default_*` 或继承引用 | `string` | 必填 |  |
+| `string` | 显示标签 | `string` | 必填 |  |
+| `help` | 悬浮提示 | `string` | `''` |  |
+| `domain` | 附加到操作域的 Python 表达式 | `Python 表达式` | `[]` | 记录必须满足 |
+| `date` | 绑定 `date`/`datetime` 字段，以生成时间相关子项 | `string` | `''` | 需要具备时间信息的字段 |
+| `start_month` | 日期过滤器可选的最早月份（相对当前月） | `int` | `-2` | 仅对设置 `date` 的过滤器生效 |
+| `end_month` | 日期过滤器可选的最晚月份（相对当前月） | `int` | `0` |  |
+| `start_year` | 日期过滤器可选的最早年份（相对当前年） | `int` | `-2` |  |
+| `end_year` | 日期过滤器可选的最晚年份（相对当前年） | `int` | `0` |  |
+| `default_period` | 默认开启的周期或 `custom_*` 过滤器 ID | `string` | `month`（不可用则取最近月份） | 可选值：`第一季度`/`第二季度`/`第三季度`/`第四季度`/`month±x`/`year±x`/同级自定义过滤器名称（需加 `custom_`） |
+| `invisible` | 控制是否显示 | `Python 表达式` | `False` | 同 `field` 的用例 |
+| `groups` | 界定可见组，支持 `!` 排除 | `string` | `''` |  |
+| `context` | 合并到上下文，可用于 `group_by` 等 | `Python 表达式` | `{}` | 通过 `context={'group_by': 'field_id:interval'}` 控制分组；`read_groups` 可能受 `group_expand` 影响 |
+
+> [!note]
+> `invisible` 可用于避免界面拥挤，也可为表达式预留字段。
+
+> [!example]
+> ```xml
+> <field name="fname_b" invisible="fname_c != 3 and fname_a == parent.fname_d"/>
+> <group invisible="fname_c != 4">
+>     <field name="fname_c"/>
+>     <field name="fname_d"/>
+> </group>
+> ```
+
+> [!example]
+> ```xml
+> <field name="FIELD_NAME" groups="base.group_no_one,!base.group_multi_company"/>
+> ```
+
+> [!note]
+> `read_groups` 结果在分组时可能受 `group_expand` 影响，导致出现空分组。详情见 `odoo.fields.Field` 相关文档。
+
+> [!warning]
+> 过滤器之间若未用 `separator`/`group` 或其他元素分隔，会被视为包容组合，最终通过 `OR` 而非默认的 `AND`。
+
+> [!example]
+> ```xml
+> <filter domain="[('state', '=', 'draft')]"/>
+> <filter domain="[('state', '=', 'done')]"/>
+> ```
+> `state` 为 `draft` 或 `done` 的记录都会展示。
+
+> [!example]
+> ```xml
+> <filter domain="[('state', '=', 'draft')]"/>
+> <separator/>
+> <filter domain="[('delay', '<', 15)]"/>
+> ```
+> `state` 为 `draft` 且 `delay < 15` 的记录才会展示。
+
+> [!note]
+> 原文包含 `filter` 用法示意图（`search_filter.svg`）。
+> ```xml
+> <search>
+>     <filter string="My Custom Name" domain="[('name', 'ilike', 'AAA')]"/>
+>     <filter string="My orders" domain="[('user_id', '=', uid)]"/>
+>     <filter string="Category" context="{'group_by': 'category_id'}"/>
+> </search>
+> ```
+
+### separator：分隔过滤器组
+
+`separator` 在简单搜索视图中提供视觉间隔，避免过滤器拥挤。更复杂的布局建议使用 `group`。
+
+```xml
+<search>
+    <FILTERS/>
+    <separator/>
+    <FILTERS/>
+</search>
+```
+
+`separator` 无属性可设置。
+
+### group：分隔过滤器组
+
+`group` 可容纳多个过滤器、按钮或说明，用于更丰富的搜索结构。
+
+```xml
+<search>
+    <group>
+        <FILTERS/>
+    </group>
+</search>
+```
+
+`group` 也没有额外属性。
+
+### searchpanel：显示搜索面板
+
+`searchpanel` 在多记录视图（如列表）左侧渲染快速筛选栏，仅允许 `field` 子元素。
+
+```xml
+<search>
+    <searchpanel>
+        <FIELDS/>
+    </searchpanel>
+</search>
+```
+
+#### searchpanel 字段属性
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `name` | 要筛选的字段 | `string` | 必填 |  |
+| `string` | 字段标签 | `string` | 模型字段的 `string` 属性 |  |
+| `select` | 控制可选值模式，`one` 允许单选，`multi` 允许多选 | `string` | `one` | `one` 适用于 `many2one`/`selection`，`multi` 还支持 `many2many`；决定是否生成值计数器 |
+| `groups` | 控制可见用户组，支持 `!` 排除 | `string` | `''` |  |
+| `icon` | 字段图标 | `string` | `''` |  |
+| `color` | 字段颜色 | `string` | `''` |  |
+| `domain` | 附加域，记录必须满足 | `Python 表达式` | `[]` |  |
+| `limit` | 单字段可获取值的最大数量，超出显示错误；`0` 表示无限 | `int` | `200` | 用于规避性能问题，亦可重写 `search_panel_select_range`/`search_panel_select_multi_range` |
+| `context` | 合并上下文，可控制 `group_by`、`group_expand` 等 | `Python 表达式` | `{}` | 只在 `many2one`/`many2many` 上有效，常用于 `context={'group_by': 'field_id:interval'}` |
+
+`select="one"` 字段可以选择在父节点下展示子类别还是直接平铺；`select="multi"` 字段可启用计数器，只在计数器非零时展示结果。
+
+> [!tip]
+> 通过 `limit` 控制数量是避免性能下降的常用手段，另一种解决方案是重写 `search_panel_select_range`/`search_panel_select_multi_range`。
+>
+> [!example]
+> ```xml
+> <searchpanel>
+>     <field name="department_id"/>
+>     <field name="manager_id" select="multi" domain="[('department_id', '=', department_id)]"/>
+> </searchpanel>
+> ```
+
+## 搜索默认值
+
+可以通过操作上下文的 `search_default_*name*` 键预设字段或过滤器。
+
+- 字段：值即写入字段的内容。
+- 过滤器：值为布尔值或数字。
+
+> [!example]
+> 对于字段 `foo` 和过滤器 `bar`，以下上下文会在 `acro` 上搜索 `foo` 并默认启用 `bar`：
+>
+> ```python
+> {
+>     'search_default_foo': 'acro',
+>     'search_default_bar': 1
+> }
+> ```
+
+可以使用 1 到 99 的数值设置默认 `groupby` 过滤器的启用顺序。
+
+> [!example]
+> 对于 `groupby` 过滤器 `foo` 和 `bar`，以下上下文会先启用 `bar`，再启用 `foo`：
+>
+> ```python
+> {
+>     'search_default_foo': 2,
+>     'search_default_bar': 1
+> }
+> ```

package/payload/skills/view-dev/references/security.md

@@ -0,0 +1,306 @@
+# Odoo 中的安全性
+
+> 来源：`https://docs.odoo.sbggai.top/developer/reference/backend/security.html`
+>
+> 本文件整理了官方安全参考的关键机制，尽量保留原文示例并在排版上做轻度拆分以便查阅。
+
+Odoo 除了可以在代码中显式判断权限外，还提供两套数据驱动机制来控制对数据的访问：*访问权限（ACL）* 和 *记录规则*。它们都与组关联，一个用户可以属于多个组，组定义的 ACL/规则会联合起来决定他能读、写、创建、删除哪些模型或记录。
+
+## 目录
+
+- [组](#组)
+- [访问权限](#访问权限)
+- [记录规则](#记录规则)
+- [规则变量](#规则变量)
+- [字段访问](#字段访问)
+- [安全陷阱](#安全陷阱)
+- [SQL 注入](#sql-注入)
+- [未转义的字段内容](#未转义的字段内容)
+- [转义与清理](#转义与清理)
+- [评估内容](#评估内容)
+- [访问对象属性](#访问对象属性)
+
+---
+
+## 组
+
+组是 Odoo 安全配置的基础承载对象。访问权限、记录规则和字段级限制都会围绕组来组合与复用。
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | 组的用户可读名称，用于说明角色或职责。 |
+| `category_id` | 模块类别，用于在用户表单中组织组选项，常表现为互斥选择。 |
+| `implied_ids` | 隐式包含的其他组，可理解为便捷继承，用于复用已有权限组合。 |
+| `comment` | 对组用途、边界或使用方式的补充说明。 |
+
+> [!note]
+> `implied_ids` 只是便捷继承。被隐含的组仍然可以在用户身上显式移除。
+
+## 访问权限
+
+访问权限（ACL）直接将某个组与模型的读/写/创建/删除操作绑定：只要当前用户所属的任一组授予某项操作，他就能执行该操作。它们的权限是累加的，跨组组合成并集。
+
+| 字段 | 说明 |
+| --- | --- |
+| `perm_read` | 是否允许读取模型数据。 |
+| `perm_write` | 是否允许更新该模型的记录。 |
+| `perm_create` | 是否允许创建新记录。 |
+| `perm_unlink` | 是否允许删除记录。 |
+| `group_id` | 绑定到某个组（空值表示授予所有用户）。 |
+
+访问权限以 `perm_*` 属性设置，默认不选中任何项（即所有 CRUD 操作都必须显式打开）。空的 `group_id` 表示非员工（例如门户或公共用户）也会被覆盖。
+
+## 记录规则
+
+记录规则是可选的“域过滤器”，它们在访问权限判断之后逐条评估：只要某条规则的域与记录匹配，就允许选定的操作；未匹配时则拒绝。规则可以绑定一个或多个组，也可以是*全局*规则（没有组约束）。
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | 规则名称（可选）。 |
+| `model_id` | 规则适用的模型。 |
+| `domain_force` | 用于匹配记录的域（Python 表达式）。 |
+| `perm_*` | `perm_read`/`perm_create`/`perm_write`/`perm_unlink`，指定该规则针对哪些操作生效。 |
+| `groups` | 规则生效的组；为空表示全局规则。 |
+
+规则使用 `groups` 构建权限的 *并集*：只要满足其中之一即可通过。如果某条规则没有组，它会作为 *全局规则* 参与交集逻辑（即所有全局规则必须同时满足）。
+
+### 全局规则与组规则
+
+- 全局规则之间是*交集*关系：若多条全局规则同时适用，则必须全部满足。
+- 组规则之间是*并集*关系：若多条组规则适用，满足其中之一即可放行。
+- 全局规则集与组规则集之间仍是*交集*关系：第一条组规则加入后，访问范围仍受全局规则上界限制。
+
+> [!note]
+> 添加多个全局规则时要小心，因为它们的交集可能完全排除所有访问权限。
+
+## 规则变量
+
+许多记录规则依赖上下文变量来构造域表达式，以下变量在规则中可直接引用：
+
+| 变量 | 说明 |
+| --- | --- |
+| `time` | Python 的 [`time`](https://docs.python.org/3/library/time.html#module-time) 模块。 |
+| `user` | 当前用户（`res.users` 实例）。 |
+| `company_id` | 当前选择的公司 ID。 |
+| `company_ids` | 当前用户有权访问的公司 ID 列表；多公司场景下通常要结合对应的安全规则一起理解。 |
+
+规则中的 `perm_*method*` 与 ACL 中的字段语义不同，它指定的是 *该规则* 针对哪些操作进行评估；未选中的操作会被忽略。默认情况下所有 CRUD 操作都被选中。
+
+## 字段访问
+
+字段可以通过 `groups` 属性绑定到某些组。若用户不属于该组：
+
+- 该字段会从请求的视图中移除（视图渲染时自动过滤）。
+- 它也会从 `fields_get()` 的响应中省略。
+- 任何显式的读写尝试都会抛出访问错误。
+
+## 安全陷阱
+
+理解常见的漏洞模式有助于编写安全的业务逻辑。
+
+### 不安全的公共方法
+
+所有公开方法都可以通过 RPC / 外部 API 调用，因此不要信任传入记录和参数（ACL 仅在 CRUD 期间生效）。
+
+```python
+# this method is public and its arguments can not be trusted
+def action_done(self):
+    if self.state == "draft" and self.env.user.has_group('base.manager'):
+        self._set_state("done")
+
+# this method is private and can only be called from other python methods
+def _set_state(self, new_state):
+    self.sudo().write({"state": new_state})
+```
+
+即使方法名以 `_` 开头，也需要额外的限制（例如 `sudo` / `check_access_rule`）来防止绕过 ACL。
+
+### 绕过 ORM
+
+直接使用数据库游标会绕过 ORM 提供的自动化（翻译、`active`、访问权限等），还可能让代码更难维护。
+
+```python
+# very very wrong
+self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in (' + ','.join(map(str, ids))+') AND state=%s AND obj_price > 0', ('draft',))
+auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]
+
+# no injection, but still wrong
+self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in %s '\
+           'AND state=%s AND obj_price > 0', (tuple(ids), 'draft',))
+auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]
+
+# better
+auction_lots_ids = self.search([('auction_id','in',ids), ('state','=','draft'), ('obj_price','>',0)])
+```
+
+### SQL 注入
+
+不要拼接字符串构造 SQL，始终让 psycopg2 或 ORM 处理参数化。
+
+```python
+# the following is very bad:
+self.env.cr.execute('SELECT distinct child_id FROM account_account_consol_rel ' +
+           'WHERE parent_id IN ('+','.join(map(str, ids))+')')
+
+# better
+self.env.cr.execute('SELECT DISTINCT child_id '\
+           'FROM account_account_consol_rel '\
+           'WHERE parent_id IN %s',
+           (tuple(ids),))
+```
+
+参考 psycopg2 文档（链接请参阅原文）了解参数化细节。
+
+- [查询参数的问题](http://initd.org/psycopg/docs/usage.html#the-problem-with-the-query-parameters)
+- [如何使用 psycopg2 传递参数](http://initd.org/psycopg/docs/usage.html#passing-parameters-to-sql-queries)
+- [高级参数类型](http://initd.org/psycopg/docs/usage.html#adaptation-of-python-values-to-sql-types)
+- [Psycopg 文档](https://www.psycopg.org/docs/sql.html)
+
+### 未转义的字段内容
+
+切勿用 `t-raw` 渲染来自用户的富文本，因为它们不会自动转义。
+
+```javascript
+QWeb.render('insecure_template', {
+    info_message: "You have an <strong>important</strong> notification",
+})
+```
+
+```xml
+<div t-name="insecure_template">
+    <div id="information-bar"><t t-raw="info_message" /></div>
+</div>
+```
+
+一旦模板里直接插入 `<strong>` 和用户输入，就会造成 XSS 风险，哪怕它最初看似安全。
+
+更安全的做法是把文本内容和表现样式拆开：
+
+```javascript
+QWeb.render('secure_template', {
+    message: "You have an important notification on the product:",
+    subject: product.name,
+})
+```
+
+```xml
+<div t-name="secure_template">
+    <div id="information-bar">
+        <div class="info"><t t-esc="message" /></div>
+        <div class="subject"><t t-esc="subject" /></div>
+    </div>
+</div>
+```
+
+```css
+.subject {
+    font-weight: bold;
+}
+```
+
+### 使用 `Markup` 构造安全内容
+
+`Markup` 类型会自动转义参数，因此可以在格式化字符串前用它包裹模板。
+
+```pycon
+>>> Markup('<em>Hello</em> ') + '<foo>'
+Markup('<em>Hello</em> &lt;foo&gt;')
+>>> Markup('<em>Hello</em> %s') % '<foo>'
+Markup('<em>Hello</em> &lt;foo&gt;')
+```
+
+不过，这会在某些组合中带来怪异结果，使用时要保持小心，例如：
+
+```pycon
+>>> Markup('<a>').replace('>', 'x')
+Markup('<a>')
+>>> Markup('<a>').replace(Markup('>'), 'x')
+Markup('<ax')
+```
+
+> [!tip]
+> 大多数安全 API 本身就会返回带有内置特性的 `Markup`。
+
+`escape`（`html_escape`）将任意字符串转成 `Markup` 并转义内容。
+
+```python
+def get_name(self, to_html=False):
+    if to_html:
+        return Markup("<strong>%s</strong>") % self.name  # escape the name
+    else:
+        return self.name
+
+>>> record.name = "<R&D>"
+>>> escape(record.get_name())
+Markup("&lt;R&amp;D&gt;")
+>>> escape(record.get_name(True))
+Markup("<strong>&lt;R&amp;D&gt;</strong>")
+```
+
+### 转义与清理
+
+> [!warning]
+> 只要混合数据与代码，转义就是必须的；这不仅是安全问题，也是正确性问题。
+
+**转义** 将文本转换为代码，把用户数据安全地插入模板。只要混合数据与模板，就必须转义。
+
+```python
+>>> from odoo.tools import html_escape, html_sanitize
+>>> data = "<R&D>"
+>>> code = html_escape(data)
+>>> self.website_description = Markup("<strong>%s</strong>") % code
+```
+
+**清理** 是在转义之后再处理*代码*，用于剥除不受信任的模式（例如删除 `style`）。它不会对文本起作用，因此只有在代码确实来自用户并且需要剪裁时才用。
+
+```python
+>>> html_sanitize(data)
+Markup('')
+>>> html_sanitize(code)
+Markup('<p>&lt;R&amp;D&gt;</p>')
+```
+
+```python
+>>> html_sanitize(code, strip_classes=True)
+Markup('<p>Important Information</p>')
+```
+
+### 评估内容
+
+千万别用 `eval` 解析用户数据，可以改用 `safe_eval` 或更安全的 `literal_eval`：
+
+```python
+# very bad
+domain = eval(self.filter_domain)
+
+# better but still not recommended
+from odoo.tools import safe_eval
+domain = safe_eval(self.filter_domain)
+
+# good
+from ast import literal_eval
+domain = literal_eval(self.filter_domain)
+```
+
+| 语言 | 数据类型 | 推荐解析器 |
+| --- | --- | --- |
+| Python | 整数/浮点等 | `int()` / `float()` / `literal_eval()` |
+| JavaScript | 对象、列表等 | `JSON.parse()` |
+
+### 访问对象属性
+
+避免直接使用 `getattr`/`setattr` 访问任意字段，它们会绕过访问控制。可以改用记录集的 `__getitem__`：
+
+```python
+# unsafe retrieval
+def _get_state_value(self, res_id, state_field):
+    record = self.sudo().browse(res_id)
+    return getattr(record, state_field, False)
+
+# better retrieval
+def _get_state_value(self, res_id, state_field):
+    record = self.sudo().browse(res_id)
+    return record[state_field]
+```
+
+无论哪个方法，都要对 ID/字段进行额外校验。

package/payload/skills/view-dev/references/settings.md

@@ -0,0 +1,140 @@
+# 设置
+
+> 来源：`docs/obsidian/07 知识库/odoo文档/03_开发者/03_参考/03_用户界面/02_视图架构.md`
+> 原文章节：`## 设置`
+>
+> 本文件从原始文档中拆分而来，以下内容尽量保留原文，仅做拆分与轻量排版。
+
+设置视图是表单视图的一种定制，它们在集中位置显示设置配置条目，内置搜索栏与侧边栏（应用导航）。
+
+> [!example]
+> ```xml
+> <app string="CRM" name="crm">
+>     <setting type="header" string="Foo">
+>         <field name="foo" title="Foo?."/>
+>         <button name="nameAction" type="object" string="Button"/>
+>     </setting>
+>     <block title="Title of group Bar">
+>         <setting help="this is bar" documentation="/applications/technical/web/settings/this_is_a_test.html">
+>             <field name="bar"/>
+>         </setting>
+>         <setting string="This is Big BAR" company_specific="1">
+>             <field name="bar"/>
+>         </setting>
+>     </block>
+>     <block title="Title of group Foo">
+>         <setting string="Personalize setting" help="this is a full personalize setting">
+>             <div>This is a different setting</div>
+>         </setting>
+>     </block>
+> </app>
+> ```
+
+## 目录
+
+- [设置视图简介](#设置视图简介)
+- [组件](#组件)
+- [`app`：声明应用程序](#app声明应用程序)
+- [`block`：声明一组设置](#block声明一组设置)
+- [`setting`：声明设置](#setting声明设置)
+
+---
+
+## 设置视图简介
+
+设置视图继承表单视图的语义组件，但额外引入搜索/侧边栏结构，方便在单个页面中编辑多组设置。
+
+## 组件
+
+设置视图接受表单视图中的 `field`、`label`、`button` 元素，以及三个额外子元素：`app`、`block`、`setting`。占位符以全大写字母表示。
+
+### `app`：声明应用程序
+
+`app` 元素在设置视图的侧边栏中注册一个应用项，并充当搜索时的分隔符。
+
+```xml
+<form>
+    <app string="NAME" name="TECHNICAL_NAME">
+    ...
+    </app>
+</form>
+```
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `string` | 应用在界面中显示的名称 | `string` | `''` | 必填 |
+| `name` | 应用的技术名称（通常与模块名一致） | `string` | `''` | 必填，用于计算图标路径 |
+| `icon` | 相对于模块的图标路径 | `string` | `/*name*/static/description/icon.png` | 默认使用 `name` 生成的路径 |
+| `groups` | 仅对这些组可见，可用 `!` 前缀排除 | `string` | `''` | 示例：`base.group_no_one,!base.group_multi_company` |
+| `invisible` | 控制是否隐藏 | `Python 表达式` | `False` | 与其他视图组件一致，支持 `True`/`False` 表达式 |
+
+> [!note]
+> `invisible` 属性既用来控制可用性（避免界面过载）也用来提前声明字段以供表达式使用。
+
+> [!example]
+> ```xml
+> <field name="fname_b" invisible="fname_c != 3 and fname_a == parent.fname_d"/>
+> <group invisible="fname_c != 4">
+>     <field name="fname_c"/>
+>     <field name="fname_d"/>
+> </group>
+> ```
+
+### `block`：声明一组设置
+
+`block` 元素将多个设置按分组组织，常用于给出标题与说明。
+
+```xml
+<form>
+    <app string="NAME" name="TECHNICAL_NAME">
+        ...
+        <block title="TITLE">
+            ...
+        </block>
+        ...
+    </app>
+</form>
+```
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `title` | 分组头部显示的标题 | `string` | `''` | 可用于搜索 |
+| `description` | 标题下方的描述文本 | `string` | `''` | 可用于搜索 |
+| `groups` | 仅对这些组可见 | `string` | `''` | 支持 `!` 排除 |
+| `invisible` | 控制是否隐藏 | `Python 表达式` | `False` | 用法同上 |
+
+### `setting`：声明设置
+
+`setting` 元素定义真正的设置项。第一个字段决定标签：布尔字段出现在左侧，其他字段出现在右侧顶部。若设置了 `type="header"`，该设置以横幅形式呈现，标明后续配置项的作用域（例如网站、公司）。
+
+```xml
+<form>
+    <app string="NAME" name="TECHNICAL_NAME">
+        <block title="TITLE">
+            ...
+            <setting string="SETTING_NAME">
+                ...
+                <field name="FIELD_NAME"/>
+                ...
+            </setting>
+            ...
+        </block>
+    </app>
+</form>
+```
+
+| 属性 | 说明 | 类型 | 默认 | 备注 |
+| --- | --- | --- | --- | --- |
+| `type` | `header` 可将设置渲染为横幅 | `string` | `''` | 其他值按常规展示 |
+| `string` | 设置标签或排序参考（第一个字段的标签） | `string` | `''` | 用作标签文本 |
+| `help` | 鼠标悬停提示文本 | `string` | `''` |  |
+| `description` | 标签下方的描述（带 `text-muted` 样式） | `string` | `''` |  |
+| `company_specific` | 若设置为 `'1'`，会在标签旁显示公司图标 | `string` | `''` |  |
+| `documentation` | 点击文档图标时的路径 | `string` | `''` | 支持绝对或相对路径（相对基于 `https://www.odoo.com/documentation/<version>`） |
+| `groups` | 仅对这些组可见（支持 `!` 排除） | `string` | `''` |  |
+| `invisible` | 控制是否隐藏 | `Python 表达式` | `False` |  |
+
+> [!example]
+> ```xml
+> <field name="FIELD_NAME" groups="base.group_no_one,!base.group_multi_company"/>
+> ```