odoo-forge-bundle 0.1.0

package/payload/skills/view-dev/references/orm-api.md

@@ -0,0 +1,149 @@
+# ORM API
+
+> 来源：`https://docs.odoo.sbggai.top/developer/reference/backend/orm.html`
+>
+> 本文件从官方 ORM API 参考整理而来，力求还原原文段落顺序，补全目录并用表格/小节提升可读性。
+
+ORM API 涵盖以下主题：
+
+- 分层结构
+- 约束一致性与验证
+- 对象元数据依赖于其状态
+- 通过复杂查询优化处理（一次执行多个操作）
+- 字段默认值
+- 权限优化
+- 持久化对象：PostgreSQL 数据库
+- 数据转换
+- 多级缓存系统
+- 两种不同的继承机制
+- 丰富的字段类型：经典类型、关系类型和功能性字段
+
+## 目录
+
+- [模型](#模型)
+- [抽象模型](#抽象模型)
+- [临时模型](#临时模型)
+- [字段](#字段)
+
+---
+
+## 模型
+
+模型通过在 Python 类中声明字段（`fields.Char()`、`fields.Many2one()` 等）来构造：这些字段就是模型的属性。下面是最基础的模型定义示例：
+
+```python
+from odoo import models, fields
+
+class AModel(models.Model):
+    _name = 'a.model.name'
+
+    field1 = fields.Char()
+```
+
+> [!warning]
+> 如果字段与方法同名，方法会默默覆盖字段。
+
+默认情况下，字段标签是字段名称的首字母大写形式，也可以通过 `string` 参数覆盖：
+
+```python
+field2 = fields.Integer(string="Field Label")
+```
+
+默认值可以直接写在字段参数里：
+
+```python
+name = fields.Char(default="a value")
+```
+
+也可以提供一个函数来计算默认值：
+
+```python
+def _default_name(self):
+    return self.get_value()
+
+name = fields.Char(default=lambda self: self._default_name())
+```
+
+### 基类与实例
+
+所有模型都继承自 `models.Model`（常规持久化模型）、`models.TransientModel`（临时数据/定期清理的模型）或 `models.AbstractModel`（抽象超类）。每个数据库会实例化一份模型类，对应模块安装情况决定哪些模型可用。模型实例即“记录集”，由 `browse()`、`search()` 等方法返回，并承载字段访问与 RPC 操作。
+
+> [!tip]
+> 继承 `AbstractModel` 可以创建不连表的模型。
+
+### 模型配置
+
+| 属性 | 说明 |
+| --- | --- |
+| `_name` | 模型的技术名称（点号命名空间）。 |
+| `_auto` | 是否自动生成数据库表（默认 `True`）。设置为 `False` 时需自定义 `init()` 创建表。 |
+| `_log_access` | 是否自动生成和更新访问日志字段。默认跟随 `_auto`。 |
+| `_table` | 当 `_auto=True` 时使用的 SQL 表名。 |
+| `_sql_constraints` | SQL 约束列表，格式通常为 `(name, sql_definition, message)`。 |
+| `_register` | 是否在注册表中创建实体实例。 |
+| `_abstract` | 模型是否为抽象模型。 |
+| `_transient` | 模型是否为临时模型。 |
+| `_description` | 模型的非正式名称。 |
+| `_inherit` / `_inherits` | `_inherit` 用于原地扩展，`_inherits` 用于组合继承（映射父模型与关系字段）。 |
+| `_rec_name` | 作为记录显示名称的字段，默认 `name`。 |
+| `_order` | 查询默认排序字段，可覆盖 `_order` 属性。 |
+| `_check_company_auto` | 在写入和创建时自动调用 `_check_company` 校验公司一致性。 |
+| `_parent_store` / `_parent_path` / `_parent_field` | 控制层次结构字段与索引，有助于 `child_of` / `parent_of` 域运算符。 |
+| `_fold_name` | 用于确定看板视图中折叠组的字段。 |
+| `_transient_max_count` / `_transient_max_hours` | 临时模型的最大记录数与最大生存小时数（仅用于 `TransientModel`）。 |
+
+> 注册表中每个模型最多实例化一次，对应特定数据库。
+
+### 记录生命周期
+
+ORM 自动生成并更新访问日志字段（参见 `ir.logging` 相关字段），并允许通过 `_check_company` 校验多公司关系字段的公司一致性。
+
+## 抽象模型
+
+`AbstractModel` 是 `odoo.models.BaseModel` 的别名，用于定义无表的超类。它提供共享逻辑供多个模型继承，使得抽象字段与方法可以复用。
+
+> [!seealso]
+> `odoo.models.AbstractModel`
+
+## 临时模型
+
+`TransientModel` 专为临时记录设计：数据存储后会定期清理，默认所有用户可以创建记录，但只能访问自己的记录，超级用户具备无限权限。
+
+| 属性 | 说明 |
+| --- | --- |
+| `_transient_max_count` | 临时记录的最大数量，`0` 表示不限制。 |
+| `_transient_max_hours` | 最大空闲生存时间（小时），`0` 表示不限制。 |
+
+实际清理通常每 5 分钟触发一次，因此可以在频繁创建记录时重复调用。
+
+## 字段
+
+字段描述符决定字段如何展示与存储，常见属性如下：
+
+| 属性 | 说明 |
+| --- | --- |
+| `string` | 用户界面标签，默认字段名首字母大写。 |
+| `help` | 鼠标悬停提示文本。 |
+| `readonly` | 是否只读（仅影响 UI）。 |
+| `required` | 是否必填。 |
+| `index` | 索引策略，可设为 `True`/`btree`/`trigram` 等。 |
+| `default` | 默认值，可为静态值或回调函数。 |
+| `groups` | 逗号分隔的安全组 XML ID，指定字段可见用户。 |
+| `company_dependent` | 是否依赖公司（以 JSONB 存储）。 |
+| `copy` | 复制记录时是否复制字段值。 |
+| `store` | 是否存储在数据库（计算字段默认 `False`）。 |
+| `aggregator` | 用于 `read_group()` 的聚合函数，如 `sum`、`count_distinct`、`array_agg`。 |
+| `group_expand` | 在当前字段上分组时，用于扩展 `read_group()` 结果的函数。 |
+| `compute` | 计算字段的方法名称。 |
+| `precompute` | 是否在插入数据库前预计算字段。 |
+| `compute_sudo` | 是否以超级用户身份重新计算字段。 |
+| `recursive` | 是否存在递归依赖。 |
+| `inverse` | 反向写回方法名。 |
+| `search` | 自定义搜索方法名。 |
+| `related` | 关联字段的字段名称序列。 |
+| `default_export_compatible` | 是否在兼容导入的导出中默认导出。 |
+
+> [!note]
+> `default` 可传递 `lambda self:` 的函数以依赖上下文。
+
+字段还可以继承 `compute` 函数、`inverse` 方法与 `search` 逻辑，以实现复杂计算与搜索行为。

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

@@ -0,0 +1,109 @@
+# 透视表
+
+> 来源：`docs/obsidian/07 知识库/odoo文档/03_开发者/03_参考/03_用户界面/02_视图架构.md`
+> 原文章节：`## 透视表`
+> 本文件从原始文档中拆分而来，以下内容尽量保留原文，仅做拆分与轻量排版。
+
+透视表视图用于将聚合结果可视化为透视表。其根元素是 `<pivot>`。
+
+## 目录
+
+- [根元素](#根元素)
+- [根属性](#根属性)
+- [`field` 元素](#field-元素)
+- [`field` 属性](#field-属性)
+- [度量与聚合规则](#度量与聚合规则)
+- [限制与注意事项](#限制与注意事项)
+- [字段格式化（widget）](#字段格式化widget)
+- [示例](#示例)
+
+---
+
+## 根元素
+
+```xml
+<pivot>
+    ...
+</pivot>
+```
+
+## 根属性
+
+`pivot` 根元素可配置以下属性：
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `disable_linking` | 设为 `1` 时，移除透视表单元格到列表视图的链接。 | `bool` / `int` | `False` |
+| `display_quantity` | 设为 `1` 时，默认显示数量列。 | `bool` / `int` | `False` |
+| `default_order` | 设置默认排序的度量及顺序（`asc` 或 `desc`）。 | `string` | `''` |
+| `sample` | 当前模型无记录时，是否填充一组示例记录。 | `bool` | `False` |
+
+> [!note]
+> 原文中的“示例记录”描述以散段出现，未紧邻属性名；此处按上下文整理为 `sample` 属性。
+
+关于 `sample`：
+
+- 虚拟记录会按字段名/模型应用启发式填充。
+- 例如 `res.users.display_name` 会生成示例人名，`email` 会类似 `firstname.lastname@sample.demo`。
+- 用户无法与这些虚拟数据交互；一旦执行创建记录、添加列等操作，示例数据会被丢弃。
+
+## `field` 元素
+
+透视表视图中唯一允许的子元素是 `field`。
+
+## `field` 属性
+
+| 属性 | 说明 | 类型 | 默认值 | 备注 |
+| --- | --- | --- | --- | --- |
+| `name` | 要在视图中使用的字段名。 | `string` | 必填 | 用于分组或聚合 |
+| `string` | 显示名称，覆盖字段默认 `string`。 | `string` | 字段默认值 |  |
+| `type` | 字段角色：`row` / `col` / `measure`。 | `string` | `row` | 用于定义分组轴或度量 |
+| `interval` | 日期/日期时间字段的分组粒度：`day` / `week` / `month` / `quarter` / `year`。 | `string` | `month` | 仅日期相关字段有效 |
+| `invisible` | 为 `true` 时，不出现在活动度量或可选度量中。 | `bool` | `False` | 常用于不适合聚合的字段（如单位不一致） |
+| `widget` | 指定字段格式化器。 | `string` | `''` | 常用：`date` / `datetime` / `float_time` / `monetary` |
+
+`type` 的取值语义：
+
+- `row`：按字段进行行分组。
+- `col`：按字段进行列分组。
+- `measure`：作为组内聚合值。
+
+## 度量与聚合规则
+
+- 度量会自动从模型字段生成。
+- 仅可聚合字段会被作为候选度量。
+- 候选度量按字段的 `string` 字母顺序排序。
+
+## 限制与注意事项
+
+> [!warning]
+> 与图表视图类似，透视表聚合在数据库内容上执行，非存储的函数字段不能用于透视表视图。
+
+## 字段格式化（widget）
+
+在透视表中可通过 `field` 的 `widget` 属性指定格式化器，常用包括：
+
+- `date`
+- `datetime`
+- `float_time`
+- `monetary`
+
+## 示例
+
+默认排序示例：
+
+```xml
+<pivot default_order="foo asc">
+   <field name="foo" type="measure"/>
+</pivot>
+```
+
+工时透视表示例：
+
+```xml
+<pivot string="Timesheet">
+    <field name="employee_id" type="row"/>
+    <field name="date" interval="month" type="col"/>
+    <field name="unit_amount" type="measure" widget="float_time"/>
+</pivot>
+```

package/payload/skills/view-dev/references/python-expressions.md

@@ -0,0 +1,48 @@
+# Python 表达式
+
+> 来源：`docs/obsidian/07 知识库/odoo文档/03_开发者/03_参考/03_用户界面/02_视图架构.md`
+> 原文章节：`## Python 表达式`
+>
+> 本文件从原始文档中拆分而来，以下内容尽量保留原文，仅做拆分与轻量排版。
+
+在评估节点属性时（例如 `readonly` 修饰符），可以提供一个 Python 表达式。表达式会在当前视图上下文中执行，并可访问模型字段与环境变量来控制界面行为。
+
+## 目录
+
+- [可用变量](#可用变量)
+- [示例](#示例)
+
+---
+
+## 可用变量
+
+| 变量 | 描述 |
+| --- | --- |
+| 所有字段 | 当前视图中所有字段的名称和值；列表视图里被 `column_invisible` 标记的字段会被排除，关系字段以 ID 列表形式提供。 |
+| `id` | 当前记录的 ID。 |
+| `parent` | 当前字段所在容器的记录，仅在子视图（如关系字段中的 `<form>`）中可用。 |
+| `context` | 当前视图的上下文字典，可以读取默认值或行为开关。 |
+| `uid` | 当前用户的 ID。 |
+| `today` | 本地日期，格式为 `YYYY-MM-DD`。 |
+| `now` | 本地日期时间，格式为 `YYYY-MM-DDhh:mm:ss`。 |
+
+## 示例
+
+### 示例 1：基于上下文与字段值控制可见性
+
+```xml
+<field name="field_a" readonly="True"/>
+<field name="field_b" invisible="context.get('show_me') and field_a == 4"/>
+```
+
+### 示例 2：在子视图中使用 `parent`
+
+```xml
+<field name="field_a"/>
+<field name="x2m">
+    <!-- sub-view -->
+    <form>
+        <field name="field_b" invisible="parent.field_a"/>
+    </form>
+</field>
+```

package/payload/skills/view-dev/references/qweb-templates.md

@@ -0,0 +1,326 @@
+# QWeb 模板
+
+> 来源：`https://docs.odoo.sbggai.top/developer/reference/frontend/qweb.html`
+>
+> 本文件按原始 QWeb 模板参考拆分，对照二级/三级标题还原全部章节，尽量保留原文示例与提示，只做排版优化。
+
+QWeb 是 Odoo 主要采用的 XML 模板引擎，模板规则通过 `t-` 前缀属性表达行为，`<t>` 元素用于执行指令但本身不渲染 DOM。
+
+## 目录
+
+- [输出](#输出)
+- [条件语句](#条件语句)
+- [循环](#循环)
+- [循环变量速查](#循环变量速查)
+- [属性指令](#属性指令)
+- [设置变量](#设置变量)
+- [调用子模板](#调用子模板)
+- [高级输出](#高级输出)
+- [已弃用的输出指令](#已弃用的输出指令)
+- [Python 相关指令](#python-相关指令)
+- [调试](#调试)
+- [缓存](#缓存)
+- [辅助工具](#辅助工具)
+- [API](#api)
+- [JavaScript 专用指令](#javascript-专用指令)
+- [旧的继承机制（已弃用）](#旧的继承机制已弃用)
+
+---
+
+## 输出
+
+`<t t-out="expr"/>` 会对结果做 HTML 转义，防止[XSS](https://en.wikipedia.org/wiki/Cross-site_scripting)攻击：
+
+```xml
+<p><t t-out="value"/></p>
+```
+
+当 `value=42` 时渲染 `<p>42</p>`；需要原样输出请参见“高级输出”。
+
+## 条件语句
+
+`<t t-if="expr">` 只在表达式为真时渲染，任何元素都能承载该属性：
+
+```xml
+<div>
+    <t t-if="condition">
+        <p>ok</p>
+    </t>
+</div>
+```
+
+`<p t-if="condition">` 与上述等效，链式条件使用 `t-elif`/`t-else`：
+
+```xml
+<div>
+    <p t-if="user.birthday == today()">Happy birthday!</p>
+    <p t-elif="user.login == 'root'">Welcome master!</p>
+    <p t-else="">Welcome!</p>
+</div>
+```
+
+## 循环
+
+`<t t-foreach="sequence" t-as="item">` 迭代数组、映射或整数区间（整数形式即 `[0,1,...n-1]`，但这种写法已弃用）：
+
+```xml
+<t t-foreach="[1, 2, 3]" t-as="i">
+    <p><t t-out="i"/></p>
+</t>
+```
+
+可以赋予任何元素该属性：
+
+```xml
+<p t-foreach="[1, 2, 3]" t-as="i">
+    <t t-out="i"/>
+</p>
+```
+
+### 循环变量速查
+
+| 变量 | 说明 | 可用范围 |
+| --- | --- | --- |
+| `$as` | 等于 `t-as` 指定名称 | 当前 `foreach` |
+| `$as_all` | 被迭代对象（数组或映射） | 当前 `foreach` |
+| `$as_value` | 当前值（映射则为 value） | 当前 `foreach` |
+| `$as_index` | 当前索引（从 0 起） | 当前 `foreach` |
+| `$as_size` | 集合长度（若可用） | 当前 `foreach` |
+| `$as_first` | 是否首项 | 当前 `foreach` |
+| `$as_last` | 是否末项 | 当前 `foreach` |
+| `$as_parity` | `"even"` / `"odd"` | 当前 `foreach` |
+| `$as_even` | 布尔，索引是否偶数 | 当前 `foreach` |
+| `$as_odd` | 布尔，索引是否奇数 | 当前 `foreach` |
+
+其中 `$as` 会被 `t-as` 指定的名字替换，例如 `t-as="item"` 时，对应变量会变成 `item_index`、`item_value` 等。
+
+这些变量仅在 `foreach` 作用域内有效；若同名变量在循环外已经存在，则循环结束后会把最终值复制回外部上下文，新建变量则不会泄漏到作用域外。
+
+## 属性指令
+
+通过 `t-att` 系列指令动态设置属性：
+
+| 指令 | 描述 |
+| --- | --- |
+| `t-att-$name` | 求值后赋值给名为 `$name` 的属性，例如 `<div t-att-a="42"/>` → `<div a="42">`。 |
+| `t-attf-$name` | 以格式化字符串生成属性值，支持 `{{...}}`（Jinja）或 `#{...}`（Ruby）。可用于类的切换。 |
+| `t-att=mapping` | 传入字典，映射中的所有键值都转换为属性。 |
+| `t-att=pair` | 传入 `[name, value]` 或 tuple，生成单个属性。 |
+
+```xml
+<t t-foreach="[1, 2, 3]" t-as="item">
+    <li t-attf-class="row {{ (item_index % 2 === 0) ? 'even' : 'odd' }}">
+        <t t-out="item"/>
+    </li>
+</t>
+```
+
+> [!tip]
+> 格式化字符串支持 `{{code}}` 与 `#{code}` 两种语法。
+
+## 设置变量
+
+`<t t-set="name" t-value="expr"/>` 定义变量；若未传 `t-value`，则节点主体渲染结果即变量值：
+
+```xml
+<t t-set="foo" t-value="2 + 1"/>
+<t t-out="foo"/>
+```
+
+```xml
+<t t-set="foo">
+    <li>ok</li>
+</t>
+<t t-out="foo"/>
+```
+
+变量在 `t-set` 作用域外仍保留。
+
+## 调用子模板
+
+`<t t-call="template_name"/>` 在当前上下文中渲染指定模板：
+
+```xml
+<t t-call="other-template"/>
+```
+
+上下文包括父层变量。可以在 `t-call` 内设置值，调用体可在被调用模板中通过特殊变量 `0` 访问：
+
+```xml
+<t t-call="other-template">
+    <t t-set="var" t-value="1"/>
+</t>
+```
+
+调用体示例输出：
+
+```xml
+<div>
+    This template was called with content:
+    <t t-out="0"/>
+</div>
+```
+
+## 高级输出
+
+默认 `t-out` 会自动转义；若想绕过可使用安全标记或 `markupsafe.Markup`。
+
+### Python
+
+下列 API 输出默认不再转义：
+
+- `odoo.fields.Html` 字段
+- `html_escape()` / `markupsafe.escape()`（同义，安全）
+- `html_sanitize()`
+- `markupsafe.Markup`（*警告*：它表明你认定内容安全，但不会验证，因此谨慎使用）
+- `to_text()`（不会回收安全标志）
+
+> [!warning]
+> `markupsafe.Markup` 是断言内容安全的类型，但并不自动校验，需要谨慎。
+
+### 强制双重转义
+
+若内容已被标记为安全但仍需转义，可调用 `str(content)`（Python）或 `String(content)`（JavaScript）剥离安全标志：
+
+> [!note]
+> `Markup` 比 `Markup()` 更丰富，字符串拼接在 Python 中会产生带安全标记的 `Markup`，而在 JavaScript 中则可能生成普通 `String`，从而泄露未转义内容。
+
+### 已弃用的输出指令
+
+| 指令 | 说明 |
+| --- | --- |
+| `esc` | `out` 的别名，功能相同但语义模糊。 |
+| `raw` | 不转义内容；15.0 版后下架，建议用 `out` + `markupsafe.Markup`。 |
+| `t-raw` | 已弃用，输出原始 HTML 带来高风险。 |
+
+## Python 相关指令
+
+| 指令 / 能力 | 说明 |
+| --- | --- |
+| `t-field` | 仅在“智能记录”（`browse` 返回）上可用，自动格式化字段，并集成网站富文本。 |
+| `t-options` | 常与 `t-field` 或 `widget` 配合使用；参数取决于具体字段或 widget。 |
+| 资产包相关指令 | 用于组织与注入模块资源（样式、脚本等）。 |
+
+## 调试
+
+| 指令 | 说明 |
+| --- | --- |
+| `t-debug` | 在渲染期间触发调试器断点（调试器激活时生效）。 |
+| `t-log` | 求值并 `console.log` 当前表达式（JavaScript QWeb）。 |
+| `t-js` | 在节点内执行 JavaScript，通常接收 `ctx` 参数访问当前上下文。 |
+
+`t-js` 示例：
+
+```xml
+<t t-set="foo" t-value="42"/>
+<t t-js="ctx">
+    console.log("Foo is", ctx.foo);
+</t>
+```
+
+## 缓存
+
+`t-cache` / `t-nocache` 用于控制局部渲染缓存。
+
+### `t-cache`
+
+`<div t-cache="expr">` 会缓存被标记区域的渲染结果，子指令通常只在首次渲染时执行。适用于依赖少量数据、且命中率高的片段。
+
+缓存键表达式应谨慎设计（例如记录 ID、`write_date` 等），以便数据更新时能自动失效。
+
+### `t-nocache`
+
+`<div t-nocache="">` 强制该节点每次重新渲染。该区域只能访问根上下文（控制器提供），不能访问局部 `t-set`。
+
+### `t-nocache-*`
+
+在 `t-cache` 区域内，`t-set` / `t-foreach` 拥有独立作用域，可能与外部同名变量产生差异。若内部再嵌套 `t-cache`，每段都有独立缓存键。
+
+可以用 `t-nocache-*="expr"` 缓存“动态值槽位”：
+
+```xml
+<section t-cache="records">
+    <article t-foreach="records" t-as="record">
+        <footer t-nocache="dynamic part" t-nocache-cached_value="record.qty">
+            <span t-out="counter + cached_value"/>
+        </footer>
+    </article>
+</section>
+```
+
+示例说明：`t-cache` 缓存主体片段，`t-nocache` 保留动态输出。
+
+## 辅助工具
+
+| 工具 / API | 说明 |
+| --- | --- |
+| `http.request.render('template', values)` | 在控制器内渲染模板并返回 `Response`；自动注入 `request`、`debug` 等上下文。 |
+| `ir.qweb._render()` | 通过 ID/外部 ID 渲染数据库模板，支持 `_prepare_environment` 设置默认上下文。 |
+| `request` / `debug` / `quote_plus` / `json` / `time` / `datetime` / `keep_query` | 常见上下文变量或工具。 |
+| `load(ref)()` | 将 XML 文档或节点加载为模板。 |
+
+## API
+
+| API / 对象 | 说明 |
+| --- | --- |
+| `core.qweb.render(template, context)` | 直接渲染模块模板。 |
+| QWeb 实例 API | 提供加载、解析、编译等能力。 |
+| `QWeb2.Engine()` | 作为“模板命名空间”，支持自定义前缀、调试模式、jQuery、文本翻译函数等，也暴露 `request` / `debug` / `json` 等常用值。 |
+
+## JavaScript 专用指令
+
+### 定义模板
+
+`<t t-name="template-name">` 必须放在 `<templates>` 的顶层：
+
+```xml
+<templates>
+    <t t-name="template-name">
+        ...
+    </t>
+</templates>
+```
+
+### 模板继承
+
+- `t-inherit`：父模板名称
+- `t-inherit-mode`：`primary`（创建新子模板）或 `extension`（就地修改）
+- `t-name`（可选）：主模式下作为新模板名称；扩展模式下作为注释辅助查找
+
+更改通过 XPath 指令完成（参见 [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) 文档）。示例 `t-inherit` / `t-inherit-mode`：
+
+```xml
+<t t-name="child.template" t-inherit="base.template" t-inherit-mode="primary">
+    <xpath expr="//ul" position="inside">
+        <li>new element</li>
+    </xpath>
+</t>
+```
+
+就地扩展：
+
+```xml
+<t t-inherit="base.template" t-inherit-mode="extension">
+    <xpath expr="//tr[1]" position="after">
+        <tr><td>new cell</td></tr>
+    </xpath>
+</t>
+```
+
+## 旧的继承机制（已弃用）
+
+`<t t-extend="base.template">` 配合 `t-jquery`/`t-operation` 操作节点：
+
+| `t-operation` | 作用 |
+| --- | --- |
+| `append` | 在上下文节点末尾添加 |
+| `prepend` | 插入到上下文节点之前 |
+| `before` | 插入到上下文节点前 |
+| `after` | 插入到上下文节点后 |
+| `inner` | 替换上下文子节点 |
+| `replace` | 替换上下文节点 |
+
+`attributes` 操作将文本设为属性值；`t-jquery` 默认将模板主体当作 JavaScript 在上下文节点执行，`this` 指向节点。
+
+> [!warning]
+> 尽管强大，旧机制难调试，建议优先采用 `t-inherit`/`t-inherit-mode`。

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

@@ -0,0 +1,53 @@
+# QWeb
+
+> 来源：`docs/obsidian/07 知识库/odoo文档/03_开发者/03_参考/03_用户界面/02_视图架构.md`
+> 原文章节：`## QWeb`
+>
+> 本文件从原始文档拆分而来，以下内容尽量保留原文，仅做拆分与轻量排版。
+
+QWeb 视图是 `arch` 中的标准 QWeb 模板元素，可在模板或实际视图中运行。它不依赖固定根元素，因此在视图模式下必须显式指定 `type`/`model` 才能绑定系统行为。
+
+## 目录
+
+- [qweb-as-template](#qweb-as-template)
+- [qweb-as-view](#qweb-as-view)
+- [渲染上下文](#渲染上下文)
+- [渲染钩子](#渲染钩子)
+
+---
+
+## qweb-as-template
+
+当 QWeb 用作模板时，可通过 `template` 作为快捷方式引用。
+
+## qweb-as-view
+
+作为实际的 qweb 视图（在操作内打开）时，它应定义为具有显式 `type` 和模型的常规视图。
+
+qweb-as-view 对 qweb-as-template 的主要补充包括：
+
+- 带 `o_qweb_cp_buttons` 的 `<nav>` 会把内部按钮提取到控制面板按钮区域，原 `<nav>` 本身会被移除。
+- 渲染过程会向标准 QWeb 上下文注入额外变量。
+- 还提供额外的渲染钩子。
+
+## 渲染上下文
+
+`qweb-as-view` 会扩展标准 QWeb 上下文，模板可以直接读取以下变量：
+
+| 变量 | 来源 | 用途 |
+| --- | --- | --- |
+| `model` | 当前视图绑定的模型类 | 访问模型字段与方法。 |
+| `domain` | 调用该视图的动作或默认视图域 | 限制渲染结果的记录范围。 |
+| `context` | 动作/视图的上下文字典 | 读取默认值、`search_default_*`、`group_by` 之类开关。 |
+| `records` | `model.search(domain)` 的惰性代理 | 用于遍历当前记录集；可直接在模板中迭代。 |
+
+如果只是遍历记录而不做更复杂的操作（例如分组），可以直接使用 `records`。
+
+## 渲染钩子
+
+客户端可以调用以下钩子来控制 qweb-as-view 的渲染流程：
+
+| 钩子 | 触发时机 | 描述 |
+| --- | --- | --- |
+| `_qweb_prepare_context(view_id, domain)` | 渲染开始前 | 准备 qweb-as-view 特定的渲染上下文。 |
+| `qweb_render_view(view_id, domain)` | 客户端请求 | 调用上下文准备方法，并最终委托 `env['ir.qweb'].render()` 渲染 HTML。 |