├── setting-up
    ├── email-gateway.md
    ├── deploying-content-delivery-networks.md
    ├── community-enterprise.md
    ├── updating-odoo-installation.md
    ├── deploying-odoo.md
    └── installing-odoo.md
├── reference
    ├── security-odoo.md
    ├── module-manifests.md
    ├── mobile-javascript.md
    ├── translating-modules.md
    ├── web-controllers.md
    ├── qweb-reports.md
    ├── actions.md
    ├── command-line-interface-odoo-bin.md
    ├── qweb.md
    ├── javascript-cheatsheet.md
    └── testing-odoo.md
├── README.md
├── tutorials
    ├── profiling-odoo-code.md
    └── theme-tutorial.md
└── web-services
    ├── creating-localization.md
    ├── database-upgrade.md
    └── in-app-purchase.md


/setting-up/email-gateway.md:
--------------------------------------------------------------------------------
 1 | # Odoo email 网关
 2 | 
 3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
 4 | 
 5 | Odoo邮件网关允许我们在Odoo中直接注入所有已接收邮件。其原理直截了当：你的SMTP服务为每个新新收邮件执行“mailgate”脚本。该脚本通过XML-RPC处理与Odoo数据库的连接，并通过MailThread.message_process()功能发送邮件。
 6 | 
 7 | ## 前提条件
 8 | 
 9 | - 对Odoo数据库的管理员权限。
10 | - 自己的邮件服务器，如 Postfix 或 Exim。
11 | - 有关如何配置邮件服务器的技术知识。
12 | 
13 | ## Postfix篇
14 | 
15 | 在alias配置 (/etc/aliases)中配置：
16 | 
17 | ```
18 | email@address: "|/odoo-directory/addons/mail/static/scripts/odoo-mailgate.py -d <database-name> -u <userid> -p <password>"
19 | ```
20 | 
21 | 郑源 - `Postfix` - `Postfix aliases` - `Postfix virtual`
22 | 
23 | ## Exim篇
24 | 
25 | ```
26 | *: |/odoo-directory/addons/mail/static/scripts/odoo-mailgate.py -d <database-name> -u <userid> -p <password>
27 | ```
28 | 
29 | 资源 - `Exim`
30 | 
31 | 如果你可以访问/管理自己的邮件服务器，使用`inbound messages`.


--------------------------------------------------------------------------------
/setting-up/deploying-content-delivery-networks.md:
--------------------------------------------------------------------------------
 1 | # 通过 CDN 进行部署
 2 | 
 3 | 本文来自[Odoo 13官方文档之开发者文档](https://alanhou.org/odoo-13-developer-documentation/)系列文章
 4 | 
 5 | ## 通过[KeyCDN](https://www.keycdn.com/)进行部署
 6 | 
 7 | 本文档将指导你为Odoo网站配置一个 [KeyCDN](https://www.keycdn.com/) 账户。
 8 | 
 9 | ### 第1步：在KeyCDN仪表盘中创建一个pull 区
10 | 
11 | ![img](https://www.odoo.com/documentation/13.0/_images/keycdn_create_a_pull_zone.png)创建该区时，在高级功能子菜单中启用CORS选择。 (更多参见后述内容)
12 | 
13 | ![img](https://www.odoo.com/documentation/13.0/_images/keycdn_enable_CORS.png)一旦完成后，需要等待片刻，此时[KeyCDN](https://www.keycdn.com/)会爬取你的网站。
14 | 
15 | ![img](https://www.odoo.com/documentation/13.0/_images/keycdn_progressbar.png)
16 | 
17 | 会为你的Zone生成一个新的 URL，本例中链接为 `http://pulltest-b49.kxcdn.com`
18 | 
19 | ### 第2步：使用你的zone 配置odoo实例
20 | 
21 | 在Odoo后台中，进入到网站设置（Website Settings）菜单，然后启用CDN并复制/拷贝你的zone URL到 CDN Base URL字段中。该字段仅在启用了开发者模式之后才可见并可配置。
22 | 
23 | ![img](https://www.odoo.com/documentation/13.0/_images/odoo_cdn_base_url.png)现在你的网站会对匹配CDN过滤器正则表达式的资源使用 CDN。
24 | 
25 | 可以查看网站的HTML源码来确定是否正确地进行了CDN集成。
26 | 
27 | ![img](https://www.odoo.com/documentation/13.0/_images/odoo_check_your_html.png)
28 | 
29 | ### 为什么要激活CORS？
30 | 
31 | 在一些浏览器(编写本文档时有Firefox 和 Chrome )的安全限制中会防止远程链接的CSS文件获取该外部服务器上的相对资源。
32 | 
33 | 如未在CDN区中启用 CORS选项，默认Odoo网站上最明显的问题是缺少 font-awesome图标，因为在 font-awesome的CSS中声明字体文件无法通过远程服务器进行加载。
34 | 
35 | 以下是在这种情况下首页的样子：
36 | 
37 | ![img](https://www.odoo.com/documentation/13.0/_images/odoo_font_file_not_loaded.png)一条安全错误信息会出现在浏览器的控制台中：
38 | 
39 | ![img](https://www.odoo.com/documentation/13.0/_images/odoo_security_message.png)在 CDN 中启用CORS选择可解决这一问题。


--------------------------------------------------------------------------------
/reference/security-odoo.md:
--------------------------------------------------------------------------------
 1 | # Odoo中的安全
 2 | 
 3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
 4 | 
 5 | 除手动通过自定义模式管理权限外，Odoo还提供了两种数据驱动的机制来管理或限制对数据的访问。
 6 | 
 7 | 这两种机制都通过**组**来与具体用户相关联：一个用户可属于多个组，安全机制与组进行关联，进而应用对用户应用安全机制。
 8 | 
 9 | 
10 | 
11 | ## 访问控制
12 | 
13 | 由`ir.model.access`记录进行管理， 定义对整个模型的访问。
14 | 
15 | 每个访问控制有其授予权限的模型，授予的权限及可选用户组。
16 | 
17 | 访问控制是附加的，对于一个给定模型用户拥有所有授予其所属组的权限，如用记属于一个允许写入的组及一个允许删除的组，那么用记就同时拥有写入和删除的权限。
18 | 
19 | 如未指定组，访问控制应用于所有用户，否则它仅应用于给定组的成员。
20 | 
21 | 可用的权限有创建(`perm_create`)、搜索和读取 (`perm_read`)、更新已有记录s (`perm_write`) 及删除已有记录(`perm_unlink`)
22 | 
23 | 
24 | 
25 | ## 记录规则
26 | 
27 | 记录规则是必须满足所允许操作（创建、读取、更新或删除）记录的条件。它在应用了访问控制后逐记录应用。
28 | 
29 | 记录规则有：
30 | 
31 | - 其所应用的模型
32 | - 一组它所应用的权限 (例如，如果设置了 `perm_read`，规则仅在读取记录时进行检查)
33 | - 一组规则所应用的用户组，如未指定组则是**全局**规则
34 | - 用于检查给定记录是否匹配规则（并可访问）或不匹配（不可访问）的[作用域](https://alanhou.org/odoo-13-orm-api/l#reference-orm-domains) 。作用域通过两个上下文变量进行运行： `user` 是当前用户的记录，`time` 是 [time模块](https://docs.python.org/2/library/time.html)
35 | 
36 | 全局赍是和组规则 (限制给定用记的规则 vs.应用所有用户的组) 的使用差别很大：
37 | 
38 | - 使用局规则做减法，它们必须匹配可访问的记录
39 | - 组规则做加法，如匹配其中任一规则 (且匹配所有全局规则)则记录可进行访问
40 | 
41 | 这表示第一个**组规则**限制访问，但其它的**组规则**对进行扩展，而**全局规则**仅限制访问 (或不起任何作用)。
42 | 
43 | ### ⚠️警告
44 | 
45 | 记录规则对管理员用户不起作用
46 | 
47 | 
48 | 
49 | ## 字段权限
50 | 
51 | 7.0版本中新增。
52 | 
53 | ORM [`字段`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Field)可带有 `groups`属性来提供一个组列表 (作为一个[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifiers)的逗号分隔字符串)。
54 | 
55 | 如当前用记不在所列举的组中，将无法访问该字段：
56 | 
57 | - 受限的字段自动从所请求的视图中删除
58 | - 受限的字段从 [`fields_get()`](https://alanhou.org/odoo-13-orm-api/#odoo.models.Model.fields_get) 响应中进行删除
59 | - 尝试 (显式地) 从受限的字段中读取或进行写入会导致访问错误


--------------------------------------------------------------------------------
/setting-up/community-enterprise.md:
--------------------------------------------------------------------------------
 1 | # 社区版转企业版
 2 | 
 3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
 4 | 
 5 | 根据当前的安装方式，有多种升级社区版的方法。各种情况下的基本指导思想是：
 6 | 
 7 | - 备份社区版数据库![img](https://www.odoo.com/documentation/13.0/_images/db_manager.png)
 8 | - 关闭服务
 9 | - 安装web_enterprise模块
10 | - 重启服务
11 | - 输入Odoo企业版订阅码
12 | 
13 | ![img](https://www.odoo.com/documentation/13.0/_images/enterprise_code.png)
14 | 
15 | ## 在Linux中使用安装包
16 | 
17 | - 备份社区版数据库
18 | 
19 | - 停止odoo服务
20 | 
21 |   ```
22 |   $ sudo service odoo stop
23 |   ```
24 | 
25 | - 安装企业版 .deb (应该在社区安装包之上安装)
26 | 
27 |   ```
28 |   $ sudo dpkg -i <path_to_enterprise_deb>
29 |   ```
30 | 
31 | - 使用如下命令更新数据库为企业版安装包
32 | 
33 |   ```
34 |   $ python3 /usr/bin/odoo-bin -d <database_name> -i web_enterprise --stop-after-init
35 |   ```
36 | 
37 | - 应当能够使用常规的认证方式连接到 Odoo企业版实例。然后你可以通过在表单输入框中输入邮件中所收到的订阅码将数据库与你的Odoo企业版订阅进行关联。
38 | 
39 | ## 在Linux中使用源代码
40 | 
41 | 有很多种使用源码启动服务器的方式，你可能已有自己的偏好。可以将下面部分调整为你自己的常规工作流。
42 | 
43 | - 关闭你的服务
44 | 
45 | - 备份社区版数据库
46 | 
47 | - 更新启动命令中的 `--addons-path` 参数 (参见 [源码安装](https://alanhou.org/odoo-13-installing-odoo/#setup-install-source))
48 | 
49 | - 通过使用如下命令安装 web_enterprise 模块
50 | 
51 |   ```
52 |   $ -d <database_name> -i web_enterprise --stop-after-init
53 |   ```
54 | 
55 |   根据数据库的大小不同，可能会花费一些时间。
56 | 
57 | - 使用第3点中更新的addons路径重新启动服务。 此时应该可以连接到实例。可以通过在表单输入框中输入邮件中所收到的订阅码将数据库与你的Odoo企业版订阅进行关联。
58 | 
59 | ## 在Windows上
60 | 
61 | - 备份社区版数据库
62 | 
63 | - 卸载Odoo 社区版 (使用安装文件夹中的 Uninstall可执行文件) - PostgreSQL将保持已安装状态![img](https://www.odoo.com/documentation/13.0/_images/windows_uninstall.png)
64 | 
65 | - 启动 Odoo企业版安装器并按照常规步骤执行。在选择安装路径时，可以设置社区版软件的文件夹(这个文件夹中还包含PostgreSQL软件 )。 在安装的最后取消勾选 `Start Odoo` ![img](https://www.odoo.com/documentation/13.0/_images/windows_setup.png)
66 | 
67 | - 使用命令行窗口，使用下面的命令（通过服务的子文件夹中的Odoo 安装路径）更新Odoo数据库
68 | 
69 |   ```
70 |   $ odoo.exe -d <database_name> -i web_enterprise --stop-after-init
71 |   ```
72 | 
73 | - 无需手动启动服务，服务已运行。这时应该可以使用常规的认证方式连接到Odoo企业版实例了。然后可以通过在表单输入框中输入邮件中所收到的订阅码将数据库与你的Odoo企业版订阅进行关联。


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Odoo 官方文档之开发者文档
 2 | 
 3 | ## Tutorials
 4 | 
 5 | - [主题教程](tutorials/theme-tutorial.md)
 6 | - [建造网站](tutorials/building-website.md)
 7 | - [构建模块](tutorials/building-module.md)
 8 | - [自定义网页客户端](tutorials/customizing-web-client.md)
 9 | - [Odoo 代码性能测试](tutorials/profiling-odoo-code.md)
10 | 
11 | ## Web Services
12 | 
13 | - [外部API](https://alanhou.org/odoo-13-external-api/)
14 | - [应用内购买](https://alanhou.org/odoo-13-in-app-purchase/)
15 | - [数据库升级](https://alanhou.org/odoo-13-database-upgrade/)
16 | - [会计本地化](https://alanhou.org/odoo-13-creating-localization/)
17 | 
18 | ## Setting Up
19 | 
20 | - [安装Odoo](https://alanhou.org/odoo-13-installing-odoo/)
21 | - [部署Odoo](https://alanhou.org/odoo-13-deploying-odoo/)
22 | - [更新Odoo安装版本](https://alanhou.org/odoo-13-updating-odoo-installation/)
23 | - [使用 CDN（内容分发网络）部署](https://alanhou.org/odoo13-deploying-content-delivery-networks/)
24 | - [社区版转企业版](https://alanhou.org/odoo-13-community-enterprise/)
25 | - [Odoo email 网关](https://alanhou.org/odoo-13-email-gateway/)
26 | 
27 | ## Reference
28 | 
29 | - [ORM API](https://alanhou.org/odoo-13-orm-api/)
30 | - [数据文件](https://alanhou.org/odoo-13-data-files/)
31 | - [动作](https://alanhou.org/odoo-13-actions/)
32 | - [视图](https://alanhou.org/odoo-13-views/)
33 | - [模块声明文件](https://alanhou.org/odoo-13-module-manifests/)
34 | - [命令行接口：odoo-bin](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/)
35 | - [Odoo中的安全](https://alanhou.org/odoo-13-security-odoo/)
36 | - [测试Odoo](https://alanhou.org/odoo-13-testing-odoo/)
37 | - [网页控制器](https://alanhou.org/odoo-13-web-controllers/)
38 | - [QWeb](https://alanhou.org/odoo-13-qweb/)
39 | - [Javascript速查](https://alanhou.org/odoo-13-javascript-cheatsheet/)
40 | - [Javascript手册](https://alanhou.org/odoo-13-javascript-reference/)
41 | - [模块翻译](https://alanhou.org/odoo-13-translating-modules/)
42 | - [QWeb报表](https://alanhou.org/odoo-13-qweb-reports/)
43 | - [Mixins和有用的类](https://alanhou.org/odoo-13-mixins-classes/)
44 | - [Odoo代码指南](https://alanhou.org/odoo-13-odoo-guidelines/)
45 | - [移动端JavaScript](https://alanhou.org/odoo-13-mobile-javascript/)


--------------------------------------------------------------------------------
/setting-up/updating-odoo-installation.md:
--------------------------------------------------------------------------------
 1 | # 更新Odoo安装版本
 2 | 
 3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
 4 | 
 5 | ## 引言
 6 | 
 7 | 为获取最新的提升、安全修复、漏洞修正及性能提升，可能会需要不时更新Odoo的软件。
 8 | 
 9 | 本指南仅用于在自己的托管基础设置上使用Odoo的情况。如果你使用的是Odoo的某种云方案，会自动为你执行升级操作。
10 | 
11 | 与软件升级相关的用词通常很让人困惑，以下是一些基本定义：
12 | 
13 | - 更新(Odoo软件)
14 | 
15 |   代指获取当前 Odoo 版本的最新修订版的过程。例如，更新你的Odoo Enterprise 13.0到最新修订版。这并不会直接引起对Odoo数据库内容的修改，并且可通过重装此前修订版的源代码来进行取消。
16 | 
17 | - 升级 (Odoo数据库)
18 | 
19 |   表示一个复杂的数据处理操作，其中数据库的内容和结构会进行永久改变来让其与新的Odoo发行版进行兼容。这种操作是不可逆的并且通常是在你决定要切换到更新的 Odoo 发行版时由Odoo的[数据库升级服务](https://upgrade.odoo.com/)来完成。曾经这一过程也称之为“迁移”，因为它包含着在数据库内部移动数据，虽然数据库在升级后可能依然处于同一个物理空间内。
20 | 
21 | 本文描述需要*更新*Odoo软件为最新版本所需要的通常步骤。如果想要了解有关升级数据库的更多信息，请访问 [Odoo升级页面 ](https://upgrade.odoo.com/)。
22 | 
23 | ## 概述
24 | 
25 | 更新Odoo仅需通过对当前所安装的Odoo 进行最新版本的最新安装即可。这样只要你不卸载PostgreSQL（Odoo所带的数据库引擎）会保留所有数据不进行任何修改。
26 | 
27 | 升级的主要指南逻辑上参考 [安装指南](https://alanhou.org/odoo-13-installing-odoo/)，其中讲解了最常见的安装方法。
28 | 
29 | 升级也最宜由最初部署Odoo的人员实施，因为其流程非常相近。
30 | 
31 | 我们经常推荐下载完整的最新Odoo版本，而不单是手动应用补丁，如安全公告中所发布的补丁。这些补丁通常是提供给那些高度客制化的安装，或那样希望在测试完整升级前临时测试最小化修改的技术人员。
32 | 
33 | ## 第1步: 下载已更新的Odoo版本
34 | 
35 | 主要下载页面是 https://www.odoo.com/page/download。如果看到下载 Odoo 企业版的“Buy”链接，请务必使用与 Odoo 企业版订阅相关联的账号登录到Odoo.com上。
36 | 
37 | 此外，你可以使用在Odoo企业版购买确认邮件中所包含的独立下载链接 。
38 | 
39 | 如果通过Github进行的安装则无需下载已升级的版本 (参照下面部分)
40 | 
41 | ## 第2步: 进行数据库备份
42 | 
43 | 升级的流程非常安全且不修改数据。但还是推荐最好在对软件执行修改前进行完整的数据库备份，并保存在另一台电脑上一个安全的地方。
44 | 
45 | 如果未禁用数据库管理界面 (在 [这里](#security)查看为什么应禁用),，则可以使用它 (在数据库选择界面的下方链接) 来下载数据库备份。如果进行了禁用，使用和日常备份桢的流程。
46 | 
47 | ## 第3步: 安装更新版本
48 | 
49 | 选择与当前安装相匹配的方法：
50 | 
51 | ### 包安装器
52 | 
53 | 如果使用从官网下载的安装包进行的Odoo安装（推荐方法），升级非常之简单。你只需要下载与系统相对应的安装包（参见第1步）并在服务器上进行安装即可。它会按日进行更新并包含最新的漏洞修复。通常，你只需在当前软件的顶部双击包来进行安装。在安装该包之后，确保要重启Odoo服务或在准备妥当的情况下重启服务器。
54 | 
55 | ### 源码安装(Tarball)
56 | 
57 | 如果你最初是通过“tarball”版本（源码存档）进行的Odoo安装，则需替换安装路径为新的版本。首先从Odoo.com下载最新的 tarball。它会按日进行更新并包含最新的漏洞修复（参见第1步）。在下载完包之后，将其解压到服务器的临时位置中。
58 | 
59 | 你将获取到一个带有源码版本标记的文件夹，例如“odoo-13.0+e.20190719”，其中包含一个“odoo.egg-info”文件夹并实际源码文件夹名为 “odoo” (Odoo 10及此后版本)或针对老版本名为“openerp”。可以忽略这个odoo.egg-info文件夹。定位到当前软件部署所在的文件夹，交将其替换为你刚刚解压的新的“odoo” 或 “openerp”文件夹。
60 | 
61 | 确保要匹配文件夹布局，例如在新源码中所含的“addons”文件夹应与之前的路径完全一致。其次注意任意你在老文件夹中手动拷贝或修改的配置文件，将它们拷贝到亲的文件夹中。最后，重启Odoo服务或在准备妥当的情况下重启服务器。
62 | 
63 | ### 源码安装(Github)
64 | 
65 | 如果最初是通过对Github上的官方仓库进行完整克隆来完成安装的话，更新过程仅需你通过git拉取最新的源代码。进入各仓库的路径(主Odoo仓库，及企业版仓库)，并运行如下命令：
66 | 
67 | ```
68 | git fetch 
69 | git rebase --autostash
70 | ```
71 | 
72 | 如果在本地编辑过Odoo源代码的话最后那条命令可能会碰到源码冲突。错误消息会给出冲突的文件列表，你需要手动处理这些冲突，通过对它们进行编辑来决定保留哪一部分的代码。
73 | 
74 | 而如果你倾向于抛弃所有的冲突修改，恢复为官方版本的话，可以使用如下命令：
75 | 
76 | ```
77 | git reset --hard
78 | ```
79 | 
80 | 最后，重启Odoo服务或重启服务器，一切应当会就绪了。
81 | 
82 | ### Docker
83 | 
84 | 请参见我们的 [Docker镜像文档](https://hub.docker.com/_/odoo/)了解最体的升级指南。


--------------------------------------------------------------------------------
/reference/module-manifests.md:
--------------------------------------------------------------------------------
  1 | # 模块声明文件
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](https://alanhou.org/odoo-13-developer-documentation/)系列文章
  4 | 
  5 | ## 声明
  6 | 
  7 | 声明文件用于声明python包为Odoo模块并指定模块元数据信息。
  8 | 
  9 | 它是一个名为`__manifest__.py`的文件，包含一个 Python字典，其中每个键指定模块元数据单元。
 10 | 
 11 | ```
 12 | {
 13 |     'name': "A Module",
 14 |     'version': '1.0',
 15 |     'depends': ['base'],
 16 |     'author': "Author Name",
 17 |     'category': 'Category',
 18 |     'description': """
 19 |     Description text
 20 |     """,
 21 |     # data files always loaded at installation
 22 |     'data': [
 23 |         'views/mymodule_view.xml',
 24 |     ],
 25 |     # data files containing optionally loaded demonstration data
 26 |     'demo': [
 27 |         'demo/demo_data.xml',
 28 |     ],
 29 | }
 30 | ```
 31 | 
 32 | 可用的声明字段有：
 33 | 
 34 | `name` (`str`, 必填)
 35 | 
 36 | 可阅读的模块名
 37 | 
 38 | `version` (`str`)
 39 | 
 40 | 该模块的版本，应遵循[语法版本号](https://semver.org/)规则
 41 | 
 42 | `description` (`str`)
 43 | 
 44 | 模块的扩展描述，格式为reStructuredText
 45 | 
 46 | `author` (`str`)
 47 | 
 48 | 模块作者的姓名
 49 | 
 50 | `website` (`str`)
 51 | 
 52 | 模块作者的网站URL
 53 | 
 54 | `license` (`str`, 默认: `LGPL-3`)
 55 | 
 56 | 模块的发行证书。可用的值有：
 57 | 
 58 | * `GPL-2`
 59 | * ``GPL-2 or any later version``
 60 | * GPL-3``GPL-3 or any later version``
 61 | * AGPL-3``LGPL-3``
 62 | * Other OSI approved licence
 63 | * ``OEEL-1` (Odoo企业版证书 v1.0)
 64 | * `OPL-1` (Odoo自有证书 v1.0)
 65 | * `其它资产`
 66 | 
 67 | ``category` (`str`, 默认: `Uncategorized`)
 68 | 
 69 | Odoo中的分类，模块的大概业务领域。
 70 | 
 71 | 虽然推荐使用 [已有分类](https://github.com/odoo/odoo/blob/13.0/odoo/addons/base/data/ir_module_category_data.xml)，但字段时自由形式的并会补时创建未知的分类。作业帮行者无疆有可使用分隔符 Category hierarchies can be cr `/`进行创建，如 `Foo / Bar` 会创建一个分类`Foo`，并创建分类 `Bar` 为 `Foo`的子分类，且会将`Bar`设置为模块的分类。
 72 | 
 73 | `depends` (`list(str)`)
 74 | 
 75 | 必须在其之前加载的Odoo模块，要么因为该模板使用了它们创建的功能或因为其修改了它们定义的资源。在安装模块时，其所有依赖会在它之前安装。类似地依赖会在模块加载完之间加载。
 76 | 
 77 | `data` (`list(str)`)
 78 | 
 79 | 必须保持通过模块安装或更新的数据文件列表。来自模块根目录的路径列表
 80 | 
 81 | `demo` (`list(str)`)
 82 | 
 83 | 仅在*演示模式*下安装或更新的数据文件列表
 84 | 
 85 | `auto_install` (`bool`, 默认: `False`)
 86 | 
 87 | `若为True`，这个模块会自动在其所有依赖已安装时进行安装。
 88 | 
 89 | 通常用于实现两个其它独立模块协同集成的“链接模块”。
 90 | 
 91 | 例如 `sale_crm` 同时依赖于 `sale` 和 `crm` 并设置为 `auto_install`。在安装了`sale` 及 `crm` 的时候，它自动添加追踪订单的CRM活动，而`sale` 或 `crm` 并不知道彼此的存在
 92 | 
 93 | `external_dependencies` (`dict(key=list(str))`)
 94 | 
 95 | 包含python 和/或二进制依赖的字典。
 96 | 
 97 | 对于python依赖，`python`键必须为这个字典定义并应分配一个导入的 python模块列表。
 98 | 
 99 | 对于二进制依赖， `bin` 键必须为定义典定义且应分配一个二进制可执行名称的列表。
100 | 
101 | 在未安装python模块时或主机或二进制没在主机的PATH环境变量中找到时不会安装该模块。
102 | 
103 | `application` (`bool`, 默认: `False`)
104 | 
105 | 模块是否应被看成是安整的应用 (`True`) 或仅是一个向已有应用模块提供功能支持的技术模块 (`False`) 。
106 | 
107 | `css` (`list(str)`)
108 | 
109 | 指定带有导入的自定义规则的css文件，这些文件应位于该模块的`static/src/css` 中。
110 | 
111 | `images` (`list(str)`)
112 | 
113 | 指定模块所使用的图片文件。
114 | 
115 | `installable` (`bool` 默认: `True`)
116 | 
117 | 用户是否能通过Web UI安装该模块。
118 | 
119 | `maintainer` (`str`)
120 | 
121 | 负责维护该模块的人或组织，默认假定作者就是维护人员。
122 | 
123 | `{pre_init, post_init, uninstall}_hook` (`str`)模块安装/卸载的钩子，它们的值应为表示定义在模块`__init__.py`内的函数名的字符串。
124 | 
125 | `pre_init_hook` 接收游标作为其唯一的参数，这个函数在模块安装之前执行。
126 | 
127 | `post_init_hook` 接收一个游标及仓库作为其参数，该函数在模块安装之后执行。
128 | 
129 | `uninstall_hook` 接收一个游标及仓库作为其参数，该函数在模块卸载之后执行。
130 | 
131 | 这些钩子应仅在配置/清理时使用，要求使用这个模块的场景是通过 api 要么非常复杂要么无法办到时。 
132 | 
133 | 


--------------------------------------------------------------------------------
/tutorials/profiling-odoo-code.md:
--------------------------------------------------------------------------------
  1 | # Odoo代码性能测试
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | ### ⚠️警告
  6 | 
  7 | 本教程要求 [已安装Odoo](https://alanhou.org/odoo-13-installing-odoo/) 并 [编写Odoo代码](https://alanhou.org/odoo-13-building-module/)
  8 | 
  9 | ## 方法的图形化
 10 | 
 11 | Odoo内嵌有性能测试器。这一内嵌性能测试器的输出可用于生成由方法所触发调用、查询数、方法内部花费时间及方法及其调用的子方法所花费时间的图表。
 12 | 
 13 | ```
 14 | from odoo.tools.misc import profile
 15 | [...]
 16 | @profile('/temp/prof.profile')
 17 | def mymethod(...)
 18 | ```
 19 | 
 20 | 这会生成一个名为/temp/prof.profile的文件
 21 | 
 22 | 一个名为 *gprof2dot* 的工具会通过这一结果生成图表：
 23 | 
 24 | ```
 25 | gprof2dot -f pstats -o /temp/prof.xdot /temp/prof.profile
 26 | ```
 27 | 
 28 | 一个名为 *xdot* 的工具将显示所生成图表：
 29 | 
 30 | ```
 31 | xdot /temp/prof.xdot
 32 | ```
 33 | 
 34 | ## 方法日志
 35 | 
 36 | 另一个性能优化器可用于记录方法的统计数据：
 37 | 
 38 | ```
 39 | from odoo.tools.profiler import profile
 40 | [...]
 41 | @profile
 42 | @api.model
 43 | def mymethod(...):
 44 | ```
 45 | 
 46 | 一旦待分析的方法完成重审后数据会显示为数据统计日志。
 47 | 
 48 | ```
 49 | 2018-03-28 06:18:23,196 22878 INFO openerp odoo.tools.profiler:
 50 | calls     queries   ms
 51 | project.task ------------------------ /home/odoo/src/odoo/addons/project/models/project.py, 638
 52 | 
 53 | 1         0         0.02          @profile
 54 |                                   @api.model
 55 |                                   def create(self, vals):
 56 |                                       # context: no_log, because subtype already handle this
 57 | 1         0         0.01              context = dict(self.env.context, mail_create_nolog=True)
 58 | 
 59 |                                       # for default stage
 60 | 1         0         0.01              if vals.get('project_id') and not context.get('default_project_id'):
 61 |                                           context['default_project_id'] = vals.get('project_id')
 62 |                                       # user_id change: update date_assign
 63 | 1         0         0.01              if vals.get('user_id'):
 64 |                                           vals['date_assign'] = fields.Datetime.now()
 65 |                                       # Stage change: Update date_end if folded stage
 66 | 1         0         0.0               if vals.get('stage_id'):
 67 |                                           vals.update(self.update_date_end(vals['stage_id']))
 68 | 1         108       631.8             task = super(Task, self.with_context(context)).create(vals)
 69 | 1         0         0.01              return task
 70 | 
 71 | Total:
 72 | 1         108       631.85
 73 | ```
 74 | 
 75 | ## Dump栈
 76 | 
 77 | 向Odoo进程发送SIGQUIT信号（仅对POSIX可用）会让这个进程输出带有消息级别的当前栈跟踪进行日志。在 odoo进程看起来卡住时，向进程发送这个信号准许来知道进程在做什么，并让进程继续其任务。
 78 | 
 79 | ## 追踪代码执行
 80 | 
 81 | 向Odoo进程发送SIGQUIT信号通常足够了，但要查看进程在哪些地方比预期的性能要差的话，我们可以使用 pyflame 工具来替我们执行。
 82 | 
 83 | ### 安装pyflame和flamegraph
 84 | 
 85 | ```
 86 | # These instructions are given for Debian/Ubuntu distributions
 87 | sudo apt install autoconf automake autotools-dev g++ pkg-config python-dev python3-dev libtool make
 88 | git clone https://github.com/uber/pyflame.git
 89 | git clone https://github.com/brendangregg/FlameGraph.git
 90 | cd pyflame
 91 | ./autogen.sh
 92 | ./configure
 93 | make
 94 | sudo make install
 95 | ```
 96 | 
 97 | ### 记录已执行代码
 98 | 
 99 | 既然已经安装了pyflame，现在我们可以使用pyflame来记录已执行代码。这个工具会每秒多次记录进程的 stacktrace（栈追踪）。一旦完成，我们将通过执行图表来进行展示。
100 | 
101 | ```
102 | pyflame --exclude-idle -s 3600 -r 0.2 -p <PID> -o test.flame
103 | ```
104 | 
105 | 其中的 <PID>是想要图表化的odoo的进程ID。这会等待直至进程灭亡，最大值为1小时，并每秒获取5次追踪。通过pyflame的输出，我们可以使用flamegraph工具生成一张SVG 图表：
106 | 
107 | ```
108 | flamegraph.pl ./test.flame > ~/mycode.svg
109 | ```
110 | 
111 | ![img](https://www.odoo.com/documentation/13.0/_images/flamegraph.svg)


--------------------------------------------------------------------------------
/reference/mobile-javascript.md:
--------------------------------------------------------------------------------
  1 | # 移动端JavaScript
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | ## 导言
  6 | 
  7 | 在Odoo 10.0中我们发布了移动端应用，可通过它访问所胡**Odoo app** (甚至是你自己的自定义模块)。
  8 | 
  9 | 该应用是**Odoo Web** 和 **Native原生移动组件**的融合。换句话说这是在原生、移动、mobile容器中加载的Odoo Web实例。
 10 | 
 11 | 本文讲解如何通过Odoo Web (借助JavaScript)访问移动原生组件如相机、振动、通知和Toast。为些，你不需要是一个移动开发者，如果了解Odoo JavaScript API就可以获取所有的移动端功能。
 12 | 
 13 | ### ⚠️警告
 14 | 
 15 | 这些功能仅在**Odoo 企业版10.0+** 中可使用
 16 | 
 17 | ## 工作原理是什么？
 18 | 
 19 | 移动端应用的内容工作原理如下：
 20 | 
 21 | ![img](https://www.odoo.com/documentation/13.0/_images/mobile_working.jpg)当然，这是一个在移动原生Web容器中加载的网页。但集成的方式是你可以通过网页端JavaScript访问原生资源。
 22 | 
 23 | WebPages (Odoo Web)在每层的上部，其中第二层是Odoo Web (JS)和原生移动组件之间的桥梁。
 24 | 
 25 | 在触发任意来自JavaScript的调用时，它通过桥梁传递并且桥梁将其传递给原生调用者来执行该动作。
 26 | 
 27 | 在原生组件完成其任务时，它再次传递给桥梁并且你可以获取到JavaScript中的输出。
 28 | 
 29 | 原生组件处理花费的时间取决于从原生资源所请求的内容。如相机或GPS定位。
 30 | 
 31 | ## 如何使用？
 32 | 
 33 | 类似于Odoo Web框架，可通过从**web_mobile.rpc**获取对象来在任意地方使用移动端API
 34 | 
 35 | ![img](https://www.odoo.com/documentation/13.0/_images/odoo_mobile_api.png)移动端RPC对象提供一个可用的方法列表 (仅配合移动端应用使用)。
 36 | 
 37 | 查看方法是否可用，然后执行它。
 38 | 
 39 | ### 方法
 40 | 
 41 | 每个方法返回一个JQuery延时对象，它返回一个数据JSON字典
 42 | 
 43 | #### 在设备中显示Toast
 44 | 
 45 | ###### `showToast()`
 46 | 
 47 | 参数
 48 | 
 49 | - **args** (`object`) – 显示的**消息**文本
 50 | 
 51 | toast提供有关小弹窗中操作的简单反馈。它仅填充消息所要求的空间且当前活动保持可见和交互性。
 52 | 
 53 | ```
 54 | mobile.methods.showToast({'message': 'Message sent'});
 55 | ```
 56 | 
 57 | ![img](https://www.odoo.com/documentation/13.0/_images/toast.png)
 58 | 
 59 | #### 振动设备
 60 | 
 61 | ###### `vibrate()`
 62 | 
 63 | 参数
 64 | 
 65 | - **args** (`object`) – 在指定时间（按毫秒）内持续振动。
 66 | 
 67 | 按照给定时长振动移动设备。
 68 | 
 69 | ```
 70 | mobile.methods.vibrate({'duration': 100});
 71 | ```
 72 | 
 73 | #### 显示带有动作的snackbar
 74 | 
 75 | ###### `showSnackBar()`
 76 | 
 77 | 参数
 78 | 
 79 | - **args** (`object`) – (*必传*)  在snackbar中显示的Snackbar及在Snackbar中的动作**按钮标签**（可选）
 80 | 
 81 | 返回
 82 | 
 83 | 若用户点击动作则为`True`，若在一段时间后SnackBar自动消失则为 `False` 。
 84 | 
 85 | Snackbar对操作提供轻量的反馈。它们在移动端屏幕的底部或在更大设备的左下角显示简短消息。Snackbar位于屏幕上所有其它元素的之上且一次只能显示一个。
 86 | 
 87 | ```
 88 | mobile.methods.showSnackBar({'message': 'Message is deleted', 'btn_text': 'Undo'}).then(function(result){
 89 |         if(result){
 90 |                 // 执行 undo 操作
 91 |         }else{
 92 |                 // 取消Snack Bar
 93 |         }
 94 | });
 95 | ```
 96 | 
 97 | ![img](https://www.odoo.com/documentation/13.0/_images/snackbar.png)
 98 | 
 99 | #### 显示通知
100 | 
101 | ###### `showNotification()`
102 | 
103 | 参数
104 | 
105 | - **args** (`object`) – 标准通知中通知的**标题**(第一行) ，通知的**信息**(第二行)。
106 | 
107 | 通知是一个在应用的常规UI之外对用户显示的信息。 在告知系统发布通知时，它首先在通知区以一个图标形式出现。要查看通知的详情，用户打开通知列表。通知区和通知列表都是系统控制的区域，用户可在任意时刻查看。
108 | 
109 | ```
110 | mobile.showNotification({'title': 'Simple Notification', 'message': 'This is a test for a simple notification'})
111 | ```
112 | 
113 | ![img](https://www.odoo.com/documentation/13.0/_images/mobile_notification.png)
114 | 
115 | #### 在设备中创建联系人
116 | 
117 | ###### `addContact()`
118 | 
119 | 参数
120 | 
121 | - **args** (`object`) – 带有联系人详情的字典。可能的键有 (姓名, 手机号, 电话, 传真, email, 网址, 街道, 街道2, 国家id, 州id, 城市, 邮编, parent_id, 函数和图像)
122 | 
123 | 使用给定的联系人详情新建一个设备联系人。
124 | 
125 | ```
126 | var contact = {
127 |         'name': 'Michel Fletcher',
128 |         'mobile': '9999999999',
129 |         'phone': '7954856587',
130 |         'fax': '765898745',
131 |         'email': 'michel.fletcher@agrolait.example.com',
132 |         'website': 'http://www.agrolait.com',
133 |         'street': '69 rue de Namur',
134 |         'street2': false,
135 |         'country_id': [21, 'Belgium'],
136 |         'state_id': false,
137 |         'city': 'Wavre',
138 |         'zip': '1300',
139 |         'parent_id': [8, 'Agrolait'],
140 |         'function': 'Analyst',
141 |         'image': '<<BASE 64 Image Data>>'
142 | }
143 | 
144 | mobile.methods.addContact(contact);
145 | ```
146 | 
147 | ![img](https://www.odoo.com/documentation/13.0/_images/mobile_contact_create.png)
148 | 
149 | #### 扫描条形码
150 | 
151 | ###### `scanBarcode()`
152 | 
153 | 返回
154 | 
155 | 通过任意条形码扫码`code`
156 | 
157 | 条形码API实时在设备上监测任意方向的条形码。
158 | 
159 | 条形码API可读取如下条形码格式：
160 | 
161 | - 1维条形码: EAN-13, EAN-8, UPC-A, UPC-E, Code-39, Code-93, Code-128, ITF, Codabar
162 | - 2D条形码: 二维友, 数据矩阵, PDF-417, AZTEC
163 | 
164 | ```
165 | mobile.methods.scanBarcode().then(function(code){
166 |         if(code){
167 |                 // 使用所扫描的编码执行操作
168 |         }
169 | });
170 | ```
171 | 
172 | #### 在设备中切换账户
173 | 
174 | ###### `switchAccount()`
175 | 
176 | 使用switchAccount在设备上从一个账户切换到另一个账户。
177 | 
178 | ```
179 | mobile.methods.switchAccount();
180 | ```
181 | 
182 | ![img](https://www.odoo.com/documentation/13.0/_images/mobile_switch_account.png)


--------------------------------------------------------------------------------
/reference/translating-modules.md:
--------------------------------------------------------------------------------
  1 | # 模块翻译
  2 | 
  3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | 这部分讲解如何对自己的模块进行翻译。
  6 | 
  7 | 如果想对Odoo本身进行翻译的藏南，请参见 [Odoo维基页面](https://github.com/odoo/odoo/wiki/Translations)。
  8 | 
  9 | ## 导出可翻译词汇
 10 | 
 11 | 你的模块中的词汇数结果是“隐式可翻译”， 即使你没有对翻译进行具体的操作也可以导出模块的可翻译词汇并能查找可操作的内容。
 12 | 
 13 | 翻译通过登录后台界面并访问Settings ‣ Translations ‣ Import / Export ‣ Export Translations来导出
 14 | 
 15 | - 将语言保持为默认 (新语言/空模板)
 16 | - 选择[PO File](https://en.wikipedia.org/wiki/Gettext#Translating)格式
 17 | - 选择模块
 18 | - 点击Export下载文件
 19 | 
 20 | [![img](https://www.odoo.com/documentation/13.0/_images/po-export.png)](https://www.odoo.com/documentation/13.0/_images/po-export.png)这会给出一个名为`*yourmodule*.pot` 的文件，应移动到 `*yourmodule*/i18n/` 目录。该文件是一个*PO 模板*，仅列出可翻译字段及通过什么创建实际翻译 (PO 文件)。PO文件可使用[msginit](https://www.gnu.org/software/gettext/manual/gettext.html#Creating)进行创建，有一个类似[POEdit](https://poedit.net/) 专门的翻译工具或者只是将模板拷贝到名为`*language*.po`的新文件。翻译文件应放到`*yourmodule*/i18n/`中，紧邻`*yourmodule*.pot`，并将在安装相应语言时自动（通过Settings ‣ Translations ‣ Languages）由Odoo加载
 21 | 
 22 | 在安装或更新模块时所有已加载语言的翻译也会进行安装或更新
 23 | 
 24 | ## 隐式导出
 25 | 
 26 | Odoo自动从“data”类型内容导出可翻译字符串：
 27 | 
 28 | - 在非QWeb视图中，会导出所有文本节点及`string`, `help`, `sum`, `confirm` 和 `placeholder` 属性的内容
 29 | 
 30 | - QWeb模板(服务端及客户端)，导出除 `t-translation="off"`代码块内的所有文本节点， `title`, `alt`, `label` 和 `placeholder`属性的内容也会进行导出
 31 | 
 32 | - 对于
 33 | 
 34 |   `Field`
 35 | 
 36 |   , 除非它们的模型通过 
 37 | 
 38 |   ```
 39 |   _translate = False
 40 |   ```
 41 | 
 42 |   进行标记：
 43 | 
 44 |   - 其 `string` 和 `help` 属性会进行导出
 45 |   - 如出现 `selection` 及列表（或元组），会导出
 46 |   - 如若其`translate` 属性设置为 `True`，它们的所有（跨越所有记录的）已存在值会导出
 47 | 
 48 | -  `_constraints` 和 `_sql_constraints` 的帮助/错误信息会导出
 49 | 
 50 | ## 显式导出
 51 | 
 52 | 在Python或Javascript代码中更“迫切”的场景中， Odoo不能自动导出词，因此它们必须进行显式的标记来导出。这通过在函数调用中封装字面量字符串来实现。
 53 | 
 54 | 在Python中，封装的函数是`odoo._()`：
 55 | 
 56 | ```
 57 | title = _("Bank Accounts")
 58 | ```
 59 | 
 60 | 在JavaScript中，封装的函数通常是 `odoo.web._t()`：
 61 | 
 62 | ```
 63 | title = _t("Bank Accounts");
 64 | ```
 65 | 
 66 | ### ⚠️警告
 67 | 
 68 | 仅有字面量字符串可标记为导出，表达式或变量不行。对于字符串需格式化的场景，这意味着格式字符串而非格式化后的字符串必须进行标记
 69 | 
 70 | `_` 和 `_t` 懒翻译版本为python中为 `odoo._lt()` ，在javascript中为 `odoo.web._lt()` 。翻译查找仅在渲染时查找并可用于声明全局变量类方法的可翻译属性。
 71 | 
 72 | ### 变量
 73 | 
 74 | **不要** 提取可能起作用但不会正确地翻译文本：
 75 | 
 76 | ```
 77 | _("Scheduled meeting with %s" % invitee.name)
 78 | ```
 79 | 
 80 | **要** 在翻译查找之外设置动态变量：
 81 | 
 82 | ```
 83 | _("Scheduled meeting with %s") % invitee.name
 84 | ```
 85 | 
 86 | ### 代码块
 87 | 
 88 | **不要** 在一些代码块或多行中分隔翻译：
 89 | 
 90 | ```
 91 | # 不妥，后缀空格，上下文外的代码块
 92 | _("You have ") + len(invoices) + _(" invoices waiting")
 93 | _t("You have ") + invoices.length + _t(" invoices waiting");
 94 | 
 95 | # 不妥, 多个碎片翻译
 96 | _("Reference of the document that generated ") + \
 97 | _("this sales order request.")
 98 | ```
 99 | 
100 | **要** 保持在一个代码块中，将全文本给到翻译器：
101 | 
102 | ```
103 | # 妥, 允许修改在翻译中数量的位置
104 | _("You have %s invoices wainting") % len(invoices)
105 | _.str.sprintf(_t("You have %s invoices wainting"), invoices.length);
106 | 
107 | # 妥, 全句可理解
108 | _("Reference of the document that generated " + \
109 |   "this sales order request.")
110 | ```
111 | 
112 | ### 复数
113 | 
114 | **不要** 按英文的方式设置词汇的复数：
115 | 
116 | ```
117 | msg = _("You have %s invoice") % invoice_count
118 | if invoice_count > 1:
119 |   msg += _("s")
120 | ```
121 | 
122 | **要** 记住各种语言有不同的复数形式：
123 | 
124 | ```
125 | if invoice_count > 1:
126 |   msg = _("You have %s invoices") % invoice_count
127 | else:
128 |   msg = _("You have %s invoice") % invoice_count
129 | ```
130 | 
131 | ### 读取vs运行时间
132 | 
133 | **不要** 在服务启动时调用翻译查询：
134 | 
135 | ```
136 | ERROR_MESSAGE = {
137 |   # 不妥, 没有用户语言时在服务端启动时运行
138 |   'access_error': _('Access Error'),
139 |   'missing_error': _('Missing Record'),
140 | }
141 | 
142 | class Record(models.Model):
143 | 
144 |   def _raise_error(self, code):
145 |     raise UserError(ERROR_MESSAGE[code])
146 | ```
147 | 
148 | **不要** 在读取javascript文件时调用翻译查询：
149 | 
150 | ```
151 | # 不妥, js _t 运行的过早
152 | var core = require('web.core');
153 | var _t = core._t;
154 | var map_title = {
155 |     access_error: _t('Access Error'),
156 |     missing_error: _t('Missing Record'),
157 | };
158 | ```
159 | 
160 | **要** 使用懒翻译查找方法：
161 | 
162 | ```
163 | ERROR_MESSAGE = {
164 |   'access_error': _lt('Access Error'),
165 |   'missing_error': _lt('Missing Record'),
166 | }
167 | 
168 | class Record(models.Model):
169 | 
170 |   def _raise_error(self, code):
171 |     # 在错误渲染时执行翻译查找
172 |     raise UserError(ERROR_MESSAGE[code])
173 | ```
174 | 
175 | 或 **要** 动态运行可翻译内容：
176 | 
177 | ```
178 | # 妥，在运行时运行
179 | def _get_error_message(self):
180 |   return {
181 |     access_error: _('Access Error'),
182 |     missing_error: _('Missing Record'),
183 |   }
184 | ```
185 | 
186 | **要** 在读取JS文件时翻译查找完成，在使用时用 `_lt` 而非 `_t`来翻译启发式规则：
187 | 
188 | ```
189 | # 妥, js _lt 进行懒运行
190 | var core = require('web.core');
191 | var _lt = core._lt;
192 | var map_title = {
193 |     access_error: _lt('Access Error'),
194 |     missing_error: _lt('Missing Record'),
195 | };
196 | ```


--------------------------------------------------------------------------------
/reference/web-controllers.md:
--------------------------------------------------------------------------------
  1 | # 网页控制器
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | ## 控制器
  6 | 
  7 | 控制器需要提供扩展性，很像 [`Model`](https://alanhou.org/odoo-13-orm-api/#odoo.models.Model)，但无法使用相同的机制作为预设条件 (带有已加载模块的数据库) 尚不可使用(如未创建或未选择数据库)。
  8 | 
  9 | 因此控制器具有其自己的扩展机制，与模型的机制相分离：
 10 | 
 11 | 控制器通过[继承](https://docs.python.org/3/tutorial/classes.html#tut-inheritance) `Controller`来进行创建。 路由通过由 [`route()`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.route)装饰的方法定义：
 12 | 
 13 | ```
 14 | class MyController(odoo.http.Controller):
 15 |     @route('/some_url', auth='public')
 16 |     def handler(self):
 17 |         return stuff()
 18 | ```
 19 | 
 20 | 要*重载*控制器，[继承](https://docs.python.org/3/tutorial/classes.html#tut-inheritance)其类并重载相关方法，如果需要重新暴露它们：
 21 | 
 22 | ```
 23 | class Extension(MyController):
 24 |     @route()
 25 |     def handler(self):
 26 |         do_before()
 27 |         return super(Extension, self).handler()
 28 | ```
 29 | 
 30 | - 有必要使用 [`route()`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.route) 进行装饰来保持方法（及路由）可见：如方法未进行装饰就重新定义，会变成“未发布”
 31 | 
 32 | - 合并所有方法的装饰器，如重载方法的装饰器没有参数则会保留此前的所有参数，所提供的任意参数会覆盖此前所定义参数，例：
 33 | 
 34 |   ```
 35 |   class Restrict(MyController):
 36 |       @route(auth='user')
 37 |       def handler(self):
 38 |           return super(Restrict, self).handler()
 39 |   ```
 40 | 
 41 |   会修改对用户公共认证的`/some_url` (要求登录)
 42 | 
 43 | ## API
 44 | 
 45 | 
 46 | 
 47 | ### 路由
 48 | 
 49 | ###### `odoo.http.route(*route=None*, ***kw*)`
 50 | 
 51 | 装饰器让所装饰的方法成为请求的处理器。该方法必须要是`Controller`子类的一部分。
 52 | 
 53 | 参数
 54 | 
 55 | - **route** – 字符串或数组。决定哪种http请求匹配所装饰方法的路由部分。可以是单个字符串或字符串数组。参见 werkzeug的路由文档了解路由表达式的格式( http://werkzeug.pocoo.org/docs/routing/ )。
 56 | 
 57 | - **type** – 请求的类型，可为`'http'` 或 `'json'`.
 58 | 
 59 | - auth
 60 | 
 61 |    – 认证方法的类型，可为以下类型：
 62 | 
 63 |   - `user`: 用户必须认证且当前请求将使用用户的权限进行执行。
 64 |   - `public`: 用户可认证也可不认证。如未认证，当前请求会使用共享Public用户进行执行。
 65 |   - `none`: 即使用没有数据库，方法也一直是活跃的。主要由框架和认证模块使用。它们的请求代码对访问数据库没有任何作用，也没有表明当前数据库或当前用户的配置。
 66 | 
 67 | - **methods** – 一个这个路由所应用的http方法的序列。如未指定，允许使用所有方法。
 68 | 
 69 | - **cors** – Access-Control-Allow-Origin cors 指令值。
 70 | 
 71 | - **csrf** ([`bool`](https://docs.python.org/3/library/functions.html#bool)) – 是否应为路由启用CSRF保护。默认为 `True`。参见[CSRF保护](https://alanhou.org/odoo-13-web-controllers/#csrf)了解更多内容。
 72 | 
 73 | ### CSRF保护
 74 | 
 75 | 版本9.0中新增。
 76 | 
 77 | Odoo实现基于令牌的[CSRF保护](https://en.wikipedia.org/wiki/CSRF)。
 78 | 
 79 | CSRF保护默认启用并应用于[**RFC 7231**](https://tools.ietf.org/html/rfc7231.html)中所定义的*不安全* HTTP 方法 ( `GET`, `HEAD`, `TRACE` 和 `OPTIONS`之外的所有方法)。
 80 | 
 81 | CSRF保护通过名为`csrf_token`值作为请求表单数据的一部分以检查请求来实现。 该值作为验证的一部分从表单中删除并在你自己的表单处理过程中不进行考虑。
 82 | 
 83 | 在为不安全方法（大多为表单等的POST）新增控制器时：
 84 | 
 85 | - 如果表单在Python中生成，csrf令牌借由`request.csrf_token() <odoo.http.WebRequest.csrf_token()`获取，`request`对象默认在QWeb (python)模块中可用，如果你不使用 QWeb它可能会被显式地添加。
 86 | 
 87 | - 如果表单在Javascript中生成， CSRF信息默认添加到 QWeb (js) 渲染上下文中作为
 88 | 
 89 |   ```
 90 |   csrf_token
 91 |   ```
 92 | 
 93 |    ，否则会在 
 94 | 
 95 |   ```
 96 |   web.core
 97 |   ```
 98 | 
 99 |    模块中作为
100 | 
101 |   ```
102 |   csrf_token
103 |   ```
104 | 
105 |   :
106 | 
107 |   ```
108 |   require('web.core').csrf_token
109 |   ```
110 | 
111 | - 如果端点（endpoint）可由外部(非Odoo内部)调用， 如其为REST API 或一个 [webhook](https://en.wikipedia.org/wiki/Webhook)，必须对端点禁用CSRF保护。如果可能，你可能会希望实现其它验证的方法(来确保它不由不相关的第三方调用)。
112 | 
113 | 
114 | 
115 | ### 请求
116 | 
117 | 请求对象在请求的一开始自动对`odoo.http.request` 进行设置
118 | 
119 | ###### `*class* odoo.http.WebRequest(*httprequest*)`
120 | 
121 | 所有Odoo Web请求类型的父类，大多处理初始化及请求对象的设置 (调度本身须由子类处理)
122 | 
123 | 参数
124 | 
125 | **httprequest** ([`werkzeug.wrappers.BaseRequest`](https://werkzeug.palletsprojects.com/en/0.16.x/wrappers/#werkzeug.wrappers.BaseRequest)) – 封装了的werkzeug Request对象
126 | 
127 | ###### `httprequest`
128 | 
129 | 提供给请求的原始[`werkzeug.wrappers.Request`](https://werkzeug.palletsprojects.com/en/0.16.x/wrappers/#werkzeug.wrappers.Request)对象
130 | 
131 | ###### `params`
132 | 
133 | 请求参数的`Mapping`，通常没有用，因为它们直接提供给handler方法作为关键字参数
134 | 
135 | ###### `cr`
136 | 
137 | 对当前方法调用初始化的`游标` 。
138 | 
139 | 在当前请求使用 `none` 认证时访问游标会报出异常。
140 | 
141 | ###### `context`
142 | 
143 | 针对当前请求上下文值的`映射`
144 | 
145 | ###### `env`
146 | 
147 | 绑定到当前请求的 `环境` 。
148 | 
149 | ###### `session`
150 | 
151 | `OpenERPSession` 存储针对当前 http 会话的 HTTP session数据
152 | 
153 | ###### `registry`
154 | 
155 | 关联当前请求的数据库的仓库、如当前请求使用`none`认证的话可以为 `None` 。
156 | 
157 | 自版本8.0开始淘汰：使用 [`env`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.WebRequest.env)
158 | 
159 | ###### `db`
160 | 
161 | 关联这一请求的数据库。如当前请求使用`none`认证的话可以为 `None` 。
162 | 
163 | ###### `csrf_token(*time_limit=3600*)`
164 | 
165 | 生成并返回当前会话的CSRF令牌
166 | 
167 | Parameters
168 | 
169 | **time_limit** (`int | None`) – CSRF令牌 token 应仅对指定时长（单位为秒）有效 ，默认为1小时，设为 `None` 表示令牌在当前用户的会话结束前有效。
170 | 
171 | 返回
172 | 
173 | ASCII 令牌字符串
174 | 
175 | ###### `*class* odoo.http.HttpRequest(**args*)`
176 | 
177 | `http` 请求类型的处理器。
178 | 
179 | 匹配作为关键字参数传递给handler方法的路由参数、查询字符串参数、[表单](http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2)参数和文件。
180 | 
181 | 在名称冲突时，路由参数的优先级最高。
182 | 
183 | handler方法的结果可为：
184 | 
185 | - 一个假值，些时HTTP响应将为一个 [HTTP 204](http://tools.ietf.org/html/rfc7231#section-6.3.5) (无内容)
186 | - werkzeug响应对象，返回原有内容
187 | - `str` 或 `unicode`，将在响应对象中封装并解析为 HTML
188 | 
189 | ###### `make_response(*data*, *headers=None*, *cookies=None*)`
190 | 
191 | 非HTML对象或带有自定义响应头呀 cookie 的HTML响应的帮助方法。
192 | 
193 | 如未返回非HTML数据，在handler仅能返回他们想要作为字符串发送页面的 HTML标记时，他们需要创建完整的响应对象，否则返回数据将不能由客户端正确地解析。
194 | 
195 | 参数
196 | 
197 | - **data** (`basestring`) – 响应体
198 | - **headers** (`[(name, value)]`) – 对响应设置的HTTP头
199 | - **cookies** (`collections.Mapping`) – 对客户端设置的cookie
200 | 
201 | ###### `not_found(*description=None*)`
202 | 
203 | [HTTP 404](http://tools.ietf.org/html/rfc7231#section-6.5.4) (Not Found) 响应的捷方式
204 | 
205 | ###### `render(*template*, *qcontext=None*, *lazy=True*, ***kw*)`
206 | 
207 | QWeb模板的懒渲染。
208 | 
209 | 给定模块的实际渲染发生在调度的最后。同时，模板及/或qcontext 可由静态响应修改甚至是替换掉。
210 | 
211 | 参数
212 | 
213 | - **template** (`basestring`) – 等渲染的模板
214 | - **qcontext** ([`dict`](https://docs.python.org/3/library/stdtypes.html#dict)) – 要使用的渲染上下文
215 | - **lazy** ([`bool`](https://docs.python.org/3/library/functions.html#bool)) – 是否应将模板渲染延时到最后一刻
216 | - **kw** – 转发到werkzeug的Response对象
217 | 
218 | ###### `*class* odoo.http.JsonRequest(**args*)`
219 | 
220 | 透过HTTP的[JSON-RPC 2](http://www.jsonrpc.org/specification) 请求handler
221 | 
222 | - 忽略`method`
223 | - `params`须为一个JSON对象 (并非数组)且传递为handler方法的关键字参数
224 | - handler方法的结果返回为 JSON-RPC `结果`并在 [JSON-RPC Response](http://www.jsonrpc.org/specification#response_object)中进行封装
225 | 
226 | 成功的请求：
227 | 
228 | ```
229 | --> {"jsonrpc": "2.0",
230 |      "method": "call",
231 |      "params": {"context": {},
232 |                 "arg1": "val1" },
233 |      "id": null}
234 | 
235 | <-- {"jsonrpc": "2.0",
236 |      "result": { "res1": "val1" },
237 |      "id": null}
238 | ```
239 | 
240 | 产生错误的请求：
241 | 
242 | ```
243 | --> {"jsonrpc": "2.0",
244 |      "method": "call",
245 |      "params": {"context": {},
246 |                 "arg1": "val1" },
247 |      "id": null}
248 | 
249 | <-- {"jsonrpc": "2.0",
250 |      "error": {"code": 1,
251 |                "message": "End user error message.",
252 |                "data": {"code": "codestring",
253 |                         "debug": "traceback" } },
254 |      "id": null}
255 | ```
256 | 
257 | ### 响应
258 | 
259 | ###### `*class* odoo.http.Response(**args*, ***kw*)`
260 | 
261 | 通过控制器路由链传递的Response对象。
262 | 
263 | [`werkzeug.wrappers.Response`](https://werkzeug.palletsprojects.com/en/0.16.x/wrappers/#werkzeug.wrappers.Response) 参数之外，这个类的构造方法可针对QWeb懒渲染接收如下的额外参数。
264 | 
265 | 参数
266 | 
267 | - **template** (`basestring`) – 等渲染的模板
268 | - **qcontext** ([`dict`](https://docs.python.org/3/library/stdtypes.html#dict)) – 要使用的渲染上下文
269 | - **uid** ([`int`](https://docs.python.org/3/library/functions.html#int)) – 针对ir.ui.view渲染调用所使用的用户 id，`None` 时使用请求的用户 (默认)
270 | 
271 | 这些属性在Response对象中作为参数使用且可在渲染之前的任意时刻进行更改
272 | 
273 | 还暴露[`werkzeug.wrappers.Response`](https://werkzeug.palletsprojects.com/en/0.16.x/wrappers/#werkzeug.wrappers.Response)的所有属性和方法。
274 | 
275 | ###### `render()`
276 | 
277 | 渲染Response的模板，返回结果
278 | 
279 | ###### `flatten()`
280 | 
281 | 强制渲染响应模板，设置结果为响应体并清除`template`


--------------------------------------------------------------------------------
/reference/qweb-reports.md:
--------------------------------------------------------------------------------
  1 | # QWeb报表
  2 | 
  3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | - 以HTML/QWeb像在Odoo中其它普通视图那样编写报表。 你可以使用通常的[QWeb控制流工作](#reference-qweb) 。PDF渲染本身由 [wkhtmltopdf](https://wkhtmltopdf.org/)执行。如果你想要对某个模型创建报表，会需要定义这个[报表](#reference-reports-report)及其需要使用的[报表模板](#reference-reports-templates)。 如果你想要，也可以为报表指定一个特定的[纸张格式](#reference-reports-paper-formats)。最终，如果需要访问自己的模型之外的内容，可以定义一个给予你访问更多模型及模板中记录的权限的[自定义报表](#reference-reports-custom-reports)类。
  5 | 
  6 | ## 报表
  7 | 
  8 | 每个报表必须由 [报表动作](https://alanhou.org/odoo-13-actions/#reference-actions-report)声明。
  9 | 
 10 | 为进行简化，`<report>`元素快捷方式在定义报表可以使用， 而非需要手动设置 [动作](https://alanhou.org/odoo-13-actions/#reference-actions-report)及其周边内容。这个 `<report>` 可以接收如下属性：
 11 | 
 12 | - `id`
 13 | 
 14 |   所生成记录的[外部id](https://www.odoo.com/documentation/13.0/glossary.html#term-external-id)
 15 | 
 16 | - `name` (必填)
 17 | 
 18 |   仅在某种列表中查找内容时用于报表的助记内容/描述
 19 | 
 20 | - `model` (必填)
 21 | 
 22 |   你的报表会相关的模型
 23 | 
 24 | - `report_type` (必填)
 25 | 
 26 |   PDF报表的`qweb-pdf` 或HTML的 `qweb-html`
 27 | 
 28 | - `report_name`
 29 | 
 30 |   你的报表名称(将会是PDF的输出名)
 31 | 
 32 | - `groups`
 33 | 
 34 |   允许浏览/使用当前报表的组的[`Many2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Many2many) 字段
 35 | 
 36 | - `attachment_use`
 37 | 
 38 |   若设置为True， 使用 `attachment`表达式所生成的名称存储为附件的报表；如果需要仅生成一次报表可以使用它 (例如出于法律原因)
 39 | 
 40 | - `attachment`
 41 | 
 42 |   定义报表名称的python 表达式；记录可作为 `object`变量访问
 43 | 
 44 | - `paperformat`
 45 | 
 46 |   希望使用的纸张格式的外部id(如未指定默认为公司的纸张格式)
 47 | 
 48 | 例：
 49 | 
 50 | ```
 51 | <report
 52 |     id="account_invoices"
 53 |     model="account.invoice"
 54 |     string="Invoices"
 55 |     report_type="qweb-pdf"
 56 |     name="account.report_invoice"
 57 |     file="account.report_invoice"
 58 |     attachment_use="True"
 59 |     attachment="(object.state in ('open','paid')) and
 60 |         ('INV'+(object.number or '').replace('/','')+'.pdf')"
 61 | />
 62 | ```
 63 | 
 64 | 
 65 | 
 66 | ## 报表模板
 67 | 
 68 | ### 最小化可选模板
 69 | 
 70 | 最小化模板像下面这样：
 71 | 
 72 | ```
 73 | <template id="report_invoice">
 74 |     <t t-call="web.html_container">
 75 |         <t t-foreach="docs" t-as="o">
 76 |             <t t-call="web.external_layout">
 77 |                 <div class="page">
 78 |                     <h2>Report title</h2>
 79 |                     <p>This object's name is <span t-field="o.name"/></p>
 80 |                 </div>
 81 |             </t>
 82 |         </t>
 83 |     </t>
 84 | </template>
 85 | ```
 86 | 
 87 | 调用`external_layout` 会在报表上添加头部和底部。PDF内容体是 `<div class="page">`内部的内容。 模板的 `id` 必须为在报表声明中指定的名称；例如对上面的报表为 `account.report_invoice` 。因为这是一个QWeb模板，你可以访问由模板接收的`docs`对象的所有字段。
 88 | 
 89 | 有一些可在报表中访问的具体变量，主要有：
 90 | 
 91 | - `docs`
 92 | 
 93 |   针对当前报表的记录
 94 | 
 95 | - `doc_ids`
 96 | 
 97 |   针对 `docs`记录的id列表
 98 | 
 99 | - `doc_model`
100 | 
101 |   针对`docs` 记录的模型
102 | 
103 | - `time`
104 | 
105 |   对Python标准库 [`time`](https://docs.python.org/3/library/time.html#module-time)的引用
106 | 
107 | - `user`
108 | 
109 |   打印报表的用户的`res.user` 记录
110 | 
111 | - `res_company`
112 | 
113 |   当前 `user`的公司的记录
114 | 
115 | 如果你希望访问模板中的记录/模型的其它记录，会需要用到[自定义报表](#reference-reports-custom-reports)。
116 | 
117 | ### 可翻译模板
118 | 
119 | 如果要翻译报表 (如翻译到伙伴的语言)，需要定义两个模板：
120 | 
121 | - 主报表模板
122 | - 可翻译的文档
123 | 
124 | 然后可以调用通过将属性设置 `t-lang` 为语言代码(例如`fr` 或 `en_US`)或是记录字段的主模板中的可翻译文档。如果使用可翻译的字段（如国家名、销售条件等）还需要通过相应的上下文重新浏览相关记录。
125 | 
126 | ### ⚠️警告
127 | 
128 | 如果报表模板不使用可翻译记录字段，不需要在另一种语言中重新浏览记录且这样会影响性能。
129 | 
130 | 例如，我们来看一下Sale模块中的销售订单报表：
131 | 
132 | ```
133 | <!-- Main template -->
134 | <template id="report_saleorder">
135 |     <t t-call="web.html_container">
136 |         <t t-foreach="docs" t-as="doc">
137 |             <t t-call="sale.report_saleorder_document" t-lang="doc.partner_id.lang"/>
138 |         </t>
139 |     </t>
140 | </template>
141 | 
142 | <!-- Translatable template -->
143 | <template id="report_saleorder_document">
144 |     <!-- Re-browse of the record with the partner lang -->
145 |     <t t-set="doc" t-value="doc.with_context(lang=doc.partner_id.lang)" />
146 |     <t t-call="web.external_layout">
147 |         <div class="page">
148 |             <div class="oe_structure"/>
149 |             <div class="row">
150 |                 <div class="col-6">
151 |                     <strong t-if="doc.partner_shipping_id == doc.partner_invoice_id">Invoice and shipping address:</strong>
152 |                     <strong t-if="doc.partner_shipping_id != doc.partner_invoice_id">Invoice address:</strong>
153 |                     <div t-field="doc.partner_invoice_id" t-options="{&quot;no_marker&quot;: True}"/>
154 |                 <...>
155 |             <div class="oe_structure"/>
156 |         </div>
157 |     </t>
158 | </template>
159 | ```
160 | 
161 | 主模板调用可翻译模板，将 `doc.partner_id.lang` 作为 `t-lang` 参数，因此它会以伙伴的语言进行渲染。这样，每个订单会以对应客户的语言进行打印。如果希望仅翻译文档内容体，但保留头部和底部为默认语言，需要像下面这样调用报表的外部布局：
162 | 
163 | ```
164 | <t t-call="web.external_layout" t-lang="en_US">
165 | ```
166 | 
167 | 注意这样仅在调用外部模板时起作用， 不能通过对`t-call`以外的xml节点设置 `t-lang`属性来翻译文档的部分内容。如果要翻译模板的部分内容，可以使用这一部分模板来创建外部模板并通过带`t-lang`属性的主模板调用它。
168 | 
169 | ### 条形码
170 | 
171 | 条形码为由控制器返回的图像，可轻易地借助QWeb语法来在报表中内嵌(例如参见[属性](#reference-qweb-attributes)):
172 | 
173 | ```
174 | <img t-att-src="'/report/barcode/QR/%s' % 'My text in qr code'"/>
175 | ```
176 | 
177 | 可以查询字符串传递更多的参数：
178 | 
179 | ```
180 | <img t-att-src="'/report/barcode/?
181 |     type=%s&value=%s&width=%s&height=%s'%('QR', 'text', 200, 200)"/>
182 | ```
183 | 
184 | ### 实用备注
185 | 
186 | - 可在报表中使用Twitter Bootstrap和FontAwesome类
187 | 
188 | - 可在模板中直接放置本地CSS
189 | 
190 | - 可通过继承模板来在主报表中插入全局CSS并插入你自己的CSS：
191 | 
192 |   ```
193 |   <template id="report_saleorder_style" inherit_id="report.style">
194 |     <xpath expr=".">
195 |       <t>
196 |         .example-css-class {
197 |           background-color: red;
198 |         }
199 |       </t>
200 |     </xpath>
201 |   </template>
202 |   ```
203 | 
204 | - 如果在 PDF报表中缺失了样式，请查看[这些指南](https://alanhou.org/odoo-13-building-module/#reference-backend-reporting-printed-reports-pdf-without-styles)。
205 | 
206 | 
207 | 
208 | ## 纸张格式
209 | 
210 | 纸张格式是`report.paperformat` 记录并可包含如下属性：
211 | 
212 | - `name` (必传)
213 | 
214 |   仅用于在某种列表中查看报表的助记内容/描述
215 | 
216 | - `description`
217 | 
218 |   格式的简短描述
219 | 
220 | - `format`
221 | 
222 |   是预定义格式(A0到A9, B0到 B10, 法律文书, 信件, 公报,…) 或 `自定义`；默认为 A4。你果定义页面大小时不能使用非自定义格式。
223 | 
224 | - `dpi`
225 | 
226 |   输出DPI；默认为90
227 | 
228 | - `margin_top`, `margin_bottom`, `margin_left`, `margin_right`
229 | 
230 |   单位为mm的边框大小
231 | 
232 | - `page_height`, `page_width`
233 | 
234 |   单位为mm的页面大小
235 | 
236 | - `orientation`
237 | 
238 |   横向或纵向
239 | 
240 | - `header_line`
241 | 
242 |   显示头部线的布尔值
243 | 
244 | - `header_spacing`
245 | 
246 |   单位为mm的头部间距
247 | 
248 | 例：
249 | 
250 | ```
251 | <record id="paperformat_frenchcheck" model="report.paperformat">
252 |     <field name="name">French Bank Check</field>
253 |     <field name="default" eval="True"/>
254 |     <field name="format">custom</field>
255 |     <field name="page_height">80</field>
256 |     <field name="page_width">175</field>
257 |     <field name="orientation">Portrait</field>
258 |     <field name="margin_top">3</field>
259 |     <field name="margin_bottom">3</field>
260 |     <field name="margin_left">3</field>
261 |     <field name="margin_right">3</field>
262 |     <field name="header_line" eval="False"/>
263 |     <field name="header_spacing">3</field>
264 |     <field name="dpi">80</field>
265 | </record>
266 | ```
267 | 
268 | 
269 | 
270 | ## 自定义报表
271 | 
272 | 报表模型有默认的`get_html`函数，会查找名为`report.*module.report_name*`的模型。如若存在，会使用它来调用QWeb引擎；否则会使用一个通用函数。如果希望通过在模板中包含更多内容来自定义报表 (例如像其它模型中记录)，可以定义这个模型，重写函数 `_get_report_values` 并在 `docargs` 字典中传递对象：
273 | 
274 | ```
275 | from odoo import api, models
276 | 
277 | class ParticularReport(models.AbstractModel):
278 |     _name = 'report.module.report_name'
279 | 
280 |     @api.model
281 |     def _get_report_values(self, docids, data=None):
282 |         report_obj = self.env['ir.actions.report']
283 |         report = report_obj._get_report_from_name('module.report_name')
284 |         docargs = {
285 |             'doc_ids': docids,
286 |             'doc_model': report.model,
287 |             'docs': self,
288 |         }
289 |         return docargs
290 | ```
291 | 
292 | 
293 | 
294 | ## 自定义字体
295 | 
296 | If you want to use如果希望使用自定义字段则需要向`web.reports_assets_common`资源包添加自定义字体相相关联的 less/CSS。向`web.assets_common` 或 `web.assets_backend`添加自定义字体不会让该字体在QWeb可用。
297 | 
298 | 例：
299 | 
300 | ```
301 | <template id="report_assets_common_custom_fonts" name="Custom QWeb fonts" inherit_id="web.report_assets_common">
302 |     <xpath expr="." position="inside">
303 |         <link href="/your_module/static/src/less/fonts.less" rel="stylesheet" type="text/less"/>
304 |     </xpath>
305 | </template>
306 | ```
307 | 
308 | 即使在（除`web.reports_assets_common`以外的）其它资源包中使用过，也需要在这个less文件中定义 `@font-face`。
309 | 
310 | 例：
311 | 
312 | ```
313 | @font-face {
314 |     font-family: 'MonixBold';
315 |     src: local('MonixBold'), local('MonixBold'), url(/your_module/static/src/fonts/MonixBold-Regular.otf) format('opentype');
316 | }
317 | 
318 | .h1-title-big {
319 |     font-family: MonixBold;
320 |     font-size: 60px;
321 |     color: #3399cc;
322 | }
323 | ```
324 | 
325 | 在将这一 less添加到资源包中以后就可以在自定义QWeb报表中使用该类了- 配合中为 `h1-title-big`。
326 | 
327 | ## 报表是网页
328 | 
329 | 报表通过report模块动态生成并可直接通过URL进行访问：
330 | 
331 | 例如，可以通过http://<server-address>/report/html/sale.report_saleorder/38来以html模式访问销售订单报表
332 | 
333 | 或者通过http://<server-address>/report/pdf/sale.report_saleorder/38访问pdf版本


--------------------------------------------------------------------------------
/reference/actions.md:
--------------------------------------------------------------------------------
  1 | # 动作
  2 | 
  3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | 动作定义对应用户动作的系统行为：登录、动作按钮、发票选取 … 动作可存储在数据库中或直接返回如按钮方法的字典。所有的动作有两个必选属性：
  6 | 
  7 | - `type`
  8 | 
  9 |   当前动作的分类，定义可使用哪些字段以及如何解析动作
 10 | 
 11 | - `name`
 12 | 
 13 |   针对动作的用户可读的简短描述，可在客户端界面中显示
 14 | 
 15 | - `binding_model_id`
 16 | 
 17 |   若进行设置，在给定模型的动作栏中的可用动作对于服务端动作，使用 `model_id`。
 18 | 
 19 | 客户端可以获取4种形式的动作：
 20 | 
 21 | - - `False`
 22 | 
 23 |     若当前有动作对话框处于打开状态，进行关闭
 24 | 
 25 | - - 字符串
 26 | 
 27 |     若匹配 [客户端动作](#reference-actions-client)，解析为客户端动作标签，否则视为数字
 28 | 
 29 | - - 数字
 30 | 
 31 |     读取数据库中的相应动作记录，可为数据库标识符或 [外部id](https://www.odoo.com/documentation/13.0/glossary.html#term-external-id)
 32 | 
 33 | - - 字典
 34 | 
 35 |     视为客户端描述符并执行
 36 | 
 37 | ## 绑定
 38 | 
 39 | 除两个必选属性外，所有的动作还可以有用于在任意模型的上下文菜单中展示动作的*可选*属性：
 40 | 
 41 | - `binding_model_id`
 42 | 
 43 |   指定动作所绑定的模型
 44 | 
 45 | - `binding_type`
 46 | 
 47 |   指定所绑定的类型，大多为动作出现在哪个上下文菜单之下`action` (默认)指定动作会出现在绑定模型Action上下文菜单中。`report`指定动作会出现在所绑定模型的Print上下文菜单中
 48 | 
 49 | - `binding_view_types`
 50 | 
 51 |   视图的逗号分隔列表，其中动作出现在上下文菜单中，大部分“列表”及/或“表单”。默认为`list,form` (列表及表单)
 52 | 
 53 | 
 54 | 
 55 | ## 窗口动作(`ir.actions.act_window`)
 56 | 
 57 | 大部分常用动作类型，用于展示通过[视图](https://alanhou.org/odoo-13-views/#reference-views)的模型可视化：定义一组视图类型的模型（可能为模型的指定记录）窗口动作 (及可能的指定视图) f
 58 | 
 59 | 其字段有：
 60 | 
 61 | - `res_model`
 62 | 
 63 |   用于展示视图的模型
 64 | 
 65 | - `views`
 66 | 
 67 |   `(view_id, view_type)` 对的列表。每组的第二个元素是视图的分类 (tree, form, graph, …) ，第一个是可选的数据库 id (或 `False`)。若未提供 id，客户端应获取对所请求模型指定类型的默认视图(默认通过[`fields_view_get()`](https://alanhou.org/odoo-13-orm-api/#odoo.models.Model.fields_view_get)来实现). 列表的第一个类型是默认视图类型列表，在动作执行时会默认打开。每个视图类型在列表中最多出现一次。
 68 | 
 69 | - `res_id` (可选)
 70 | 
 71 |   若默认视图为 `form`，指定要加载的记录(否则应创建一条新记录)
 72 | 
 73 | - `search_view_id` (可选)
 74 | 
 75 |   `(id, name)` 对， `id` 为针对动作所加载的指定搜索视图的数据库标识符。默认获取模型的默认搜索视图
 76 | 
 77 | - `target` (可选)
 78 | 
 79 |   是否应在主内容区 (`current`)中以全屏模式（`fullscreen`）或对话框/弹窗（`new`）中打开视图。使用 `main` 代替 `current` 来清除面包屑导航。默认为`current`。
 80 | 
 81 | - `context` (可选)
 82 | 
 83 |   传递给视图的额外上下文数据
 84 | 
 85 | - `domain` (可选)
 86 | 
 87 |   隐式添加给所有视图搜索查询的过滤作用域
 88 | 
 89 | - `limit` (可选)
 90 | 
 91 |   默认在列表中显示的记录数。在网页客户端中默认为80
 92 | 
 93 | 例如，要通过列表及表单视图打开客户 (配合 `customer` 标记集) ：
 94 | 
 95 | ```
 96 | {
 97 |     "type": "ir.actions.act_window",
 98 |     "res_model": "res.partner",
 99 |     "views": [[False, "tree"], [False, "form"]],
100 |     "domain": [["customer", "=", true]],
101 | }
102 | ```
103 | 
104 | 或在新对话框中打开指定产品（单独获取）的表单视图：
105 | 
106 | ```
107 | {
108 |     "type": "ir.actions.act_window",
109 |     "res_model": "product.product",
110 |     "views": [[False, "form"]],
111 |     "res_id": a_product_id,
112 |     "target": "new",
113 | }
114 | ```
115 | 
116 | 数据库中的窗口动作有一些应由客户端忽略的不同字段，大多数用于组成`views` 列表：
117 | 
118 | - `view_mode` (默认= `tree,form` )
119 | 
120 |   视图类型的逗号分隔列表作为字符串(/!\ 无空格 /!\)。所有这些类型会在生成的`views` 列表中出现 (至少有一个`False` view_id)
121 | 
122 | - `view_ids`
123 | 
124 |   M2M[1](#notquitem2m) 的视图对象，定义 `views`的初始内容Act_window视图也可通过`ir.actions.act_window.view`清晰地定义。如果你打算允许模型的多个视图，推荐使用ir.actions.act_window.view 而不是动作 `view_ids``<record model="ir.actions.act_window.view" id="test_action_tree">   <field name="sequence" eval="1"/>   <field name="view_mode">tree</field>   <field name="view_id" ref="view_test_tree"/>   <field name="act_window_id" ref="test_action"/> </record>`
125 | 
126 | - `view_id`
127 | 
128 |   在类型是`view_mode`列表的一部分且没有由`view_ids`中的视图进行填充时，添加到 `views` 中的指定视图
129 | 
130 | These are mostly used when defining actions from这些大多在 [数据文件](https://www.odoo.com/documentation/13.0/reference/data.html#reference-data)中定义动作时使用：
131 | 
132 | ```
133 | <record model="ir.actions.act_window" id="test_action">
134 |     <field name="name">A Test Action</field>
135 |     <field name="res_model">some.model</field>
136 |     <field name="view_mode">graph</field>
137 |     <field name="view_id" ref="my_specific_view"/>
138 | </record>
139 | ```
140 | 
141 | 即使不是模型的默认视图，也将使用“my_specific_view”视图。
142 | 
143 | 服务端的 `views` 序列的组合如下：
144 | 
145 | - 通过 `view_ids` 获取每个`(id, type)`(通过`sequence`排序)
146 | - 若定义了 `view_id` 且未填充其类型，追加其 `(id, type)`
147 | - 对每个 `view_mode`中未填充的类型，追加 `(False, type)`
148 | 
149 | [[1\]](#id1) 技术上不是 M2M: 添加序列字段及可能只由视图类型组成，不带有视图id。
150 | 
151 | 
152 | 
153 | ## URL动作 (`ir.actions.act_url`)
154 | 
155 | (website/web page) via an 允许Odoo动作打开URL（网站/网页）。可由两个字段进行自定义：
156 | 
157 | - `url`
158 | 
159 |   在激活动作时打开的地址
160 | 
161 | - `target`
162 | 
163 |   若为 `new`在新窗口/页面打开该地址，若为 `self`使用该页面替换当前内容。默认值为 `new`
164 | 
165 | ```
166 | {
167 |     "type": "ir.actions.act_url",
168 |     "url": "https://odoo.com",
169 |     "target": "self",
170 | }
171 | ```
172 | 
173 | 将使用Odoo首页替换当前内容版块。
174 | 
175 | 
176 | 
177 | ## 服务端动作 (`ir.actions.server`)
178 | 
179 | ###### `*class* odoo.addons.base.models.ir_actions.IrActionsServer(*pool*, *cr*)`
180 | 
181 | 服务端动作模型。服务端动作在基模型上运作并且提供种类可自动执行的动作类型，例如，手动通过在 More 上下文菜单中添加动作来使用基动作规则。
182 | 
183 | 从Odoo 8.0开始，在动作表单视图中出现了‘Create Menu Action’按钮。它在基模型的More菜单中创建一个入口。这允许在界面中创建服务端动作并以批量模式进行运行。
184 | 
185 | 可以使用的动作有：
186 | 
187 | - ‘Execute Python Code’: 将会执行的 Python 代码块
188 | - ‘Create a new Record’: 使用新值新建记录
189 | - ‘Write on a Record’: 更新记录值
190 | - ‘Execute several actions’: 定义触发一些其它服务端动作的动作
191 | 
192 | 允许通过任意有效动作位置触发复杂服务端代码。仅有两个字段与客户端相关：
193 | 
194 | - `id`
195 | 
196 |   待运行服务端动作的数据库中的标识符
197 | 
198 | - `context` (可选)
199 | 
200 |   在运行服务端动作时使用的上下文数据
201 | 
202 | In-database records 数据库中的记录很明显的更丰富并可执行一些基于它们的`state`的特定或通用动作。一些字段 (及相应行为) 在状态之间进行分享：
203 | 
204 | - `model_id`
205 | 
206 |   链接到动作的Odoo模型。
207 | 
208 | ```
209 | state
210 | ```
211 | 
212 | - `code`: 执行通过`code` 参数给定的python代码。
213 | - `object_create`: 根据`fields_lines` 规格新建`crud_model_id`模型的记录。
214 | - `object_write`: 按照`fields_lines` 规格更新当前记录。
215 | - `multi`: 执行通过`child_ids` 参数给定的一些动作。
216 | 
217 | ### 状态字段
218 | 
219 | 根据其状态通过不同的字段来定义行为。相关的状态在每个字段后给出。
220 | 
221 | - `code` (代码)
222 | 
223 |   指定调用动作时所要执行的Python代码块`<record model="ir.actions.server" id="print_instance">    <field name="name">Res Partner Server Action</field>    <field name="model_id" ref="model_res_partner"/>    <field name="code">        raise Warning(record.name)    </field> </record>`代码块中可定义`action`的变量，它将以要执行的下一个动作返回客户端：`    <field name="name">Res Partner Server Action</field>    <field name="model_id" ref="model_res_partner"/>    <field name="code">        if record.some_condition():            action = {                "type": "ir.actions.act_window",                "view_mode": "form",                "res_model": record._name,                "res_id": record.id,            }    </field> </record>`会要求客户端在满足某些条件时打开记录的表单
224 | 
225 | - `crud_model_id` (创建)(必传)
226 | 
227 |   新建记录的所在模型
228 | 
229 | - `link_field_id` (创建)
230 | 
231 |   `ir.model.fields`的many2one关联，指定当前记录的m2o字段，在其中应设置新创建字段（模型应匹配）
232 | 
233 | - `fields_lines` (创建/写入)
234 | 
235 |   在创建或拷贝记录时重载的字段。与字段的关联为 [`One2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.One2many)：`col1`在相关模型中设置`ir.model.fields` (`crud_model_id` 用于创建， `model_id` 用于更新)`value`字段的值，通过 `type`解析`type` (value|reference|equation)若为 `value`, `value` 字段解析为字面量值(可能会进行格式转换)，若为`equation`，`value` 字段解析为Python 表达式并进行运行
236 | 
237 | - `child_ids` (multi)
238 | 
239 |   指定多个子动作 (`ir.actions.server`) 来启用多状态。如子动作本身返回动作，上一个会作为multi自己的下一个动作返回客户端
240 | 
241 | 
242 | 
243 | ### 运行上下文
244 | 
245 | 在服务端动作的运行上下文或周边存在很多键可以使用：
246 | 
247 | - `model` 通过 `model_id`关联动作的模型对象
248 | - `record`/`records` 动作所触发的记录/记录集，可以为空。
249 | - `env` Odoo环境
250 | - `datetime`, `dateutil`, `time`, `timezone` 相应Python模块
251 | - `log: log(message, level='info')` 在ir.logging表中用于记录信息的日志函数
252 | - `Warning` 针对`Warning` 异常的构造器
253 | 
254 | 
255 | 
256 | ## 报表动作(`ir.actions.report`)
257 | 
258 | 触发报表打印
259 | 
260 | - `name` (必传)
261 | 
262 |   仅在查询一些排序列表中的某一个时用于报表的助记符/描述
263 | 
264 | - `model` (必传)
265 | 
266 |   报表相关的模型
267 | 
268 | - `report_type` (default=qweb-pdf)
269 | 
270 |   要么是用于PDF报表的 `qweb-pdf` ，要么是用于HTML报表的 `qweb-html`
271 | 
272 | - `report_name` (必传)
273 | 
274 |   报表的名称 (将会与PDF的输出名称相同)
275 | 
276 | - `groups_id`
277 | 
278 |   允许查看/使用当前报表用户组的[`Many2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Many2many) 字段
279 | 
280 | - `multi`
281 | 
282 |   若设置为`True`, 该动作将不会在表单视图中显示。
283 | 
284 | - `paperformat_id`
285 | 
286 |   希望用于此报表的对应于纸张格式的[`Many2one`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Many2one)字段(若未指定，会使用公司格式)
287 | 
288 | - `attachment_use`
289 | 
290 |   若设置为`True`, 该报表仅在请求的初次进行生成，随后会从存储的报表中重新打印，而不会每次都重新生成。可用于必须仅生成一次的报表 (例如出于法律原因)
291 | 
292 | - `attachment`
293 | 
294 |   定义报表名称的python表达式；记录可以 `object`变量进行访问
295 | 
296 | 
297 | 
298 | ## 客户端动作(`ir.actions.client`)
299 | 
300 | 触发完全在客户端实现的动作。
301 | 
302 | - `tag`
303 | 
304 |   动作的客户端标识符， 客户端应知道如何响应的任意字符串
305 | 
306 | - `params` (可选)
307 | 
308 |   与客户端动作标记一起发送到客户端的附加数据的Python字典
309 | 
310 | - `target` (可选)
311 | 
312 |   客户端动作是否应在主内容区(`current`)、以全屏模式(`fullscreen`)或对话框/弹窗(`new`)中打开。使用 `main` 代替`current` 来清除面包屑。默认值为 `current`。
313 | 
314 | ```
315 | {
316 |     "type": "ir.actions.client",
317 |     "tag": "pos.ui"
318 | }
319 | ```
320 | 
321 | 告诉客户端启动POS 界面，服务端并不了解 POS 界面的运行方式。
322 | 
323 | 
324 | 
325 | ## 自动化动作(`ir.cron`)
326 | 
327 | 以预定义频率自动触发的动作。
328 | 
329 | - `name`
330 | 
331 |   自动化动作的名称 (主要在日志显示中使用)
332 | 
333 | - `interval_number`
334 | 
335 |   在两个动作执行之间的*nterval_type* 计量单位数
336 | 
337 | - `interval_type`
338 | 
339 |   频率间隔的计量单位(`minutes`, `hours`, `days`, `weeks`, `months`,
340 | 
341 | - `numbercall`
342 | 
343 |   这一动作需要运行的次数。如果动作要进行无限动作，设置为 `-1`。
344 | 
345 | - `doall`
346 | 
347 |   在服务重启时指定是否执行未执行动作的布尔值。
348 | 
349 | - `model_id`
350 | 
351 |   这一动作将会被调用的模型
352 | 
353 | - `code`
354 | 
355 |   动作的代码内容。可以是对模型方法的简单调用：`model.<method_name>()`
356 | 
357 | - `nextcall`
358 | 
359 |   该动作的下一次计划执行日期(date/time 格式)
360 | 
361 |  


--------------------------------------------------------------------------------
/reference/command-line-interface-odoo-bin.md:
--------------------------------------------------------------------------------
  1 | # 命令行接口：odoo-bin
  2 | 
  3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | ## 运行服务
  6 | 
  7 | ###### `-d <database>, --database <database>`
  8 | 
  9 | 在安装或更新文件时使用的数据库。提供一个逗号分隔列表，列表中提供数据库限制权限。
 10 | 
 11 | 高级数据库选项请参见 [下方内容](#reference-cmdline-server-database)。
 12 | 
 13 | ###### `-i <modules>, --init <modules>`
 14 | 
 15 | 在运行服务前要安装的模块的逗号分隔列表(要求有 [`-d`](#cmdoption-odoo-bin-d)选项)。
 16 | 
 17 | ###### `-u <modules>, --update <modules>`
 18 | 
 19 | 在运行服务前要更新的模块的逗号分隔列表(要求有 [`-d`](#cmdoption-odoo-bin-d)选项)。
 20 | 
 21 | ###### `--addons-path <directories>`
 22 | 
 23 | 模块所存储的目录的逗号分隔列表。这些目录供模块扫描。
 24 | 
 25 | ###### `-c <config>, --config <config>`
 26 | 
 27 | 指供一个替代 [配置文件](#reference-cmdline-config)
 28 | 
 29 | ###### `-s, --save`
 30 | 
 31 | 保存服务端配置到当前配置文件中 (默认为`*$HOME*/.odoorc` ，可通过使用 [`-c`](#cmdoption-odoo-bin-c)进行重载)。
 32 | 
 33 | ###### `--without-demo`
 34 | 
 35 | 在模块安装时禁止加载演示数据的逗号分隔列表，使用 `all` 来针对所有模块。
 36 | 
 37 | ###### `--test-enable`
 38 | 
 39 | 在安装模块之后运行测试
 40 | 
 41 | ###### `--test-tags 'tag_1,tag_2,...,-tag_n'`
 42 | 
 43 | 选择通过使用标签运行的测试。
 44 | 
 45 | ###### `--screenshots`
 46 | 
 47 | 指定在HttpCase.browser_js测试失败时写入截屏快照的路径。 默认值为`/tmp/odoo_tests/*db_name*/screenshots`
 48 | 
 49 | ###### `--screencasts`
 50 | 
 51 | 启用录屏并指定写入录屏文件的路径。需要安装 `ffmpeg`工具来将各帧编码入视频文件中。否则将保存帧而不是视频文件。
 52 | 
 53 | `1`, `t` 或 `true` 可用于使用同一目录作为上述的 `--screenshots` 选项。
 54 | 
 55 | 
 56 | 
 57 | ### 数据库
 58 | 
 59 | ###### `-r <user>, --db_user <user>`
 60 | 
 61 | 数据库用户名，用于连接PostgreSQL.
 62 | 
 63 | ###### `-w <password>, --db_password <password>`
 64 | 
 65 | 若使用了 [密码验证](https://www.postgresql.org/docs/9.3/static/auth-methods.html#AUTH-PASSWORD)时，为数据库密码。
 66 | 
 67 | ###### `--db_host <hostname>`
 68 | 
 69 | 数据库服务端的主机
 70 | 
 71 | - Windows上的`localhost`
 72 | - 否则为UNIX套接字
 73 | 
 74 | ###### `--db_port <port>`
 75 | 
 76 | 数据库监听的端口，默认为5432
 77 | 
 78 | ###### `--db-filter <filter>`
 79 | 
 80 | 隐藏不匹配`<filter>`的数据库。过滤器是一个[正则表达式](https://docs.python.org/3/library/re.html)，额外之处有：
 81 | 
 82 | - `%h` 由所进行请求的完整主机名替换。
 83 | - `%d`由所进行请求的子域名进行替换，`www` 除外(因此域名`odoo.com` 和 `www.odoo.com` 同时匹配数据库`odoo`)。这些运算是区分大小写的。添加选项 `(?i)` 来匹配所有数据库(因此域名 `odoo.com` 使用 `(?i)%d` 匹配数据库 `Odoo`).
 84 | 
 85 | 自版本11开始，还可以通过使用–database参数并指定一个逗号分隔的数据库列表来限定对指定数据库的访问
 86 | 
 87 | 在合并这两个参数时，db-filter替代限定数据库列表的逗号分隔列表，而逗号分隔列表用于执行像升级模块这类请求运算。
 88 | 
 89 | ```
 90 | $ odoo-bin --db-filter ^11.*$
 91 | ```
 92 | 
 93 | 限制对名称以11开头的数据库的访问
 94 | 
 95 | ```
 96 | $ odoo-bin --database 11firstdatabase,11seconddatabase
 97 | ```
 98 | 
 99 | 限定仅访问两个数据库， 11firstdatabase 和 11seconddatabase
100 | 
101 | ```
102 | $ odoo-bin --database 11firstdatabase,11seconddatabase -u base
103 | ```
104 | 
105 | 限定仅访问两个数据库，11firstdatabase 和 11seconddatabase，并升级一个数据库中的 base模块：11firstdatabase。如果数据库11seconddatabase 不存在，会创建数据库并安装base模块
106 | 
107 | ```
108 | $ odoo-bin --db-filter ^11.*$ --database 11firstdatabase,11seconddatabase -u base
109 | ```
110 | 
111 | 限定对名称以11开头的数据库的访问，并对一个数据库的 base模块进行升级：11firstdatabase。如数据库11seconddatabase 不存在，会创建该数据库并安装 base 模块
112 | 
113 | ###### `--db-template <template>`
114 | 
115 | 在通过数据库管理界面新建数据库时，使用指定的[模板数据库](https://www.postgresql.org/docs/9.3/static/manage-ag-templatedbs.html)。默认为`template0`。
116 | 
117 | ###### `--pg_path </path/to/postgresql/binaries>`
118 | 
119 | 由数据库管理器用于导出及还原数据库的PostgreSQL二进制的路径。应仅在这些二进制文件位于非标准目录内时才进行指定。
120 | 
121 | ###### `--no-database-list`
122 | 
123 | 限制在系统中列出可用数据库列表的功能
124 | 
125 | ###### `--db_sslmode`
126 | 
127 | 控制在Odoo 和 PostgreSQL之间连接的SSL安全。值应为‘disable’, ‘allow’, ‘prefer’, ‘require’, ‘verify-ca’ 或 ‘verify-full’之一。默认值为‘prefer’
128 | 
129 | 
130 | 
131 | ### Email
132 | 
133 | ###### `--email-from <address>`
134 | 
135 | 在Odoo需要发送邮件时用作<FROM>的Email地址
136 | 
137 | ###### `--smtp <server>`
138 | 
139 | 连接来发送邮件的SMTP服务器地址
140 | 
141 | ###### `--smtp-port <port>`
142 | 
143 | ###### `--smtp-ssl`
144 | 
145 | 若进行了设置，odoo 应使用 SSL/STARTSSL SMTP 连接
146 | 
147 | ###### `--smtp-user <name>`
148 | 
149 | 连接到SMTP服务器的用户名
150 | 
151 | ###### `--smtp-password <password>`
152 | 
153 | 连接到SMTP服务器的密码
154 | 
155 | 
156 | 
157 | ### 国际化
158 | 
159 | 使用这些选项来翻译Odoo为另一咱语言。参见用户手册的 i18n 版块。选项‘-d’是必传的。在导入时选项‘-l’是必传的
160 | 
161 | ###### `--load-language <languages>`
162 | 
163 | 指定希望加载翻译的语言 (由逗号分隔)
164 | 
165 | ###### `-l, --language <language>`
166 | 
167 | 指定翻译文件的语言。通过–i18n-export 或 –i18n-import来进行使用
168 | 
169 | ###### `--i18n-export <filename>`
170 | 
171 | 导出所有要翻译的句子到一个CSV文件、一个PO文件或一个TGZ 存档中并退出。
172 | 
173 | ###### `--i18n-import <filename>`
174 | 
175 | 导入一个带有翻译的CSV 或 PO文件并退出。 要求使用 ‘-l’选项。
176 | 
177 | ###### `--i18n-overwritec`
178 | 
179 | 对更新的模块重写已有翻译词汇或导入一个CSV 或 PO 文件
180 | 
181 | ###### `--modules`
182 | 
183 | 指定导出的模块。与 –i18n-export一并使用
184 | 
185 | 
186 | 
187 | ### 高级选项
188 | 
189 | 
190 | 
191 | #### 开发者功能
192 | 
193 | ###### `--dev <feature,feature,...,feature>`
194 | 
195 | - `all`: 激活下面所有的功能
196 | - `xml`: 从xml文件而非数据库直接读取模板。一旦在数据库中修改了模板，在下一次更新/初始化之前它将不会从 xml 中进行读取。
197 | - `reload`: 在python文件更新时重启服务端 (根据所使用的文本编辑器可能不会被监测到)
198 | - `qweb`: 在节点包含 `t-debug='debugger'`时qweb模板执行的断点
199 | - `(i)p(u)db`: 在日志和返回错误前抛出预期外错误时在代码中开启所选中的python调试器。
200 | 
201 | 
202 | 
203 | #### HTTP
204 | 
205 | ###### `--no-http`
206 | 
207 | 不启动HTTP 或 长轮询 worker (可能仍会启动[cron](https://alanhou.org/odoo-13-actions/#reference-actions-cron) worker)
208 | 
209 | ### ⚠️警告
210 | 
211 | 若设置了[`--test-enable`](#cmdoption-odoo-bin-test-enable) 时没有效果，因为测试要求可访问HTTP 服务
212 | 
213 | ###### `--http-interface <interface>`
214 | 
215 | HTTP服务监听的TCP/IP地址，默认为 `0.0.0.0` (所有地址)
216 | 
217 | ###### `--http-port <port>`
218 | 
219 | HTTP服务监听的端口，默认为 8069。
220 | 
221 | ###### `--longpolling-port <port>`
222 | 
223 | 在多进程或gevent模式下长轮询连接的TCP端口，默认为8072。在默认（线程）模式下不进行使用。
224 | 
225 | ###### `--proxy-mode`
226 | 
227 | 启用通过 [Werkzeug代理支持](http://werkzeug.pocoo.org/docs/contrib/fixers/#werkzeug.contrib.fixers.ProxyFix)的`X-Forwarded-*`头部的使用。
228 | 
229 | ### ⚠️警告
230 | 
231 | 在反向代理场景之外**不可**启动代理模式
232 | 
233 | 
234 | 
235 | #### 日志
236 | 
237 | 默认Odoo显示除工作流日志(仅为`warning` )以外的所有 `info` [级别](https://docs.python.org/3/library/logging.html#logging.Logger.setLevel) 的日志，并且输出被发送到`stdout`。也有重定向日志到其它目的地及自定义日志输出的量的各种选项可以使用。
238 | 
239 | ###### `--logfile <file>`
240 | 
241 | 发送日志输出到指定的文件而非stdout。在Unix中，文件 [可由外部日志轮转程序管理](https://docs.python.org/3/library/logging.handlers.html#watchedfilehandler)并在替换时自动被重新打开=
242 | 
243 | ###### `--syslog`
244 | 
245 | 记录到系统的事件记录器中： [Unix 系统中的syslog](https://docs.python.org/3/library/logging.handlers.html#sysloghandler)及 [Windowsk 的事件日志](https://docs.python.org/3/library/logging.handlers.html#nteventloghandler)。
246 | 
247 | 都不可进行配置。
248 | 
249 | ###### `--log-db <dbname>`
250 | 
251 | 记录到指定数据库的 `ir.logging`模型 (`ir_logging` 数据表) 中。数据库可以是在“当前”PostgreSQL中的数据库名称或一个针对日志聚合等的 [PostgreSQL URI](https://www.postgresql.org/docs/9.2/static/libpq-connect.html#AEN38208)。
252 | 
253 | ###### `--log-handler <handler-spec>`
254 | 
255 | `*LOGGER*:*LEVEL*`，在所提供的 `LEVEL` 中启用`LOGGER`，如`odoo.models:DEBUG` 会启用所有模型中`DEBUG`及以上级别的所有日志消息。
256 | 
257 | - 冒号 `:` 为必选
258 | - 可省略日志器来配置根 (默认)处理器
259 | - 如果省略了日志级别，日志设置为 `INFO`级别
260 | 
261 | 可重复选项来配置多个日志器，如
262 | 
263 | ```
264 | $ odoo-bin --log-handler :DEBUG --log-handler werkzeug:CRITICAL --log-handler odoo.fields:WARNING
265 | ```
266 | 
267 | ###### `--log-request`
268 | 
269 | 对RPC请求启用DEBUG日志，等价于 `--log-handler=odoo.http.rpc.request:DEBUG`
270 | 
271 | ###### `--log-response`
272 | 
273 | 对RPC响应启用DEBUG日志，等价于 `--log-handler=odoo.http.rpc.response:DEBUG`
274 | 
275 | ###### `--log-web`
276 | 
277 | 启用HTTP请求和响应的 DEBUG日志，等价于 `--log-handler=odoo.http:DEBUG`
278 | 
279 | ###### `--log-sql`
280 | 
281 | 启用SQL查询的DEBUG日志，等价于 `--log-handler=odoo.sql_db:DEBUG`
282 | 
283 | ###### `--log-level <level>`
284 | 
285 | 对指定日志器更易于设置预定义级别的快捷方式。“真实” 级别 (`critical`, `error`, `warn`, `debug`) 在`odoo` 和 `werkzeug`日志器中进行设置loggers (除了仅对`odoo`设置的`debug` )。
286 | 
287 | Odoo还提供应用于不同日志设置的调试伪日志级别：
288 | 
289 | - `debug_sql`
290 | 
291 |   设置SQL日志器为 `debug`等价于 `--log-sql`
292 | 
293 | - `debug_rpc`
294 | 
295 |   设置 `odoo` 及HTTP请求日志器为 `debug`等价于`--log-level debug --log-request`
296 | 
297 | - `debug_rpc_answer`
298 | 
299 |   设置 `odoo` 和 HTTP 请求及响应日志器为 `debug`等价于 `--log-level debug --log-request --log-response`
300 | 
301 | 在[`--log-level`](#cmdoption-odoo-bin-log-level) 和 [`--log-handler`](#cmdoption-odoo-bin-log-handler)产生冲突时， 使用后者
302 | 
303 | 
304 | 
305 | #### 多进程
306 | 
307 | ###### `--workers <count>`
308 | 
309 | 若`count` 不为0 (默认值)，启用多进程并设置指定的HTTP worker数量(子进程处理 HTTP 及 RPC 请求)。
310 | 
311 | 多进程模式仅在基于Unix的系统中可以使用
312 | 
313 | 一些选项允许限制及回收worker：
314 | 
315 | ###### `--limit-request <limit>`
316 | 
317 | 在回收和重启前将处理的worker请求数。
318 | 
319 | 默认值为*8196*。
320 | 
321 | ###### `--limit-memory-soft <limit>`
322 | 
323 | 每个worker所允许使用的最大虚拟内存。如超出限制，会在杀死worker并在当前请求结束时回收它。
324 | 
325 | 默认值为*2048MiB*.
326 | 
327 | ###### `--limit-memory-hard <limit>`
328 | 
329 | 对虚拟内存的硬性限制，任何超过这一限制的worker都会立即被杀死，不会等待当前请求进程的结束。
330 | 
331 | 默认值为 *2560MiB*。
332 | 
333 | ###### `--limit-time-cpu <limit>`
334 | 
335 | 防止 worker每次请求使用超出<limit> CPU 秒数。若超出了限制，会杀死该worker。
336 | 
337 | 默认值为*60*。
338 | 
339 | ###### `--limit-time-real <limit>`
340 | 
341 | 防止worker处理请求时超出 <limit>秒。如超出限制，会杀死该worker。
342 | 
343 | 不同于[`--limit-time-cpu`](#cmdoption-odoo-bin-limit-time-cpu) ，这是包含SQL查询在内的“wall time”（绝对时间） 限制。
344 | 
345 | 默认值为 *120*。
346 | 
347 | ###### `--max-cron-threads <count>`
348 | 
349 | 用于 [cron](https://alanhou.org/odoo-13-actions/#reference-actions-cron)任务的worker数。默认值为*2*。 worker是多线程模式中的线程，在多进程模式中进行处理。
350 | 
351 | 对于多进程模式，这是对HTTP worker进程的补充。
352 | 
353 | 
354 | 
355 | ## 配置文件
356 | 
357 | 大部分命令行选项也可通过配置文件进行指定。大部分时候，它们使用去除了`-`前缀的相似名称，而其它`-` 由 `_` 进行替换，如 [`--db-template`](#cmdoption-odoo-bin-db-template) 变为 `db_template`.
358 | 
359 | 一些转换与该模式不相匹配：
360 | 
361 | - [`--db-filter`](#cmdoption-odoo-bin-db-filter) 变为 `dbfilter`
362 | - [`--no-http`](#cmdoption-odoo-bin-no-http) 对应 `http_enable` 的布尔值
363 | - 日志预设(所有带有`--log-` 但除[`--log-handler`](#cmdoption-odoo-bin-log-handler) 和 [`--log-db`](#cmdoption-odoo-bin-log-db)以外的选项) 只会将内容添加到 `log_handler`中，在配置文件中直接使用它
364 | - [`--smtp`](#cmdoption-odoo-bin-smtp) 存储为 `smtp_server`
365 | - [`--database`](#cmdoption-odoo-bin-d)存储为 `db_name`
366 | - [`--i18n-import`](#cmdoption-odoo-bin-i18n-import) 及 [`--i18n-export`](#cmdoption-odoo-bin-i18n-export) 在配置文件中完全不可用
367 | 
368 | 默认配置文件是 `*$HOME*/.odoorc` ，它可使用[`--config`](#cmdoption-odoo-bin-c)进行重置。指定 [`--save`](#cmdoption-odoo-bin-s) 会保存回当前配置状态到该文件中。
369 | 
370 | ## Shell
371 | 
372 | Odoo命令行还允许以python终端环境启动odoo。这会启用与[orm](https://alanhou.org/odoo-13-orm-api/#reference-orm)及其功能的直接交互。
373 | 
374 | ```
375 | $ odoo_bin shell
376 | ```
377 | 
378 | ###### `--shell-interface (ipython|ptpython|bpython|python)`
379 | 
380 | 指定在shell模式下使用推荐的 REPL。
381 | 
382 | 
383 | 
384 | ## 脚手架
385 | 
386 | 脚手架是简化初始搭建的（在Odoo中为模块）自动化框架结构的创建。 虽然不是必须，但它避免了一些配置基础结构及查看启动要求的无聊操作。
387 | 
388 | 脚本架可通过 **odoo-bin scaffold** 子命令进行使用。
389 | 
390 | ###### `name (required)`
391 | 
392 | 要创建的模块名，可以不同方式生成程序名称 (如模块目录名、模型名称 …)
393 | 
394 | ###### `destination (default=current directory)`
395 | 
396 | 新建模块的目录，默认为当前目录
397 | 
398 | ###### `-t <template>`
399 | 
400 | 一个模板目录，文件通过[jinja2](http://jinja.pocoo.org/) 传递然后拷贝到 `destination`目录中
401 | 
402 | ```
403 | $ odoo_bin scaffold my_module /addons/
404 | ```
405 | 
406 | 这将在 */addons/*中创建*my_module*模块。


--------------------------------------------------------------------------------
/reference/qweb.md:
--------------------------------------------------------------------------------
  1 | # QWeb
  2 | 
  3 | - 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | QWeb是由Odoo[2](#othertemplates)所使用的一种主要[模板](https://en.wikipedia.org/wiki/Template_processor)引擎。它是一种模板引擎[1](#genshif) 并多用于生成 [HTML](https://en.wikipedia.org/wiki/HTML)片断和页面。指定为XML属性的模板指令以 `t-`为前缀，例如 `t-if` 用于[条件判断](#reference-qweb-conditionals)，其元素和其它属性会直接进行渲染。为避免元素渲染，还有 `<t>`占位符元素，它执行其指令但不会在自身及其中生成输出：
  6 | 
  7 | ```
  8 | <t t-if="condition">
  9 |     <p>Test</p>
 10 | </t>
 11 | ```
 12 | 
 13 | 以上会产生的结果：
 14 | 
 15 | ```
 16 | <p>Test</p>
 17 | ```
 18 | 
 19 | 如 `condition`为 true, 但使用：
 20 | 
 21 | ```
 22 | <div t-if="condition">
 23 |     <p>Test</p>
 24 | </div>
 25 | ```
 26 | 
 27 | 会产生如下结果：
 28 | 
 29 | ```
 30 | <div>
 31 |     <p>Test</p>
 32 | </div>
 33 | ```
 34 | 
 35 | 
 36 | 
 37 | ## 数据输出
 38 | 
 39 | QWeb有一个主输出指令，它自动对其内容进行HTML转义，来在显示用户所提供的内容时降低 [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) 风险： `esc`.
 40 | 
 41 | `esc` 接收一个表达式，运行它并打印出内容：
 42 | 
 43 | ```
 44 | <p><t t-esc="value"/></p>
 45 | ```
 46 | 
 47 | 通过将`value` 设置为 `42` 来进行渲染并产生结果：
 48 | 
 49 | ```
 50 | <p>42</p>
 51 | ```
 52 | 
 53 | 还有另一个输出指令 `raw` ，它的行为和 `esc` 相同，但*不对输出进行HTML转义。*它可用于显示单独的构建标记 (e.g. 通过函数) 或已清洗的用户提供标记。
 54 | 
 55 | 
 56 | 
 57 | ## 条件判断
 58 | 
 59 | QWeb拥有一个条件指令 `if`，它运行给定为属性值的表达式：
 60 | 
 61 | ```
 62 | <div>
 63 |     <t t-if="condition">
 64 |         <p>ok</p>
 65 |     </t>
 66 | </div>
 67 | ```
 68 | 
 69 | 如果条件为true的话会渲染元素：
 70 | 
 71 | ```
 72 | <div>
 73 |     <p>ok</p>
 74 | </div>
 75 | ```
 76 | 
 77 | 但如果条件为false，它会从结果中删除：
 78 | 
 79 | ```
 80 | <div>
 81 | </div>
 82 | ```
 83 | 
 84 | 条件渲染应用于指令的所有者，不必一定为 `<t>`：
 85 | 
 86 | ```
 87 | <div>
 88 |     <p t-if="condition">ok</p>
 89 | </div>
 90 | ```
 91 | 
 92 | 将给出与前例相同的结果。
 93 | 
 94 | 还存在额外的分支指令 `t-elif` 和 `t-else` ：
 95 | 
 96 | ```
 97 | <div>
 98 |     <p t-if="user.birthday == today()">Happy birthday!</p>
 99 |     <p t-elif="user.login == 'root'">Welcome master!</p>
100 |     <p t-else="">Welcome!</p>
101 | </div>
102 | ```
103 | 
104 | 
105 | 
106 | ## 循环
107 | 
108 | QWeb拥有遍历指令`foreach`，它接收一个表达式，返回待遍历的集合以及第二个用于对遍历的“当前项”提供名称的参数 `t-as` ：
109 | 
110 | ```
111 | <t t-foreach="[1, 2, 3]" t-as="i">
112 |     <p><t t-esc="i"/></p>
113 | </t>
114 | ```
115 | 
116 | 将会渲染为：
117 | 
118 | ```
119 | <p>1</p>
120 | <p>2</p>
121 | <p>3</p>
122 | ```
123 | 
124 | 类似条件，`foreach` 应用于带有指令属性的元素，并且
125 | 
126 | ```
127 | <p t-foreach="[1, 2, 3]" t-as="i">
128 |     <t t-esc="i"/>
129 | </p>
130 | ```
131 | 
132 | 等价于前例。
133 | 
134 | `foreach` 可对数组 (当前项为当前值)或映射(当前项为当前键)进行遍历。.仍支持对整数的遍历（等价于遍历一个包含0到所提供整数（不含）的数组）但已淘汰。
135 | 
136 | 除通过`t-as`传递名称乐， `foreach`还对不同数据点提供一些其它变量：
137 | 
138 | ### ⚠️警告
139 | 
140 | `$as`会替换为传递给 `t-as`的名称
141 | 
142 | - `*$as*_all` (淘汰)
143 | 
144 |   所进行遍历的对象这个变量仅在JavaScript QWeb中可用，在 Python中不可用。
145 | 
146 | - `*$as*_value`
147 | 
148 |   当前遍历值，和列表与整型的 `$as` 相同，但对于映射它提供了值 (其中 `$as`提供了键)
149 | 
150 | - `*$as*_index`
151 | 
152 |   当前迭代索引 (遍历中索引为0的第一项)
153 | 
154 | - `*$as*_size`
155 | 
156 |   如果可用时为集合的大小
157 | 
158 | - `*$as*_first`
159 | 
160 |   当前项是否为遍历的第一项 (等价于 `*$as*_index == 0`)
161 | 
162 | - `*$as*_last`
163 | 
164 |   当前项是否为遍历的最后一项(等价于 `*$as*_index + 1 == *$as*_size`)，要求遍历的大小可用
165 | 
166 | - `*$as*_parity` (淘汰)
167 | 
168 |    为`"even"` 或 `"odd"`，当前遍历回合索引的奇偶性
169 | 
170 | - `*$as*_even` (淘汰)
171 | 
172 |   一个用于表明当前遍历回合为偶数索引的布尔标记
173 | 
174 | - `*$as*_odd` (淘汰)
175 | 
176 |   一个用于表明当前遍历回合为奇数索引的布尔标记
177 | 
178 | 这些提供的额外变量及 `foreach`中创建的新变量仅在``foreach``的作用域中可用。若变量存在于`foreach`的上下文之外， foreach末尾的值会拷贝到全局上下文中
179 | 
180 | ```
181 | <t t-set="existing_variable" t-value="False"/>
182 | <!-- existing_variable now False -->
183 | 
184 | <p t-foreach="[1, 2, 3]" t-as="i">
185 |     <t t-set="existing_variable" t-value="True"/>
186 |     <t t-set="new_variable" t-value="True"/>
187 |     <!-- existing_variable and new_variable now True -->
188 | </p>
189 | 
190 | <!-- existing_variable always True -->
191 | <!-- new_variable undefined -->
192 | ```
193 | 
194 | 
195 | 
196 | ## 属性
197 | 
198 | QWeb可补时计算属性并对输出节点设置计算的结果。这通过 `t-att` (属性)指令完成，存在3种不同形式：
199 | 
200 | - `t-att-*$name*`
201 | 
202 |   创建名为 `$name` 的属性，运行属性值并将结果设置为属性的值：`<div t-att-a="42"/>`将会被渲染为：`<div a="42"></div>`
203 | 
204 | - `t-attf-*$name*`
205 | 
206 |   与前述相同，但参数是 [格式字符串](https://www.odoo.com/documentation/13.0/glossary.html#term-format-string)而不仅仅是一个表达式，通常用于混合字面量及非字面量字符串 (e.g. 类)：`<t t-foreach="[1, 2, 3]" t-as="item">    <li t-attf-class="row {{ (item_index % 2 === 0) ? 'even' : 'odd' }}">        <t t-esc="item"/>    </li> </t>`将会被渲染为：`<li class="row even">1</li> <li class="row odd">2</li> <li class="row even">3</li>`
207 | 
208 | - `t-att=mapping`
209 | 
210 |   如果参数是一个映射，第个 (key, value) 对生成一个新属性及其值：`<div t-att="{'a': 1, 'b': 2}"/>`会被渲染为：`<div a="1" b="2"></div>`
211 | 
212 | - `t-att=pair`
213 | 
214 |   如果参数是一个值对 (两个元素的元组或数组)，值对的第一项是属性的名称，第二项是其值：`<div t-att="['a', 'b']"/>`会被渲染为：`<div a="b"></div>`
215 | 
216 | ## 设置变量
217 | 
218 | QWeb允许在模板内创建变量，来存储（memoize）一个运算 (多次使用它)，提供一个更清晰名称的数据， …
219 | 
220 | 这通过`set`指令完成，它接收待创建变量的名称。设置的值通过两种方式提供：
221 | 
222 | - 一个包含表达式的 
223 | 
224 |   ```
225 |   t-value
226 |   ```
227 | 
228 |    属性，会设置其运行的结果：
229 | 
230 |   ```
231 |   <t t-set="foo" t-value="2 + 1"/>
232 |   <t t-esc="foo"/>
233 |   ```
234 | 
235 |   以上将打印 `3`
236 | 
237 | - 如果没有 
238 | 
239 |   ```
240 |   t-value
241 |   ```
242 | 
243 |    属性，节点的内容体会进行渲染并设置为变量的值：
244 | 
245 |   ```
246 |   <t t-set="foo">
247 |       <li>ok</li>
248 |   </t>
249 |   <t t-esc="foo"/>
250 |   ```
251 | 
252 |   将会生成 `<li>ok</li>` (因我们使用了 `esc` 指令内容会进行转义)
253 | 
254 |   使用这一运算的结果是`raw` 指令的一个显著用例。
255 | 
256 | ## 调用子模板
257 | 
258 | QWeb模板可用于顶层渲染，但它们也可在其它模板之内 (来避免复制或对部分模板给定) 使用 `t-call` 指令：
259 | 
260 | ```
261 | <t t-call="other-template"/>
262 | ```
263 | 
264 | 若定义`other_template`为下面的内容，通过父级执行上下文调用命名模板：
265 | 
266 | ```
267 | <p><t t-value="var"/></p>
268 | ```
269 | 
270 | 上面的调用会被渲染为 `<p/>` (无内容)，但：
271 | 
272 | ```
273 | <t t-set="var" t-value="1"/>
274 | <t t-call="other-template"/>
275 | ```
276 | 
277 | 会被渲染为 `<p>1</p>`.
278 | 
279 | 但这在 `t-call`之外的可见性存在问题。此外，`call` 指令体内的内容会在运行子模板之前调用，并可更改本地内容：
280 | 
281 | ```
282 | <t t-call="other-template">
283 |     <t t-set="var" t-value="1"/>
284 | </t>
285 | <!-- "var" does not exist here -->
286 | ```
287 | 
288 | `call` 指令体可任意复杂 (不仅仅是 `set` 指令)，并且其渲染形式将在所调用模板为魔法 `0` 变量之内可用：
289 | 
290 | ```
291 | <div>
292 |     This template was called with content:
293 |     <t t-raw="0"/>
294 | </div>
295 | ```
296 | 
297 | 被调用为：
298 | 
299 | ```
300 | <t t-call="other-template">
301 |     <em>content</em>
302 | </t>
303 | ```
304 | 
305 | 会产生结果：
306 | 
307 | ```
308 | <div>
309 |     This template was called with content:
310 |     <em>content</em>
311 | </div>
312 | ```
313 | 
314 | ## Python
315 | 
316 | ### 独家指令
317 | 
318 | #### 资源包
319 | 
320 | #### “智能记录”字段模式化
321 | 
322 | `t-field` 指令仅在对“智能”记录（`browse`方法的结果）执行字段访问(`a.b`) 时才可使用。它可以自动根据字段类型格式化，并且在网站的富文本版本中集成。
323 | 
324 | `t-options` 可用于自定义字段，最常见的选项是 `widget`，其它选项独立于字段或组件。
325 | 
326 | ### 调试
327 | 
328 | - `t-debug`
329 | 
330 |   使用PDB的`set_trace` API调用调试器。参数应为模块名，对其调用`set_trace` 方法：`<t t-debug="pdb"/>`等价于 `importlib.import_module("pdb").set_trace()`
331 | 
332 | ### 帮助函数
333 | 
334 | #### 基于请求
335 | 
336 | QWeb的大部分Python端使用在控制器（HTTP请求时）中进行，其中存储在数据库中的模板 (作为 [视图](https://alanhou.org/odoo-13-views/#reference-views-qweb)) 可通过调用 [`odoo.http.HttpRequest.render()`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.HttpRequest.render)来进行渲染：
337 | 
338 | ```
339 | response = http.request.render('my-template', {
340 |     'context_value': 42
341 | })
342 | ```
343 | 
344 | 这会自动创建一个[`Response`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.Response) 对象，它可在控制器中返回(或进行一步自定义在适配)。
345 | 
346 | #### 基于视图
347 | 
348 | 比上述帮助函数更深层次的是`ir.ui.view`中的`render`方法：
349 | 
350 | ###### `render(*cr, uid, id[, values][, engine='ir.qweb][, context]*)`
351 | 
352 | 通过数据库 id 或[外部id](https://www.odoo.com/documentation/13.0/glossary.html#term-external-id)渲染QWeb 视图/模板。模板会自动从`ir.ui.view` 记录中进行加载。
353 | 
354 | 在渲染上下文中设置了很多地默认值：
355 | 
356 | - `request`
357 | 
358 |   若存在，为当前 [`WebRequest`](https://alanhou.org/odoo-13-web-controllers/#odoo.http.WebRequest) 对象
359 | 
360 | - `debug`
361 | 
362 |   当前请求（若有）是否为 `debug` 模式
363 | 
364 | - [`quote_plus`](https://werkzeug.palletsprojects.com/en/0.16.x/urls/#werkzeug.urls.url_quote_plus)
365 | 
366 |   url编码工具函数
367 | 
368 | - [`json`](https://docs.python.org/3/library/json.html#module-json)
369 | 
370 |   相应的标准库模块
371 | 
372 | - [`time`](https://docs.python.org/3/library/time.html#module-time)
373 | 
374 |   相应的标准库模块
375 | 
376 | - [`datetime`](https://docs.python.org/3/library/datetime.html#module-datetime)
377 | 
378 |   相应的标准库模块
379 | 
380 | - [relativedelta](https://labix.org/python-dateutil#head-ba5ffd4df8111d1b83fc194b97ebecf837add454)
381 | 
382 |   参见模块
383 | 
384 | - `keep_query`
385 | 
386 |   `keep_query` 帮助函数
387 | 
388 | 参数
389 | 
390 | - **values** – 传递给QWeb供渲染的上下文值
391 | - **engine** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – 用于渲染的Odoo模型名称，可用于扩展或在本地自定义 QWeb (基于 `ir.qweb` 的修改创建“新”qweb)
392 | 
393 | ## Javascript
394 | 
395 | ### 独家指令
396 | 
397 | #### 定义模板
398 | 
399 | `t-name` 指令仅可放在模板文件（文档根目标的直接后代）的顶层：
400 | 
401 | ```
402 | <templates>
403 |     <t t-name="template-name">
404 |         <!-- template code -->
405 |     </t>
406 | </templates>
407 | ```
408 | 
409 | 它不接收其它参数，便可与`<t>`元素或任意其它元素共同使用。 通过 `<t>` 元素时， `<t>` 应包含一个子元素。
410 | 
411 | 模板名是一个任意字符串，虽然关联了多个模板 (e.g. 调用了子模板)，可自定义使用点击分隔名称来表明层级关系。
412 | 
413 | #### 模板继承
414 | 
415 | 模板继承用于在原处更改已有模板，e.g. 向由其它模块创建的模板添加信息。
416 | 
417 | 模板继承通过`t-extend` 指令执行，它接收模板名称来修改为参数。
418 | 
419 | 在 `t-extend` 与 `t-name` 进行合并时，会创建带有给定名称的新模板。在这种情况下所扩展的模板未进行修改，而是由指令定义了如何新建模板。
420 | 
421 | 在这两种情况下修改由任意数量的 `t-jquery` 子指令执行：
422 | 
423 | ```
424 | <t t-extend="base.template">
425 |     <t t-jquery="ul" t-operation="append">
426 |         <li>new element</li>
427 |     </t>
428 | </t>
429 | ```
430 | 
431 | `t-jquery`指令接收一个 [CSS选择器](https://api.jquery.com/category/selectors/)。该选择器用于所继承的模板来选择*上下文节点*来应用所指定的 `t-operation` ：
432 | 
433 | - `append`
434 | 
435 |   节点的内容体添加到上下文节点的结束处 (在上下文节点最一个子元素之后)
436 | 
437 | - `prepend`
438 | 
439 |   节点的内容体前置到上下文节点 (在上下文节点的第一个子元素之前插入)
440 | 
441 | - `before`
442 | 
443 |   节点的内容体插入到上下文节点为之前
444 | 
445 | - `after`
446 | 
447 |   节点的内容体插入到上下文节点为之后
448 | 
449 | - `inner`
450 | 
451 |   节点的内容体替换上下文节点的子元素
452 | 
453 | - `replace`
454 | 
455 |   节点的内容体用于替换上下文节点本身
456 | 
457 | - `attributes`
458 | 
459 |   节点的内容体可为任意数量的`attribute` 元素，每个都带有`name` 属性和一些文本内容，上下文节点的命令属性将设置为指定值(如已存在则替换否则进行添加)
460 | 
461 | - No operation
462 | 
463 |   如未指定`t-operation` ，模板体会解析为 javascript代码并以 `this`通过上下文节点执行⚠️警告虽然比其它操作强大得多，但这一模式更难调试、更难维护，推荐避免使用它。
464 | 
465 | ### 调试
466 | 
467 | javascript QWeb实现提供了一些调试钩子：
468 | 
469 | - `t-log`
470 | 
471 |   接收表达式参数，在渲染期间运行表达式并通过`console.log`在结果中进行记录：`<t t-set="foo" t-value="42"/> <t t-log="foo"/>`将在控制台中打印出print `42`
472 | 
473 | - `t-debug`
474 | 
475 |   在模板渲染时触发调试器断点：`<t t-if="a_test">    <t t-debug=""> </t>`如调试为活跃状态则停止执行 (具体的情况取决于浏览器及其开发工具)
476 | 
477 | - `t-js`
478 | 
479 |   节点内容体为在模板渲染时执行的javascript代码。接收一个 `context` 参数，渲染上下文所使用的名称在 `t-js`的内容体中可以获取到：`<t t-set="foo" t-value="42"/> <t t-js="ctx">    console.log("Foo is", ctx.foo); </t>`
480 | 
481 | ### 帮助对象
482 | 
483 | ###### `core.qweb`
484 | 
485 | (core是 `web.core` 模块) 是加载了所有模块定义的模板的[`QWeb2.Engine()`](#QWeb2.Engine) 实例，并引用标准帮助对象 `_` (下划线), `_t` (翻译函数) 和 [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON).
486 | 
487 | `core.qweb.render` can be used to easily render basic module templates
488 | 
489 | 
490 | 
491 | ### API
492 | 
493 | ###### `*class* QWeb2.Engine()`
494 | 
495 | QWeb “渲染器”，处理大部分QWeb逻辑(加载、解析、编译及渲染模板)。
496 | 
497 | Odoo Web在core模板为用户进行实例化，并将其导出到 `core.qweb`中。它还加载各种模板中的所有模板文件到该QWeb实例中。
498 | 
499 | [`QWeb2.Engine()`](#QWeb2.Engine) 还作为“模板命名空间”提供服务。
500 | 
501 | ###### `QWeb2.Engine.QWeb2.Engine.render(*template*[, *context*])`
502 | 
503 | 渲染此前加载的模板为字符串，使用 `context` (若提供)来查找在模板渲染期间访问的变量(e.g. 要显示的字符串)。
504 | 
505 | 参数
506 | 
507 | - **template** (`String`) – 待渲染的模板名
508 | - **context** (`Object`) – 模板渲染要使用的基本命名空间
509 | 
510 | 返回
511 | 
512 | 字符串
513 | 
514 | 该引擎暴露另一个方法，可在一些用例下使用 (e.g. 如需在Odoo Web,中通过看板视图分离模板命名空间来获取它们自己的[`QWeb2.Engine()`](#QWeb2.Engine) 实例，因此它们的模板不与更通用的“模块”模板相冲突)：
515 | 
516 | ###### `QWeb2.Engine.QWeb2.Engine.add_template(*templates*)`
517 | 
518 | 在QWeb实例中加载一个模板文件 (一个模板集合) 。模板可指定为：
519 | 
520 | - 一个XML字符串
521 | 
522 |   QWeb会尝试解析其为一个XML文档然后加载它。
523 | 
524 | - 一个URL
525 | 
526 |   QWeb会尝试下载 URL内容，然后加载结果XML字符串。
527 | 
528 | - 一个`Document` 或 `Node`
529 | 
530 |   QWeb会遍历文档的第一级 (所提供根的子节点)并加载任意命名模板或模板重载。
531 | 
532 |  
533 | 
534 | [`QWeb2.Engine()`](#QWeb2.Engine) 还针对自定义行为暴露不同的属性：
535 | 
536 | ###### `QWeb2.Engine.QWeb2.Engine.prefix`
537 | 
538 | 用于在解析期间识别指令的前缀。一个字符串。默认为 `t`。
539 | 
540 | ###### `QWeb2.Engine.QWeb2.Engine.debug`
541 | 
542 | 将引擎置为“调试模式”的布尔标记。通常，QWeb拦截在模板执行期间抛出的任意错误。在调试模式下，它让所有的异常通过不进行拦截。
543 | 
544 | ###### `QWeb2.Engine.QWeb2.Engine.jQuery`
545 | 
546 | 这个 jQuery实例在模板继承处理过程中进行使用。默认为`window.jQuery`。
547 | 
548 | ###### `QWeb2.Engine.QWeb2.Engine.preprocess_node`
549 | 
550 | 一个`函数`。如存在，在编译每个DOM 节点到模板节点之前进行调用。在 Web中，它用于在模板中自动转译文本内容和一些属性。默认为 `null`。
551 | 
552 | [[1\]](#id2) 类似于[Genshi](https://genshi.edgewall.org/)之中的， 但它不使用 (且不支持) [XML命名空间](https://en.wikipedia.org/wiki/XML_namespace)
553 | 
554 | [[2\]](#id1) 但出于历史原因或因适合用例还保留一些其它模板。 Odoo 9.0仍依赖于 [Jinja](http://jinja.pocoo.org/) 和 [Mako](https://www.makotemplates.org/)。


--------------------------------------------------------------------------------
/reference/javascript-cheatsheet.md:
--------------------------------------------------------------------------------
  1 | # Javascript速查
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](https://alanhou.org/odoo-13-developer-documentation/)系列文章
  4 | 
  5 | 在JavaScript和Odoo中有很多种解决问题的方式。但 Odoo框架的设计是具有可扩展性的 (这一个巨大的约束)，而很多常见的问题有漂亮标准方案。标准方案可能具有易于 Odoo 开发者理解的优势，在 Odoo 修改时可保持继续有效。本文档尝试讲解我们可以解决这些问题的方式。注意这不一个手册。只是一个随机集合，或讲解了如何在某些情况下进行处理。首先，记住通过JS自定义odoo的第一条规则是：*尽量在python中解决*。 这看起来很奇怪，但这个python框架极具扩展性，很多行为只需通过对xml或python.进行少量修改即可实现。 这通常会比操作 JS 的维护成本更低：
  6 | 
  7 | *   JS框架会倾向于修改是多内容，因此 JS代码需要进行更频繁的更新
  8 | *   如需与服务端通讯并适当集成javascript 框架实现自定义行为经常会更为复杂。有很多由框架处理的小细节的自定义代码也需要重复编写。例如，响应式、更新 URL 或无闪烁显示数据。
  9 | 
 10 | 本文档并没有真的讲解任何概念。更多的是一个速查小指南。更多详情，请参见javascript手册页面 (见[Javascript手册](https://alanhou.org/odoo-13-javascript-reference/))
 11 | 
 12 | ## 新建字段组件
 13 | 
 14 | 这可能是很常见的用例：我们希望在表单视图中以非常具体的（可能取决于业务）方式显示一些信息。 例如，假定我们希望根据一些业务条件来修改文本的颜色。
 15 | 
 16 | 这可通过三个步骤来实现：新建一个组件、在字段仓库中注册它，然后在表单视图中添加组件到该字段中
 17 | 
 18 | *   新建组件：
 19 | 
 20 |     可通过继承组件来实现：
 21 | 
 22 | ```
 23 | var FieldChar = require('web.basic_fields').FieldChar;
 24 | 
 25 |     var CustomFieldChar = FieldChar.extend({
 26 |         _renderReadonly: function () {
 27 |             // 在此处实现一些自定义逻辑
 28 |         },
 29 |     });
 30 | ```
 31 | 
 32 | *   在字段仓库中注册它：
 33 | 
 34 |     网页客户端需要知道组件名称和其实际类之间的映射。这通过仓库完成：
 35 | ```
 36 |  var fieldRegistry = require('web.field_registry');
 37 | 
 38 |     fieldRegistry.add('my-custom-field', CustomFieldChar);
 39 | ```
 40 | 
 41 | *   向表单视图添加该组件：
 42 | ```
 43 | <field name="somefield" widget="my-custom-field"/>
 44 | ```
 45 | 
 46 |     注意只有表单、列表和看板视图使用这种字段组件仓库。这些视图紧密集成，因为列表和看板视图可以在表单视图中出现。
 47 | 
 48 |    
 49 | 
 50 | ## 修改已有字段组件
 51 | 
 52 | 另一种用例是我们希望修改已有字段组件。例如，odoo中的voip插件需要修改FieldPhone组件来添加对voip易于调用给定号码的可能性。这通过*包含*FieldPhone组件来实现，因此无需修改已有表单视图。
 53 | 
 54 | 字段组件 (AbstractField的实例(子类 ))像每个其它组件一样，因此它们可以打[猴子补丁](# "Monkey Patch猴子补丁的含义是指在动态语言中，不去改变源码而对功能进行追加和变更。")。类似下面这样：
 55 | 
 56 | ```
 57 | var basic_fields = require('web.basic_fields');
 58 | var Phone = basic_fields.FieldPhone;
 59 | 
 60 | Phone.include({
 61 |     events: _.extend({}, Phone.prototype.events, {
 62 |         'click': '_onClick',
 63 |     }),
 64 | 
 65 |     _onClick: function (e) {
 66 |         if (this.mode === 'readonly') {
 67 |             e.preventDefault();
 68 |             var phoneNumber = this.value;
 69 |             // 对voip调用电话号码...
 70 |         }
 71 |     },
 72 | });
 73 | ```
 74 | 
 75 | 注意这里无需添加组件到仓库中，因其已进行了注册。
 76 | 
 77 | ## 从界面修改主组件
 78 | 
 79 | 另一个常见用例是需要通过用户界面自定义一些元素。例如，在 home 菜单中添加消息。这种情况下的常用处理还是*包含*组件。这是实现它的唯一方式，因为对这些组件没有仓库。
 80 | 
 81 | 通常通过下面这样的代码实现：
 82 | 
 83 | ```
 84 | var HomeMenu = require('web_enterprise.HomeMenu');
 85 | 
 86 | HomeMenu.include({
 87 |     render: function () {
 88 |         this._super();
 89 |         // do something else here...
 90 |     },
 91 | });
 92 | ```
 93 | 
 94 | ## （全新）新建视图
 95 | 
 96 | 新建视图是一个更高级的话题。这篇速查仅能重点介绍一些很可能会做的步骤 (排序无先后):
 97 | 
 98 | *   在`ir.ui.view`的`type`字段中新增一种视图类型：
 99 | ```
100 | class View(models.Model):
101 |         _inherit = 'ir.ui.view'
102 | 
103 |         type = fields.Selection(selection_add=[('map', "Map")])
104 | ```
105 | 
106 | *   在`ir.actions.act_window.view`的`view_mode`字段中新建视图类型：
107 | ```
108 | class ActWindowView(models.Model):
109 |         _inherit = 'ir.actions.act_window.view'
110 | 
111 |         view_mode = fields.Selection(selection_add=[('map', "Map")])
112 | ```
113 | 
114 | * (在JavaScript中)创建4个组成视图的主要部分：
115 | 
116 |     我们需要一个视图(`AbstractView`的子类，这是工厂类)，一个渲染器(来自 `AbstractRenderer`)，一个控制器 (来看`AbstractController`) 以及一个模型 (来自 `AbstractModel`)。我推荐通过简单继承超类来开始：
117 | 
118 |  ```
119 | var AbstractController = require('web.AbstractController');
120 |     var AbstractModel = require('web.AbstractModel');
121 |     var AbstractRenderer = require('web.AbstractRenderer');
122 |     var AbstractView = require('web.AbstractView');
123 | 
124 |     var MapController = AbstractController.extend({});
125 |     var MapRenderer = AbstractRenderer.extend({});
126 |     var MapModel = AbstractModel.extend({});
127 | 
128 |     var MapView = AbstractView.extend({
129 |         config: {
130 |             Model: MapModel,
131 |             Controller: MapController,
132 |             Renderer: MapRenderer,
133 |         },
134 |     });
135 |  ```
136 | 
137 | *  在仓库中添加视图：
138 | 
139 |     和平常一样，视图类型和实际类之间的映射需要进行更新：
140 | 
141 | ```
142 | var viewRegistry = require('web.view_registry');
143 | 
144 |     viewRegistry.add('map', MapView);
145 | ```
146 | 
147 | 
148 | *   实现4个主要类：
149 | 
150 | `View`类需要解析 `arch`字段并设置其它3个类。 `Renderer` 负责在用户界面中展示数据， `Model` 用于和服务端对话、加载数据并处理数据。`Controller` 用于协调、与网页客户端对话, …
151 | 
152 | *   在数据库中创建一些视图：
153 | 
154 | 
155 | ```
156 | <record id="customer_map_view" model="ir.ui.view">
157 |         <field name="name">customer.map.view</field>
158 |         <field name="model">res.partner</field>
159 |         <field name="arch" type="xml">
160 |             <map latitude="partner_latitude" longitude="partner_longitude">
161 |                 <field name="name"/>
162 |             </map>
163 |         </field>
164 |     </record>
165 | ```
166 | 
167 | ## 自定义已有视图
168 | 
169 | 假定我们需要创建一个通用视图的自定义版本。例如，在上方面带有一些额外类似*ribbon*的看板视图（来显示一些具体自定义信息）。在这种情况下，它可通过3个步骤来实现：继承看板视图(可能还表示继承 控制器/渲染器及/或模型)，然后在视图仓库中注册视图，并且最终在看板框架中使用视图 (具体的示例是helpdesk仪表盘)。
170 | 
171 | *   继承视图：
172 | 
173 |     以下是其可能会有的样子：
174 | 
175 | ```
176 | var HelpdeskDashboardRenderer = KanbanRenderer.extend({
177 |         ...
178 |     });
179 | 
180 |     var HelpdeskDashboardModel = KanbanModel.extend({
181 |         ...
182 |     });
183 | 
184 |     var HelpdeskDashboardController = KanbanController.extend({
185 |         ...
186 |     });
187 | 
188 |     var HelpdeskDashboardView = KanbanView.extend({
189 |         config: _.extend({}, KanbanView.prototype.config, {
190 |             Model: HelpdeskDashboardModel,
191 |             Renderer: HelpdeskDashboardRenderer,
192 |             Controller: HelpdeskDashboardController,
193 |         }),
194 |     });
195 | ```
196 | 
197 | 
198 | *  将其添加到视图仓库中：
199 | 
200 |     和平常一样，我们需要告知网页客户端视图名称和实际类之间的映射。
201 | 
202 | ```
203 | var viewRegistry = require('web.view_registry');
204 |     viewRegistry.add('helpdesk_dashboard', HelpdeskDashboardView);
205 | ```
206 | 
207 | 
208 | *   在实际视图中使用它：
209 | 
210 |     现在我们需要告知网页客户端指定的 `ir.ui.view`需要使用我们的新类。注意这是一个网页客户端的具体考虑。从服务端的视角来看，我们还是对应看板视图。这么做的相应方式是通过对框架的根节点使用特殊属性`js_class`(某一天会被重命名为 `widget`，因为这个名称不够好) ：
211 | 
212 |  ```
213 | <record id="helpdesk_team_view_kanban" model="ir.ui.view" >
214 |         ...
215 |         <field name="arch" type="xml">
216 |             <kanban js_class="helpdesk_dashboard">
217 |                 ...
218 |             </kanban>
219 |         </field>
220 |     </record>
221 |  ```
222 | 
223 | 注意： 可以改变视图解析框架结构的方式。但从服务端的视角，这还是同一个基类型的视图，受制于相同的规则 (例如rng验证)。因此你的视图仍需具有有效的arch字段。
224 | 
225 | ## Promise和异步代码
226 | 
227 | 有关promise的良好和完整介绍，请参阅这篇优质文章 [https://github.com/getify/You-Dont-Know-JS/blob/1st-ed/async%20%26%20performance/ch3.md](https://github.com/getify/You-Dont-Know-JS/blob/1st-ed/async%20%26%20performance/ch3.md)
228 | 
229 | ### 新建Promise
230 | 
231 | *   将常量转换 promise
232 | 
233 |     Promise有两个静态函数根据常量分别创建已完成（resolved）和已失败（rejected）的promise：
234 | 
235 | ```
236 | var p = Promise.resolve({blabla: '1'}); // 创建一个已完成的promise
237 |     p.then(function (result) {
238 |         console.log(result); // --> {blabla: '1'};
239 |     });
240 | 
241 |     var p2 = Promise.reject({error: 'error message'}); // 创建一个已失败的promise
242 |     p2.catch(function (reason) {
243 |         console.log(reason); // --> {error: 'error message');
244 |     });
245 | ```
246 | 
247 | 注意即使promise的创建已经成功或是失败，`then` 或 `catch` 处理器还是会被异步地调用。
248 | 
249 | *  基于已有的异步代码
250 | 
251 | 假设在函数你必须执行rpc，在已对this完成设置结果时。`this._rpc` 是一个返回`Promise`的函数。
252 | 
253 | ```
254 | function callRpc() {
255 |         var self = this;
256 |         return this._rpc(...).then(function (result) {
257 |             self.myValueFromRpc = result;
258 |         });
259 |     }
260 | ```
261 | 
262 | *   对于基于回调的函数
263 | 
264 |     假定你在使用一个接收在完成时调用的回调作为参数的 `this.close` 函数。再假设你在一个方法中执行它且该方法必须在关闭完成时返回一个promise。
265 | 
266 | ```
267 | function waitForClose() {
268 |         var self = this;
269 |         return new Promise (function(resolve, reject) {
270 |             self.close(resolve);
271 |         });
272 |     }
273 | ```
274 |     *   第2行: 我们将 `this` 保存到一个变量中，这样在内部函数中，我们可以访问该作用域来作为组件。
275 |     *   第3行: 我们创建并返回了一个新的promise。promise的构造函数接收一个函数作为参数。该函数本身有两个函数，这里我们称之为 `resolve` 和 `reject`
276 |     
277 |         *   `resolve` 是一个在调用时将promise置为resolved状态的函数。
278 |         *   `reject` 是一个在调用时将promise置为rejected状态的函数。这里我们不使用reject，可以将其省略。
279 |     
280 |     *   第4行: 我们调用关闭对象的函数。它接收一个函数作为参数（回调）并在resolve已是一个函数时发生，因此可以直接进行传递。进一步说明，我们可以这样写：
281 | 
282 | ```
283 | return new Promise (function (resolve) {
284 |         self.close(function () {
285 |             resolve();
286 |         });
287 |     });
288 | ```
289 | 
290 | *   创建一个 promise生成器 (按序分别调用不同的promise并等待最一个promise)
291 | 
292 |     假定你需要对数组进行循环，按顺序执行操作并在最后一个操作完成时返回一个 promise。
293 | 
294 | ```
295 | function doStuffOnArray(arr) {
296 |         var done = Promise.resolve();
297 |         arr.forEach(function (item) {
298 |             done = done.then(function () {
299 |                 return item.doSomethingAsynchronous();
300 |             });
301 |         });
302 |         return done;
303 |     }
304 | ```
305 | 
306 |     通过这种方式，我所返回的 promise就是最后那个promise。
307 | 
308 | *   创建一个promise，然后在其定义的作用域外部解析它（反模式）
309 | 
310 |     我们不推荐使用它，但有时很有用。先仔细思考下如下的替代做法…
311 | 
312 | ```
313 | ...
314 |     var resolver, rejecter;
315 |     var prom = new Promise(function (resolve, reject){
316 |         resolver = resolve;
317 |         rejecter = reject;
318 |     });
319 |     ...
320 | 
321 |     resolver("done"); // will resolve the promise prom with the result "done"
322 |     rejecter("error"); // will reject the promise prom with the reason "error"
323 | ```
324 | 
325 | ### 等待Promise
326 | 
327 | *   等待数个Promise
328 | 
329 |     如果你有多个需要等待的promise， 可以将它们转化为单个promise，它将在promise所有使用Promise.all(arrayOfPromises)进行解析时解析。
330 | 
331 | ```
332 | var prom1 = doSomethingThatReturnsAPromise();
333 |     var prom2 = Promise.resolve(true);
334 |     var constant = true;
335 | 
336 |     var all = Promise.all([prom1, prom2, constant]); // all是一个promise
337 |     // 产生一个数组，单个结果对应它们的索引
338 |     // Promise.all()中调用的promise
339 |     all.then(function (results) {
340 |         var prom1Result = results[0];
341 |         var prom2Result = results[1];
342 |         var constantResult = results[2];
343 |     });
344 |     return all;
345 | ```
346 | 
347 | *   等待promise链中的一部分，另一部分不进行等待
348 | 
349 | 
350 |     If you have an asynchronous process that you want to wait to do something, but you also want to return to the caller before that something is done.
351 | 
352 | ```
353 | function returnAsSoonAsAsyncProcessIsDone() {
354 |         var prom = AsyncProcess();
355 |         prom.then(function (resultOfAsyncProcess) {
356 |                 return doSomething();
357 |         });
358 |         /* returns prom which will only wait for AsyncProcess(),
359 |            and when it will be resolved, the result will be the one of AsyncProcess */
360 |         return prom;
361 |     }
362 | ```
363 | 
364 | ### 错误处理
365 | 
366 | *   in general in promises
367 | 
368 |     总体思想是promise在控制流中不应失败，仅在出现错误时失败。在这种情况下，promise应当有多个已完成状态，例如在`then`处理器的状态码及promise链最终的单个 `catch` 处理器。
369 | 
370 | ```
371 | function a() {
372 |         x.y();  // <-- this is an error: x is undefined
373 |         return Promise.resolve(1);
374 |     }
375 |     function b() {
376 |        return Promise.reject(2);
377 |     }
378 | 
379 |     a().catch(console.log);           // 会把错误记录在a中
380 |     a().then(b).catch(console.log);   // 会把错误记录在a中，then不执行
381 |     b().catch(console.log);           // 会记录b失败的原因 (2)
382 |     Promise.resolve(1)
383 |            .then(b)                   // 执行then，它又执行b
384 |            .then(...)                 // 这个then不被执行
385 |            .catch(console.log);       // 会记录b失败的原因 (2)
386 | ```
387 | 
388 | 
389 | *   Odoo中具体情况
390 | 
391 |     在Odoo,中，我们对控制流使用promise的失败状态，类似互拆体和`web.concurrency`中定义的其它并发原语。出于*业务原因*我们还希望执行 catch，但不是在promise或处理器的定义中有代码错误时。因此，我们引入 了`guardedCatch`的概念。它的调用类似 `catch` ，但不在失败的原因为错误时
392 | 
393 | ```
394 | function blabla() {
395 |         if (someCondition) {
396 |             return Promise.reject("someCondition is truthy");
397 |         }
398 |         return Promise.resolve();
399 |     }
400 | 
401 |     // ...
402 | 
403 |     var promise = blabla();
404 |     promise.then(function (result) { console.log("everything went fine"); })
405 |     // 在blabla调用返回一个rejected的promise时调用，但不在其报错时
406 |     promise.guardedCatch(function (reason) { console.log(reason); });
407 | 
408 |     // ...
409 | 
410 |     var anotherPromise =
411 |             blabla().then(function () { console.log("everything went fine"); })
412 |                     // 若blabla返回一个rejected的promise时调用，
413 |                     // 但不在其报错时
414 |                     .guardedCatch(console.log);
415 | ```
416 | 
417 | ```
418 | var promiseWithError = Promise.resolve().then(function () {
419 |         x.y();  // <-- this is an error: x is undefined
420 |     });
421 |     promiseWithError.guardedCatch(function (reason) {console.log(reason);}); // 不会被调用
422 |     promiseWithError.catch(function (reason) {console.log(reason);}); // 会被调用
423 | ```
424 | 
425 | 
426 | ### 测试异步代码
427 | 
428 | *   在测试中使用promises
429 | 
430 |     在测试代码中，我们支持Javascript的最新版本， 包含`async` 和 `await`和这样的原语。 这样 promise 的使用和等待都非常容易。大部分帮助方法还返回 promise (通过标记为`async` 或通过直接返回一个promise）。
431 | 
432 | ```
433 | var testUtils = require('web.test_utils');
434 |     QUnit.test("My test", async function (assert) {
435 |         // 让函数变为异步有两大好处：
436 |         // 1) 它总是返回一个promise，这样你无需定义`var done = assert.async()`
437 |         // 2) 它允许你使用 `await`
438 |         assert.expect(1);
439 | 
440 |         var form = await testUtils.createView({ ... });
441 |         await testUtils.form.clickEdit(form);
442 |         await testUtils.form.click('jquery selector');
443 |         assert.containsOnce('jquery selector');
444 |         form.destroy();
445 |     });
446 | 
447 |     QUnit.test("My test - no async - no done", function (assert) {
448 |         // 这个函数不是异步的，但它返回一个promise。
449 |         // QUnit将等待这个promise完成。 
450 |         assert.expect(1);
451 | 
452 |         return testUtils.createView({ ... }).then(function (form) {
453 |             return testUtils.form.clickEdit(form).then(function () {
454 |                 return testUtils.form.click('jquery selector').then(function () {
455 |                     assert.containsOnce('jquery selector');
456 |                     form.destroy();
457 |                 });
458 |             });
459 |         });
460 |     });
461 | 
462 |     QUnit.test("My test - no async", function (assert) {
463 |         // 这个函数不是异步的且不返回promise。
464 |         // 我们需要使用done函数来向QUnit发出信息表明测试是异步的且会在异步回调中完成
465 |         assert.expect(1);
466 |         var done = assert.async();
467 | 
468 |         testUtils.createView({ ... }).then(function (form) {
469 |             testUtils.form.clickEdit(form).then(function () {
470 |                 testUtils.form.click('jquery selector').then(function () {
471 |                 assert.containsOnce('jquery selector');
472 |                 form.destroy();
473 |                 done();
474 |                 });
475 |             });
476 |         });
477 |     });
478 | ```
479 | 
480 | 可以目测到，更好的形式是使用 `async/await` ，因其更为清晰、编写更简短。


--------------------------------------------------------------------------------
/setting-up/deploying-odoo.md:
--------------------------------------------------------------------------------
  1 | # 部署Odoo
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | 本文档描述在生产或面向因特网的环境下配置Odoo的步骤。它紧承[安装](https://alanhou.org/odoo-13-installing-odoo/)一节，对于不暴露到互联网的开发系统并不是很有必要。
  6 | 
  7 | ### ⚠️警告
  8 | 
  9 | 如果在建立对外服务，确保查看 [安全权限](#security)中的建议！
 10 | 
 11 | 
 12 | 
 13 | ## dbfilter
 14 | 
 15 | Odoo是一套多租户系统：单个 Odoo系统可在多个服务库实际上运行并提供服务。它也是高度可定制的，自定义内容（通过所加载的模块开始）可在“当前数据库”中实现。
 16 | 
 17 | 这对于以公司用户在后台（客户端）登录时并不会成为问题：数据库可在登录时进行选择，并在之后加载自定义内容。
 18 | 
 19 | 但对于未登录的用户（门户、网站）则会形成问题，他们未与数据库进行绑定：Odoo需要知道应当用于加载网页或执行操作的数据库。未使用多租户不会构成问题，这时仅有一个数据库，但如果存在多个数据库时， Odoo需要知道该使用哪个数据库的规则。
 20 | 
 21 | 这也是使用 [`--db-filter`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-db-filter)的目的之一：它指定应如何根据所请求的主机名（域名）来选择数据。其值是一个 [正则表达式](https://docs.python.org/3/library/re.html)，可能包含动态注入的用于访问系统的主机名 (`%h`) 或首个子域名 (`%d`) 。
 22 | 
 23 | 对于在生产环境托管多个数据库的服务器，尤其是那些使用了 `website` 模块的，**必须**要设置dbfilter，否则一些功能将无法正确运行。
 24 | 
 25 | ### 配置样例
 26 | 
 27 | - 显示仅以‘mycompany’名称开头的数据库
 28 | 
 29 | 在 `/etc/odoo.conf` 中设置：
 30 | 
 31 | ```
 32 | [options] 
 33 | dbfilter = ^mycompany.*$
 34 | ```
 35 | 
 36 | - 仅显示匹配 `www`之后首个子域名的数据库：例如如果请求是发送到 `www.mycompany.com` 或 `mycompany.co.uk`而非`www2.mycompany.com` 或 `helpdesk.mycompany.com`的话则会显示“mycompany”数据库
 37 | 
 38 | 在 `/etc/odoo.conf` 中设置：
 39 | 
 40 | ```
 41 | [options] 
 42 | dbfilter = ^%d$
 43 | ```
 44 | 
 45 | 设置适当的 [`--db-filter`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-db-filter) 是确保部署正常的一个重要部分。一旦正确运行且每个主机名仅匹配一个数据库的话，强烈推荐限制对数据库管理器界面的访问，可以使用 `--no-database-list` 启动参数在防止列出数据库，并阻止对数据库管理界面的访问，参见 [权限安全](#security)。
 46 | 
 47 | ## PostgreSQL
 48 | 
 49 | 默认，PostgreSQL仅允许通过UNIX套接字及回环地址（PostgreSQL服务所安装的同一台机器，使用localhost）连接来进行连接。
 50 | 
 51 | 如果Odoo和PostgreSQL在同一台机器上执行的话UNIX套接字是没有问题的，并且也是在未提供主机参数时的默认值，但如果希望Odoo 和 PostgreSQL在不同机器上进行执行 [1](#different-machines)，它就需要通过之一[监听网卡](https://www.postgresql.org/docs/9.6/static/runtime-config-connection.html) [2](#remote-socket)：
 52 | 
 53 | - 仅接受回环连接并在Odoo和PostgreSQL所运行的机器之间[使用一条SSH通道](https://www.postgresql.org/docs/9.6/static/ssh-tunnels.html)，然后配置Odoo来连接通道的另一端
 54 | - 接受来自Odoo所安装的机器的连接，可能是通过ssl (参见 [PostgreSQL连接设置](https://www.postgresql.org/docs/9.6/static/runtime-config-connection.html)了解详情)，然后配置Odoo来在网络上进行连接
 55 | 
 56 | ### 配置样例
 57 | 
 58 | - 允许在localhost上的tcp连接
 59 | - 允许来自网络上192.168.1.x 的tcp连接
 60 | 
 61 | 在`/etc/postgresql/9.5/main/pg_hba.conf` 中设置：
 62 | 
 63 | ```
 64 | # IPv4 local connections:
 65 | host    all             all             127.0.0.1/32            md5
 66 | host    all             all             192.168.1.0/24          md5
 67 | ```
 68 | 
 69 | 在 `/etc/postgresql/9.5/main/postgresql.conf` 中设置：
 70 | 
 71 | ```
 72 | listen_addresses = 'localhost,192.168.1.2'
 73 | port = 5432
 74 | max_connections = 80
 75 | ```
 76 | 
 77 | 
 78 | 
 79 | ### 配置Odoo
 80 | 
 81 | 默认，Odoo在5432端口上通过UNIX套接字连接本地postgres。这对Postgres不在本地部署Postgres或软件不使用默认配置时可以使用[数据库选项](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#reference-cmdline-server-database)进行重置。[安装包安装](https://alanhou.org/odoo-13-installing-odoo/#setup-install-packaged)时会自动新建用户 (`odoo`) 并将其设置为数据库用户。
 82 | 
 83 | - 数据库管理界面由 `admin_passwd` 设置进行保护。这一设置仅能通过配置文件进行设置，并且仅在执行数据库修改前进行检查。可以设置为一个随机生成的值来确保第三方不会使用到这个界面。
 84 | 
 85 | - 所有的数据库操作使用 [数据库选项](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#reference-cmdline-server-database)，包括数据库管理界面。要让数据库管理界面运行，要求 PostgreSQL 用户拥有 `createdb` 权限。
 86 | 
 87 | - 用户总是可以删除他们所拥有的数据库。要让数据库管理界面完成不可使用，PostgreSQL用户需要通过
 88 | 
 89 |   ```
 90 |   no-createdb
 91 |   ```
 92 | 
 93 |   创建数据库，并且该数据库必须要为另一个PostgreSQL 用户所持有。
 94 | 
 95 |   ### ⚠️警告
 96 | 
 97 |   该PostgreSQL用户*必须*不能是超级用户
 98 | 
 99 | #### 配置样例
100 | 
101 | - 连接192.168.1.2上的PostgreSQL服务
102 | - 端口为 5432
103 | - 使用 ‘odoo’ 用户
104 | - 通过‘pwd’ 来作为密码
105 | - 过滤出以‘mycompany’名称开头的数据库
106 | 
107 | 在 `/etc/odoo.conf` 中设置：
108 | 
109 | ```
110 | [options]
111 | admin_passwd = mysupersecretpassword
112 | db_host = 192.168.1.2
113 | db_port = 5432
114 | db_user = odoo
115 | db_password = pwd
116 | dbfilter = ^mycompany.*$
117 | ```
118 | 
119 | 
120 | 
121 | ### Odoo和PostgreSQL之间的SSL
122 | 
123 | 自从Odoo 11.0开始，可以强制在Odoo 和 PostgreSQL之间使用ssl连接，在 Odoo中， db_sslmode控制着ssl安全连接，值有‘disable’, ‘allow’, ‘prefer’, ‘require’, ‘verify-ca’ 或 ‘verify-full’
124 | 
125 | [PostgreSQL 文档](https://www.postgresql.org/docs/current/static/libpq-ssl.html)
126 | 
127 | 
128 | 
129 | ## 内置服务端
130 | 
131 | Odoo包含一个内置的HTTP服务端，可以使用多线程或多进程。
132 | 
133 | 在生产使用中，推荐使用多进程服务端，因其增强了稳定性，让其更好的利用了计算资源并可以更好地进行监控和资源管控。
134 | 
135 | - 多进程通过配置 [`worker进程数据为非0的数字`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-workers)来启用， worker的数量应根据服务器的核数来计算(可能要根据预期有多少个cron任务来为cron的worker预留空间)
136 | - Worker的限定可根据硬件配置来设置，这样才能避免资源耗尽
137 | 
138 | ### ⚠️警告
139 | 
140 | 多进程模式当前在Windows中尚无法使用
141 | 
142 | ### Worker数量计算
143 | 
144 | - 基本准备则 : (#CPU * 2) + 1
145 | - Cron worker需要使用CPU
146 | - 1 worker ~= 6个并发用户
147 | 
148 | ### 内存大小的计算
149 | 
150 | - 我们认为20%的请求是复杂的重度请求，而80%是简单请求
151 | - 重度worker，在对所有的计算字段及SQL请求...都进行了良好设计时， 可能会消耗约1G的内存
152 | - 轻量的worker，在相同的场景下，预计会消耗约150MB 的 RAM
153 | 
154 | 所需RAM = #worker * ( (light_worker_ratio * light_worker_ram_estimation) + (heavy_worker_ratio * heavy_worker_ram_estimation) )
155 | 
156 | ### LiveChat
157 | 
158 | 在多进程中，会自动启动一个独立的LiveChat工作进程并监听[`长轮询端口`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-longpolling-port) 但客户端不会对其进行连接。
159 | 
160 | 而你必须要有一个将以 `/longpolling/` 开头的URL请求重定向到长轮询端口的代理。其它的请求应当代理至[`普通HTTP端口`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-http-port)。
161 | 
162 | 要实现这点，你需要在Odoo之前部署一个反向代理 ，比如Nginx或Apache。这么做时，需要转发更多的http头给Odoo，并在Odoo中激活proxy_mode来让 Odoo读取这些头部信息。
163 | 
164 | ### 配置样例
165 | 
166 | - 4 CPU, 8 线的服务器
167 | - 60个并发用户
168 | - 60 个用户 / 6 = 10 <- 理论上所需的worker数量
169 | - (4 * 2) + 1 = 9 <-理论最大worker数
170 | - 我们将使用8个worker + 1个用于cron。我们还将使用监控系统来测量cpu负载，并检查其是否在 7 和 7.5之间。
171 | - RAM = 9 * ((0.8*150) + (0.2*1024)) ~= 3个针对Odoo的Go RAM
172 | 
173 | `/etc/odoo.conf`中的配置：
174 | 
175 | ```
176 | [options]
177 | limit_memory_hard = 1677721600
178 | limit_memory_soft = 629145600
179 | limit_request = 8192
180 | limit_time_cpu = 600
181 | limit_time_real = 1200
182 | max_cron_threads = 1
183 | workers = 8
184 | ```
185 | 
186 | 
187 | 
188 | ## HTTPS
189 | 
190 | 不论是通过网站/网页客户端还是网页服务来进行访问，Odoo都以明文传输认证信息。这表示Odoo的安全部署必须使用 HTTPS[3 ](#switching)。SSL终端可通过任意SSL终端代理来实现，但要求进行如下设置：
191 | 
192 | - 启用Odoo的[`代理模式`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-proxy-mode)。这应当仅在Odoo位于反向代理之后时启用
193 | - 设置SSL终端代理([Nginx终端示例](https://nginx.com/resources/admin-guide/nginx-ssl-termination/))
194 | - 设置代理本身 ([Nginx代理示例](https://nginx.com/resources/admin-guide/reverse-proxy/))
195 | - 你的SSL终端代理也就自动重定向非安全连接到安全端口上
196 | 
197 | ### ⚠️警告
198 | 
199 | 万一你使用 [POSBox](https://www.odoo.com/page/point-of-sale-hardware#part_2)来配合销售点（POS）模块，则必须对`/pos/web` 路由禁用HTTPS配置，以避免混合内容的错误。
200 | 
201 | ### 配置样例
202 | 
203 | - 重定向http请求到 https
204 | - 重定向请求至odoo
205 | 
206 | 在 `/etc/odoo.conf`中设置：
207 | 
208 | ```
209 | proxy_mode = True
210 | ```
211 | 
212 | 在 `/etc/nginx/sites-enabled/odoo.conf` 中设置：
213 | 
214 | ```
215 | #odoo server
216 | upstream odoo {
217 |  server 127.0.0.1:8069;
218 | }
219 | upstream odoochat {
220 |  server 127.0.0.1:8072;
221 | }
222 | 
223 | # http -> https
224 | server {
225 |    listen 80;
226 |    server_name odoo.mycompany.com;
227 |    rewrite ^(.*) https://$host$1 permanent;
228 | }
229 | 
230 | server {
231 |  listen 443;
232 |  server_name odoo.mycompany.com;
233 |  proxy_read_timeout 720s;
234 |  proxy_connect_timeout 720s;
235 |  proxy_send_timeout 720s;
236 | 
237 |  # Add Headers for odoo proxy mode
238 |  proxy_set_header X-Forwarded-Host $host;
239 |  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
240 |  proxy_set_header X-Forwarded-Proto $scheme;
241 |  proxy_set_header X-Real-IP $remote_addr;
242 | 
243 |  # SSL parameters
244 |  ssl on;
245 |  ssl_certificate /etc/ssl/nginx/server.crt;
246 |  ssl_certificate_key /etc/ssl/nginx/server.key;
247 |  ssl_session_timeout 30m;
248 |  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
249 |  ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
250 |  ssl_prefer_server_ciphers on;
251 | 
252 |  # log
253 |  access_log /var/log/nginx/odoo.access.log;
254 |  error_log /var/log/nginx/odoo.error.log;
255 | 
256 |  # Redirect longpoll requests to odoo longpolling port
257 |  location /longpolling {
258 |  proxy_pass http://odoochat;
259 |  }
260 | 
261 |  # Redirect requests to odoo backend server
262 |  location / {
263 |    proxy_redirect off;
264 |    proxy_pass http://odoo;
265 |  }
266 | 
267 |  # common gzip
268 |  gzip_types text/css text/scss text/plain text/xml application/xml application/json application/javascript;
269 |  gzip on;
270 | }
271 | ```
272 | 
273 | ## 运行 Odoo为WSGI应用
274 | 
275 | 也可以将Odoo挂载为标准的 [WSGI](https://wsgi.readthedocs.org/) 应用。Odoo 通过`odoo-wsgi.example.py`提供了WSGI的基础启动脚本。该脚本应当进行自定义 (可能是将其从配置目录拷贝出来)以在 `odoo.tools.config`中进行正确的配置，而不是通过命令行或配置文件配置。
276 | 
277 | WSGI服务仅向网页客户端、网站及网页服务 API暴露主要的HTTP 端点。因Odoo不再控制worker的创建，它法再设置cron或 livechat工作进程。
278 | 
279 | ### Cron工作进程
280 | 
281 | 要将Odoo部署的cron任务运行为WSGI应用，要求：
282 | 
283 | - 经典的Odoo ( 通过`odoo-bin`运行)
284 | - 连接到cron所要运行的数据库 (通过 [`odoo-bin -d`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-d))
285 | - 不应暴露到网络中。要确保cron运行器不能通过网络访问，可以通过 [`odoo-bin --no-http`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-no-http) 或在配置文件中设置 `http_enable = False` 完全禁用内置HTTP服务
286 | 
287 | ### LiveChat
288 | 
289 | 第二个 WSGI部署会存在问题的子系统是LiveChat：这里大部分 HTTP连接是相对较短的，并且为下一个请求快速清理worker进程， LiveChat要求对每个客户端的长连接以实现接近补时的通知。
290 | 
291 | 这与基于进程的worker模型是相悖的，因为它会绑住 worker进程并阻止新用户访问系统。但时，这些长连接所做的事甚少，大多数时间停在那里等待通知。
292 | 
293 | 在WSGI中支持livechat/通知的方案是：
294 | 
295 | - 部署一个Odoo的线程版本 (代替基于进程的预创建版本)并仅将以 `/longpolling/` 开头的 URL 重定向到Odoo，这是最简单的并且长轮询URL会叠加成cron实例。
296 | - 通过 `odoo-gevent` 部署带事件Odoo并代理以 `/longpolling/`开头的请求至 [`长轮询端口`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-longpolling-port)。
297 | 
298 | ## 静态文件服务
299 | 
300 | 为开发方便，Odoo直接在模块中提供静态文件服务。这在性能方面可能并不算理想，因为静态文件通常会通过静态HTTP服务器来提供服务。
301 | 
302 | Odoo静态文件位于每个模块的 `static/` 文件夹中，因此静态文件可通过将所有请求拦截至 `/*MODULE*/static/*FILE*`来进行服务的提供，并在各个addon路径中查找正确的模块（及文件）。
303 | 
304 | 
305 | 
306 | ## 安全权限
307 | 
308 | 对于入门人员，请记住保证信息系统的安全是一个持之以恒的过程，没有一劳永逸的法门。此时，你的安全状况和环境中最脆弱的链接如出一辙。
309 | 
310 | 因此不要把本部分看作能够防止所有安全问题的终极宝典。它仅是对在安全动作计划中首要需做的事情的总结。其余的自于你的操作系统及发行版的最佳安全实践，这些最佳实践有用户、密码及访问控制管理等。
311 | 
312 | 在部署面向互联网的服务时，应确保考虑如下安全相关的主题：
313 | 
314 | - 保持设置一个复杂的超级管理员admin的密码，并在建立系统伊始就限制对数据库管理页面的访问。参见 [数据库管理器权限](#db-manager-security)。
315 | - 为所有的数据库管理员账户选择独立的登录名及复杂密码。不要使用‘admin’作为登录名。 不要使用这些登录名进行日常运维，仅在控制/管理软件时进行使用。*永远不要*使用默认密码，如admin/admin，即使在测试/上线前数据库中也不要使用。
316 | - **不要**在面向互联网的服务中安装 demo数据。带有演示数据的数据库包含默认登录名和密码，即使在上线前/dev 系统中也可能会用于进入你的系统并产生巨大的麻烦。
317 | - 使用适当的数据库过滤器( [`--db-filter`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-db-filter)) 来根据主机名限制你的数据识图的可见性。参见[dbfilter](#db-filter)。你也可以使用[`-d`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-d) 来提供自己的 (逗号分隔) 列表来用于过滤可用的数据库，而不是让系统获取数据库后台中的所有数据库。
318 | - 一旦配置了 `db_name` 和 `db_filter` 并仅对每个主机名匹配单个数据库，应当设置 `list_db` 配置项为 `False`来防止整个列出所有气数库，并阻止对数据库管理界面的访问(也可使用 [`--no-database-list`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-no-database-list) 命名行选项进行实现)
319 | - 确保PostgreSQL用户 ([`--db_user`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-r)) 不是超级用户，并且数据库为另一个用户所持有。例如，如果你在使用独立非特权的`db_user`时可能会由 `postgres` 超级用户所拥有。参见 [配置Odoo](#setup-deploy-odoo)。
320 | - 通过 GitHub或从 https://www.odoo.com/page/download 及[http://nightly.odoo.com](http://nightly.odoo.com/)下载最新版本定期安装最新构建在保持软件的更新。
321 | - 使用多进程模式配置服务端，做与你的日常使用相匹配的适当限制 (内存y/CPU/超时)。参见 [内置服务器](#builtin-server)。
322 | - 使用有效的 SSL 证书在提供 HTTPS 终端的网页服务端背后台运行Odoo，以防止对纯文本通讯的窃听。SSL证书很便宜，并且还存在很多免费的证书。配置web 代理来限制请求的大小、设置适当的超时，然后启用[`proxy mode`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-proxy-mode) （代理模式）选项。参见 [HTTPS](#https-proxy)。
323 | - 如果需要允许对服务端的远程 SSH访问，确保对**所有**账户而非`root`仅仅设置复杂密码。强烈推荐完全禁止基于密码的验证，而只使用公钥验证。同时考虑限制通过VPN的访问，仅允许防火墙中受信 IP 的访问，可同时运行诸如 `fail2ban` 或相似的暴力破解监测系统。
324 | - 考虑在代理或防火墙上实施相应的频率限制，以防止暴力破解攻击及DoS（拒绝服务）攻击。参见 [防止暴力攻击](#login-brute-force) 获取更多具体的方法。很多网络提供商提供对DDoS（分布式拒绝服务攻击）的自动防护，但这通常是可选的服务，请进行咨询了解更多详情。
325 | - 只有条件允许，请将面向公众的 demo/test/staging 实例放在与生产实际不同的机器上。并应用与生产相同的安全防护。
326 | - 如果托管着多个客户，使用容器或相应的“jail”技术来相互隔离用户数据及文件。
327 | - 设置对数据库和文件存储数据的日常备份，并将它们拷贝到服务端自身无法访问到的远程存储服务器。
328 | 
329 | 
330 | 
331 | ### 防止暴力攻击
332 | 
333 | 对于面向因特网的部署，针对用户密码的暴力破解攻击很常见，这一威胁在 Odoo 服务端也不应忽视。在尝试执行登录时Odoo发送一条日志记录，并报告结果：成功或失败，以及目标登录名和源 IP。
334 | 
335 | 日志记录有如下的形式：
336 | 
337 | 登录失败：
338 | 
339 | ```
340 | 2018-07-05 14:56:31,506 24849 INFO db_name odoo.addons.base.res.res_users: Login failed for db:db_name login:admin from 127.0.0.1
341 | ```
342 | 
343 | 登录成功：
344 | 
345 | ```
346 | 2018-07-05 14:56:31,506 24849 INFO db_name odoo.addons.base.res.res_users: Login successful for db:db_name login:admin from 127.0.0.1
347 | ```
348 | 
349 | 这些日志可轻易地由 `fail2ban`等入侵防护系统进行分析。
350 | 
351 | 例如，如下的 fail2ban过滤器定义应当会匹配一次登录失败：
352 | 
353 | ```
354 | [Definition]
355 | failregex = ^ \d+ INFO \S+ \S+ Login failed for db:\S+ login:\S+ from <HOST>
356 | ignoreregex =
357 | ```
358 | 
359 | 这可用于 jail定义来禁用对 HTTP(S)进行攻击的IP。
360 | 
361 | 以下是在监测到1分钟内有10次登录尝试失败时禁用该 IP 15分钟的示例：
362 | 
363 | ```
364 | [odoo-login]
365 | enabled = true
366 | port = http,https
367 | bantime = 900  ; 15 min ban
368 | maxretry = 10  ; if 10 attempts
369 | findtime = 60  ; within 1 min  /!\ Should be adjusted with the TZ offset
370 | logpath = /var/log/odoo.log  ;  set the actual odoo log path here
371 | ```
372 | 
373 | 
374 | 
375 | ### 数据库管理器权限
376 | 
377 | [ 配置Odoo](#setup-deploy-odoo) 中提到了传递 `admin_passwd` 。
378 | 
379 | 这一设置用于所有的数据库管理界面 (创建、删除、导出或还原数据库)。
380 | 
381 | 如果必须禁止所有的管理界面， 应当设置 `list_db` 配置选项为`False`，以阻止对所有数据库选择及管理界面的访问。
382 | 
383 | ### ⚠️警告
384 | 
385 | 强烈建议禁用面向因特网系统中的数据库管理器。它是用作开发/演示的工作，以方便快速创建及管理数据库。并不是设计用于生产环境中的，可能会向攻击者暴露一些危险的功能。它也不是设计用来处理大量数据库的，并可能会触发内存极限。
386 | 
387 | 在生产系统中，数据库管理操作应保持由系统管理员执行，包括配置新数据库及自动化备份。
388 | 
389 | 确保配置一个适当的`db_name` 参数 (可选项还有`db_filter`)，这样系统可以决定每个请求的目标数据库，否则会因被禁止自己选择数据库而无法访问。
390 | 
391 | 如果管理界面必须仅能由一部分机器访问，使用代理服务器的功能来阻止所有以`/web/database`开头的路由的访问，但（可能）不包含用于显示数据库选择界面的`/web/database/selector` 。
392 | 
393 | 如果数据库管理界面应保持可供访问，`admin_passwd` 设置必须由其 `admin` 默认值进行修改：这个密码在允许进行数据库修改操作前会进行检查。
394 | 
395 | 它应进行安全的存储，并应是随机生成的，例如：
396 | 
397 | ```
398 | $ python3 -c 'import base64, os; print(base64.b64encode(os.urandom(24)))'
399 | ```
400 | 
401 | 这会在成一个32个字符的伪随机可打印字符串。
402 | 
403 | ## 所支持的浏览器
404 | 
405 | Odoo支持多个版本的多种浏览器。在浏览器版本间保持最新并没有什么不同。Odoo在当前浏览器版本中都支持。所支持的浏览器列表如下：
406 | 
407 | - IE11,
408 | - Mozilla Firefox,
409 | - Google Chrome,
410 | - Safari,
411 | - Microsoft Edge
412 | 
413 | [[1\]](#id1) 让多个Odoo软件使用同一个PostgreSQL数据库，或对这两个服务提供更多的计算资源。
414 | 
415 | [[2\]](https://alanhou.org/odoo-13-deploying-odoo/#id2) 技术上存在一个 [socat](http://www.dest-unreach.org/socat/)这样的工具，可用于在网络中代理UNIX套接字，但那多针对仅通过UNIX套接字才能使用的软件
416 | 
417 | [[3\]](#id6) 或通过任何内部包交换的网络进行访问，但那会要求安全交换、对 [ARP攻击](https://en.wikipedia.org/wiki/ARP_spoofing)的保护以及防止使用WiFi。哪怕是通过安全的包交换网络，也推荐使用HTTPS进行部署，可能产生的费用可通过“自签署”证书来降低，并且自控的网络中要比在互联网上的部署更为简单。


--------------------------------------------------------------------------------
/web-services/creating-localization.md:
--------------------------------------------------------------------------------
  1 | # 会计本地化
  2 | 
  3 | 完整文档：[Odoo 13官方文档之开发者文档](../README.md)
  4 | 
  5 | ### ⚠️警告
  6 | 
  7 | 本教程要求已了解有关在Odoo中构建模块的相关知识(参见[构建模块](https://alanhou.org/odoo-13-building-module/) )。
  8 | 
  9 | ## 创建本地化模块
 10 | 
 11 | 在安装 `accounting` 模块时，本地化模块对应公司自动安装的国家代码。如未设置国家代码或未找到本地化模块，默认会安装`l10n_generic_coa` (US) 本地化模块。
 12 | 
 13 | 例如，`l10n_be` 会在公司的国家设置为`Belgium`时进行安装。
 14 | 
 15 | 这一行为通过使用包含如下代码的 *.xml* 文件来进行获取：
 16 | 
 17 | ```
 18 | <function model="account.chart.template" name="try_loading_for_current_company">
 19 |    <value eval="[ref(module.template_xmlid)]"/>
 20 | </function>
 21 | ```
 22 | 
 23 | 其中 `module.template_xmlid` 是相应模板的**完全限定**xmlid 。
 24 | 
 25 | 通常位于 `data` 文件夹下，它必须在 `__manifest__.py` 文件的最后进行加载。
 26 | 
 27 | ### 🚫危险
 28 | 
 29 | 如果不存在该 *.xml* 文件，则不会及时加载正确的会计科目表！
 30 | 
 31 | ## 配置自己会计科目表？
 32 | 
 33 | 首先，在继续之前，我们需要讨论下模板。模板是一条允许自己被复制的记录。这一机制在操作多公司时需要用到。例如，新账户的创建通过 `account.account.template` 模型完成。但是，每个使用这个会计科目表的公司会被链接到一个以 `account.account` 作为模型的复制内容上。因此，该模板不会直接在公司中进行使用。
 34 | 
 35 | 然后，如果需要安装会计科目表，所有依赖于它的模板会创建一个复制并将这个新生成的记录链接到公司用户。它表示所有这种模板必须以相同的方式链接到会计科目表上。要实现这点，每个必须使用 `chart_template_id` 字段引用所需要的会计科目表。出于这个原因，我们需要在创建其模板前定义一个 `account.chart.template` 模型的实例。
 36 | 
 37 | ```
 38 | <record id="..." model="account.chart.template">
 39 |     <!-- [Required] Specify the name to display for this CoA. -->
 40 |     <field name="name">...</field>
 41 | 
 42 |     <!-- [Required] Specify the currency. E.g. "base.USD". -->
 43 |     <field name="currency_id" ref="..."/>
 44 | 
 45 |     <!-- [Required] Specify a prefix of the bank accounts. -->
 46 |     <field name="bank_account_code_prefix">...</field>
 47 | 
 48 |     <!-- [Required] Specify a prefix of the cash accounts. -->
 49 |     <field name="cash_account_code_prefix">...</field>
 50 | 
 51 |     <!-- [Optional] Define a parent chart of accounts that will be installed just before this one. -->
 52 |     <field name="parent_id" ref="..."/>
 53 | 
 54 |     <!-- [Optional] Define the number of digits of account codes. By default, the value is 6. -->
 55 |     <field name="code_digits">...</field>
 56 | 
 57 |     <!-- [Optional] Boolean to show or not this CoA on the list. By default, the CoA is visible.
 58 |      This field is mostly used when this CoA has some children (see parent_id field). -->
 59 |     <field name="visible" eval="..."/>
 60 | 
 61 |     <!-- [Optional] Boolean to enable the Anglo-Saxon accounting. By default, this field is False. -->
 62 |     <field name="use_anglo_saxon" eval="..."/>
 63 | 
 64 |     <!-- [Optional] Boolean to enable the complete set of taxes. By default, this field is True.
 65 |     This boolean helps you to choose if you want to propose to the user to encode the sale and purchase rates or choose from list of taxes.
 66 |     This last choice assumes that the set of tax defined on this template is complete. -->
 67 |     <field name="complete_tax_set" eval="..."/>
 68 | 
 69 |     <!-- [Optional] Specify the spoken languages.
 70 |     /!\ This option is only available if your module depends of l10n_multilang.
 71 |     You must provide the language codes separated by ';', e.g. eval="'en_US;ar_EG;ar_SY'". -->
 72 |     <field name="spoken_languages" eval="..."/>
 73 | </record>
 74 | ```
 75 | 
 76 | 例如，让我们来看一下比利时的会计科目表。
 77 | 
 78 | ```
 79 | <record id="l10nbe_chart_template" model="account.chart.template">
 80 |     <field name="name">Belgian PCMN</field>
 81 |     <field name="currency_id" ref="base.EUR"/>
 82 |     <field name="bank_account_code_prefix">550</field>
 83 |     <field name="cash_account_code_prefix">570</field>
 84 |     <field name="spoken_languages" eval="'nl_BE'"/>
 85 | </record>
 86 | ```
 87 | 
 88 | 既然已创建了会计科目表，我们可以聚焦到模板创建身上了。如前所述，每条记录必须通过 `chart_template_id` 字段引用这条记录。若未引用，则模板会被忽略。下面的部分显示如何创建这些模板的详情。
 89 | 
 90 | ### 向自己的会计科目表新增账户
 91 | 
 92 | 是时候创建我们自己的账户了。它存在于 `account.account.template` 类型的创建记录中。每个 `account.account.template` 可以为每个公司创建一个 `account.account` 。
 93 | 
 94 | ```
 95 | <record id="..." model="account.account.template">
 96 |     <!-- [Required] Specify the name to display for this account. -->
 97 |     <field name="name">...</field>
 98 | 
 99 |     <!-- [Required] Specify a code. -->
100 |     <field name="code">...</field>
101 | 
102 |     <!-- [Required] Specify a type. -->
103 |     <field name="user_type_id">...</field>
104 | 
105 |     <!-- [Required] Set the CoA owning this account. -->
106 |     <field name="chart_template_id" ref="..."/>
107 | 
108 |     <!-- [Optional] Specify a secondary currency for each account.move.line linked to this account. -->
109 |     <field name="currency_id" ref="..."/>
110 | 
111 |     <!-- [Optional] Boolean to allow the user to reconcile entries in this account. True by default. -->
112 |     <field name="reconcile" eval="..."/>
113 | 
114 |     <!-- [Optional] Specify a group for this account. -->
115 |     <field name="group_id" ref="...">
116 | 
117 |     <!-- [Optional] Specify some tags. -->
118 |     <field name="tag_ids" eval="...">
119 | </record>
120 | ```
121 | 
122 | 以上所述的一些字段需要做更进一步的讲解。
123 | 
124 | `user_type_id`字段要求一个类型为`account.account.type`的值。虽然可以在本地化模块中创建一些其它类型，但我们推荐使用[account/data/data_account_type.xml](https://github.com/odoo/odoo/blob/13.0/addons/account/data/data_account_type.xml) 文件中的已有类型。这使用这些通用类型可确保你在本地化模块中创建的报表以外的通用报表可正确运行。
125 | 
126 | ### ⚠️警告
127 | 
128 | 避免使用流动资金 `account.account.type`！确实，银行及现金账户在安装本地化模块时直接创建，然后链接到 `account.journal`。
129 | 
130 | ### ⚠️警告
131 | 
132 | 仅一个 payable/receivable类型账户就够了。
133 | 
134 | 虽然 `tag_ids` 字段为可选，但它是一个很强大的功能。其实它让你可以为账户定义不同的标签并在报表中进行正确的传播。例如，假定你想要创建一个带有多行的财务报告，但又没有方法去查找一个按照 `code` 或 `name`分配账户的规则 。解决方案就是使用标签，每个报表线有一个标签，按照需要进行传播和聚合。
135 | 
136 | 和其它记录相似，标签可通过如下xml 结构进行创建：
137 | 
138 | ```
139 | <record id="..." model="account.account.tag">
140 |     <!-- [Required] Specify the name to display for this tag. -->
141 |     <field name="name">...</field>
142 | 
143 |     <!-- [Optional] Define a scope for this applicability.
144 |     The available keys are 'accounts' and 'taxes' but 'accounts' is the default value. -->
145 |     <field name="applicability">...</field>
146 | </record>
147 | ```
148 | 
149 | 你可能会想到，这个功能也可以用于计税。
150 | 
151 | `l10n_be` 模块中有如下示例：
152 | 
153 | ```
154 | <record id="a4000" model="account.account.template">
155 |     <field name="name">Clients</field>
156 |     <field name="code">4000</field>
157 |     <field name="user_type_id" ref="account.data_account_type_receivable"/>
158 |     <field name="chart_template_id" ref="l10nbe_chart_template"/>
159 | </record>
160 | ```
161 | 
162 | ### ⚠️警告
163 | 
164 | 不要创建过多的账户：200-300个足够了。
165 | 
166 | ### 向自己的会计科目表新增税务
167 | 
168 | 要创建税务记录，只需要按照创建账户相同的流程就好了。唯一的不同是你必须使用 `account.tax.template` 模型。
169 | 
170 | ```
171 | <record id="..." model="account.tax.template">
172 |     <!-- [Required] Specify the name to display for this tax. -->
173 |     <field name="name">...</field>
174 | 
175 |     <!-- [Required] Specify the amount.
176 |     E.g. 7 with fixed amount_type means v + 7 if v is the amount on which the tax is applied.
177 |      If amount_type is 'percent', the tax amount is v * 0.07. -->
178 |     <field name="amount" eval="..."/>
179 | 
180 |     <!-- [Required] Set the CoA owning this tax. -->
181 |     <field name="chart_template_id" ref="..."/>
182 | 
183 |     <!-- [Required/Optional] Define an account if the tax is not a group of taxes. -->
184 |     <field name="account_id" ref="..."/>
185 | 
186 |     <!-- [Required/Optional] Define an refund account if the tax is not a group of taxes. -->
187 |     <field name="refund_account_id" ref="..."/>
188 | 
189 |     <!-- [Optional] Define the tax's type.
190 |     'sale', 'purchase' or 'none' are the allowed values. 'sale' is the default value.
191 |     Note: 'none' means a tax can't be used by itself, however it can still be used in a group. -->
192 |     <field name="type_tax_use">...</field>
193 | 
194 |     <!-- [Optional] Define the type of amount:
195 |     'group' for a group of taxes, 'fixed' for a tax with a fixed amount or 'percent' for a classic percentage of price.
196 |     By default, the type of amount is percentage. -->
197 |     <field name="amount_type" eval="..."/>
198 | 
199 |     <!-- [Optional] Define some children taxes.
200 |     /!\ Should be used only with an amount_type with 'group' set. -->
201 |     <field name="children_tax_ids" eval="..."/>
202 | 
203 |     <!-- [Optional] The sequence field is used to define order in which the tax lines are applied.
204 |     By default, sequence = 1. -->
205 |     <field name="sequence" eval="..."/>
206 | 
207 |     <!-- [Optional] Specify a short text to be displayed on invoices.
208 |     For example, a tax named "15% on Services" can have the following label on invoice "15%". -->
209 |     <field name="description">...</field>
210 | 
211 |     <!-- [Optional] Boolean that indicates if the amount should be considered as included in price. False by default.
212 |     E.g. Suppose v = 132 and a tax amount of 20.
213 |     If price_include = False, the computed amount will be 132 * 0.2 = 26.4.
214 |     If price_include = True, the computed amount will be 132 - (132 / 1.2) = 132 - 110 = 22. -->
215 |     <field name="price_include" eval="..."/>
216 | 
217 |     <!-- [Optional] Boolean to set to include the amount to the base. False by default.
218 |      If True, the subsequent taxes will be computed based on the base tax amount plus the amount of this tax.
219 |      E.g. suppose v = 100, t1, a tax of 10% and another tax t2 with 20%.
220 |      If t1 doesn't affects the base,
221 |      t1 amount = 100 * 0.1 = 10 and t2 amount = 100 * 0.2 = 20.
222 |      If t1 affects the base,
223 |      t1 amount = 100 * 0.1 = 10 and t2 amount = 110 * 0.2 = 22.  -->
224 |     <field name="include_base_amount" eval="..."/>
225 | 
226 |     <!-- [Optional] Boolean false by default.
227 |      If set, the amount computed by this tax will be assigned to the same analytic account as the invoice line (if any). -->
228 |     <field name="analytic" eval="..."/>
229 | 
230 |     <!-- [Optional] Specify some tags.
231 |     These tags must have 'taxes' as applicability.
232 |     See the previous section for more details. -->
233 |     <field name="tag_ids" eval="...">
234 | 
235 |     <!-- [Optional] Define a tax group used to display the sums of taxes in the invoices. -->
236 |     <field name="tax_group_id" ref="..."/>
237 | 
238 |     <!-- [Optional] Define the tax exigibility either based on invoice ('on_invoice' value) or
239 |     either based on payment using the 'on_payment' key.
240 |     The default value is 'on_invoice'. -->
241 |     <field name="tax_exigibility">...</field>
242 | 
243 |     <!-- [Optional] Define a cash basis account in case of tax exigibility 'on_payment'. -->
244 |     <field name="cash_basis_account" red="..."/>
245 | </record>
246 | ```
247 | 
248 | `l10n_pl` 模块中有如下示例：
249 | 
250 | ```
251 | <record id="vp_leas_sale" model="account.tax.template">
252 |     <field name="chart_template_id" ref="pl_chart_template"/>
253 |     <field name="name">VAT - leasing pojazdu(sale)</field>
254 |     <field name="description">VLP</field>
255 |     <field name="amount">1.00</field>
256 |     <field name="sequence" eval="1"/>
257 |     <field name="amount_type">group</field>
258 |     <field name="type_tax_use">sale</field>
259 |     <field name="children_tax_ids" eval="[(6, 0, [ref('vp_leas_sale_1'), ref('vp_leas_sale_2')])]"/>
260 |     <field name="tag_ids" eval="[(6,0,[ref('l10n_pl.tag_pl_21')])]"/>
261 |     <field name="tax_group_id" ref="tax_group_vat_23"/>
262 | </record>
263 | ```
264 | 
265 | ### 在会计科目表中新增账务状况
266 | 
267 | 如需要了解有有关财务状况的更多详情以及其在Odoo中的运行方式，请参见please refer to [如何根据我的客户的状态及本地化调整计税](https://www.odoo.com/documentation/user/online/accounting/others/taxes/application.html)。
268 | 
269 | 要新增财务状况，仅需要使用 `account.fiscal.position.template` 模型：
270 | 
271 | ```
272 | <record id="..." model="account.fiscal.position.template">
273 |     <!-- [Required] Specify the name to display for this fiscal position. -->
274 |     <field name="name">...</field>
275 | 
276 |     <!-- [Required] Set the CoA owning this fiscal position. -->
277 |     <field name="chart_template_id" ref="..."/>
278 | 
279 |     <!-- [Optional] Add some additional notes. -->
280 |     <field name="note">...</field>
281 | </record>
282 | ```
283 | 
284 | ### 向自己的会计科目表添加属性
285 | 
286 | 在生成整个账户时，可以通过添加具体状况中所用的默认账户相对应的属性来重载新生成的会计科目表。必须在账户创建完成后 ，才能将每个账户与会计科目表进行关联。
287 | 
288 | ```
289 | <?xml version="1.0" encoding="utf-8"?>
290 | <odoo>
291 |     <record id="l10n_xx_chart_template" model="account.chart.template">
292 | 
293 |         <!-- Define receivable/payable accounts. -->
294 |         <field name="property_account_receivable_id" ref="..."/>
295 |         <field name="property_account_payable_id" ref="..."/>
296 | 
297 |         <!-- Define categories of expense/income account. -->
298 |         <field name="property_account_expense_categ_id" ref="..."/>
299 |         <field name="property_account_income_categ_id" ref="..."/>
300 | 
301 |         <!-- Define input/output accounts for stock valuation. -->
302 |         <field name="property_stock_account_input_categ_id" ref="..."/>
303 |         <field name="property_stock_account_output_categ_id" ref="..."/>
304 | 
305 |         <!-- Define an account template for stock valuation. -->
306 |         <field name="property_stock_valuation_account_id" ref="..."/>
307 | 
308 |         <!-- Define loss/gain exchange rate accounts. -->
309 |         <field name="expense_currency_exchange_account_id" ref="..."/>
310 |         <field name="income_currency_exchange_account_id" ref="..."/>
311 | 
312 |         <!-- Define a transfer account. -->
313 |         <field name="transfer_account_id" ref="..."/>
314 |     </record>
315 | </odoo>
316 | ```
317 | 
318 | 例如，让我们回归到比利时PCMN（Plan Comptable Minimum Normalisé标准化最低会计计划）。会计科目表以添加一些属性的方式进行重载。
319 | 
320 | ```
321 | <record id="l10nbe_chart_template" model="account.chart.template">
322 |     <field name="property_account_receivable_id" ref="a4000"/>
323 |     <field name="property_account_payable_id" ref="a440"/>
324 |     <field name="property_account_expense_categ_id" ref="a600"/>
325 |     <field name="property_account_income_categ_id" ref="a7010"/>
326 |     <field name="expense_currency_exchange_account_id" ref="a654"/>
327 |     <field name="income_currency_exchange_account_id" ref="a754"/>
328 |     <field name="transfer_account_id" ref="trans"/>
329 | </record>
330 | ```
331 | 
332 | ## 如何新建一个银行操作模型？
333 | 
334 | Odoo中的银行操作模型如何运作? 参见[配置各方的模型](https://www.odoo.com/documentation/user/online/accounting/bank/reconciliation/configure.html)。
335 | 
336 | 从 `V10`开始，在银行对账表组件中新增了一个功能：银行操作模型。这让用户可以通过单次点击预填写一些计账方。`account.reconcile.model.template` 记录的创建非常容易：
337 | 
338 | ```
339 | <record id="..." model="account.reconcile.model.template">
340 |      <!-- [Required] Specify the name to display. -->
341 |      <field name="name">...</field>
342 | 
343 |      <!-- [Required] Set the CoA owning this. -->
344 |      <field name="chart_template_id" ref="..."/>
345 | 
346 |      <!-- [Optional] Set a sequence number defining the order in which it will be displayed.
347 |      By default, the sequence is 10. -->
348 |      <field name="sequence" eval="..."/>
349 | 
350 |      <!-- [Optional] Define an account. -->
351 |      <field name="account_id" ref="..."/>
352 | 
353 |      <!-- [Optional] Define a label to be added to the journal item. -->
354 |      <field name="label">...</field>
355 | 
356 |      <!-- [Optional] Define the type of amount_type, either 'fixed' or 'percentage'.
357 |      The last one is the default value. -->
358 |      <field name="amount_type">...</field>
359 | 
360 |      <!-- [Optional] Define the balance amount on which this model will be applied to (100 by default).
361 |      Fixed amount will count as a debit if it is negative, as a credit if it is positive. -->
362 |      <field name="amount">...</field>
363 | 
364 |      <!-- [Optional] Define eventually a tax. -->
365 |      <field name="tax_id" ref="..."/>
366 | 
367 |      <!-- [Optional] The sames fields are available twice.
368 |      To enable a second journal line, you can set this field to true and
369 |      fill the fields accordingly. -->
370 |      <field name="has_second_line" eval="..."/>
371 |      <field name="second_account_id" ref="..."/>
372 |      <field name="second_label">...</field>
373 |      <field name="second_amount_type">...</field>
374 |      <field name="second_amount">...</field>
375 |      <field name="second_tax_id" ref="..."/>
376 | </record>
377 | ```
378 | 
379 | ## 如何新建一个动态报表？
380 | 
381 | 如果需要对本地添加一些报表，要新建一个名为**l10n_xx_reports**的模块。此外，这模块必须放在 `enterprise` 仓库中，并且必须有两个依赖，一个是将所有内容加到你的本地化模块中，另一个是 `account_reports`，用于设计动态报表 。
382 | 
383 | ```
384 | 'depends': ['l10n_xx', 'account_reports'],
385 | ```
386 | 
387 | 一旦完成，就可以开始创建报表账单了。 文档请参见如下[s幻灯片](https://www.odoo.com/slides/slide/how-to-create-custom-accounting-report-415)。


--------------------------------------------------------------------------------
/web-services/database-upgrade.md:
--------------------------------------------------------------------------------
  1 | # 数据库升级
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | ## 引言
  6 | 
  7 | 本文档讲解有关将Odoo数据库升级为更高版本的API。
  8 | 
  9 | 允许在[https://upgrade.odoo.com](https://upgrade.odoo.com/)无需助还原html表单升级数据库。但数据库会按照表单中所述相同的过程进行处理。
 10 | 
 11 | 所要求的步骤为：
 12 | 
 13 | - [ 创建请求](#upgrade-api-create-method)
 14 | - [上传数据库导出文件](#upgrade-api-upload-method)
 15 | - [运行升级处理](#upgrade-api-process-method)
 16 | - [获取数据库请求的状态](#upgrade-api-status-method)
 17 | - [下载已升级数据库导出文件](#upgrade-api-download-method)
 18 | 
 19 | ## 方法
 20 | 
 21 | 
 22 | 
 23 | ### 创建一个数据库升级请求
 24 | 
 25 | 这个动作通过如下信息创建一个数据库请求：
 26 | 
 27 | - 你的合同备案号
 28 | - 你的邮箱地址
 29 | - 目标版本 （想要升级到的Odoo版本）
 30 | - 请求的目的（测试或生产）
 31 | - 数据库导出文件名（必须但仅用于提供信息）
 32 | - 可选服务端时区 (针对 Odoo 源版本 < 6.1)
 33 | 
 34 | #### `create` 方法
 35 | 
 36 | ###### `https://upgrade.odoo.com/database/v1/create`
 37 | 
 38 | 创建一个数据库升级请求
 39 | 
 40 | 参数
 41 | 
 42 | - **contract** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你的企业合同备案号
 43 | - **email** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你的邮箱地址
 44 | - **target** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你想要升级到的Odoo版本。有效选项： 11.0, 12.0, 13.0
 45 | - **aim** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你升级数据库请求的目的。有效选项： test, production.
 46 | - **filename** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 针对数据库导出文件的信息提示名称
 47 | - **timezone** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (可选) 你的服务器所使用的时区。仅针对源版本< 6.1
 48 | 
 49 | 返回 请求结果
 50 | 
 51 | 返回类型 JSON字典
 52 | 
 53 | *create* 方法返回一个包含如下键的JSON字典：
 54 | 
 55 | 
 56 | 
 57 | ##### `failures`
 58 | 
 59 | 错误列表。
 60 | 
 61 | 一个字典列表，每字典给出一个具体错误的相关信息。每个字典可包含依赖于不同类型错误的不同键，但其中总会包含 `reason` 和 `message` 这两个键：
 62 | 
 63 | - `reason`: 错误类型
 64 | - `message`: 易于阅读的消息
 65 | 
 66 | 一些可能出现的键：
 67 | 
 68 | - `code`: 一个错误码
 69 | - `value`: 一个错误值
 70 | - `expected`: 一个错误值列表
 71 | 
 72 | 参见如下示例：
 73 | 
 74 | - JSON
 75 | 
 76 | ```
 77 | {
 78 |   "failures": [
 79 |     {
 80 |       "expected": [
 81 |         "11.0",
 82 |         "12.0",
 83 |         "13.0",
 84 |       ],
 85 |       "message": "Invalid value \"5.0\"",
 86 |       "reason": "TARGET:INVALID",
 87 |       "value": "5.0"
 88 |     },
 89 |     {
 90 |       "code": "M123456-abcxyz",
 91 |       "message": "Can not find contract M123456-abcxyz",
 92 |       "reason": "CONTRACT:NOT_FOUND"
 93 |     }
 94 |   ]
 95 | }
 96 | ```
 97 | 
 98 | ##### `request`
 99 | 
100 | 如果 *create* 方法执行成功的话，与 *request* 键相关联的键会是包含与创建请求相关的各种信息的字典：
101 | 
102 | 最重要的键有：
103 | 
104 | - `id`: 请求id
105 | - `key`: 这个请求的私钥
106 | 
107 | 这两个值将会由其它方法（upload, process和status）所请求。
108 | 
109 | 其它键会在描述 [status方法](#upgrade-api-status-method)的部分中进行讲解。
110 | 
111 | ##### 示例脚本
112 | 
113 | 这里有两个数据升级请求的示例，使用：
114 | 
115 | - 一个使用Python语言编写，用到了requests库
116 | - 一个使用bash语言编写，用到了 [curl](https://curl.haxx.se/) (使用http传输数据的工具) and [jq](https://stedolan.github.io/jq) (JSON处理器)：
117 | 
118 | - Python 2
119 | 
120 |   ```
121 |   import requests
122 |   
123 |   CREATE_URL = "https://upgrade.odoo.com/database/v1/create"
124 |   CONTRACT = "M123456-abcdef"
125 |   AIM = "test"
126 |   TARGET = "12.0"
127 |   EMAIL = "john.doe@example.com"
128 |   FILENAME = "db_name.dump"
129 |   
130 |   fields = dict([
131 |       ('aim', AIM),
132 |       ('email', EMAIL),
133 |       ('filename', DB_SOURCE),
134 |       ('contract', CONTRACT),
135 |       ('target', TARGET),
136 |   ])
137 |   
138 |   r = requests.get(CREATE_URL, data=fields)
139 |   print(r.text)
140 |   ```
141 | 
142 | - Bash
143 | 
144 |   ```
145 |   CONTRACT=M123456-abcdef
146 |   AIM=test
147 |   TARGET=12.0
148 |   EMAIL=john.doe@example.com
149 |   FILENAME=db_name.dump
150 |   CREATE_URL="https://upgrade.odoo.com/database/v1/create"
151 |   URL_PARAMS="contract=${CONTRACT}&aim=${AIM}&target=${TARGET}&email=${EMAIL}&filename=${FILENAME}"
152 |   curl -sS "${CREATE_URL}?${URL_PARAMS}" > create_result.json
153 |   
154 |   # check for failures
155 |   failures=$(cat create_result.json | jq -r '.failures[]')
156 |   if [ "$failures" != "" ]; then
157 |     echo $failures | jq -r '.'
158 |     exit 1
159 |   fi
160 |   ```
161 | 
162 |    
163 | 
164 | 
165 | 
166 | ### 上传数据库导出文件
167 | 
168 | 有两种上传数据库导出文件的方法：
169 | 
170 | - `upload` 方法使用的是HTTPS协议
171 | - `request_sftp_access` 方法使用的是SFTP协议
172 | 
173 | #### `upload` 方法
174 | 
175 | 这是上传数据库导出文件最简单直接的方式。 它使用 HTTPS协议。
176 | 
177 | ###### `https://upgrade.odoo.com/database/v1/upload`
178 | 
179 | 上传一个数据库导出文件
180 | 
181 | 参数
182 | 
183 | - **key** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你的私钥
184 | - **request** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必填) 你的请求 id
185 | 
186 | 返回 请求结果
187 | 
188 | 返回类型 JSON字典
189 | 
190 | 请求id和私钥通过使用 [create方法](#upgrade-api-create-method)获取
191 | 
192 | 结果是一个包含 `failures`列表的JSON字典，如果一切正常的话它应当为空。
193 | 
194 | - Python 2
195 | 
196 |   ```
197 |   import requests
198 |   
199 |   UPLOAD_URL = "https://upgrade.odoo.com/database/v1/upload"
200 |   DUMPFILE = "/tmp/dump.sql"
201 |   
202 |   fields = dict([
203 |       ('request', '10534'),
204 |       ('key', 'Aw7pItGVKFuZ_FOR3U8VFQ=='),
205 |   ])
206 |   headers = {"Content-Type": "application/octet-stream"}
207 |   
208 |   with open(DUMPFILE, 'rb') as f:
209 |       requests.post(UPLOAD_URL, data=f, params=fields, headers=headers)
210 |   ```
211 | 
212 | - Bash
213 | 
214 |   ```
215 |   UPLOAD_URL="https://upgrade.odoo.com/database/v1/upload"
216 |   DUMPFILE="openchs.70.cdump"
217 |   KEY="Aw7pItGVKFuZ_FOR3U8VFQ=="
218 |   REQUEST_ID="10534"
219 |   URL_PARAMS="key=${KEY}&request=${REQUEST_ID}"
220 |   HEADER="Content-Type: application/octet-stream"
221 |   curl -H $HEADER --data-binary "@${DUMPFILE}" "${UPLOAD_URL}?${URL_PARAMS}"
222 |   ```
223 | 
224 |    
225 | 
226 | 
227 | 
228 | #### `request_sftp_access` 方法
229 | 
230 | 本方法推荐对大的数据库导出文件使用。它使用SFTP协议并支持断点续传。
231 | 
232 | 这将创建一个临时的SFTP服务器，可以对其进行连接并允许你使用SFTP客户端上传数据库导出文件。
233 | 
234 | ###### `https://upgrade.odoo.com/database/v1/request_sftp_access`
235 | 
236 | 创建一个SFTP服务端
237 | 
238 | 参数
239 | 
240 | - **key** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的私钥
241 | - **request** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的请求id
242 | - **ssh_keys** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 包含你想要使用的ssh公钥的文件路径
243 | 
244 | 返回 请求结果
245 | 
246 | 返回类型 JSON字典
247 | 
248 | 请求id和私钥通过使用 [create方法](#upgrade-api-create-method)获取
249 | 
250 | 包含ssh公钥的文件应当类似于标准的 `authorized_keys` 文件。该文件应仅包含公钥、空行或注释 (以 `#` 字符开头的行)
251 | 
252 | 你的数据库升级请求应当会处于 `draft`（草稿）状态。
253 | 
254 | - Python 2
255 | 
256 |   ```
257 |   import requests
258 |   
259 |   UPLOAD_URL = "https://upgrade.odoo.com/database/v1/request_sftp_access"
260 |   SSH_KEY = "$HOME/.ssh/id_rsa.pub"
261 |   SSH_KEY_CONTENT = open(SSH_KEY,'r').read()
262 |   
263 |   fields = dict([
264 |       ('request', '10534'),
265 |       ('key', 'Aw7pItGVKFuZ_FOR3U8VFQ=='),
266 |       ('ssh_keys', SSH_KEY_CONTENT)
267 |   ])
268 |   
269 |   r = requests.post(UPLOAD_URL, params=fields)
270 |   print(r.text)
271 |   ```
272 | 
273 | - Bash
274 | 
275 |   ```
276 |   REQUEST_SFTP_ACCESS_URL="https://upgrade.odoo.com/database/v1/request_sftp_access"
277 |   SSH_KEYS=/path/to/your/authorized_keys
278 |   KEY="Aw7pItGVKFuZ_FOR3U8VFQ=="
279 |   REQUEST_ID="10534"
280 |   URL_PARAMS="key=${KEY}&request=${REQUEST_ID}"
281 |   
282 |   curl -sS "${REQUEST_SFTP_ACCESS_URL}?${URL_PARAMS}" -F ssh_keys=@${SSH_KEYS} > request_sftp_result.json
283 |   
284 |   # check for failures
285 |   failures=$(cat request_sftp_result.json | jq -r '.failures[]')
286 |   if [ "$failures" != "" ]; then
287 |     echo $failures | jq -r '.'
288 |     exit 1
289 |   fi
290 |   ```
291 | 
292 | `request_sftp_access` 方法返回一个包含如下键的 JSON 字典：
293 | 
294 | ##### `failures`
295 | 
296 | 错误列表。参见 [错误](#upgrade-api-json-failure) 部分获取有关在错误时返回的JSON 字典。
297 | 
298 | ##### `request`
299 | 
300 | 如果调用成功，与 *request* 键相关联的值将会是一个包含SFTP 连接参数的字典：
301 | 
302 | - `hostname`: 待连接的主机地址
303 | - `sftp_port`: 待连接的端口
304 | - `sftp_user`: 用于连接的SFTP用户
305 | - `shared_file`: 你需要使用的文件名 (和在[create方法](#upgrade-api-create-method)中创建请求时所使用的 `filename` 值相同。)
306 | - `request_id`: 相关联的升级请求id (仅提供信息，在进行连接时并非必须要有)
307 | - `sample_command`:使用‘sftp’客户端的示例命令
308 | 
309 | 通常应该能够按照原示例命令来进行连接。
310 | 
311 | 你将仅能访问 `shared_file`。其它文件不可访问并且在SFTP服务器的共享环境下你将无法新建文件。
312 | 
313 | ###### 使用‘sftp’客户端
314 | 
315 | 一旦使用SFTP客户端进行了成功连接，你就可以上传数据库导出文件了。这里有一个使用‘sftp’ 客户端的示例会话：
316 | 
317 | ```
318 | $ sftp -P 2200 user_10534@upgrade.odoo.com
319 | Connected to upgrade.odoo.com.
320 | sftp> put /path/to/openchs.70.cdump openchs.70.cdump
321 | Uploading /path/to/openchs.70.cdump to /openchs.70.cdump
322 | sftp> ls -l openchs.70.cdump
323 | -rw-rw-rw-    0 0        0          849920 Aug 30 15:58 openchs.70.cdump
324 | ```
325 | 
326 | 如果你的连接被打断，你可以继续使用`-a` 命令行开关进行文件传输：
327 | 
328 | ```
329 | sftp> put -a /path/to/openchs.70.cdump openchs.70.cdump
330 | Resuming upload of /path/to/openchs.70.cdump to /openchs.70.cdump
331 | ```
332 | 
333 | 如果不想要手动输入命令，而是使用脚本自动化数据库升级，你可以使用一个批处理文件或者使用管道符将命令重定向到‘sftp’：
334 | 
335 | ```
336 | echo "put /path/to/openchs.70.cdump openchs.70.cdump" | sftp -b - -P 2200 user_10534@upgrade.odoo.com
337 | ```
338 | 
339 | `-b` 参数接收一个文件名。如果文件名为 `-`，它会从标准输入中读取命令。
340 | 
341 | 
342 | 
343 | ### 要求处理请求
344 | 
345 | 这个动作要求**升级平台**来处理你的数据库文件。
346 | 
347 | #### `process` 方法
348 | 
349 | ###### `https://upgrade.odoo.com/database/v1/process`
350 | 
351 | 处理数据库文件
352 | 
353 | 参数
354 | 
355 | - **key** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的私钥
356 | - **request** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的请求id
357 | 
358 | 返回 请求结果
359 | 
360 | 返回类型 JSON字典
361 | 
362 | 请求id和私钥通过使用 [create方法](#upgrade-api-create-method)获取
363 | 
364 | 结果是一个包含 `failures`列表的JSON字典，如果一切正常的话它应当为空。
365 | 
366 | - Python 2
367 | 
368 |   ```
369 |   import requests
370 |   
371 |   PROCESS_URL = "https://upgrade.odoo.com/database/v1/process"
372 |   
373 |   fields = dict([
374 |       ('request', '10534'),
375 |       ('key', 'Aw7pItGVKFuZ_FOR3U8VFQ=='),
376 |   ])
377 |   
378 |   r = requests.get(PROCESS_URL, data=fields)
379 |   print(r.text)
380 |   ```
381 | 
382 | - Bash
383 | 
384 |   ```
385 |   PROCESS_URL="https://upgrade.odoo.com/database/v1/process"
386 |   KEY="Aw7pItGVKFuZ_FOR3U8VFQ=="
387 |   REQUEST_ID="10534"
388 |   URL_PARAMS="key=${KEY}&request=${REQUEST_ID}"
389 |   curl -sS "${PROCESS_URL}?${URL_PARAMS}"
390 |   ```
391 | 
392 |    
393 | 
394 | 
395 | 
396 | ### 请求跳过测试
397 | 
398 | 这个动作要求**升级平台**对你的请求跳过测试。如果你不想要Odoo来测试和验证迁移，可以跳过测试步骤、直接获取迁移导出文件。
399 | 
400 | #### `skip_test` 方法
401 | 
402 | ###### `https://upgrade.odoo.com/database/v1/skip_test`
403 | 
404 | 跳过测试，传输已升级导出文件，并设置状态为‘delivered’（已投递）
405 | 
406 | 参数
407 | 
408 | - **key** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的私钥
409 | - **request** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的请求id
410 | 
411 | 返回 请求结果
412 | 
413 | 返回类型 JSON字典
414 | 
415 | 请求id和私钥通过使用 [create方法](#upgrade-api-create-method)获取
416 | 
417 | 结果是一个包含 `failures`列表的JSON字典，它应该在一切正常是为空。
418 | 
419 | - Python 2
420 | 
421 |   ```
422 |   import requests
423 |   
424 |   PROCESS_URL = "https://upgrade.odoo.com/database/v1/skip_test"
425 |   
426 |   fields = dict([
427 |       ('request', '10534'),
428 |       ('key', 'Aw7pItGVKFuZ_FOR3U8VFQ=='),
429 |   ])
430 |   
431 |   r = requests.get(PROCESS_URL, data=fields)
432 |   print(r.text)
433 |   ```
434 | 
435 | - Bash
436 | 
437 |   ```
438 |   PROCESS_URL="https://upgrade.odoo.com/database/v1/skip_test"
439 |   KEY="Aw7pItGVKFuZ_FOR3U8VFQ=="
440 |   REQUEST_ID="10534"
441 |   URL_PARAMS="key=${KEY}&request=${REQUEST_ID}"
442 |   curl -sS "${PROCESS_URL}?${URL_PARAMS}"
443 |   ```
444 | 
445 |    
446 | 
447 | 
448 | 
449 | ### 获取请求状态
450 | 
451 | 这个动作要求获取你的数据库升级请求的状态。
452 | 
453 | #### `status` 方法
454 | 
455 | ###### `https://upgrade.odoo.com/database/v1/status`
456 | 
457 | 获取数据库升级请求的状态
458 | 
459 | 参数
460 | 
461 | - **key** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的私钥
462 | - **request** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – (必传) 你的请求 id
463 | 
464 | 返回 请求结果
465 | 
466 | 返回类型 JSON字典
467 | 
468 | 请求id和私钥通过使用 [create方法](#upgrade-api-create-method)获取
469 | 
470 | 结果是一个包含有关数据库升级请求不同信息的JSON字典。
471 | 
472 | - Python 2
473 | 
474 |   ```
475 |   import requests
476 |   
477 |   PROCESS_URL = "https://upgrade.odoo.com/database/v1/status"
478 |   
479 |   fields = dict([
480 |       ('request', '10534'),
481 |       ('key', 'Aw7pItGVKFuZ_FOR3U8VFQ=='),
482 |   ])
483 |   
484 |   r = requests.get(PROCESS_URL, data=fields)
485 |   print(r.text)
486 |   ```
487 | 
488 | - Bash
489 | 
490 |   ```
491 |   STATUS_URL="https://upgrade.odoo.com/database/v1/status"
492 |   KEY="Aw7pItGVKFuZ_FOR3U8VFQ=="
493 |   REQUEST_ID="10534"
494 |   URL_PARAMS="key=${KEY}&request=${REQUEST_ID}"
495 |   curl -sS "${STATUS_URL}?${URL_PARAMS}"
496 |   ```
497 | 
498 |    
499 | 
500 | #### 示例输出
501 | 
502 | `request` 键包含有关请求的各种有用信息：
503 | 
504 | - `id`
505 | 
506 |   请求id
507 | 
508 | - `key`
509 | 
510 |   你的私钥
511 | 
512 | - `email`
513 | 
514 |   在创建请求时你所提供的email地址
515 | 
516 | - `target`
517 | 
518 |   在创建请求时你所提供的目标Odoo版本
519 | 
520 | - `aim`
521 | 
522 |   在创建请求时你所提供的数据库升级请求的目的（测试，生产）
523 | 
524 | - `filename`
525 | 
526 |   在创建请求时你所提供的文件名
527 | 
528 | - `timezone`
529 | 
530 |   在创建请求时你所提供的时区
531 | 
532 | - `state`
533 | 
534 |   你的请求的状态
535 | 
536 | - `issue_stage`
537 | 
538 |   在Odoo主服务器上我们所创建的事项阶段
539 | 
540 | - `issue`
541 | 
542 |   在Odoo主服务器上我们所创建的事项id
543 | 
544 | - `status_url`
545 | 
546 |   访问你的数据库升级请求html页面的URL
547 | 
548 | - `notes_url`
549 | 
550 |   获取有关数据库升级记录的URL
551 | 
552 | - `original_sql_url`
553 | 
554 |   用于获取你的已上传（非已升级）数据库来作为SQL流的URL
555 | 
556 | - `original_dump_url`
557 | 
558 |   用于获取你的已上传（非已升级）数据库来作为存档文件的URL
559 | 
560 | - `upgraded_sql_url`
561 | 
562 |   用于获取你的已升级数据库来作为SQL流的URL
563 | 
564 | - `upgraded_dump_url`
565 | 
566 |   用于获取你的已上升级数据库来作为存档文件的URL
567 | 
568 | - `modules_url`
569 | 
570 |   用于获取你的自定义模块的URL
571 | 
572 | - `filesize`
573 | 
574 |   你的已上传数据文件的大小
575 | 
576 | - `database_uuid`
577 | 
578 |   你的数据库的唯一ID
579 | 
580 | - `created_at`
581 | 
582 |   你创建请求时的日期
583 | 
584 | - `estimated_time`
585 | 
586 |   升级数据库所花费时间的预估
587 | 
588 | - `processed_at`
589 | 
590 |   数据库升级开启时的时间
591 | 
592 | - `elapsed`
593 | 
594 |   升级数据库所花费的时间
595 | 
596 | - `filestore`
597 | 
598 |   你的附件转化为了文件存储
599 | 
600 | - `customer_message`
601 | 
602 |   有关你的请求的重要消息
603 | 
604 | - `database_version`
605 | 
606 |   猜测的你所上传的（非升级后）Odoo版本。
607 | 
608 | - `postgresql`
609 | 
610 |   猜测的你所上传的（非升级后） PostgreSQL 版本
611 | 
612 | - `compressions`
613 | 
614 |   由你的已上传数据库所使用的压缩方法
615 | 
616 | - JSON
617 | 
618 | ```
619 | {
620 |   "failures": [],
621 |   "request": {
622 |     "id": 10534,
623 |     "key": "Aw7pItGVKFuZ_FOR3U8VFQ==",
624 |     "email": "john.doe@example.com",
625 |     "target": "12.0",
626 |     "aim": "test",
627 |     "filename": "db_name.dump",
628 |     "timezone": null,
629 |     "state": "draft",
630 |     "issue_stage": "new",
631 |     "issue": 648398,
632 |     "status_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/status",
633 |     "notes_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/upgraded/notes",
634 |     "original_sql_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/original/sql",
635 |     "original_dump_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/original/archive",
636 |     "upgraded_sql_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/upgraded/sql",
637 |     "upgraded_dump_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/upgraded/archive",
638 |     "modules_url": "https://upgrade.odoo.com/database/eu1/10534/Aw7pItGVKFuZ_FOR3U8VFQ==/modules/archive",
639 |     "filesize": "912.99 Kb",
640 |     "database_uuid": null,
641 |     "created_at": "2018-09-09 07:13:49",
642 |     "estimated_time": null,
643 |     "processed_at": null,
644 |     "elapsed": "00:00",
645 |     "filestore": false,
646 |     "customer_message": null,
647 |     "database_version": null,
648 |     "postgresql": "9.4",
649 |     "compressions": [
650 |       "pgdmp_custom",
651 |       "sql"
652 |     ]
653 |   }
654 | }
655 | ```
656 | 
657 | 
658 | 
659 | ### 下载数据库导出文件
660 | 
661 | 除使用由[status方法](#upgrade-api-status-method)所提供的URL下载迁移后数据库外，你还可以按照[request_sftp_access 方法](#upgrade-api-request-sftp-access-method)中所述那样使用 SFTP协议
662 | 
663 | 不同之处在于你将仅能下载迁移后的数据库。无法进行上传。
664 | 
665 | 你的数据库升级请求应当处于 `done` 状态。
666 | 
667 | 一旦你成功地使用SFTP 客户端进行了连接，就可以下载数据库导出文件。以下是一个使用‘sftp’ 客户端的示例会话：
668 | 
669 | ```
670 | $ sftp -P 2200 user_10534@upgrade.odoo.com
671 | Connected to upgrade.odoo.com.
672 | sftp> get upgraded_openchs.70.cdump /path/to/upgraded_openchs.70.cdump
673 | Downloading /upgraded_openchs.70.cdump to /path/to/upgraded_openchs.70.cdump
674 | ```


--------------------------------------------------------------------------------
/setting-up/installing-odoo.md:
--------------------------------------------------------------------------------
  1 | # 安装Odoo
  2 | 
  3 | 安装 Odoo 有很多种方式，或者是根本无需进行安装，这取决于你的用例。
  4 | 
  5 | 本文旨在描述大部分的安装选项。
  6 | 
  7 | - [在线使用](#setup-install-online)
  8 | 
  9 |   在生产环境或测试使用Odoo最简便的方式。
 10 | 
 11 | - [安装包](#setup-install-packaged)
 12 | 
 13 |   适于测试Odoo、开发模块及用于通过额外的部署和维护工作来在长期生产环境使用。
 14 | 
 15 | - [源码安装](#setup-install-source)
 16 | 
 17 |   提供更强的灵活性：例如允许在同一个系统中运行多个Odoo版本。有益于开发模块，可用作生产部署的基础。
 18 | 
 19 | - [Docker](https://www.odoo.com/documentation/13.0/setup/install.html#setup-install-docker)
 20 | 
 21 |   如果你经常使用[docker](https://www.docker.com/)来进行开发或部署，可使用获取官方[docker](https://www.docker.com/)基础镜像。
 22 | 
 23 | 
 24 | 
 25 | ## 版本
 26 | 
 27 | Odoo有两种不同的[版本](https://www.odoo.com/pricing#pricing_table_features)：社区版和企业版。使用企业版可以通过[SaaS](https://www.odoo.com/page/start)并获取仅限于企业版客户和合作伙伴的代码。社区版免费向所有人开放。
 28 | 
 29 | 如果你在使用社区版并希望升级到企业版，请参考[社区版升级到企业版](https://www.odoo.com/documentation/13.0/setup/enterprise.html#setup-enterprise) ([源码安装](#setup-install-source)除外)。
 30 | 
 31 | 
 32 | 
 33 | ## 在线使用
 34 | 
 35 | ### Demo
 36 | 
 37 | 要快速了解Odoo, 可使用[demo](https://demo.odoo.com/)实例。这是仅供使用几小时的共享实例，可在不进行安装购买的情况下浏览及测试功能。
 38 | 
 39 | [Demo](https://demo.odoo.com/)实例无需本地安装，仅需通过浏览器访问即可。
 40 | 
 41 | ### SaaS
 42 | 
 43 | 轻松开启, 由Odoo S.A.全权管理及进行迁移，Odoo的 [SaaS](https://www.odoo.com/page/start)(Software as a Service)提供私有实例并可免费开始使用。可用于发现和测试Odoo并进行无本地安装非代码自定义（即与Odoo应用商店中的自定义模块不相兼容）。
 44 | 
 45 | 既可用于测试Odoo，也可供长期生产使用。
 46 | 
 47 | 类似[demo](https://demo.odoo.com/)实例，[SaaS](https://www.odoo.com/page/start)实例无需本地安装，仅通过浏览器即可访问。
 48 | 
 49 | 
 50 | 
 51 | ## 安装包
 52 | 
 53 | Odoo提供针对Windows、基于deb的发行版(Debian, Ubuntu, …)及基于RPM的发行版 (Fedora, CentOS, RHEL, …) 的安装包，包括社区版和企业版。
 54 | 
 55 | 这些安装包自动安装（社区版的）所有依赖，但可能会很难进行最新版的更新。
 56 | 
 57 | 带有所要求相关依赖的官方社区版安装包可通过[nightly](https://nightly.odoo.com/)服务器获取。 社区版和企业版的安装包均可通过[下载](https://www.odoo.com/page/download)页面进行下载（必须要通过付费用户或合作伙伴账户登录才能下载企业版安装包）。
 58 | 
 59 | ### Windows
 60 | 
 61 | -  通过[nightly](https://nightly.odoo.com/)服务器的下载安装包（仅社区版）或通过[下载页面](https://www.odoo.com/page/download)下载Windows 安装包（任意版本）。
 62 | 
 63 | - 运行所下载文件
 64 | 
 65 |   ### 警告
 66 | 
 67 |   在Windows 8中，你可能会看到标题为“Windows protected your PC”的警告。点击更多信息并继续运行。
 68 | 
 69 | - 接受 [UAC](http://en.wikipedia.org/wiki/User_Account_Control) 弹窗
 70 | 
 71 | - 执行各个安装步骤
 72 | 
 73 | Odoo会在安装的最后自动启动。
 74 | 
 75 | ### Linux
 76 | 
 77 | #### Debian/Ubuntu
 78 | 
 79 | Odoo 13.0的deb安装包当前支持[Debian Buster](https://www.debian.org/releases/buster/), [Ubuntu 18.04](http://releases.ubuntu.com/18.04/)及以上版本。
 80 | 
 81 | ##### 准备工作
 82 | 
 83 | Odoo需要有[PostgreSQL](http://www.postgresql.org/)服务才能正常运行。Odoo的deb包默认配置是使用在Odoo实例的相同主机上的PostgreSQL。以 root 用户执行如下命令来安装PostgreSQL服务：
 84 | 
 85 | ```
 86 |  apt-get install postgresql -y
 87 | ```
 88 | 
 89 | 要进行PDF报表的打印，必须要自己安装[wkhtmltopdf](http://wkhtmltopdf.org/)： Debian仓库中的[wkhtmltopdf](http://wkhtmltopdf.org/)版本无法支持页眉和页脚，因此不能直接用作依赖。推荐的版本是 0.12.5，可通过[wkhtmltopdf的下载页面](https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5)的存档版块进行获取。之前推荐的0.12.1版本是一个不错的替代。针对各种版本的更多详情以及各自的特殊情况可通过[wiki](https://github.com/odoo/odoo/wiki/Wkhtmltopdf)页面进行了解。
 90 | 
 91 | ##### 仓库
 92 | 
 93 | Odoo S.A.提供一个可用于Debian和Ubuntu不同发行版的仓库。可通过以 root 执行如下命令来安装Odoo社区版：
 94 | 
 95 | ```
 96 | wget -O - https://nightly.odoo.com/odoo.key | apt-key add -
 97 |  echo "deb http://nightly.odoo.com/13.0/nightly/deb/ ./" >> /etc/apt/sources.list.d/odoo.list
 98 | apt-get update && apt-get install odoo
 99 | ```
100 | 
101 | 然后可以通过常规的 `apt-get upgrade` 命令来保持安装为最新版本。
102 | 
103 | 截至目前，还没有针对企业版的仓库。
104 | 
105 | ##### Deb安装包
106 | 
107 | 作为上述仓库的替代方法，可通过如下方式下载deb安装包：
108 | 
109 | - 社区版: [nightly](https://nightly.odoo.com/)
110 | - 企业版[下载页面](https://www.odoo.com/page/download)
111 | 
112 | 然后可以使用 `gdebi`：
113 | 
114 | ```
115 | gdebi 
116 | ```
117 | 
118 | 或 `dpkg`:
119 | 
120 | ```
121 | dpkg -i  # 这步可能会由于缺少依赖而失败
122 | apt-get install -f # 应该会安装所缺少的依赖
123 | dpkg -i <path_to_installation_package>
124 | ```
125 | 
126 | 这会将Odoo安装为一个服务、创建必要的[PostgreSQL](http://www.postgresql.org/)用户并自动启动服务。
127 | 
128 | ### 警告
129 | 
130 | python3-xlwt Debian包在Debian Buster和Ubuntu 18.04中不存在。这个python模块在导出为 xls 格式时需要用到。
131 | 
132 | 如果需要这一功能，可以手动进行安装。一种方式是简单地通过下面的pip3命令来安装：
133 | 
134 | ```
135 | $ sudo pip3 install xlwt
136 | ```
137 | 
138 | ### 警告
139 | 
140 | Debian 9和Ubuntu中不提供针对python模块num2words的包。文本数量值在Odoo中不会进行渲染，使用l10n_mx_edi模块时会产生问题。
141 | 
142 | 如果你需要这一功能，可以像下面这样安装该 python模块：
143 | 
144 | ```
145 | $ sudo pip3 install num2words
146 | ```
147 | 
148 | #### Fedora
149 | 
150 | Odoo 13.0的rpm包支持Fedora 26。截至2017年，CentOS还没有对Odoo 13.0的所要求最小Python版本（3.5）的支持。
151 | 
152 | **译者注：**CentOS 8中已添加了对 Python 3的默认支持
153 | 
154 | ##### 准备工作
155 | 
156 | Odoo需要有[PostgreSQL](http://www.postgresql.org/)服务来正常运行。这里假设可以使用sudo命令并进行了适当的配置，运行如下命令：
157 | 
158 | ```
159 | $ sudo dnf install -y postgresql-server
160 | $ sudo postgresql-setup --initdb --unit postgresql
161 | $ sudo systemctl enable postgresql
162 | $ sudo systemctl start postgresql
163 | ```
164 | 
165 | 要进行PDF报表的打印，必须要自己安装[wkhtmltopdf](http://wkhtmltopdf.org/)： Debian仓库中的[wkhtmltopdf](http://wkhtmltopdf.org/)版本无法支持页眉和页脚，因此不能直接用作依赖。推荐的版本是 0.12.5，可通过[wkhtmltopdf的下载页面](https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5)的存档版块进行获取。之前推荐的0.12.1版本是一个不错的替代。针对各种版本的更多详情以及各自的特殊情况可通过[wiki](https://github.com/odoo/odoo/wiki/Wkhtmltopdf)页面进行了解。
166 | 
167 | ##### 仓库
168 | 
169 | Odoo S.A.提供一个可用于Fedora发行版的仓库。可通过执行如下命令来安装Odoo社区版：
170 | 
171 | ```
172 | $ sudo dnf config-manager --add-repo = https://nightly.odoo.com/13.0/nightly/rpm/odoo.repo
173 | $ sudo dnf install -y odoo
174 | $ sudo systemctl enable odoo
175 | $ sudo systemctl start odoo
176 | ```
177 | 
178 | ##### RPM包
179 | 
180 | 代替使用以上所描述的仓库，可通过下面下载‘rpm’ 包：
181 | 
182 | - 社区版： [nightly](https://nightly.odoo.com/)
183 | - 企业版 [下载](https://www.odoo.com/page/download)
184 | 
185 | 下载后，包通过使用‘dnf’包管理器来进行安装：
186 | 
187 | ```
188 | $ sudo dnf localinstall odoo_13.0.latest.noarch.rpm
189 | $ sudo systemctl enable odoo
190 | $ sudo systemctl start odoo
191 | ```
192 | 
193 | 
194 | 
195 | ## 源码安装
196 | 
197 | 源码安装并不真的是关乎安装，而是直接通过源码进行运行。
198 | 
199 | 对于模块开发者这会更为方便，因为这样会比使用安装包安装更容易获取Odoo源代码（相关信息或构建这一文件并离线获取）。
200 | 
201 | 这也会让启动和停止Odoo比通过安装包配置的服务更为灵活和显式，同时它允许使用[命令行参数](https://www.odoo.com/documentation/13.0/reference/cmdline.html#reference-cmdline)无需编辑配置文件即重载设置。
202 | 
203 | 最后，它提供对于系统设置更强的控制，并允许在系统中同时轻易地保留（及运行）多个版本的Odoo。
204 | 
205 | ### Windows
206 | 
207 | #### 获取源码
208 | 
209 | 有两种获取Odoo源代码的方式：zip**压缩包**或通过**git。**
210 | 
211 | ##### 压缩包
212 | 
213 | 社区版：
214 | 
215 | - [官方下载页面](https://www.odoo.com/page/download)
216 | - [GitHub仓库](https://github.com/odoo/odoo)
217 | - [Nightly服务器](https://nightly.odoo.com/)
218 | 
219 | 企业版：
220 | 
221 | - [官方下载页面](https://www.odoo.com/page/download)
222 | - [GitHub仓库](https://github.com/odoo/enterprise)
223 | 
224 | ##### Git
225 | 
226 | 以下部分要求在电脑主安装了[git](https://git-scm.com/)，并且你对于 git 命令有基础知识的掌握。
227 | 
228 | 社区版：
229 | 
230 | ```
231 | C:\> git clone https://github.com/odoo/odoo.git
232 | ```
233 | 
234 | 企业版：(参见 [版本](#setup-install-editions)部分进行获取)
235 | 
236 | ```
237 | C:\> git clone https://github.com/odoo/enterprise.git
238 | ```
239 | 
240 | **企业版git仓库并不包含完整的Odoo源代码。**它仅是一个附加插件的集合。主服务端代码在社区版中。运行企业版实际是将addons-path选项设置为企业版的文件夹并运行社区版服务。你需要同时克隆社区版和企业版来得到一个运行中的Odoo企业版安装。
241 | 
242 | #### 准备工作
243 | 
244 | ##### Python
245 | 
246 | Odoo运行要求Python 3.5或更新的版本。使用官方的[Python 3安装包](https://www.python.org/downloads/windows/)来在你的电脑上下载并安装Python 3。
247 | 
248 | 在安装期间，勾选**Add Python 3 to PATH**，然后点击**Customize Installation**并确保勾选了**pip**。
249 | 
250 | 如果已安装了Python 3，确保版本为3.5或以上，因为之前的版本与Odoo不兼容。
251 | 
252 | ```
253 | C:\> python3 --version
254 | ```
255 | 
256 | 同时验证针对该版本是否安装了[pip](https://pip.pypa.io/)。
257 | 
258 | ```
259 | C:\> pip3 --version
260 | ```
261 | 
262 | ##### PostgreSQL
263 | 
264 | Odoo使用PostgreSQL来作为数据库管理系统。下载并安装 [最新版本的 PostgreSQL](https://www.postgresql.org/download/windows/)。
265 | 
266 | 默认唯一的用户是`postgres`，但Odoo禁止通过`postgres`来进行连接，因此你需要新建一个PostgreSQL用户：
267 | 
268 | 1. 在`PATH`中添加PostgreSQL的 `bin` 目录（默认为`C:\Program Files\PostgreSQL\<version>\bin`）。
269 | 2. 使用pg admin 图形化工具创建一个postgres用户并设置密码：
270 |    - 打开**pgAdminIII**.
271 |    - 双击服务端来创建一个连接。
272 |    - 选择Edit ‣ New Object ‣ New Login Role。
273 |    - 在**Role Name**字段中输入用户名（例如`odoo`）。
274 |    - 打开**Definition**标签栏并输入密码（如 `odoo`），然后点击**OK**。
275 | 
276 | **译者注：**目前使用较多的为 pgAdmin 4，在 Login/Group Roles下进行操作
277 | 
278 | ##### 依赖
279 | 
280 | Odoo的依赖在Odoo社区版根目录下的`requirements.txt` 文件中列出了所需的依赖。其中大部分都可以通过**pip**进行安装。
281 | 
282 | 推荐不要将不同Odoo实例间或者与系统的python模块包混放在到一起。可以使用[virtualenv](https://pypi.python.org/pypi/virtualenv)来创建隔离的Python环境。
283 | 
284 | 导航到Odoo社区安装位置的路径 (`YourOdooCommunityPath`) 并对requirements文件运行**pip**命令：
285 | 
286 | ```
287 | C:\> cd \YourOdooCommunityPath
288 | C:\YourOdooCommunityPath> C:\Python35\Scripts\pip.exe install -r requirements.txt
289 | ```
290 | 
291 | ### 警告
292 | 
293 | 一些依赖无法通过pip进行安装，要求进行手动安装。尤其是：
294 | 
295 | - `psycopg` 必须通过[这个安装包](http://www.stickpeople.com/projects/python/win-psycopg/)进行安装。
296 | - 要支持页眉和页脚，`wkhtmltopdf`的安装版本必须为 [0.12.5](https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5)。查看[wiki](https://github.com/odoo/odoo/wiki/Wkhtmltopdf)页面获取更多有关更多版本的详情。
297 | 
298 | 对于从右向左的语言 (如阿拉伯语或希伯来语)，需要使用 `rtlcss` 包：
299 | 
300 | 1. 下载并安装[nodejs](https://nodejs.org/en/download/)。
301 | 
302 | 2. 安装 
303 | 
304 |    ```
305 |    rtlcss
306 |    ```
307 | 
308 |    :
309 | 
310 |    ```
311 |    C:\> npm install -g rtlcss
312 |    ```
313 | 
314 | 3. 编辑系统环境变量`PATH` 来添加 `rtlcss.cmd` 所处的文件夹(通常为: `C:\Users\<user>\AppData\Roaming\npm\`).
315 | 
316 | #### 运行Odoo
317 | 
318 | 一旦设置了所有的依赖，可通过运行服务端的命令行`odoo-bin`来启动Odoo。它位于Odoo社区版的根目录下。
319 | 
320 | 要进行服务端的配置，你可以指定 [命令行参数](https://www.odoo.com/documentation/13.0/reference/cmdline.html#reference-cmdline-server) 或 [配置文件](https://www.odoo.com/documentation/13.0/reference/cmdline.html#reference-cmdline-config)。
321 | 
322 | 对于企业版，必须将`enterprise`插件的路径添加`addons-path`参数中。注意要将它放在`addons-path`中的其它路径之前，以正确地加载插件。
323 | 
324 | 常用的必要配置有：
325 | 
326 | - PostgreSQL用户和密码。
327 | - 默认以外的自定义插件路径，来加载你自己的模块。
328 | 
329 | 一个典型的方式是通过如下命令运行服务端：
330 | 
331 | ```
332 | C:\YourOdooCommunityPath> python3 odoo-bin -r dbuser -w dbpassword --addons-path=addons,../mymodules --db-filter=mydb$
333 | ```
334 | 
335 | 其中`YourOdooCommunityPath` 是Odoo社区版所安装的路径， `dbuser`是PostgreSQL的登录用户，`dbpassword`是PostgreSQL的密码，`../mymodules`是一个带有附加插件的路径，而 `mydb` 是通过`localhost:8069`提供服务的默认数据库。
336 | 
337 | ### Linux
338 | 
339 | #### 获取源码
340 | 
341 | 有两种获取Odoo源代码的方式：zip**压缩包**或通过**git**。
342 | 
343 | ##### 压缩包
344 | 
345 | 社区版：
346 | 
347 | - [官方下载页面](https://www.odoo.com/page/download)
348 | - [GitHub仓库](https://github.com/odoo/odoo)
349 | - [Nightly服务器](https://nightly.odoo.com/)
350 | 
351 | 企业版：
352 | 
353 | - [官方下载页面](https://www.odoo.com/page/download)
354 | - [GitHub仓库](https://github.com/odoo/enterprise)
355 | 
356 | ##### Git
357 | 
358 | 以下部分要求在电脑主安装了[git](https://git-scm.com/)，并且你已掌握了git 命令的基础知识。
359 | 
360 | 社区版：
361 | 
362 | ```
363 | $ git clone https://github.com/odoo/odoo.git
364 | ```
365 | 
366 | **译者注：**可使用sudo git clone -b 13.0 --depth 1 https://github.com/odoo/odoo.git 来减少下载的代码量
367 | 
368 | 企业版：(参见 [版本](#setup-install-editions)部分进行获取)
369 | 
370 | ```
371 | $ git clone https://github.com/odoo/enterprise.git
372 | ```
373 | 
374 | **企业版git仓库并不包含完整的Odoo源代码。**它仅是一个附加插件的集合。主服务端代码在社区版中。运行企业版实际是将addons-path选项设置为企业版的文件夹并运行社区版服务。你需要同时克隆社区版和企业版来得到一个运行中的Odoo企业版安装。
375 | 
376 | #### 准备工作
377 | 
378 | ##### Python
379 | 
380 | Odoo运行要求Python 3.5或更新的版本。如尚未安装Python 3请使用官方的包管理器来在你的电脑上下载并安装。
381 | 
382 | 如果已经安装了Python 3，请确保版本为3.5或以上，因为更早的版本与Odoo并不兼容。
383 | 
384 | ```
385 | $ python3 --version
386 | ```
387 | 
388 | 同时验证是否安装了相应版本的 [pip](https://pip.pypa.io/)。
389 | 
390 | ```
391 | $ pip3 --version
392 | ```
393 | 
394 | ##### PostgreSQL
395 | 
396 | Odoo使用PostgreSQL来作为数据库管理系统。使用包管理器来下载并安装最新版本的PostgreSQL。
397 | 
398 | 默认仅有用户`postgres`，但Odoo禁止通过`postgres`来进行连接，因此你需要新建一个PostgreSQL用户：
399 | 
400 | ```
401 | $ sudo -u postgres createuser -s $USER
402 | $ createdb $USER
403 | ```
404 | 
405 | 因为你的PostgreSQL用户名称与Unix登录名相同，可以无需密码来连接数据库。
406 | 
407 | ##### 依赖
408 | 
409 | Odoo的依赖在Odoo社区版根目录下的`requirements.txt` 文件中列出了所需的依赖。其中大部分都可以通过**pip**进行安装。
410 | 
411 | 推荐不要将不同Odoo实例间或者与系统的python模块包混放在到一起。可以使用[virtualenv](https://pypi.python.org/pypi/virtualenv)来创建隔离的Python环境。
412 | 
413 | 导航到Odoo社区安装位置的路径 (`YourOdooCommunityPath`) 并对requirements文件运行**pip**命令：
414 | 
415 | ```
416 | $cd /YourOdooCommunityPath
417 | /YourOdooCommunityPath$ pip3 install -r requirements.txt
418 | ```
419 | 
420 | ### 警告
421 | 
422 | 对于使用原生代码的库 (Pillow, lxml, greenlet, gevent, psycopg2, ldap)，可能在pip在能够安装依赖之前需要安装开发工具和原生依赖。在针对Python, PostgreSQL, libxml2, libxslt, libevent, libsasl2和libldap2的`-dev` 或 `-devel`包中均可获取。
423 | 
424 | ### 警告
425 | 
426 | 一些依赖无法通过pip进行安装，要求手动安装。尤其是：
427 | 
428 | - 要支持页眉和页脚，`wkhtmltopdf`的安装版本必须为 [0.12.5](https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5)。查看[wiki](https://github.com/odoo/odoo/wiki/Wkhtmltopdf)页面获取更多有关更多版本的详情。
429 | 
430 | 对于从右向左的语言 (如阿拉伯语或希伯来语)，需要使用 `rtlcss` 包：
431 | 
432 | 1. 通过包管理器下载并安装 **nodejs**和**npm**。
433 | 
434 | 2. 安装
435 | 
436 |    ```
437 |    rtlcss
438 |    ```
439 | 
440 |    :
441 | 
442 |    ```
443 |    $ sudo npm install -g rtlcss
444 |    ```
445 | 
446 | #### 运行Odoo
447 | 
448 | 一旦配置了所有依赖， 可通过运行服务端命令行工具`odoo-bin`来启动Odoo。它位于Odoo社区版所在的根目录下。
449 | 
450 | 要进行服务端的配置，可以通过[命令行参数](https://www.odoo.com/documentation/13.0/reference/cmdline.html#reference-cmdline-server)或 [配置文件](https://www.odoo.com/documentation/13.0/reference/cmdline.html#reference-cmdline-config)进行指定。
451 | 
452 | 企业版中必须将`enterprise`插件的路径添加`addons-path`参数中。注意要将它放在`addons-path`中的其它路径之前，这样才能正确地加载插件。
453 | 
454 | 通常所需配置有：
455 | 
456 | - PostgreSQ用户和密码。除[psycopg2默认值](http://initd.org/psycopg/docs/module.html)以外没有其它的默认项： 通过当前用户无需密码在`5432`端口上连接 UNIX套接字。
457 | - 默认值以外的自定义插件路径，来加载你自己的模块。
458 | 
459 | 通常运行服务端的方式为：
460 | 
461 | ```
462 | /YourOdooCommunityPath$ python3 odoo-bin --addons-path=addons,../mymodules --db-filter=mydb$
463 | ```
464 | 
465 | `YourOdooCommunityPath`是 Odoo社区版安装的路径， `../mymodules` 是带有附加插件的目录，而 `mydb`是通过`localhost:8069`提供服务的默认数据库。
466 | 
467 | ### Mac OS
468 | 
469 | #### 获取源码
470 | 
471 | 有两种获取Odoo源代码的方式：zip**压缩包**或通过**git**。
472 | 
473 | ##### 压缩包
474 | 
475 | 社区版：
476 | 
477 | - [官方下载页面](https://www.odoo.com/page/download)
478 | - [GitHub仓库](https://github.com/odoo/odoo)
479 | - [Nightly服务器](https://nightly.odoo.com/)
480 | 
481 | 企业版：
482 | 
483 | - [官方下载页面](https://www.odoo.com/page/download)
484 | - [GitHub仓库](https://github.com/odoo/enterprise)
485 | 
486 | ##### Git
487 | 
488 | 以下部分要求在电脑主安装了[git](https://git-scm.com/)，并且你已掌握了git 命令的基础知识。
489 | 
490 | 社区版：
491 | 
492 | ```
493 | $ git clone https://github.com/odoo/odoo.git
494 | ```
495 | 
496 | 企业版：(参见 [版本](#setup-install-editions)部分进行获取)
497 | 
498 | ```
499 | $ git clone https://github.com/odoo/enterprise.git
500 | ```
501 | 
502 | **企业版git仓库并不包含完整的Odoo源代码。**它仅是一个附加插件的集合。主服务端代码在社区版中。运行企业版实际是将addons-path选项设置为企业版的文件夹并运行社区版服务。你需要同时克隆社区版和企业版来得到一个运行中的Odoo企业版安装。
503 | 
504 | #### 准备工作
505 | 
506 | ##### Python
507 | 
508 | Odoo要求使用Python 3.5或之后的版本进行运行。如未安装，请使用你喜欢的包管理器 ([homebrew](http://brew.sh/), [macports](https://www.macports.org/)) 来在电脑上下载并安装Python 3。
509 | 
510 | 如果已安装了Python 3，请确保版本为3.5或以上，因为更老的版本与Odoo不兼容。
511 | 
512 | ```
513 | $ python3 --version
514 | ```
515 | 
516 | 同时验证已安装了对应版本的 [pip](https://pip.pypa.io/)。
517 | 
518 | ```
519 | $ pip3 --version
520 | ```
521 | 
522 | ##### PostgreSQL
523 | 
524 | Odoo使用PostgreSQL来作为数据库管理系统。使用[postgres.app](https://postgresapp.com/)来下载并安装最新版本的PostgreSQL。
525 | 
526 | 默认仅有用户`postgres`，但Odoo禁止通过`postgres`来进行连接，因此你需要新建一个PostgreSQL用户：
527 | 
528 | ```
529 | $ sudo -u postgres createuser -s $USER
530 | $ createdb $USER
531 | ```
532 | 
533 | 因为PostgreSQL用户与Unix登录名相同，所以可以无需密码直接连接该数据库。
534 | 
535 | ##### 依赖
536 | 
537 | Odoo的依赖在Odoo社区版根目录下的`requirements.txt` 文件中列出了所需的依赖。其中大部分都可以通过**pip**进行安装。
538 | 
539 | 推荐不要将不同Odoo实例间或者与系统的python模块包混放在到一起。可以使用[virtualenv](https://pypi.python.org/pypi/virtualenv)来创建隔离的Python环境。
540 | 
541 | 导航到Odoo社区安装位置的路径 (`YourOdooCommunityPath`) 并对requirements文件运行**pip**命令：
542 | 
543 | ```
544 | $ cd  /YourOdooCommunityPath
545 | /YourOdooCommunityPath$ pip3 install -r requirements.txt
546 | ```
547 | 
548 | ### 警告
549 | 
550 | 非Python依赖需要通过包管理器来进行安装：
551 | 
552 | 1. 下载交安装
553 | 
554 |    命令行工具：
555 | 
556 |    ```
557 |    $ xcode-select --install
558 |    ```
559 | 
560 | 2. 下载并安装你所选择的包管理器 ([homebrew](http://brew.sh/), [macports](https://www.macports.org/))。
561 | 
562 | 3. 安装非python依赖。
563 | 
564 | ### 警告
565 | 
566 | 有些依赖无法通过pip进行安装，要求进行手动安装。尤其是：
567 | 
568 | - 要支持页眉和页脚，`wkhtmltopdf`安装的版本必须为[0.12.5](https://github.com/wkhtmltopdf/wkhtmltopdf/releases/tag/0.12.5)。参见[wiki](https://github.com/odoo/odoo/wiki/Wkhtmltopdf)页面获取更多版本的详情。
569 | 
570 | 对于从右向左阅读的语言(如阿拉伯语或希伯来语)，需要使用 `rtlcss` 包：
571 | 
572 | 1. 通过自己喜欢的包管理器([homebrew](http://brew.sh/), [macports](https://www.macports.org/))下载并安装**nodejs** 。
573 | 
574 | 2. 安装 
575 | 
576 |    ```
577 |    rtlcss
578 |    ```
579 | 
580 |    :
581 | 
582 |    ```
583 |    $ sudo npm install -g rtlcss
584 |    ```
585 | 
586 | 
587 | 
588 | ## Docker
589 | 
590 | 如何通过Docker使用Odoo的完整文档中参见官方的Odoo [docker镜像](https://registry.hub.docker.com/_/odoo/)页面。
591 | 
592 | ## 译者补充安装方法（Ubuntu）
593 | 
594 | [![Odoo 13后台页面](https://alanhou.org/homepage/wp-content/uploads/2019/10/2019101009424619.jpg)](https://alanhou.org/homepage/wp-content/uploads/2019/10/2019101009424619.jpg)
595 | 
596 | ```
597 | # 更新为国内apt源（以阿里云镜像为例）
598 | sudo sed -i "s/archive.ubuntu.com/mirrors.aliyun.com/g" /etc/apt/sources.list
599 | sudo sed -i "s/security.ubuntu.com/mirrors.aliyun.com/g" /etc/apt/sources.list
600 | sudo apt-get update 
601 | sudo adduser -system -home=/opt/odoo -group odoo -shell /bin/bash # 添加odoo用户和组
602 | sudo apt-get install -y postgresql # 安装PostgreSQL数据库
603 | sudo service postgresql start # 启动 PostgreSQL
604 | # 创建数据库用户
605 | sudo su - postgres
606 | createuser --createdb --username postgres --no-createrole --no-superuser --pwprompt odoo
607 | exit
608 | sudo service postgresql restart
609 | # 安装依赖
610 | sudo apt-get install -y python3-pip
611 | sudo apt-get install virtualenv
612 | sudo apt-get install libsasl2-dev python-dev libldap2-dev libssl-dev python3-pypdf2
613 | 
614 | sudo su - odoo
615 | git clone -b 13.0 --depth 1 https://github.com/odoo/odoo.git 
616 | virtualenv -p python3 odoo-env
617 | source odoo-env/bin/activate
618 | pip3 install -r odoo/requirements.txt
619 | 
620 | # 配置文件
621 | sudo vim /etc/odoo-server.conf
622 | # 示例配置内容
623 | [options]
624 | ; This is the password that allows database operations:
625 | ; admin_passwd = admin
626 | db_host = False
627 | db_port = False
628 | db_name = odoo
629 | db_user = odoo
630 | db_password = False
631 | logfile = /var/log/odoo/odoo-server.log
632 | addons_path = /opt/odoo/odoo/addons,/opt/odoo/odoo/odoo/addons
633 | 
634 | # 设置权限
635 | sudo chown odoo: /etc/odoo-server.conf 
636 | sudo chmod 640 /etc/odoo-server.conf
637 | sudo mkdir /var/log/odoo 
638 | sudo chown odoo:root /var/log/odoo
639 | 
640 | # 安装 wkhmtltopdf（选择对应的 Ubuntu 版本）
641 | wget "https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.xenial_amd64.deb" -O /tmp/wkhtml.deb 
642 | sudo dpkg -i /tmp/wkhtml.deb  # 忽略此处报错，直接执行下一步
643 | sudo apt-get -fy install
644 | 
645 | # 设置服务启动
646 | 
647 | vi /etc/systemd/system/odoo13.service
648 | 
649 | # 内容
650 | [Unit]
651 | Description=Odoo13
652 | Requires=postgresql.service
653 | After=network.target postgresql.service
654 | 
655 | [Service]
656 | Type=simple
657 | SyslogIdentifier=odoo13
658 | PermissionsStartOnly=true
659 | User=odoo
660 | Group=odoo
661 | WorkingDirectory=/opt/odoo
662 | Environment=/opt/odoo/odoo-env/bin/activate
663 | ExecStart=/opt/odoo/odoo-env/bin/python3 /opt/odoo/odoo/odoo-bin -c /etc/odoo-server.conf
664 | StandardOutput=journal+console
665 | 
666 | [Install]
667 | WantedBy=multi-user.target
668 | 
669 | # 启动服务
670 | sudo systemctl start odoo13
671 | ```
672 | 
673 |   


--------------------------------------------------------------------------------
/reference/testing-odoo.md:
--------------------------------------------------------------------------------
  1 | # 测试Odoo
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](https://alanhou.org/odoo-13-developer-documentation/)系列文章</dt>
  4 | 
  5 | 有很多种测试应用的方法。在Odoo中，我们有三种测试
  6 | 
  7 | *   Python 单元测试 (参见[测试Python代码](#testing-python-code))：用于测试模型业务逻辑
  8 | *   JS单元测试(参见[测试JS代码](#testing-js-code))：用于分离测试javascript代码
  9 | *   导览(参见[集成测试](#integration-testing))：模拟真实场景的导览。它们确保python及 javascript部分正常进行对话。
 10 | 
 11 | ## 测试Python代码
 12 | 
 13 | Odoo提供使用单元测试来测试模块的支持。
 14 | 
 15 | 编写测试只需在模块中定义一个 `tests` 子包，它会自动查看测试模块。测试模块应有一个以`test_`开头的名称并且会从 `tests/__init__.py`, 进行导入，如：
 16 | 
 17 | ```
 18 | your_module
 19 | |-- ...
 20 | `-- tests
 21 |     |-- __init__.py
 22 |     |-- test_bar.py
 23 |     `-- test_foo.py
 24 | ```
 25 | 
 26 | 且 `__init__.py` 包含：
 27 | 
 28 | `from . import test_foo, test_bar`
 29 | 
 30 | ### ⚠️警告
 31 | 
 32 | 不是通过 `tests/__init__.py`导入的测试模块将不会运行
 33 | 
 34 | 测试运行器只是会运行测试类，正如[unittest 官方文档](https://docs.python.org/3/library/unittest.html)所描述的那样， 但 Odoo提供了一些与测试Odoo内容（主要是模块）相关的工具和帮助类：
 35 | 
 36 | ###### `*class *odoo.tests.common.TransactionCase(*methodName='runTest'*)`
 37 | 
 38 | 每个TestCase的测试方法以自己的游标在自身的事务中运行。在每次测试完成后会回滚事务并关闭游标。
 39 | 
 40 | ###### `browse_ref(*xid*)`
 41 | 
 42 | 为所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回记录对象
 43 | 
 44 | 参数
 45 | 
 46 | **xid** – 完全限定[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为 `*module*.*identifier*`
 47 | 
 48 | 在未找到时抛出
 49 | 
 50 | ValueError
 51 | 
 52 | 返回
 53 | 
 54 | [`BaseModel`](https://alanhou.org/odoo-13-orm-api/#odoo.models.BaseModel "odoo.models.BaseModel")
 55 | 
 56 | ###### `ref(*xid*)`
 57 | 
 58 | 对所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回数据库ID，`get_object_reference`的快捷方式
 59 | 
 60 | 参数
 61 | 
 62 | **xid** – 完全限定 [外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为`*module*.*identifier*`
 63 | 
 64 | 在未找到时抛出
 65 | 
 66 | ValueError
 67 | 
 68 | 返回
 69 | 
 70 | 注册的 id
 71 | 
 72 | ###### `*class *odoo.tests.common.SingleTransactionCase(*methodName='runTest'*)`
 73 | 
 74 | 所有测试方法的TestCase在同一个事务中运行，事务通过第一个测试方法启动并在最后一个测试方法完成后进行回滚。
 75 | 
 76 | ###### `browse_ref(*xid*)`
 77 | 
 78 | 对所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回记录对象
 79 | 
 80 | 参数
 81 | 
 82 | **xid** – 完全限定 [外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为 `*module*.*identifier*`
 83 | 
 84 | 在未找到时抛出
 85 | 
 86 | ValueError
 87 | 
 88 | 返回
 89 | 
 90 | [`BaseModel`](https://alanhou.org/odoo-13-orm-api/#odoo.models.BaseModel "odoo.models.BaseModel")
 91 | 
 92 | ###### `ref(*xid*)`
 93 | 
 94 | 对所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回数据库ID，快捷方式为 `get_object_reference`
 95 | 
 96 | 参数
 97 | 
 98 | **xid** – 完全限定 [外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为 `*module*.*identifier*`
 99 | 
100 | 在未找到时抛出
101 | 
102 | ValueError
103 | 
104 | 返回
105 | 
106 | 注册的id
107 | 
108 | ###### `*class *odoo.tests.common.SavepointCase(*methodName='runTest'*)`
109 | 
110 | 类似于 [`SingleTransactionCase`](#odoo.tests.common.SingleTransactionCase "odoo.tests.common.SingleTransactionCase") ，其中所有测试方法都在单个事务中运行，但每个测试用例在回滚的保存点（子事务）内部运行。
111 | 
112 | 用于包含快速测试的测试用例，但具有所有测试用例的常见数据库配置(复杂in-db测试数据)： `setUpClass()` 可用于生成一次数据库测试数据，然后所有测试用例使用不影响其它测试的相同数据， 但也无需重建测试数据。
113 | 
114 | ###### `*class *odoo.tests.common.HttpCase(*methodName='runTest'*)`
115 | 
116 | 带有url_open和Chrome headless帮助方法的事务型HTTP TestCase。
117 | 
118 | ###### `browse_ref(*xid*)`
119 | 
120 | 为所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回记录对象
121 | 
122 | 参数
123 | 
124 | **xid** – 完全限定[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为`*module*.*identifier*`
125 | 
126 | 在未找到时返回
127 | 
128 | ValueError
129 | 
130 | 返回
131 | 
132 | [`BaseModel`](https://alanhou.org/odoo-13-orm-api/#odoo.models.BaseModel "odoo.models.BaseModel")
133 | 
134 | ###### `phantom_js(*url_path*, *code*, *ready=''*, *login=None*, *timeout=60*, ***kw*)`
135 | 
136 | 在浏览器中运行的Test js代码 - 可日志为‘login’ - 加载url_path给定的页面 - 等待对象就绪 - 页面内部的eval(code)
137 | 
138 | 标识成功测试执行： console.log(‘test successful’)
139 | 
140 | 标识失败时执行: console.error(‘test failed’)
141 | 
142 | 在超时前两者都未执行则测试失败。
143 | 
144 | ###### `ref(*xid*)`
145 | 
146 | 对所提供的[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)返回数据库ID，是 `get_object_reference`的快捷方式
147 | 
148 | 参数
149 | 
150 | **xid** – 完全限定[外部标识符](https://www.odoo.com/documentation/13.0/glossary.html#term-external-identifier)，形式为 `*module*.*identifier*`
151 | 
152 | 在未找到时抛出
153 | 
154 | ValueError
155 | 
156 | 返回
157 | 
158 | 注册的id
159 | 
160 | ###### `odoo.tests.common.tagged(**tags*)`
161 | 
162 | 标记BaseCase对象标签的装饰器存储于一个可由‘test_tags’属性访问的集合中。以 ‘-‘ 为标签的前缀会删除该标签，如要删除‘standard’标签。默认所有odoo.tests.common 中的测试类有一个默认为‘standard’及模块技术名称。在使用类继承时，标签未被继承。
163 | 
164 | 默认，测试在相应模块安装后运行一次。测试用例也可配置为所有模块安装后运行，而不是紧接着模块安装后运行：
165 | 
166 | ###### `odoo.tests.common.at_install(*flag*)`
167 | 
168 | 设置测试的在安装状态，该标记是一个指定测试应(`True`)或不应 (`False`) 在模块安装时运行的布尔值。
169 | 
170 | 默认，测试在模块安装之后、开始下一个模块安装之前运行。
171 | 
172 | 自从版本12.0开始淘汰： `at_install` 当前是一个标记，虽然`tagged` 仅在测试类中生效，但你可以使用 [`tagged()`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.tagged "odoo.tests.common.tagged") 来添加/删除它
173 | 
174 | ###### `odoo.tests.common.post_install(*flag*)`
175 | 
176 | 设置测试的安装后状态。该标记是一个指定测试应或不应在模块安装集合之后运行的布尔值。
177 | 
178 | 默认，在当前安装集合中所有模块的安装测试不运行测试。
179 | 
180 | 从版本12.0开始淘汰： `post_install`现在是一个标记， 虽然`tagged` 仅在测试类中生效，但你可以使用 [`tagged()`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.tagged "odoo.tests.common.tagged") 来添加/删除它
181 | 
182 | 最常见的情况是使用 [`TransactionCase`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.TransactionCase "odoo.tests.common.TransactionCase") 并在每个方法中测试模型的属性：
183 | 
184 | ```
185 | class TestModelA(common.TransactionCase):
186 |     def test_some_action(self):
187 |         record = self.env['model.a'].create({'field': 'value'})
188 |         record.some_action()
189 |         self.assertEqual(
190 |             record.field,
191 |             expected_field_value)
192 | 
193 |     # other tests...
194 | ```
195 | 
196 | 测试方法必须以 `test_`开头
197 | 
198 | ###### `*class *odoo.tests.common.Form(*recordp*, *view=None*)`
199 | 
200 | 服务端 (部分)表单视图实现
201 | 
202 | 实现很多的“表单视图”操作流，如服务端测试可更好的反映行为，它将在操作界面时观察到：
203 | 
204 | *   对“创建”调用相关的 onchange
205 | *   对设置字段调用相关的onchange
206 | *   对在 x2many字段相应地处理默认值 & onchange
207 | 
208 | 保存创建模式下返回的创建记录表单。
209 | 
210 | 常用字段可仅直接分配给表单，对[`Many2one`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Many2one "odoo.fields.Many2one") 字段分配一个singleton记录集：
211 | 
212 | ```
213 | # empty recordset => creation mode
214 | f = Form(self.env['sale.order'])
215 | f.partner_id = a_partner
216 | so = f.save()
217 | ```
218 | 
219 | 在编辑记录时，使用表单作为上下文管理器来自动在作用域结束处保存它：
220 | 
221 | ```
222 | with Form(so) as f2:
223 |     f2.payment_term_id = env.ref('account.account_payment_term_15days')
224 |     # f2 is saved here
225 | ```
226 | 
227 | 对于 [`Many2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.Many2many "odoo.fields.Many2many") 字段，字段本身是一个 [`M2MProxy`](#odoo.tests.common.M2MProxy "odoo.tests.common.M2MProxy") 并可通过添加或删除记录来进行修改：
228 | 
229 | ```
230 | with Form(user) as u:
231 |     u.groups_id.add(env.ref('account.group_account_manager'))
232 |     u.groups_id.remove(id=env.ref('base.group_portal').id)
233 | ```
234 | 
235 | 最后 [`One2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.One2many "odoo.fields.One2many") 具体化为[`O2MProxy`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.O2MProxy "odoo.tests.common.O2MProxy")。
236 | 
237 | 因 [`One2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.One2many "odoo.fields.One2many") 仅通过其父级存在，它更直接地通过[`new()`](#odoo.tests.common.O2MProxy.new "odoo.tests.common.O2MProxy.new") 和 [`edit()`](#odoo.tests.common.O2MProxy.edit "odoo.tests.common.O2MProxy.edit") 方法创建“子表单” 。这些通常将用作上下文管理器，因为它们在父级记录中进行保存：
238 | 
239 | ```
240 | with Form(so) as f3:
241 |     # add support
242 |     with f3.order_line.new() as line:
243 |         line.product_id = env.ref('product.product_product_2')
244 |     # add a computer
245 |     with f3.order_line.new() as line:
246 |         line.product_id = env.ref('product.product_product_3')
247 |     # we actually want 5 computers
248 |     with f3.order_line.edit(1) as line:
249 |         line.product_uom_qty = 5
250 |     # remove support
251 |     f3.order_line.remove(index=0)
252 |     # SO is saved here
253 | ```
254 | 
255 | 参数
256 | 
257 | *   **recordp** ([`odoo.models.Model`](https://alanhou.org/odoo-13-orm-api/#odoo.models.Model "odoo.models.Model")) – 对于singleton记录为空。空记录集会将视图置为“创建”模式并触发对default_get 和 on-load onchange的调用，一个 singleton会将其设置为“编辑”模式并仅加载视图的数据。
258 | *   **view** (`int | str | odoo.model.Model`) – onchange和视图约束所使用的id, xmlid 或实际视图对象。如未提供，仅加载模型的默认视图。
259 | 
260 | 版本12.0中新增。
261 | 
262 | ###### `save()`
263 | 
264 | 保存表单，在可用时返回所创建的记录
265 | 
266 | *   不保存 `只读` 字段
267 | *   （在编辑时）不保存未修改字段 — 任何赋值或 onchange返回标记字段为已修改，设置为当前值也是如此
268 | 
269 | 抛出
270 | 
271 | [**AssertionError**](https://docs.python.org/3/library/exceptions.html#AssertionError "(in Python v3.8)") – 若表单没有任何未填写的必填字段
272 | 
273 | ###### `*class *odoo.tests.common.M2MProxy`
274 | 
275 | 作为记录集的`序列`，可进行索引或切片来获取实际底层记录集。
276 | 
277 | ###### `add(*record*)`
278 | 
279 | 向字段添加`记录`，记录必须是已存在的。
280 | 
281 | 所添加的内容仅在保存父级记录时最终生效。
282 | 
283 | ###### `clear()`
284 | 
285 | 删除m2m中的所有已有记录
286 | 
287 | ###### `remove(*id=None*, *index=None*)`
288 | 
289 | 删除指定索引或字段中具有所提供 id 的记录。
290 | 
291 | ###### `*class *odoo.tests.common.O2MProxy`
292 | 
293 | ###### `edit(*index*)`
294 | 
295 | 返回一个 [`表单`](#odoo.tests.common.Form "odoo.tests.common.Form") 来编辑已存在的 [`One2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.One2many "odoo.fields.One2many") 记录。
296 | 
297 | 表单通过可编辑的列表视图或通过字段的表单视图进行创建。
298 | 
299 | 抛出
300 | 
301 | [**AssertionError**](https://docs.python.org/3/library/exceptions.html#AssertionError "(in Python v3.8)") – 若字段不可编辑
302 | 
303 | ###### `new()`
304 | 
305 | 返回一个相应初始化的新 [`One2many`](https://alanhou.org/odoo-13-orm-api/#odoo.fields.One2many "odoo.fields.One2many") 记录的[`表单`](#odoo.tests.common.Form "odoo.tests.common.Form")。
306 | 
307 | 表单通过可编辑的列表视图或通过字段的表单视图进行创建。
308 | 
309 | 抛出
310 | 
311 | [**AssertionError**](https://docs.python.org/3/library/exceptions.html#AssertionError "(in Python v3.8)") – 若字段不可编辑
312 | 
313 | ###### `remove(*index*)`
314 | 
315 | 删除父级表单中位于 `index`处的记录。
316 | 
317 | 抛出
318 | 
319 | [**AssertionError**](https://docs.python.org/3/library/exceptions.html#AssertionError "(in Python v3.8)") – 若字段不可编辑
320 | 
321 | ### 运行测试
322 | 
323 | 如果在启动Odoo服务启用了[`--test-enable`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-test-enable)，测试在安装或升级模块时自动运行。
324 | 
325 | ### 测试选择
326 | 
327 | 在Odoo中， Python测试可打标签，来便于在运行测试时选择测试。
328 | 
329 | `odoo.tests.common.BaseCase` (通过通过 [`TransactionCase`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.TransactionCase "odoo.tests.common.TransactionCase"), [`SavepointCase`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.SavepointCase "odoo.tests.common.SavepointCase") 或 [`HttpCase`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.HttpCase "odoo.tests.common.HttpCase")) 的子类自动使用 `standard`, `at_install` 及默认用它们的源模块的免进行打标签。
330 | 
331 | #### 调用
332 | 
333 | [`--test-tags`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-test-tags) 可用于选择/过滤在命令行中运行的测试。
334 | 
335 | 这个选项默认为 `+standard` ，表示测试（显式或隐式地）使用 `standard` 打标签，在使用 [`--test-enable`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-test-enable)启动Odoo时默认运行。
336 | 
337 | 在编写测试时，[`tagged()`](https://alanhou.org/odoo-13-testing-odoo/#odoo.tests.common.tagged "odoo.tests.common.tagged") 装饰器可用于**测试类**来添加或删除标签。
338 | 
339 | 装饰器的参数为标签名，为字符串。
340 | 
341 | ### 🚫危险
342 | 
343 | [`tagged()`](#odoo.tests.common.tagged "odoo.tests.common.tagged")是一个类装饰器，对于函数或方法没有效果
344 | 
345 | 标签可使用减号 (`-`) 作为前缀，来删除而非添加或选择它们，例：如果你不想要测试默认执行，可以删除 `standard` 标签：
346 | 
347 | ```
348 | from odoo.tests import TransactionCase, tagged
349 | 
350 | @tagged('-standard', 'nice')
351 | class NiceTest(TransactionCase):
352 |     ...
353 | ```
354 | 
355 | 这个测试默认不会选中，要运行它必须显式地选中相关标签：
356 | 
357 | `$ odoo-bin --test-enable --test-tags nice`
358 | 
359 | 注意只有添加了`nice` 标签的测试会进行执行。要同时运行 `nice` 和 `standard` 测试，为[`--test-tags`](#cmdoption-odoo-bin-test-tags)提供多个值：在命令行中，值是累加的 (你选择带有指定标签中的任意一个的所有测试)
360 | 
361 | `$ odoo-bin --test-enable --test-tags nice,standard`
362 | 
363 | 配置切换参数还接收 `+` 和 `-` 前缀。 `+` 前缀是暗含的，因此完全可选。即使由其它标签选中， `-` (减号) 前缀用于取消选择具有该前缀标签的测试， 例：如有 `standard` 的测试，还使用 `slow` 添加了标签，那么会运行除 slow 以外的所有标准测试：
364 | 
365 | `$ odoo-bin --test-enable --test-tags 'standard,-slow'`
366 | 
367 | 在编写不继承 `BaseCase`的测试时， 这个测试不会有默认标签，你需要显式地添加它们来让测试包含在默认测试套件中。这在使用简单的`unittest.TestCase` 时是一个普遍问题，因为它们不会进行运行：
368 | 
369 | ```
370 | import unittest
371 | from odoo.tests import tagged
372 | 
373 | @tagged('standard', 'at_install')
374 | class SmallTest(unittest.TestCase):
375 |     ...
376 | ```
377 | 
378 | #### 特殊标记
379 | 
380 | *   `standard`: 所有继承自`BaseCase` 的Odoo测试都隐式地打了standard标签。 [`--test-tags`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-test-tags)默认也为`standard`。这表示未打标签的测试在启用测试时会默认执行。
381 | *   `at_install`: 表示测试会在该模块安装后及其它模块安装前执行。这是默认的隐式标签。
382 | *   `post_install`: 表示测试会在所有模块安装完之后执行。对于大部分时候的HttpCase测试会希望这么做。注意这与`at_install`并不互斥，但通常不会需要两者同时使用，`post_install`通常在对测试类打标签时与 `-at_install` 配对。
383 | *   *module_name*: Odoo测试类继承`BaseCase`，隐式地使用模块的技术名称打标签。这允许在测试时轻易地选择或排除具体模块，例：如果希望仅通过`stock_account`来运行测试：
384 | 
385 | `$ odoo-bin --test-enable --test-tags stock_account`
386 | 
387 | #### 示例
388 | 
389 | ### ⚠️重要
390 | 
391 | 测试仅在安装或升级模块时执行。因此模块需要通过 [`-u`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-u) 或 [`-i`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-i) 选项进行选中。为保持简洁，下面的示例中没有指定这些选项。
392 | 
393 | 仅通过sale模块运行测试：
394 | 
395 | `$ odoo-bin --test-enable --test-tags sale`
396 | 
397 | 通过sale模块但不包含打了 slow 标签的内容运行测试：
398 | 
399 | `$ odoo-bin --test-enable --test-tags 'sale,-slow'`
400 | 
401 | 仅对stock或打了 slow 标签的运行测试：
402 | 
403 | `$ odoo-bin --test-enable --test-tags '-standard, slow, stock'`
404 | 
405 | `-standard` 是隐式的(非必须的)，添加它是为了保持清晰
406 | 
407 | ## 测试JS代码
408 | 
409 | 测试复杂系统是防止退化的重要保障并可确保一些基本功能仍正常运行。因Odoo有大量的Javascript代码，很有必要对其进行测试。在这一小节中，我们将讨论在隔离的状态下测试 JS 代码的实践，这些测试只保留在浏览器层面，而不触达服务端。
410 | 
411 | ### Qunit 测试套件
412 | 
413 | Odoo框架使用[QUnit](https://qunitjs.com/) 库测试框架来作为测试运行器。QUnit定义了**测试**和**模组**（一组相关测试）的概念，并为我们提供了执行测试的web 界面。
414 | 
415 | 例如，以下是 pyUtils测试运行的状况：
416 | 
417 | ```
418 | QUnit.module('py_utils');
419 | 
420 | QUnit.test('simple arithmetic', function (assert) {
421 |     assert.expect(2);
422 | 
423 |     var result = pyUtils.py_eval("1 + 2");
424 |     assert.strictEqual(result, 3, "should properly evaluate sum");
425 |     result = pyUtils.py_eval("42 % 5");
426 |     assert.strictEqual(result, 2, "should properly evaluate modulo operator");
427 | });
428 | ```
429 | 
430 | 运行测试套件的主要方式是要有运行中的Odoo服务，然后在浏览器中导航至 `/web/tests`。然后测试套件会由浏览器的.Javascript引擎进行运行。
431 | 
432 | ![image](https://upload-images.jianshu.io/upload_images/14565748-7e4cbfcf6a5f0628.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)
433 | 
434 | 网页 UI有很多有用的功能：它可以仅运行一些子模块，或过滤匹配某字符串的测试。它可以显示每个断言，不管成功或失败，重新运行具体测试, …
435 | 
436 | ### ⚠️警告
437 | 
438 | 在运行测试套件时，要确保：
439 | 
440 | *   焦点在浏览器窗口中，
441 | *   未进行放大/缩放。需要是100%的精确原大小比例。
442 | 
443 | 如果不是如此，有些测试会失败，不返回相当的说明。
444 | 
445 | ### 测试基础框架
446 | 
447 | 以下是对测试框架重要部分的高级别概览：
448 | 
449 | *   有一个名为[web.js_tests_assets](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L427)的资源包。 这个包中包含主要代码 (通用资源+ 后台资源), 一些库, QUnit测试运行器, 及一些其它帮助方法代码
450 | *   另一个资源包[web.qunit_suite](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L509), 包含所有测试(及 js_tests_assets 代码)。几乎所有测试文都应添加到这个包里
451 | *   在网页中有一个[控制器](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/controllers/main.py#L637)，映射到路由 */web/tests*。这个控制器仅渲染 *web.qunit_suite* 模板。
452 | *   要执行测试，我们可以仅将浏览器指向路由 */web/tests*。这种情况下，浏览器会下载所有资源，而 QUnit会接管。
453 | *   在[qunit_config.js](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/qunit_config.js#L49)中有一些代码， 在测试成功或失败时会在控制台中记录一些信息。
454 | *   我们希望runbot也能运行这些测试， 因此(在 [test_js.py](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/tests/test_js.py#L13)中)有一个测试，它只是产生一个浏览器并指向*web/tests* 链接。注意phantom_js 方法并不产生phantom_js，而是用的Chrome headless 。
455 | 
456 | ### 模块化及测试
457 | 
458 | 通过Odoo设计的方式，任何插件可修改系统中其它部分的行为。例如，*voip* 插件可修改 *FieldPhone* 张爱玲的来使用额外的功能。从测试系统的角度来看这并不是好事，因为这表示在插件网页中安装voip插件时测试会失败(注意runbot运行测试时安装了所有的插件)。
459 | 
460 | 同时，我们的测试系统很棒，因为它会监测到其它影响核心功能的模块。对这一问题没有完整的方案。当前我们按具体情况逐一进行解决。
461 | 
462 | 通常修改其它行为不是个好想法。就我们的voip示例来说，添加新的*FieldVOIPPhone组件*及修改需要它的一些视图显然更为清晰。通过这种方式，*FieldPhone* 组件不会受影响，两者均可进行测试。
463 | 
464 | ### 新增测试用例
465 | 
466 | 假设我们在维护一个插件*my_addon*，交且我们希望对一些javascript代码添加测试 (例如，位于*my_addon.utils*中的工具函数 myFunction)。添加u 新测试用例的流程如下：
467 | 
468 | 1.  新建文件 *my_addon/static/tests/utils_tests.js*。该文件包含添加 QUnit 模块 *my_addon > utils*的基本代码。
469 | ```
470 |     odoo.define('my_addon.utils_tests', function (require) {
471 |     "use strict";
472 |      
473 |     var utils = require('my_addon.utils');
474 |     
475 |     QUnit.module('my_addon', {}, function () {
476 |      
477 |         QUnit.module('utils');
478 |     
479 |     });
480 |     });
481 | ```
482 | 
483 | 2.  在*my_addon/assets.xml*中，将该文件添加到主测试资源中：
484 | ```
485 |     <?xml version="1.0" encoding="utf-8"?>
486 |     <odoo>
487 |         <template id="qunit_suite" name="my addon tests" inherit_id="web.qunit_suite">
488 |             <xpath expr="//script[last()]" position="after">
489 |                 <script type="text/javascript" src="/my_addon/static/tests/utils_tests.js"/>
490 |             </xpath>
491 |         </template>
492 |     </odoo>
493 | ```
494 | 
495 | 3.  重启服务并更新*my_addon*，或通过界面进行 (来确保加载了新测试文件)
496 | 4.  在*utils* 子测试套件的定义之后添加一个测试用例：
497 | 
498 | ```
499 | QUnit.test("some test case that we want to test", function (assert) {
500 |     assert.expect(1);
501 |     
502 |    var result = utils.myFunction(someArgument);
503 |     assert.strictEqual(result, expectedResult);
504 |     > });
505 | ```
506 | 
507 | 5.  访问*/web/tests/* 来确保执行了测试
508 | 
509 | ### 帮助函数和特殊化断言
510 | 
511 | 不借助帮助，很难测试到Odoo的某些部分。具体的说，视图很复杂，因其与服务端进行通讯并可能会执行一些rpc调用，这需要mock数据。这正是我们开发了一些特定帮助函数的原因，位于 [test_utils.js](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/test_utils.js)中。
512 | 
513 | *   Mock测试函数：这些函数帮助设置测试环境。最重要的用例是mock由Odoo服务所给定的结果。这些函数使用一个[mock服务](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/mock_server.js)。 这是一个模拟常用模型方法如read, search_read, nameget…的返回结果的 javascript类
514 | *   DOM帮助函数：用于对具体目标模拟事件/动作。例如， testUtils.dom.click 对目标执行点击。注意这样比手动更为安全，因为它还检查目标是否存在及可见。
515 | *   创建帮助函数：它们可能是由[test_utils.js](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/test_utils.js)导出的最为重要的函数。 这些函数用于通过 mock 环境创建组件，以大量尽可能模拟真实条件的小细节。最重要的肯定是 [createView](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/test_utils_create.js#L267)。
516 | *   [qunit断言](https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/qunit_asserts.js)： QUnit可通过特定断言进行扩展。对于Odoo，我们经常测试一些DOM 属性。这是我们进行一些断言来进行协助的原因。例如，*containsOnce* 断言接收一个widget/jQuery/HtmlElement 和一个选择器，然后查看目标是否刚好匹配该 css 选择器。
517 | 
518 | 例如，借助这些帮助函数，以下是简单的表单测试的示例：
519 | 
520 | ```
521 | QUnit.test('simple group rendering', function (assert) {
522 |     assert.expect(1);
523 | 
524 |     var form = testUtils.createView({
525 |         View: FormView,
526 |         model: 'partner',
527 |         data: this.data,
528 |         arch: '<form string="Partners">' +
529 |                 '<group>' +
530 |                     '<field name="foo"/>' +
531 |                 '</group>' +
532 |             '</form>',
533 |         res_id: 1,
534 |     });
535 | 
536 |     assert.containsOnce(form, 'table.o_inner_group');
537 | 
538 |     form.destroy();
539 | });
540 | ```
541 | 
542 | 注意使用testUtils.createView帮助函数及containsOnce断言。同时，表单控制在测试结束会进行相应的销毁。
543 | 
544 | ### 最佳实践
545 | 
546 | 以下并未进行排顺序：
547 | 
548 | *   所有测试文件应在*some_addon/static/tests/*中进行添加
549 | *   对于漏洞修复，确保不进行漏洞修复时测试失败，修复时测试成功。这会确保其真实有效。
550 | *   尝试使用所需的最小化测试代码来让测试有效。
551 | *   通常，两个小测试胜于一个大测试。小测试更易于理解及修复。
552 | *   在测试后保持进行清理。例如，如果测试实例化了一个组件，应在结束时销毁它。
553 | *   无需要进行完整的代码覆盖。但添加一些测试会有所帮助：这让你的代码不会完全崩溃，并在测试修复时，它更易于向已有测试套件添加测试。
554 | *   如果想要查看一些负向断言(例如，HtmlElement 没有具体的 css 类)， 那么尝试在相同测试中添加正向断言 (例如，通过执行一个修改该状态的动作)。这会帮助避免测试在未来无用 (例如在修改了css类时)。
555 | 
556 | ### ℹ️小贴士
557 | 
558 | *   仅运行一个测试：你可以 (临时！) 修改*QUnit.test(…)* 的定义到 *QUnit.only(…)*。这有助于确保QUnit 仅运行具体的测试。
559 | *   debug 标记：大多数工具函数都有测试模式 (通过 debug: true 参数进行启用)。在这种情况下，目标组件会被放到DOM中而非隐藏的 qunit 具体夹具中，并且会记录更多信息。例如，所有的 mock网络通讯在控制台中都可用。
560 | *   在处理失败的测试时，通常会添加 debug 标记，然后注释测试的结尾 (具体地说是销毁的调用)。通过它，可以直接查看组件的状态，甚至能通过点击/与其交互来操作组件。
561 | 
562 | ## 集成测试
563 | 
564 | 分别Python代码和 JS代码非常有益，但无法证明网页客户端和服务端共同有效。为进行验证，我们可以编写另一种测试：导览。导览是一种有意义的业务流的小型场景。它说明了一系列应该遵循的步骤。然后测试运行器会创建一个phantom_js浏览器，指向相应的url并根据场景模拟点击和输入。
565 | 
566 | ### 在browser_js测试时截屏和录屏
567 | 
568 | 在通过命令行运行使用HttpCase.browser_js的测试时，Chrome浏览器在headless模式下运行。默认在测试失败时，会在失败的瞬间截一张PNGu 并保存在：
569 | 
570 | ```
571 | '/tmp/odoo_tests/{db_name}/screenshots/'
572 | ```
573 | 
574 | 自Odoo 13.0开始添加了两个控制这一行为命令行参数： [`--screenshots`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-screenshots) and [`--screencasts`](https://alanhou.org/odoo-13-command-line-interface-odoo-bin/#cmdoption-odoo-bin-screencasts)


--------------------------------------------------------------------------------
/web-services/in-app-purchase.md:
--------------------------------------------------------------------------------
  1 | # 应用内购买
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | 应用内购买(IAP)允许持续通过 Odoo 提供服务的供应商进行持续的服务收费，而不是单独的一次性购买。在这一背景下， Odoo扮演客户和Odoo应用开发者之间的*经纪人*的角色：
  6 | 
  7 | - 用户通过Odoo购买服务令牌。
  8 | - 服务提供者在用户请求服务时从其Odoo账户中提取令牌。
  9 | 
 10 | ### ⚠️注意
 11 | 
 12 | 本文档针对 *服务提供者* 并提供第二项，可直接通过 [JSON-RPC2](https://www.jsonrpc.org/specification) 进行实现或者如对使用Odoo的人提供便捷的帮助类/方法。
 13 | 
 14 | ## 概览
 15 | 
 16 | ![img](https://www.odoo.com/documentation/13.0/_images/players.png)
 17 | 
 18 | #### 玩家
 19 | 
 20 | - 服务提供者 (可能是)读者你自己，你可以按使用收费服务的形式为客户提供价值。
 21 | - 客户安装了你的 Odoo应用，并藉此请求服务。
 22 | - Odoo从间进行余额控制，客户向账户中充值，然后你在提供服务时从该账户提供金额。
 23 | - 外部服务也可以加入：你可以直接提供服务，或者代理实际的服务，在其中作为 Odoo 系统和实际服务之间的桥梁或转换者。
 24 | 
 25 | ![img](https://www.odoo.com/documentation/13.0/_images/credits.jpg)
 26 | 
 27 | #### 积分余额
 28 | 
 29 | 从**2018年10月**开始积分余额由整数变成了浮点数。仍然保持对整数值的支持。
 30 | 
 31 | 每个通过IAP平台提供的服务可由客户通过令牌或余额来进行使用。积分余额是一个浮点单位，其货币价值取决所使用服务并由服务商决定。可以是：
 32 | 
 33 | - 短信服务： 1 积分 = 1 条短信;
 34 | - 广告服务： 1 积分 = 1 条广告; 或
 35 | - 邮政服务： 1 积分 = 1张邮票。
 36 | 
 37 | 积分也可仅与固定金额的钱挂钩来缓解价格的波动 (例如短信和邮票在不同国家的价格会不同)。
 38 | 
 39 | 积分的价值借助于购买的预付积分包来进行确定，客户可通过[https://iap.odoo.com](https://iap.odoo.com/) (参见 [积分包](#iap-packages))进行购买。
 40 | 
 41 | 在以下的讨论中我们将忽略外部服务，它们仅是你所提供服务的细节问题。
 42 | 
 43 | ![img](https://www.odoo.com/documentation/13.0/_images/normal.png)
 44 | 
 45 | #### “正常”服务流
 46 | 
 47 | 如果一切顺利，正常的流程如下：
 48 | 
 49 | 1. 客户请求某种服务。
 50 | 2. 服务提供者询问Odoo在该客户账户中是否有足够用于服务的积分，并通过该金额创建交易。
 51 | 3. 服务提供者提供服务 (通过他们自己或外部服务)。
 52 | 4. 服务提供者回到Odoo来捕获(若已提供服务)或取消(若无法提供服务) 第2步中所创建的交易。
 53 | 5. 最后，服务方提供客户服务已提供，（根据服务）可能会在客户的系统中显示或存储该结果。
 54 | 
 55 | ![img](https://www.odoo.com/documentation/13.0/_images/no-credit.png)
 56 | 
 57 | #### 余额不足
 58 | 
 59 | 但在客户账户里的余额不足支付服务时，流程如下：
 60 | 
 61 | 1. 客户像之前一样请求服务。
 62 | 2. 服务提供者向Odoo询问客户账户中是否有足够余额并获得一个否定的回复。
 63 | 3. 将这一信号返回给客户。
 64 | 4. 客户被重定向到Odoo账户中进行充值并再次尝试。
 65 | 
 66 | ## 构建你的服务
 67 | 
 68 | 本例中，我们将提供的服务- 狗币（dogecoin）挖矿 - 每个积分运行10秒钟CPU。对于你自己的服务，你可以：
 69 | 
 70 | - 自己提供在线服务 (如将报价转换为日本的商务传真);
 71 | - 自己提供*离线*服务 (如提供会计服务); 或
 72 | - 作为其他服务提供者的中介 (如彩信网关的中介)。
 73 | 
 74 | 
 75 | 
 76 | ### 在Odoo中注册服务
 77 | 
 78 | 开始实际查询用户账户前的第一步是在 IAP端点中注册服务（生产和/或测试）。要创建服务，进入你在IAP（生产环境为[https://iap.odoo.com](https://iap.odoo.com/) 测试环境为https://iap-sandbox.odoo.com，端点是独立非同步的）的 *Portal* 账户。或者可以进入在Odoo的门户 (https://iap.odoo.com/my/home) 并选择 *In-App Services*。
 79 | 
 80 | 在生产环境中，服务用于管理真实交易前有一个手动验证的步骤。这一步会在沙盒中自动传递在减轻测试压力。
 81 | 
 82 | 登录，然后进入My Account ‣ Your In-App Services， 占Create并提供你的服务的相关信息。
 83 | 
 84 | 服务有7个重要字段：
 85 | 
 86 | - `name` - [`ServiceName`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceName): 这是在通过 Odoo 请求交易时需要在客户的 [app](https://alanhou.org/odoo-13-in-app-purchase/#iap-odoo-app) 中进行提供的。(如 `self.env['iap.account].get(name)`)。作为一个良好实践，它应当与你的应用名称相匹配。
 87 | - `label` - `Label`: 这个名称在客户端的购买门户上显示。
 88 | 
 89 | ### ⚠️警告
 90 | 
 91 | [`ServiceName`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceName) 和 `Label` 都是唯一的。作为良好实践， [`ServiceName`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceName) 通常应与 Odoo客户端应用名称相匹配。
 92 | 
 93 | - `icon` - `Icon`: 在你的[服务包](https://alanhou.org/odoo-13-in-app-purchase/#iap-packages)中作为默认的图标。
 94 | - `key` - [`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey): 在IAP中标识你的开发者密钥 (参见 [你的服务](#iap-service)) 并允许从客户端中提取积分。它仅好在创建服务时显示一次，并且可随意进行重新生成。
 95 | 
 96 | ### 🚫危险
 97 | 
 98 | 你的 [`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey) 是一个密钥，泄漏服务密钥会导致其他应用开发人员可提供你的服务所赚取的积分。
 99 | 
100 | - `试用积分` - `Float`: 对应你准备为第一次使用应用的用户所提供的积分。注意这类服务仅对有企业合同在身的用户可用。
101 | - `隐私政策` - `PrivacyPolicy`: 这是一个可访问你的服务隐私政策的链接。应明确表明**所收集的信息**，如何**使用信息**，与你的服务的**关联性**，并告知客户他们如何**访问、更新或删除他们的个人信息。**
102 | 
103 | ![img](https://www.odoo.com/documentation/13.0/_images/menu.png)![img](https://www.odoo.com/documentation/13.0/_images/service_list.png)![img](https://www.odoo.com/documentation/13.0/_images/creating_service.png)![img](https://www.odoo.com/documentation/13.0/_images/service_created.png)然后你可以创建客户使用你的服务可购买的 *积分包*。
104 | 
105 | 
106 | 
107 | ### 积分包
108 | 
109 | 积分包是一个具有五大特性的产品：
110 | 
111 | - 名称：包的名称，
112 | - 图标：服务包的具体图标 (如未提供，则回到使用服务图标)，
113 | - 描述：出现在购买页面及发票上的服务包详情，
114 | - 额度：在购买包时客户可获取的积分额度，
115 | - 价格：价格为欧元 (截至目前，有规划对美元的支持)。
116 | 
117 | Odoo对每个包的销售提取 25%的佣金。相应地调整你的售卖价格。
118 | 
119 | 根据策略不足，每个积分的价格在不同包间可不同。
120 | 
121 | ![img](https://www.odoo.com/documentation/13.0/_images/package.png)
122 | 
123 | 
124 | 
125 | ### Odoo应用
126 | 
127 | 第二步是开发一个客户可在 Odoo实例中安装的 [Odoo应用](https://www.odoo.com/apps) 并且通过它他们可以*请求*你所提供的服务。我们的应用将仅向Partner表单提供一个按钮来让用户请求使用 一段时间服务器上的CPU。
128 | 
129 | 首先，我们将根据`iap`创建一个 *odoo 模块* 。IAP是一个标准的 V11 模块并且其依赖确保本地账户进行了相应的配置，我们将可以访问一些必要的视图和有用的帮助信息。
130 | 
131 | *coalroller/__manifest__.py*
132 | 
133 | ```
134 | {
135 |     'name': "Coal Roller",
136 |     'category': 'Tools',
137 |     'depends': ['iap'],
138 | }
139 | ```
140 | 
141 | *coalroller/__init__.py*
142 | 
143 | ```
144 | # -*- coding: utf-8 -*-
145 | ```
146 | 
147 | 然后， 集成的 “本地” 方面。这里我们将仅向伙伴视图添加一个动作按钮，但你完全可以通过你的应用提供本地值及通过远程服务提供额外的部分。
148 | 
149 | *coalroller/__manifest__.py*
150 | 
151 | ```
152 |     'name': "Coal Roller",
153 |     'category': 'Tools',
154 |     'depends': ['iap'],
155 |     'data': [
156 |         'views/views.xml',
157 |     ],
158 | }
159 | ```
160 | 
161 | *coalroller/views/views.xml*
162 | 
163 | ```
164 | <odoo>
165 |   <record model="ir.ui.view" id="partner_form_coalroll">
166 |     <field name="name">partner.form.coalroll</field>
167 |     <field name="model">res.partner</field>
168 |     <field name="inherit_id" ref="base.view_partner_form" />
169 |     <field name="arch" type="xml">
170 |       <xpath expr="//div[@name='button_box']">
171 |         <button type="object" name="action_partner_coalroll"
172 |                 class="oe_stat_button" icon="fa-gears">
173 |           <div class="o_form_field o_stat_info">
174 |             <span class="o_stat_text">Roll Coal</span>
175 |           </div>
176 |         </button>
177 |       </xpath>
178 |     </field>
179 |   </record>
180 | </odoo>
181 | ```
182 | 
183 | ![img](https://www.odoo.com/documentation/13.0/_images/button.png)现在我们可以实现动作方法/回调。这将调用我们自己的服务端。
184 | 
185 | 对服务应用和服务端的通讯协议和服务器并没有什么要求，但 `iap` 提供了一个 `jsonrpc()` 帮助方法来调用其它 Odoo 实例上的[JSON-RPC2](https://www.jsonrpc.org/specification) 端点并透明地重新抛出相关Odoo异常 ([`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError), `odoo.exceptions.AccessError` 和 `odoo.exceptions.UserError`).
186 | 
187 | 在这个调用中，我们需要提供：
188 | 
189 | - 任意相关的客户端参数(此处没有)，
190 | - 由 `iap.account` 模型的 `account_token` 字段提供的当前客户端`token`。你可以通过调用`env['iap.account'].get(*service_name*)` 来获取服务的账户，其中[`service_name`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceName) 是注册在IAP端点的服务名称。
191 | 
192 | *coalroller/__init__.py*
193 | 
194 | ```
195 | # -*- coding: utf-8 -*-
196 | from . import models
197 | ```
198 | 
199 | *coalroller/models/__init__.py*
200 | 
201 | ```
202 | from . import res_partner
203 | ```
204 | 
205 | *coalroller/models/res_partner.py*
206 | 
207 | ```
208 | # -*- coding: utf-8 -*-
209 | from odoo import api, models
210 | from odoo.addons.iap import jsonrpc, InsufficientCreditError
211 | 
212 | # whichever URL you deploy the service at, here we will run the remote
213 | # service in a local Odoo bound to the port 8070
214 | DEFAULT_ENDPOINT = 'http://localhost:8070'
215 | class Partner(models.Model):
216 |     _inherit = 'res.partner'
217 |     def action_partner_coalroll(self):
218 |         # fetch the user's token for our service
219 |         user_token = self.env['iap.account'].get('coalroller')
220 |         params = {
221 |             # we don't have any parameter to provide
222 |             'account_token': user_token.account_token
223 |         }
224 |         # ir.config_parameter allows locally overriding the endpoint
225 |         # for testing & al
226 |         endpoint = self.env['ir.config_parameter'].sudo().get_param('coalroller.endpoint', DEFAULT_ENDPOINT)
227 |         jsonrpc(endpoint + '/roll', params=params)
228 |         return True
229 | ```
230 | 
231 | `iap` 自动处理来自动作的 [`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError) 并弹出让用户向自己的账户添加积分。
232 | 
233 | `jsonrpc()` 替你处理 [`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError) 重新抛出。
234 | 
235 | ### 🚫危险
236 | 
237 | 如果你不使用 `jsonrpc()` ，则*必须*在处理器中谨慎抛出 [`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError) ，否则不会跳出让用户向账户扣积分操作，下一次的调用会以相同的方式失败。
238 | 
239 | 
240 | 
241 | ### 服务
242 | 
243 | 虽然并非必须，因为 `iap` 为 [JSON-RPC2](https://www.jsonrpc.org/specification)调用(`jsonrpc()`) 提供了客户端帮助方法并为事务 ([`charge`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.charge)) 提供了服务帮助方法，但我们还可以用 Odoo模块实现服务层面：
244 | 
245 | *coalroller_service/__init__.py*
246 | 
247 | ```
248 | # -*- encoding: utf-8 -*-
249 | ```
250 | 
251 | *coalroller_service/__manifest__.py*
252 | 
253 | ```
254 | {
255 |     'name': "Coal Roller Service",
256 |     'category': 'Tools',
257 |     'depends': ['iap'],
258 | }
259 | ```
260 | 
261 | 因为来自客户端的查询以 [JSON-RPC2](https://www.jsonrpc.org/specification) 的形式出现，我们需要对应的控制器，它可以调用[`charge`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.charge)并执行其中的服务：
262 | 
263 | *coalroller_service/controllers/main.py*
264 | 
265 | ```
266 | import time
267 | 
268 | from passlib import pwd, hash
269 | 
270 | from odoo import http
271 | from odoo.addons.iap import charge
272 | 
273 | class CoalBurnerController(http.Controller):
274 |     @http.route('/roll', type='json', auth='none', csrf='false')
275 |     def roll(self, account_token):
276 |         # the service key *is a secret*, it should not be committed in
277 |         # the source
278 |         service_key = self.env['ir.config_parameter'].sudo().get_param('coalroller.service_key')
279 | 
280 |         # we charge 1 credit for 10 seconds of CPU
281 |         cost = 1
282 |         # TODO: allow the user to specify how many (tens of seconds) of CPU they want to use
283 |         with charge(http.request.env, service_key, account_token, cost):
284 | 
285 |             # 10 seconds of CPU per credit
286 |             end = time.time() + (10 * cost)
287 |             while time.time() < end:
288 |                 # we will use CPU doing useful things: generating and
289 |                 # hashing passphrases
290 |                 p = pwd.genphrase()
291 |                 h = hash.pbkdf2_sha512.hash(p)
292 |         # here we don't have anything useful to the client, an error
293 |         # will be raised & transmitted in case of issue, if no error
294 |         # is raised we did the job
295 | ```
296 | 
297 | *coalroller_service/controllers/__init__.py*
298 | 
299 | ```
300 | # -*- encoding: utf-8 -*-
301 | from . import main
302 | ```
303 | 
304 | *coalroller_service/__init__.py*
305 | 
306 | ```
307 | # -*- encoding: utf-8 -*-
308 | from . import controllers
309 | ```
310 | 
311 | [`charge`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.charge) 帮助方法将：
312 | 
313 | 1. 通过具体积分额授权（创建）事务，如果账户没有足够积分，将会报出相关错误
314 | 2. 执行 `with`语句体
315 | 3. 如果 `with` 体执行成功，在需要时更新交易的价格
316 | 4. 捕获（确认）交易
317 | 5. 否则，如果从 `with`体中抛出错误，取消交易 (并释放所保留的积分)
318 | 
319 | ### 🚫危险
320 | 
321 | 默认， [`charge`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.charge) 连接*生产环境* IAP端点 [https://iap.odoo.com](https://iap.odoo.com/).。而在开发及测试服务时，你可能会希望指向*开发环境* IAP 端点 [https://iap-sandbox.odoo.com](https://iap-sandbox.odoo.com/)。
322 | 
323 | 要实现这点，在Odoo服务中设置`iap.endpoint`配置参数：在调试/开发模式下，访问Setting ‣ Technical ‣ Parameters ‣ System Parameters，仅为 `iap.endpoint` （如尚未存在）端点定义入口。
324 | 
325 | [`charge`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.charge) 帮助方法有两个额外的可选参数，我们可用于让内容对终端用户更为清晰。
326 | 
327 | - `description`
328 | 
329 |   是一条消息，它与交易相关联并将在用户的仪表盘中显示，有助于提醒用户为什么存在这笔费用。
330 | 
331 | - `credit_template`
332 | 
333 |   是[QWeb](https://alanhou.org/odoo-13-qweb/#reference-qweb) 模板的名称，它将在用户积分不足以支付服务商所请求的金额时进行渲染并显示给用户，其目的是告诉用户为什么他们会对IAP内容感兴趣。
334 | 
335 | *coalroller_service/controllers/main.py*
336 | 
337 | ```
338 |     def roll(self, account_token):
339 |         # the service key *is a secret*, it should not be committed in
340 |         # the source
341 |         service_key = http.request.env['ir.config_parameter'].sudo().get_param('coalroller.service_key')
342 | 
343 |         # we charge 1 credit for 10 seconds of CPU
344 |         cost = 1
345 |         # TODO: allow the user to specify how many (tens of seconds) of CPU they want to use
346 |         with charge(http.request.env, service_key, account_token, cost,
347 |                     description="We're just obeying orders",
348 |                     credit_template='coalroller_service.no_credit'):
349 | 
350 |             # 10 seconds of CPU per credit
351 |             end = time.time() + (10 * cost)
352 | ```
353 | 
354 | *coalroller_service/views/no-credit.xml*
355 | 
356 | ```
357 | <odoo>
358 |   <template id="no_credit" name="No credit warning">
359 |     <div>
360 |       <div class="container-fluid">
361 |         <div class="row">
362 |           <div class="col-md-7 offset-lg-1 mt32 mb32">
363 |             <h2>Consume electricity doing nothing useful!</h2>
364 |             <ul>
365 |               <li>Heat our state of the art data center for no reason</li>
366 |               <li>Use multiple watts for only 0.1€</li>
367 |               <li>Roll coal without going outside</li>
368 |             </ul>
369 |           </div>
370 |         </div>
371 |       </div>
372 |     </div>
373 |   </template>
374 | </odoo>
375 | ```
376 | 
377 | *coalroller_service/__manifest__.py*
378 | 
379 | ```
380 |     'name': "Coal Roller Service",
381 |     'category': 'Tools',
382 |     'depends': ['iap'],
383 |     'data': [
384 |         'views/no-credit.xml',
385 |     ],
386 | }
387 | ```
388 | 
389 | ## [JSON-RPC2](https://www.jsonrpc.org/specification) 交易API
390 | 
391 | ![img](https://www.odoo.com/documentation/13.0/_images/flow.png)
392 | 
393 | - IAP 交易 API 不要求在实现服务端网关时使用Odoo，调用是标准的 [JSON-RPC2](https://www.jsonrpc.org/specification)。
394 | - 调用使用不同的*端点* 但对所有端点是相同的*方法* (`call`)。
395 | - 异常以 [JSON-RPC2](https://www.jsonrpc.org/specification) 错误的形式返回，正式的异常名可在程序操作中通过 `data.name` 获取。
396 | 
397 | ### 授权
398 | 
399 | ###### `/iap/1/authorize`
400 | 
401 | 验证用户的账户中至少有可用 `积分` 并对该金额创建一个 *预授权(等待交易) 。*
402 | 
403 | 任意当前由进行中交易所预授权的金额都进一步的授权调用都是不可用的。
404 | 
405 | 返回 [`TransactionToken`](https://alanhou.org/odoo-13-in-app-purchase/#TransactionToken) 标识进行中的交易为可用于捕获 (确认) 或取消所涉及的交易。
406 | 
407 | 参数
408 | 
409 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
410 | - **account_token** ([`UserToken`](https://alanhou.org/odoo-13-in-app-purchase/#UserToken)) –
411 | - **credit** ([`float`](https://docs.python.org/3/library/functions.html#float)) –
412 | - **description** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – 可选，帮助用户知晓账户中扣费的原因
413 | - **dbuuid** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) – 可选，让用户在其数据库有效时利用试用积分 (参见 [注册服务](https://alanhou.org/odoo-13-in-app-purchase/#register-service))
414 | 
415 | 若授权成功，返回
416 | 
417 | [`TransactionToken`](https://alanhou.org/odoo-13-in-app-purchase/#TransactionToken)
418 | 
419 | 若服务令牌无效，抛出
420 | 
421 | ```
422 | AccessError
423 | ```
424 | 
425 | 若账户无足够余额，抛出
426 | 
427 | [`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError)
428 | 
429 | 若`credit`值不为整型或浮点型，抛出
430 | 
431 | ```
432 | TypeError
433 | r = requests.post(ODOO + '/iap/1/authorize', json={
434 |     'jsonrpc': '2.0',
435 |     'id': None,
436 |     'method': 'call',
437 |     'params': {
438 |         'account_token': user_account,
439 |         'key': SERVICE_KEY,
440 |         'credit': 25,
441 |         'description': "Why this is being charged",
442 |     }
443 | }).json()
444 | if 'error' in r:
445 |     # handle authorize error
446 | tx = r['result']
447 | 
448 | # provide your service here
449 | ```
450 | 
451 | ### 捕获
452 | 
453 | ###### `/iap/1/capture`
454 | 
455 | 确定具体的交易，将保留的积分从用户账户转账到服务提供方账户。
456 | 
457 | 捕获调用是幂等的：对已捕获交易执行捕获调用不会有任何效果。
458 | 
459 | 参数
460 | 
461 | - **token** ([`TransactionToken`](https://alanhou.org/odoo-13-in-app-purchase/#TransactionToken)) –
462 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
463 | - **credit_to_capture** ([`float`](https://docs.python.org/3/library/functions.html#float)) – 可选参数，用于捕获少于预授权的积分的金额
464 | 
465 | 异常后抛出
466 | 
467 | ```
468 | AccessError
469 |   r2 = requests.post(ODOO + '/iap/1/capture', json={
470 |       'jsonrpc': '2.0',
471 |       'id': None,
472 |       'method': 'call',
473 |       'params': {
474 |           'token': tx,
475 |           'key': SERVICE_KEY,
476 |           'credit_to_capture': credit or False,
477 |       }
478 |   }).json()
479 |   if 'error' in r:
480 |       # handle capture error
481 |   # otherwise transaction is captured
482 | ```
483 | 
484 | ### 取消
485 | 
486 | ###### `/iap/1/cancel`
487 | 
488 | 取消具体的交易，释放所保留的用户积分。
489 | 
490 | 取消调用是幂等的：对已取消调用执行捕获调用不会产生任何效果。
491 | 
492 | 参数
493 | 
494 | - **token** ([`TransactionToken`](https://alanhou.org/odoo-13-in-app-purchase/#TransactionToken)) –
495 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
496 | 
497 | 异常抛出
498 | 
499 | ```
500 | AccessError
501 | r2 = requests.post(ODOO + '/iap/1/cancel', json={
502 |     'jsonrpc': '2.0',
503 |     'id': None,
504 |     'method': 'call',
505 |     'params': {
506 |         'token': tx,
507 |         'key': SERVICE_KEY,
508 |     }
509 | }).json()
510 | if 'error' in r:
511 |     # handle cancel error
512 | # otherwise transaction is cancelled
513 | ```
514 | 
515 | ### 类型
516 | 
517 | 异常放到一边，这些用于清晰化的*抽象类型*， 无需关心其底层实现。
518 | 
519 | ###### `*class* ServiceName`
520 | 
521 | 字符串标识你在 [https://iap.odoo.com](https://iap.odoo.com/) (生产环境)上的服务以及在客户端数据库中与服务相关联的账户。
522 | 
523 | ###### `*class* ServiceKey`
524 | 
525 | 为提供者的服务所生成的标识符。 每个键（及服务）与一个由服务提供者生成的固定值令牌相匹配。
526 | 
527 | 多种类型的令牌对应多个服务。举个例子，SMS 和 MMS 可以是相同的服务 (一条 MMS 等价于多条SMS) or 或不同价格的不同服务。
528 | 
529 | ### 🚫危险
530 | 
531 | 服务密钥需要*保密，*泄漏服务密钥会让其它应用的开发者可以提取出你的服务所赚得的积分。
532 | 
533 | ###### `*class* UserToken`
534 | 
535 | 用于用户账户的标识符。
536 | 
537 | ###### `*class* TransactionToken`
538 | 
539 | 事务标识符，由授权过程返回并由捕获或取消交易进行消费。
540 | 
541 | ###### `*exception* odoo.addons.iap.models.iap.InsufficientCreditError`
542 | 
543 | 如果在账户中当前没有所请求的积分时在交易授权过程中抛出（没有足够积分或过多待完成交易/已有保留授权）。
544 | 
545 | ###### `*exception* odoo.exceptions.AccessError`
546 | 
547 | 由以下抛出：
548 | 
549 | - 如果服务令牌无效，对于要求有服务令牌的任意操作；
550 | - 跨服务端调用的任意错误。(经常是在 `jsonrpc()`中)。
551 | 
552 | ###### `*exception* odoo.exceptions.UserError`
553 | 
554 | 在对应用开发者（也就是你）的审查时由任意预期外行为抛出。
555 | 
556 | ### 测试API
557 | 
558 | 为测试已开发应用， 我们推荐使用沙盒平台，这样你可以：
559 | 
560 | 1. 从客户视角测试整个流程 - 可能产生的实际服务和交易。 (当然这要求修改端点，参见[服务](#iap-service)中的危险事项).
561 | 2. 测试API。
562 | 
563 | 后者在具体的仅在**IAP沙盒**中生效的令牌中存在。
564 | 
565 | - 令牌 `000000`: 表示一个不存在的账户。在尝试授权时返回[`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError) 。
566 | - 令牌 `000111`: 表示执行任意服务积分不足的账户。在尝试授权时返回 [`InsufficientCreditError`](https://alanhou.org/odoo-13-in-app-purchase/#odoo.addons.iap.models.iap.InsufficientCreditError) 。
567 | - 令牌 `111111`: 表示执行任意服务时具有足够积分的账户。尝试授权时会返回一个由捕获和取消路由所处理的交易令牌。
568 | 
569 | - 这些令牌仅在IAP - 沙盒服务端有效。
570 | - 服务密钥在这个流程中完全被忽略。如果想要对服务运行健壮的测试，应当忽略这些令牌。
571 | 
572 | ## Odoo帮助类
573 | 
574 | 为方便起见，如果使用Odoo实现服务， `iap` 模块提供一些让 IAP 流程更为简单的帮助类。
575 | 
576 | 
577 | 
578 | ### 收费
579 | 
580 | ###### `*class* odoo.addons.iap.models.iap.charge(*env*, *key*, *account_token*, *credit*[, *dbuuid*, *description*, *credit_template*])`
581 | 
582 | 用于授权及自动捕获或取消后台/代理使用的交易的*上下文管理器*。
583 | 
584 | 运行方式类似于游标（cursor）上下文管理器：
585 | 
586 | - 立即通过具体的参数授权交易；
587 | - 执行 `with` 体；
588 | - 如果内容体完整执行且未报错，则捕获交易；
589 | - 否则取消交易。
590 | 
591 | 参数
592 | 
593 | - **env** (`odoo.api.Environment`) – 用于获取 `iap.endpoint` 配置密钥
594 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
595 | - **token** ([`UserToken`](https://alanhou.org/odoo-13-in-app-purchase/#UserToken)) –
596 | - **credit** ([`float`](https://docs.python.org/3/library/functions.html#float)) –
597 | - **description** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) –
598 | - **模板 credit_template** (`Qweb`) –
599 | 
600 | ```
601 |   @route('/deathstar/superlaser', type='json')
602 |   def superlaser(self, user_account,
603 |                  coordinates, target,
604 |                  factor=1.0):
605 |       """
606 |       :param factor: superlaser power factor,
607 |                      0.0 is none, 1.0 is full power
608 |       """
609 |       credits = int(MAXIMUM_POWER * factor)
610 |       description = "We will demonstrate the power of this station on your home planet of Alderaan."
611 |       with charge(request.env, SERVICE_KEY, user_account, credits, description) as transaction:
612 |           # TODO: allow other targets
613 |           transaction.credit = max(credits, 2)
614 |           # Sales ongoing one the energy price,
615 |           # a maximum of 2 credits will be charged/captured.
616 |           self.env['systems.planets'].search([
617 |               ('grid', '=', 'M-10'),
618 |               ('name', '=', 'Alderaan'),
619 |           ]).unlink()
620 | ```
621 | 
622 | ### 授权
623 | 
624 | ###### `*class* odoo.addons.iap.models.iap.authorize(*env*, *key*, *account_token*, *credit*[, *dbuuid*, *description*, *credit_template*])`
625 | 
626 | 将授权所有操作。
627 | 
628 | 参数
629 | 
630 | - **env** (`odoo.api.Environment`) – 用于获取 `iap.endpoint` 配置密钥
631 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
632 | - **token** ([`UserToken`](https://alanhou.org/odoo-13-in-app-purchase/#UserToken)) –
633 | - **credit** ([`float`](https://docs.python.org/3/library/functions.html#float)) –
634 | - **description** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) –
635 | - **template credit_template** (`Qweb`) –
636 | 
637 | ```
638 |   @route('/deathstar/superlaser', type='json')
639 |   def superlaser(self, user_account,
640 |                  coordinates, target,
641 |                  factor=1.0):
642 |       """
643 |       :param factor: superlaser power factor,
644 |                      0.0 is none, 1.0 is full power
645 |       """
646 |       credits = int(MAXIMUM_POWER * factor)
647 |       description = "We will demonstrate the power of this station on your home planet of Alderaan."
648 |       #actual IAP stuff
649 |       transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
650 |       try:
651 |           # Beware the power of this laser
652 |           self.put_galactical_princess_in_sorrow()
653 |       except Exception as e:
654 |           # Nevermind ...
655 |           r = cancel(env,transaction_token, key)
656 |           raise e
657 |       else:
658 |           # We shall rule over the galaxy!
659 |           capture(env,transaction_token, key, min(credits, 2))
660 | ```
661 | 
662 | ### 取消
663 | 
664 | ###### `*class* odoo.addons.iap.models.iap.cancel(*env*, *transaction_token*, *key*)`
665 | 
666 | 将取消已授权交易。
667 | 
668 | 参数
669 | 
670 | - **env** (`odoo.api.Environment`) – 用于获取 `iap.endpoint` 配置密钥
671 | - **transaction_token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) –
672 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
673 | 
674 | ```
675 |   @route('/deathstar/superlaser', type='json')
676 |   def superlaser(self, user_account,
677 |                  coordinates, target,
678 |                  factor=1.0):
679 |       """
680 |       :param factor: superlaser power factor,
681 |                      0.0 is none, 1.0 is full power
682 |       """
683 |       credits = int(MAXIMUM_POWER * factor)
684 |       description = "We will demonstrate the power of this station on your home planet of Alderaan."
685 |       #actual IAP stuff
686 |       transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
687 |       try:
688 |           # Beware the power of this laser
689 |           self.put_galactical_princess_in_sorrow()
690 |       except Exception as e:
691 |           # Nevermind ...
692 |           r = cancel(env,transaction_token, key)
693 |           raise e
694 |       else:
695 |           # We shall rule over the galaxy!
696 |           capture(env,transaction_token, key, min(credits, 2))
697 | ```
698 | 
699 | ### 捕获
700 | 
701 | ###### `*class* odoo.addons.iap.models.iap.capture(*env*, *transaction_token*, *key*, *credit*)`
702 | 
703 | 将对给定交易捕获取 `credit` 金额。
704 | 
705 | 参数
706 | 
707 | - **env** (`odoo.api.Environment`) – 用于获取 `iap.endpoint` 配置密钥
708 | - **transaction_token** ([`str`](https://docs.python.org/3/library/stdtypes.html#str)) –
709 | - **key** ([`ServiceKey`](https://alanhou.org/odoo-13-in-app-purchase/#ServiceKey)) –
710 | - **credit** –
711 | 
712 | ```
713 |   @route('/deathstar/superlaser', type='json')
714 |   def superlaser(self, user_account,
715 |                  coordinates, target,
716 |                  factor=1.0):
717 |       """
718 |       :param factor: superlaser power factor,
719 |                      0.0 is none, 1.0 is full power
720 |       """
721 |       credits = int(MAXIMUM_POWER * factor)
722 |       description = "We will demonstrate the power of this station on your home planet of Alderaan."
723 |       #actual IAP stuff
724 |       transaction_token = authorize(request.env, SERVICE_KEY, user_account, credits, description=description)
725 |       try:
726 |           # Beware the power of this laser
727 |           self.put_galactical_princess_in_sorrow()
728 |       except Exception as e:
729 |           # Nevermind ...
730 |           r = cancel(env,transaction_token, key)
731 |           raise e
732 |       else:
733 |           # We shall rule over the galaxy!
734 |           capture(env,transaction_token, key, min(credits, 2))
735 | ```


--------------------------------------------------------------------------------
/tutorials/theme-tutorial.md:
--------------------------------------------------------------------------------
  1 | # 主题教程
  2 | 
  3 | 本文来自[Odoo 13官方文档之开发者文档](../README.md)系列文章
  4 | 
  5 | Odoo热爱自由。自由让设计师可以更进一步，自由让用户可以根据自己的需求来进行自定义。
  6 | 
  7 | 准备好创建自己的主题了吗？很好。在开始前应该要知道一些内容。本教程旨在引导读者创建一个Odoo主题。
  8 | 
  9 | ![Odoo 13开发者文档：主题教程](https://www.odoo.com/documentation/13.0/_images/Intro.jpg)
 10 | 
 11 | ## 针对网页设计师的导言
 12 | 
 13 | 如果你是初次使用Odoo的网页设计师，就来对地方了。本导言将勾勒出Odoo主题创建的基本框架。
 14 | 
 15 | Odoo团队创建了一个强大且易于使用的框架。使用这套工具无需预知任何特殊的语法。
 16 | 
 17 | ### 从常用CMS转向Odoo
 18 | 
 19 | 如果你经常使用同一种方式思考和工作，那么很可能得到的是相同的结果。如果想要一些全新的结果，那么请尝试一些新的事物。
 20 | 
 21 | > header.php文件来哪里呢?
 22 | 
 23 | 这通常是习惯于使用Wordpress或Joomla的网页设计师在初次使用 Odoo 时所会问到的问题。
 24 | 
 25 | ![img](https://www.odoo.com/documentation/13.0/_images/cms.jpg)
 26 | 
 27 | 确实，在使用常见的CMS时，你需要对多个文件进行代码编写(如header.php, page.php, post.php等等)来为网站创建基本结构。使用这些系统，这一基本结构作为一个设计基础，可以随着时间推移不断更新来确保CMS的兼容性。因此可能在编写几个小时的代码之后还没有真正的开始设计的工作。
 28 | 
 29 | 对于 Odoo 主题则**并非**如此。
 30 | 
 31 | 我们认为主题设计应当简洁（而强大）。在创建我们的网站构造器时，我们决定从头开始而不是依赖于已有的其它框架。这一方法让我们有足够的自由去集中到对设计师真正重要的部分：样式、内容和它们背后的逻辑。而无需再挣扎于技术的细枝末节。
 32 | 
 33 | ### Odoo默认主题结构
 34 | 
 35 | Odoo自带默认的主题结构。这是一个基本的“主题”，它提供最小的结构和布局。在新建主题时，你实际上是在对进行扩展。它在设置中保持启用并扮演像前面提到的CMS基础结构相似的角色，只是你无需创建并维护。它会在你的Odoo安装包中自动进行升级，因为其包含于网站构造器模块之中，默认所有部分都平滑的集成于其中
 36 | 
 37 | 结果是，你可以完全的自由集中于设计上，由这个结构来完成集成和功能的任务。
 38 | 
 39 | ![img](https://www.odoo.com/documentation/13.0/_images/def_structure.jpg)
 40 | 
 41 | **主要功能：**
 42 | 
 43 | - 页面、博客和电商的基本布局
 44 | - 集成网站构造器
 45 | - 基础代码片断
 46 | - 自动化的Less/Sass编译
 47 | - 自动化的Js和CSS最小化和合并
 48 | 
 49 | **主要技术:**
 50 | 
 51 | - Twitter Bootstrap
 52 | - jQuery
 53 | - jQuery UI
 54 | - underscore.js
 55 | 
 56 | ## “模块化”思维
 57 | 
 58 | Odoo主题不是一个包含HTML或PHP文件的文件夹，它是一个使用XML编写的模块化的框架。以前从来没使用过XML文件？不必担心，在学习了本课程后，你就可以通过很基础的 HTML 知识来创建自己的每一个主题了。
 59 | 
 60 | 使用经典的网页设计工作流，你通常要编写整个页面的布局。这样的结果是一个“静态”网页。当然可以更新内容，但你的客户会需要你来完成哪怕是最基础的修改。
 61 | 
 62 | 为Odoo创建主题是一个全新的体验。你无需定义页面的整个布局，只要创建代码块（代码片断）来让用户选择在何处“拖放”它们，自己创建页面布局。我们称其为模块化设计。
 63 | 
 64 | 想像Odoo主题是一个由创建并定义样式的元素和选项“列表”。作为设计师，你的目标是设计这些元素的样式来实现美妙的效果，而无需关注终端用户把它们放在哪里。
 65 | 
 66 | 让我们开启“列表”元素之旅吧：
 67 | 
 68 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet.jpg)
 69 | 
 70 | #### 代码片断 (或构造版块)
 71 | 
 72 | 一段HTML代码。 用户可以使用我们内置的网站构造器界面拖放、修改并修改它们。你可以定义为每个片断定义一组选项和样式。用户可以根据他们的需求进行选择。
 73 | 
 74 | ![img](https://www.odoo.com/documentation/13.0/_images/page.jpg)
 75 | 
 76 | #### 页面
 77 | 
 78 | 这些是普通的网页，只是对于终端用户可编辑并且可以你可以定义一个空的区域让用户可以通过把代码片断拖放到其中进行“填充”。
 79 | 
 80 |  
 81 | 
 82 | ![img](https://www.odoo.com/documentation/13.0/_images/styles.jpg)
 83 | 
 84 | #### 样式
 85 | 
 86 | 样式通过使用标准CSS文件(或Less/Sass)。你可以将样式定义为 **默认**或 **可选**。默认样式在主题中总是处于活跃状态，可选样式可以由用户启用或禁用。
 87 | 
 88 | ![img](https://www.odoo.com/documentation/13.0/_images/functionalities.jpg)
 89 | 
 90 | #### 功能
 91 | 
 92 | 借助于Odoo的模块化，所有内容可以做进下的自定义化。这表示有无限发挥你的创意的可能。添加功能很容易，为终端用户提供自定义选项也很简单。
 93 | 
 94 | ### Odoo的XML文件概览
 95 | 
 96 | 任意Odoo XML文件都以编码的定义开启。之后，可以在 `<odoo>` 标签中编写代码
 97 | 
 98 | ```
 99 | [XML] 
100 | <?xml version="1.0" encoding="utf-8" ?> 
101 | <odoo>
102 |    ## 此处编写代码 
103 | </odoo>
104 | ```
105 | 
106 | 几乎你所创建的所有元素和选项都要放在 `<template>` 标签中，如下例所示。
107 | 
108 | ```
109 | [XML]
110 |  <template id="my_title" name="My title">
111 | 	<h1>This is an HTML block</h1>
112 |   <h2 class="lead">And this is a subtitle</h2
113 | </template>
114 | ```
115 | 
116 | ### 划重点
117 | 
118 | 不要误解 `template` 的含义。template标签仅用于定义一段html代码或选项 - 但不定与元素的视觉排列相关。
119 | 
120 | 上面的代码定义了一个标题，但它不会在任何地方显示，因为该*template*没有与**Odoo默认结构** 存在任何关联。要进行关联，可以使用**xpath**, **qWeb** 或两者混用。
121 | 
122 | 继续阅读本教程来学习如何使用你自己的代码进行适当的扩展。
123 | 
124 | ### 更新你的主题
125 | 
126 | 因为XML文件仅在安装主题时进行加载，你需要在每次对xml文件进行修改时强制进行重载。
127 | 
128 | 要进行重载，点击模块页面中的升级（Upgrade）按钮。
129 | 
130 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)
131 | 
132 | ![img](https://www.odoo.com/documentation/13.0/_images/upgrade_module.png)
133 | 
134 | ## 创建一个主题模块
135 | 
136 | Odoo的主题像模块那样进行了打包。即使是为公司或客户设计一个很简单的网站，也需要将主题打包成Odoo模块。
137 | 
138 | - `main folder`
139 | 
140 |   创建一个文件夹并将其命名为： `theme_` 后接主题名。
141 | 
142 | - `__manifest__.py`
143 | 
144 |   创建一个空文档并将其保存到文件夹中，名为 `__manifest__.py`。这将包含你主题的配置信息。
145 | 
146 | - `__init__.py`
147 | 
148 |   创建一个空文件并命名为 `__init__.py`。这是必需的系统文件。创建后内容留空。
149 | 
150 | - `views` 和 `static` 文件夹
151 | 
152 |   在主文件夹中创建这两个文件夹。 在 `views` 中放置定义代码片断、页面和选项的 xml文件。`static` 文件夹是放置样式、图片和自定义 js 代码的相应位置。
153 | 
154 | ### 划重点
155 | 
156 | .在odoo 和 init 文件开头和结束处分别使用两个下划线字符，
157 | 
158 | 最终结果类似下面这样：
159 | 
160 | ![img](https://www.odoo.com/documentation/13.0/_images/folder.jpg)
161 | 
162 | ### 编辑 `__manifest__.py`
163 | 
164 | 打开所创建的 `__manifest__.py` 文件并复制/粘贴如下内容：
165 | 
166 | ```
167 | {
168 |   'name':'Tutorial theme',
169 |   'description': 'A description for your theme.',
170 |   'version':'1.0',
171 |   'author':'Your name',
172 | 
173 |   'data': [
174 |   ],
175 |   'category': 'Theme/Creative',
176 |   'depends': ['website'],
177 | }
178 | ```
179 | 
180 | 将前4个属性值替换为你所想要的内容。这些值将用于标识你在Odoo后台中的新主题。
181 | 
182 | `data` 属性将包含xml文件列表。现在是空的，但我们将添加新新建的文件。
183 | 
184 | `category` 定义你的模块分类（一直是“Theme”）并且在斜杠后放置子类别。可以使用Odoo应用分类列表的子分类。 (https://www.odoo.com/apps/themes)
185 | 
186 | `depends` 指定我们的主题正常运行所需的模块。对本课程的主题，只需要用到website。如果你还需要用到博客或电商功能，还需要添加下面这些模块。
187 | 
188 | ```
189 | ...
190 | 'depends': ['website', 'website_blog', 'sale'],
191 | ...
192 | ```
193 | 
194 | ### 安装你的主题
195 | 
196 | 要安装主题，需要将主题文件夹放到Odoo安装所在的addons目录中。
197 | 
198 | 然后，导航到Odoo的 **Website** 模块，进入Configuration ‣ Settings。
199 | 
200 | 在 **Website** 版块中，点击 **Choose a theme** 按钮，然后悬停在主题上并点击 **Use this theme**。
201 | 
202 | ## Odoo页面的结构
203 | 
204 | Odoo页面是一个两种元素组合的视觉结果： **cross-pages** 和 **unique**。默认，Odoo提供一个**Header** 和一个 **Footer** (跨页面) 以及包含让页面独特的内容的一个的主元素。
205 | 
206 | 跨页面元素在每个页面都相同。独立元素仅与特定页面相关。
207 | 
208 | ![img](https://www.odoo.com/documentation/13.0/_images/page_structure.jpg)To inspect the 默认布局，仅使用网站构造器新建一个页面。点击Content ‣ New Page并添加一个页面名称。使用浏览器查看页面元素。
209 | 
210 | ```
211 | <div id=“wrapwrap”>
212 |   <header />
213 |   <main />
214 |   <footer />
215 | </div>
216 | ```
217 | 
218 | ### 扩展默认 Header
219 | 
220 | 默认，Odoo的header 包含一个响应式的导航菜单和公司的logo。你可以轻易地对已有内容添加新元素或样式。.
221 | 
222 | 要进行添加，在**views**文件夹中创建一个**layout.xml** 文件并添加默认的Odoo xml 标记。
223 | 
224 | ```
225 | <?xml version="1.0" encoding="utf-8" ?>
226 | <odoo>
227 | 
228 | 
229 | 
230 | </odoo>
231 | ```
232 | 
233 | 在`<odoo>` 标签中新建一个模板，复制-粘贴以下代码：
234 | 
235 | ```
236 | <!-- Customize header  -->
237 | <template id="custom_header" inherit_id="website.layout" name="Custom Header">
238 | 
239 |   <!-- Assign an id  -->
240 |   <xpath expr="//div[@id='wrapwrap']/header" position="attributes">
241 |     <attribute name="id">my_header</attribute>
242 |   </xpath>
243 | 
244 |   <!-- Add an element after the top menu  -->
245 |   <xpath expr="//div[@id='wrapwrap']/header/div" position="after">
246 |     <div class="container">
247 |       <div class="alert alert-info mt16" role="alert">
248 |         <strong>Welcome</strong> in our website!
249 |       </div>
250 |     </div>
251 |   </xpath>
252 | </template>
253 | ```
254 | 
255 | 第一个xpath将在header添加 id `my_header` 。最好的方法是将css规则定位到该元素并且避免影响到页面上的其它内容。
256 | 
257 | ### 警告
258 | 
259 | 在替换默认元素属性时要非常小心。因为你的主题会继承默认主题，你的修改优先级会高于未来Odoo的更新。
260 | 
261 | 第二个xpath将紧随导航菜单之后添加一条欢迎消息。
262 | 
263 | 最后一步是将layout.xml添加到主题所使用的xml文件列表中。此时应像下面这样编辑 `__manifest__.py` 文件：
264 | 
265 | ```
266 | 'data': [ 'views/layout.xml' ],
267 | ```
268 | 
269 | 更新你的主题
270 | 
271 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)非常棒！我们成功的在header中添加了一个id并在导航菜单中添加了一个元素。这些修改将应用于网站的每个页面。
272 | 
273 | ![img](https://www.odoo.com/documentation/13.0/_images/after-menu.png)
274 | 
275 | ## 创建一个具体的页面布局
276 | 
277 | 想像我们要创建一个服务页面的具体布局。对于这一页面，我们需要在顶部添加一个服务列表并赋予客户使用代码片段设置页面剩余内容的可能性。
278 | 
279 | 在*views* 文件夹内，创建一个 **pages.xml** 文件并添加默认的Odoo 标记。在 `<odoo>`中，代替 `<template>`的定义，我们将创建一个*page* 对象。
280 | 
281 | ```
282 | <?xml version="1.0" encoding="utf-8" ?>
283 | <odoo>
284 | 
285 |      <!-- === Services Page === -->
286 |      <record id="services_page" model="website.page">
287 |          <field name="name">Services page</field>
288 |          <field name="website_published">True</field>
289 |          <field name="url">/services</field>
290 |          <field name="type">qweb</field>
291 |          <field name="key">theme_tutorial.services_page</field>
292 |          <field name="arch" type="xml">
293 |              <t t-name="theme_tutorial.services_page_template">
294 |                  <h1>Our Services</h1>
295 |                  <ul class="services">
296 |                      <li>Cloud Hosting</li>
297 |                      <li>Support</li>
298 |                      <li>Unlimited space</li>
299 |                  </ul>
300 |              </t>
301 |          </field>
302 |      </record>
303 | 
304 |  </odoo>
305 | ```
306 | 
307 | 可以看到，页面中有很多额外的属性，如 *name* 或 可以进行访问的 *url* 。
308 | 
309 | 我们成功地创建了一个新页面布局，但还没有告诉系统**如何使用它**。这时，我们可以使用 **QWeb**。将html代码包裹在 `<t>` 标签中，如下例所示。
310 | 
311 | ```
312 | <!-- === Services Page === -->
313 | <record id="services_page" model="website.page">
314 |     <field name="name">Services page</field>
315 |     <field name="website_published">True</field>
316 |     <field name="url">/services</field>
317 |     <field name="type">qweb</field>
318 |     <field name="key">theme_tutorial.services_page</field>
319 |     <field name="arch" type="xml">
320 |         <t t-name="theme_tutorial.services_page_template">
321 |             <t t-call="website.layout">
322 |                 <div id="wrap">
323 |                     <div class="container">
324 |                         <h1>Our Services</h1>
325 |                         <ul class="services">
326 |                             <li>Cloud Hosting</li>
327 |                             <li>Support</li>
328 |                             <li>Unlimited space</li>
329 |                         </ul>
330 |                     </div>
331 |                 </div>
332 |             </t>
333 |         </t>
334 |     </field>
335 | </record>
336 | ```
337 | 
338 | 使用 `<t t-call="website.layout">`我们将通过自己的代码扩展Odoo的默认页面布局。
339 | 
340 | 可以看坏以，我们将自己的代码放到了两个 `<div>`中，一个带有 ID `wrap` ，另一个带有class `container`。这是提供最小化的布局。
341 | 
342 | 下一步是添加一个空区域，用户可以在其中添加代码片断。要实现这点，只需在封闭`div#wrap`元素前创建一个`oe_structure`类的 `div` 。
343 | 
344 | ```
345 | <?xml version="1.0" encoding="utf-8" ?>
346 | <odoo>
347 | 
348 |     <!-- === Services Page === -->
349 |     <record id="services_page" model="website.page">
350 |         <field name="name">Services page</field>
351 |         <field name="website_published">True</field>
352 |         <field name="url">/services</field>
353 |         <field name="type">qweb</field>
354 |         <field name="key">theme_tutorial.services_page</field>
355 |         <field name="arch" type="xml">
356 |             <t t-name="theme_tutorial.services_page_template">
357 |                 <t t-call="website.layout">
358 |                     <div id="wrap">
359 |                         <div class="container">
360 |                             <h1>Our Services</h1>
361 |                             <ul class="services">
362 |                                 <li>Cloud Hosting</li>
363 |                                 <li>Support</li>
364 |                                 <li>Unlimited space</li>
365 |                             </ul>
366 | 
367 |                             <!-- === Snippets' area === -->
368 |                             <div class="oe_structure" />
369 |                         </div>
370 |                     </div>
371 |                 </t>
372 |             </t>
373 |         </field>
374 |     </record>
375 | 
376 | </odoo>
377 | ```
378 | 
379 | 你可以创建所要数量的代码片断区域，并将它们放在页面的任意位置。
380 | 
381 | 值得一提的是我们前面所见的`<template>`指令有替代方法可创建页面。
382 | 
383 | ```
384 | <?xml version="1.0" encoding="utf-8" ?>
385 | <odoo>
386 | 
387 |     <!-- === Services Page === -->
388 |     <template id="services_page_template">
389 |         <t t-call="website.layout">
390 |             <div id="wrap">
391 |                 <div class="container">
392 |                     <h1>Our Services</h1>
393 |                     <ul class="services">
394 |                         <li>Cloud Hosting</li>
395 |                         <li>Support</li>
396 |                         <li>Unlimited space</li>
397 |                     </ul>
398 | 
399 |                     <!-- === Snippets' area === -->
400 |                     <div class="oe_structure" />
401 |                 </div>
402 |             </div>
403 |         </t>
404 |     </template>
405 |     <record id="services_page" model="website.page">
406 |         <field name="name">Services page</field>
407 |         <field name="website_published">True</field>
408 |         <field name="url">/services</field>
409 |         <field name="view_id" ref="services_page_template"/>
410 |     </record>
411 | 
412 | </odoo>
413 | ```
414 | 
415 | 这将允许页面内容使用 `<xpath>`做更进一步的自定义
416 | 
417 | 我们的页面准备基本完毕。现在需要在**__manifest__.py** 文件中添加**pages.xml**
418 | 
419 | ```
420 | 'data': [
421 |   'views/layout.xml',
422 |   'views/pages.xml'
423 | ],
424 | ```
425 | 
426 | 更新你的主题
427 | 
428 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)太好了，我们的服务页面已准备就绪，可以通过`<yourwebsite>/services`（以上我们所选择的URL）来进行访问了。
429 | 
430 | 你会注意到可以在 *Our Services*列表下方拖放代码片断。
431 | 
432 | ![img](https://www.odoo.com/documentation/13.0/_images/services_page_nostyle.png)现在让回到我们的*pages.xml* ，在页面模板后复制粘贴如下代码。
433 | 
434 | ```
435 | <record id="services_page_link" model="website.menu">
436 |   <field name="name">Services</field>
437 |   <field name="page_id" ref="services_page"/>
438 |   <field name="parent_id" ref="website.main_menu" />
439 |   <field name="sequence" type="int">99</field>
440 | </record>
441 | ```
442 | 
443 | 这段代码会为主菜单添加一个链接，指向我们所创建的页面。
444 | 
445 | ![img](https://www.odoo.com/documentation/13.0/_images/services_page_menu.png)**sequence** 属性定义了链接在顶部菜单的位置。在本例中，我们设置其值为 `99` 来将其放到最后。如果你希望将其放在具体的位置上，需要替换该值为所需的值。
446 | 
447 | 如你在`website`模块的*data.xml* 文件中所见，默认 **Home** 链接设置为`10` 而 **Contact us** 页面则设置为 `60` 。例如假如你想要将自己的链接放在**中间**，可以设置链接的排序为 `40`。
448 | 
449 | ## 添加样式
450 | 
451 | Odoo默认包含了 Bootstrap。这表示你可以马上使用所有的 Bootstrap 样式以及布局功能。
452 | 
453 | 当然如果你想要提供一个独特的页面 Bootstrap 是不够的。以下步骤将引导你了解如何为自己的主题添加自定义样式。最终的结果不会很漂亮，但可以提供足够的信息让你自己继续进行构建。
454 | 
455 | 我们先创建一个名为 **style.scss** 的空文件将将其放到static目录下名为 **scss** 的文件夹下。以下的规则会为我们的*服务*页面添加样式。复制粘贴并保存文件。
456 | 
457 | ```
458 | .services {
459 |     background: #EAEAEA;
460 |     padding: 1em;
461 |     margin: 2em 0 3em;
462 |     li {
463 |         display: block;
464 |         position: relative;
465 |         background-color: #16a085;
466 |         color: #FFF;
467 |         padding: 2em;
468 |         text-align: center;
469 |         margin-bottom: 1em;
470 |         font-size: 1.5em;
471 |     }
472 | }
473 | ```
474 | 
475 | 我们的文件准备就绪了，但还没有包含到主题当中。
476 | 
477 | 让我们导航到 view 文件夹并创建一个名为*a**ssets.xml*的XML文件。添加默认的 Odoo xml 标记并复制粘贴如下代码。记得用你主题的主文件夹名称替换掉 `theme folder` 。
478 | 
479 | ```
480 | <template id="mystyle" name="My style" inherit_id="website.assets_frontend">
481 |     <xpath expr="link[last()]" position="after">
482 |         <link rel="stylesheet" type="text/scss" href="/theme folder/static/scss/style.scss"/>
483 |     </xpath>
484 | </template>
485 | ```
486 | 
487 | 我们刚刚创建了一个指定scss文件的template。如你所见，我们的模板有一个特殊属性，名为 `inherit_id`。 该属性告诉Odoo我们的模板引用了k 另一个template来实现正常操作。
488 | 
489 | 本例中，我们引用了 `assets_frontend` 模板，它位于 `website` 模块中。 `assets_frontend` 指定了由网站构造器所加载的资源列表，我们的目标是在这个列表中添加自己的scss 文件。
490 | 
491 | 这可以通过使用带有`expr="link[last()]"` 和 `position="after"`属性的xpath来实现，它表示“*将我的样式文件并将其放到资源列表的最后一个链接后面*”。
492 | 
493 | 将其放到最后面，这样我们可以确保它最后加载并具有优先级。
494 | 
495 | 最后在**__manifest__.py**文件中添加 **assets.xml。**
496 | 
497 | 更新主题
498 | 
499 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)我们的 scss 文件现在包含在主题当中了，它将会自动编译、最小化并与所有 Odoo 资源进行合并。
500 | 
501 | ![img](https://www.odoo.com/documentation/13.0/_images/services_page_styled.png)
502 | 
503 | ## 创建代码片断
504 | 
505 | 因代码片断是用户设计和布局页面的方式，它们是你设计时最重要的元素。我们来为服务页面创建一个代码片断。代码片断将显示3段文字并可由终端用户通过网站构造器界面进行编辑。导航至view文件夹并创建名为**snippets.xml** 的XML文件。添加默认的Odoo xml标记并复制/粘贴如下代码。template包含有可由代码片断显示的HTML标记。
506 | 
507 | ```
508 | <template id="snippet_testimonial" name="Testimonial snippet">
509 |   <section class="snippet_testimonial">
510 |     <div class="container text-center">
511 |       <div class="row">
512 |         <div class="col-lg-4">
513 |           <img alt="client" class="rounded-circle" src="/theme_tutorial/static/src/img/client_1.jpg"/>
514 |           <h3>Client Name</h3>
515 |           <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
516 |         </div>
517 |         <div class="col-lg-4">
518 |           <img alt="client" class="rounded-circle" src="/theme_tutorial/static/src/img/client_2.jpg"/>
519 |           <h3>Client Name</h3>
520 |           <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
521 |         </div>
522 |         <div class="col-lg-4">
523 |           <img alt="client" class="rounded-circle" src="/theme_tutorial/static/src/img/client_3.jpg"/>
524 |           <h3>Client Name</h3>
525 |           <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
526 |         </div>
527 |       </div>
528 |     </div>
529 |   </section>
530 | </template>
531 | ```
532 | 
533 | 可以看到，我们对这三栏使用了Bootstrap默认类。不仅是关乎布局，这些类将**由网站构造器触发让用户可以调整它们的尺寸**。
534 | 
535 | 前面的代码将创建代码片断内容，但我们需要将其放到编辑器栏中，这样用户可以将其拖放到页面中。复制/粘贴这个模板到你的 **snippets.xml** 文件中。
536 | 
537 | ```
538 | <template id="place_into_bar" inherit_id="website.snippets" name="Place into bar">
539 |   <xpath expr="//div[@id='snippet_structure']/div[@class='o_panel_body']" position="inside">
540 |     <t t-snippet="theme_tutorial.snippet_testimonial"
541 |        t-thumbnail="/theme_tutorial/static/src/img/ui/snippet_thumb.jpg"/>
542 |   </xpath>
543 | </template>
544 | ```
545 | 
546 | 使用xpath，我们通过 id `snippet_structure`定位到具体的元素。这表示这个代码片段会出现在Structure标签栏中。如果希望修改目标标签栏，需要在xpath中替换掉`id`值。
547 | 
548 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet_bar.png)
549 | 
550 | | 标签栏名称 | Xpath表达式                      |
551 | | ---------- | -------------------------------- |
552 | | Structure  | `//div[@id='snippet_structure']` |
553 | | Content    | `//div[@id='snippet_content']`   |
554 | | Feature    | `//div[@id='snippet_feature']`   |
555 | | Effect     | `//div[@id='snippet_effect']`    |
556 | 
557 | `<t>`标签将调用我们的代码片断模板并赋值一个img文件夹中放置的缩略图。现在可以从代码片断栏中将其播放到页面中并查看效果。
558 | 
559 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet_default.png)
560 | 
561 | ## 代码片断选项
562 | 
563 | 选项允许发面都使用网站构造器界面编辑代码片断的外观。借助网站构造器的功能，你可以轻松地创建一个代码片断选项并自动将它们添加到界面中。
564 | 
565 | ### 选项组属性
566 | 
567 | 选项封装成组。组中有属性来定义所包含选项如何与用户界面进行交互。
568 | 
569 | - `data-selector="[css selector(s)]"`
570 | 
571 |   将所有选项绑定到针对具体元素的组。
572 | 
573 | - `data-js=" custom method name "`
574 | 
575 |   用于绑定自定义Javascript方法。
576 | 
577 | - `data-drop-in="[css selector(s)]"`
578 | 
579 |   定义代码片断所放置入的元素列表。
580 | 
581 | - `data-drop-near="[css selector(s)]"`
582 | 
583 |   定义可将代码片断放置在其附近的代码片断。
584 | 
585 | ### 默认选项方法
586 | 
587 | 选项向脚本应用标准CSS类。根据你所选择的方法，用户界面的行为会有所区别。
588 | 
589 | - `data-select-class="[class name]"`
590 | 
591 |   在相同组内的多个data-select-class定义一系列用户可选择应用的类。一次仅能启用一个选项。
592 | 
593 | - `data-toggle-class="[class name]"`
594 | 
595 |   data-toggle-class用于从代码片断列表中应用一个或多个 CSS类。可同时应用多个。
596 | 
597 | 我们来演示默认选项与用于一个基本示例。
598 | 
599 | 我们一开始在views文件夹中新增一个文件，将其命名为**options.xml** 并在其中滞默认的Odoo XML标记。新建模板复制、粘贴如下内容：
600 | 
601 | ```
602 | <template id="snippet_testimonial_opt" name="Snippet Testimonial Options" inherit_id="website.snippet_options">
603 |   <xpath expr="//div[@data-js='background']" position="after">
604 |     <div data-selector=".snippet_testimonial"> <!-- Options group -->
605 |       <li class="dropdown-submenu">
606 |         <a href="#">Your Option</a>
607 |         <div class="dropdown-menu"> <!-- Options list -->
608 |           <a href="#" class="dropdown-item" data-select-class="opt_shadow">Shadow Images</a>
609 |           <a href="#" class="dropdown-item" data-select-class="opt_grey_bg">Grey Bg</a>
610 |           <a href="#" class="dropdown-item" data-select-class="">None</a>
611 |         </div>
612 |       </li>
613 |     </div>
614 |   </xpath>
615 |  </template>
616 | ```
617 | 
618 | 以上的模板将扩展默认的**snippet_options模板**，将我们的选项添加到 **background** 选项之后options (xpath expr 属性)。要以具体的顺序放置选项，查看**website模块**中的 **snippet_options模板** 并将你的选项添加到所需位置的之前或之后。
619 | 
620 | 可以看到，我们将所有的选项放到一个 DIV 标签内，那会将它们定位到正确的选择器上 (`data-selector=".snippet_testimonial"`)。
621 | 
622 | 要定义我们的选项，我们对`li`元素中应用了 `data-select-class` 属性。在用户选择一个选项时，属性中所包含的类将自动应用于该元素。
623 | 
624 | 因为 `selectClass` 方法避免了多选，最后一个“empty”选项将重置代码片断为默认值。
625 | 
626 | 在 `__manifest__.py` 中添加**options.xml**并更新主题。
627 | 
628 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)把我们的代码片断放到页面中，你会注意到新选项自动添加到了自定义菜单中。查看日志，你会注意到在选择一个选项时该类会应用到元素上。
629 | 
630 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet_options.png)我们来创建一些css规则，来为我们的选择添加视觉效果。打开 **style.scss** 文件并添加如下内容：
631 | 
632 | ```
633 | .snippet_testimonial {
634 |   border: 1px solid #EAEAEA;
635 |   padding: 20px;
636 | }
637 | 
638 | // These lines will add a default style for our snippet. Now let's create our custom rules for the options.
639 | 
640 | .snippet_testimonial {
641 |   border: 1px solid #EAEAEA;
642 |   padding: 20px;
643 | 
644 |   &.opt_shadow img {
645 |     box-shadow: 0 2px 5px rgba(51, 51, 51, 0.4);
646 |   }
647 | 
648 |   &.opt_grey_bg {
649 |     border: none;
650 |     background-color: #EAEAEA;
651 |   }
652 | }
653 | ```
654 | 
655 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet_options2.png)太棒了！我们成功地为代码片断创建了选项。
656 | 
657 | 每当发布者点击一个选项时，系统会添加在 data-select-class中指定的类。
658 | 
659 | 通过将 `data-select-class` 替换为 `data-toggle-class` ，你将能够同时选择多个类。
660 | 
661 | ### Javascript选项
662 | 
663 | 如果你需要执行简单的类修改操作的话`data-select-class` 和 `data-toggle-class` 会非常好。但如果代码片断的自定义要求有更多操作呢？
664 | 
665 | 如前面所述， `data-js` 属性可分配给一个选项组，来定义一个自定义方法。我们通过向早前创建的选项组div添加`data-js`属性来为*testimonials*代码片断创建一个选项。
666 | 
667 | ```
668 | <div data-js="snippet_testimonial_options" data-selector=".snippet_testimonial">
669 |   [...]
670 | </div>
671 | ```
672 | 
673 | 搞定。 从现在开始，网站构造器在发布者每次进入编辑模式时都会查找 `snippet_testimonial_options` 方法。
674 | 
675 | 我们再进一步，创建一个名为**tutorial_editor.js** 的javascript文件并将其放到 **static** 文件夹下。复制、粘贴如下代码：
676 | 
677 | ```
678 | (function() {
679 |     'use strict';
680 |     var website = odoo.website;
681 |     website.odoo_website = {};
682 | })();
683 | ```
684 | 
685 | 很好，我们成功地创建了自己的javascript编辑器文件。 该文件将包含编辑模式下我们的代码片断所使用的javascript函数。我们来使用前面创建的`snippet_testimonial_options`方式】法为证言代码片断新建一个函数。
686 | 
687 | ```
688 | (function() {
689 |     'use strict';
690 |     var website = odoo.website;
691 |     website.odoo_website = {};
692 | 
693 |     website.snippet.options.snippet_testimonial_options = website.snippet.Option.extend({
694 |         onFocus: function() {
695 |             alert("On focus!");
696 |         }
697 |     })
698 | })();
699 | ```
700 | 
701 | 可以注意到，我们使用了一个名为 `onFocus`的方法来触发我们的函数。网站构造器提供了一些你可以用于触发自定义函数的事件。
702 | 
703 | | 事件           | 描述                                                         |
704 | | -------------- | ------------------------------------------------------------ |
705 | | `start`        | 在编辑会话中发布者第一次选中代码片断时或播放到页面中时触发。 |
706 | | `onFocus`      | 每次用户选择脚本时或将脚本播放到页面中时触发。               |
707 | | `onBlur`       | 在代码片断失去焦点是发生该事件。                             |
708 | | `onClone`      | 在复制了代码片断后触发。                                     |
709 | | `onRemove`     | 在删除代码片断之彰触发。                                     |
710 | | `onBuilt`      | 在将代码片断拖放到拖放区域时触发。事件触发时，内容已插入到页面中。 |
711 | | `cleanForSave` | 在发布者保存页面时触发。                                     |
712 | 
713 | 我们来往编辑器资源列表中新增一些javascript文件。回到 **assets.xml** 并新建像前一个那样的 template。这次我们需要继承 `assets_editor`来代替 `assets_frontend`。
714 | 
715 | ```
716 | <template id="my_js" inherit_id="website.assets_editor" name="My Js">
717 |   <xpath expr="script[last()]" position="after">
718 |     <script type="text/javascript" src="/theme_tutorial/static/src/js/tutorial_editor.js" />
719 |   </xpath>
720 | </template>
721 | ```
722 | 
723 | 更新你的主题
724 | 
725 | ![img](https://www.odoo.com/documentation/13.0/_images/restart.png)我们来测试新的javascript函数。进入编辑模式并播放入页面。你应该可以看到我们绑定到`onFocus`事件上的javascript警告。如果关闭然后点击代码片断外部，接着再次在其中进行点击，该事件会再次被触发。
726 | 
727 | ![img](https://www.odoo.com/documentation/13.0/_images/snippet_custom_method.png)
728 | 
729 | ## 编辑手册指南
730 | 
731 | Basically all the elements in a page can be edited by the publisher. Besides that, some element types and css classes will trigger special Website Builder functionalities when edited.
732 | 
733 | ### 布局
734 | 
735 | - `<section />`
736 | 
737 |   Any section element can be edited like a block of content. The publisher can move or duplicate it. It’s also possible to set a background image or color. Section is the standard main container of any snippet.
738 | 
739 | - `.row > .col-lg-*`
740 | 
741 |   Any large bootstrap columns directly descending from a .row element, will be resizable by the publisher.
742 | 
743 | - `contenteditable="False"`
744 | 
745 |   This attribute will prevent editing to the element and all its children.
746 | 
747 | - `contenteditable="True"`
748 | 
749 |   Apply it to an element inside a contenteditable=”False” element in order to create an exception and make the element and its children editable.
750 | 
751 | - `<a href=”#” />`
752 | 
753 |   In Edit Mode, any link can be edited and styled. Using the “Link Modal” it’s also possible to replace it with a button.
754 | 
755 | ### Media
756 | 
757 | - `<span class=”fa” />`
758 | 
759 |   Pictogram elements. Editing this element will open the Pictogram library to replace the icon. It’s also possible to transform the elements using CSS.
760 | 
761 | - `<img />`
762 | 
763 |   Once clicked, the Image Library will open and you can replace images. Transformation is also possible for this kind of element.
764 | 
765 | ```
766 | <div class="media_iframe_video" data-src="[your url]" >
767 |   <div class="css_editable_mode_display"/>
768 |   <div class="media_iframe_video_size"/>
769 |   <iframe src="[your url]"/>
770 | </div>
771 | ```
772 | 
773 | This html structure will create an `<iframe>` element editable by the publisher.
774 | 
775 | ## SEO最佳实践
776 | 
777 | ### 利用内容插入
778 | 
779 | 现代搜索引擎算法越来越关注内容，这表示对于**关键词密度**的关注减少而对于内容是否与**关键词真实相关**的关注增多。
780 | 
781 | 因为内容对于SEO如此重要，你应当集中于给发布者可以轻松插入内容的工具。代码片断为“响应式内容”也会重要，即应适配发布者的内容，不论其长短。
782 | 
783 | 我们来看这个经典两列代码一片断的示例，通过两种不同的方式来实现。
784 | 
785 | ![img](https://www.odoo.com/documentation/13.0/_images/seo_snippet_wrong.png)
786 | 
787 | **不好的做法**
788 | 
789 | 使用固定大小图片，发布者将不得不限制文本来遵循这一布局。
790 | 
791 | ![img](https://www.odoo.com/documentation/13.0/_images/seo_snippet_good.png)
792 | 
793 | **好的做法**
794 | 
795 | 使用适配列高的背景图片，发布者可自由添加内容，而无需顾及图片的高度。
796 | 
797 | ### 页面分隔
798 | 
799 | 基本上，页面分区表示页面被分成几个独立的部分，而这些部分被搜索引擎看作独立的词条。在你设计页面或代码片断时，应当确保使用正确的标签来有助于搜索引擎的索引。
800 | 
801 | - `<article>`
802 | 
803 |   指定一个独立的内容区。其中应为一块自包含的内容并且本身具有意义。你可以对 `<article>` 元素进行彼此间的嵌套。在这种情况下，它表示嵌套的元素与外部的 `<article>` 元素相关联。
804 | 
805 | - `<header>`
806 | 
807 |   表示内容自包含区块（`<article>`）的header区域。
808 | 
809 | - `<section>`
810 | 
811 |   是代码片断的默认标签，并且它指定内容区块的子区域。它可用于将`<article>` 内容分隔为几个部分。推荐使用标题元素(`<h1>` – `<h6>`)来定义section主题。
812 | 
813 | - `<hgroup>`
814 | 
815 |   用于幸运糖果屋标题 (`<h1>` - `<h6>`)区域。一个较好的例子是在顶部包含标题和子标题的article：`<hgroup>  <h1>Main Title</h1>  <h2>Subheading</h2> </hgroup>`
816 | 
817 | ### 描述你的页面
818 | 
819 | #### 定义关键词
820 | 
821 | 你应当使用恰当、相关的关键词及这些关键词的近义词。可以使用页面顶栏中可以找到的内置“Promote”函数来对每个页面定义这些关键词。
822 | 
823 | #### 定义标题和描述
824 | 
825 | 使用“Promote”函数来定义它们。 保持页面标题简短并为页面添加主关键词词组。好标题会带来情感响应、设问或预示某些内容。
826 | 
827 | 描述（Description），虽然对于搜索引擎排名不太重要，但对于获取用户点击率极其重要。这些是为内容打广告的机会，让那些搜索的人们可以精准地知道页面中是否包含他们所需要的内容。每个页面的标题和描述保持唯一性非常重要。


--------------------------------------------------------------------------------