DTCloud模块开发规范

开源市场介绍

DTCloud开发者社区，赋能开发者，共建企业应用市场。

个人开发者，可在开源市场下载安装模块，也可将自己开发的模块，上传开源市场。

DTCloud模块开发规范

1.应用模块目录

• 项目名称

1. 统一的前缀 dt_
2. 统一为英语字母小写
3. 不用驼峰表示法，如果有多个单词，建议以"_"分隔，比如 dictionary_management 这两个单词之间为_下划线。

• 各目录含义

api 提供外部调用接口
controller 控制器
data 数据
demo 必须要有demo,用户需要知道怎么操作
doc 放入相关文档，如doc等，用于介绍项目或其它
edi 数据交换
i18n 语言目录
models 模型定义
report 报表相关
security 权限相关
static 静态文件等
tests 存放python或yml测试用例
views 视图模板
wizard 存放临时的model和视图

2. __manifest__.py标准

• 统一文件注释，除最后一行日期，其它不建议更改

  # -*- coding: utf-8 -*-
  # &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
  # DTCloud v2.0
  # QQ: 35350428
  # 邮件: [e-mail]
  # 手机: [phone]
  # 作者: 'zyf_Amos'
  # 公司网址: http://www.dtcloud360.com
  # Copyright 中亿丰数字科技有限公司 2012-2022 Amos
  # 日期: 2022/5/29

• manifest.py标准

  {
    'name': "百度地图",  #  模块名称
    'summary': """百度地图视图""",  # 模块介绍
    'category': '中台应用/地图',
    'author': "zyfd_Amos",  # 模块开发者名称
    'website': "http://www.dtcloud360.com",
    'depends': ['web'],
    'version': '1.0',  # 版本号注意, 两位，初始版本为1.0
    'installable': True,
    'application': True,
    'auto_install': False,
    'license': 'LGPL-3',
    'price': '10',  #   模块价格，在应用市场上会显示这里的价格
    'currency': 'CNY',  # 价格以人民币为标准
    'data': [
        'security/data.xml',
        'views/views.xml',
        'views/templates.xml',
    ],
    'images': [
        'static/description/static/images/map.png',
        'static/description/banner.png',
    ],
    'assets': {
        'web.assets_backend': [
            'dt_map/static/src/js/bmap_model.js',
            'dt_map/static/src/js/bmap_controller.js',
            'dt_map/static/src/js/bmap_view.js',
            'dt_map/static/src/js/bmap_render.js',
            'dt_map/static/src/js/geolocation.js',
            'dt_map/static/src/css/bmap.css',
            'dt_map/static/src/css/bmap_view.scss',
        ],
        'web.assets_qweb': [
            'dt_map/static/src/xml/bmap.xml',
            'dt_map/static/src/xml/geolocation.xml',
        ],
    },
    'description': """""",  # 相关模块介绍
  }

• 分类

中台应用：基础，短信，邮件，地图
解决方案：XX智慧工地解决方案，XX公司ERP解决方案等
企业应用：销售，采购，仓库，生产，会计，人事，项目等
工地应用：IOT设备（门禁，视频，门磁，升降机等）,人员管理等
楼宇应用：IOT设备（空调，门禁），客房系统，停车系统等
城市应用：智慧社区，智慧园区，智慧城市等

3. Banner图片、icon文件文件等，可参照以下文档部分

https://blog.csdn.net/ekcchina/article/details/125080888

DTCloud常用代码开发命名规则

常用

• 避免创建生成器和装饰器：仅使用DTCloud API已有的
• 可使用filtered，mapped，sorted方法来提升代码可读性和性能

• 尽量使用ORM
  当ORM可以实现的时候尽量使用ORM而不要直接写sql，因为它可能会绕过orm的一些规则如权限、事务等，还会让代码变得难读且不安全。

  # 错误的写法，注入风险，代码效率低
  self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in (' + ','.join(map(str, ids))+') AND state=%s AND obj_price > 0', ('draft',))
  auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]
  
  # 不会被注入，但仍然是错误的写法
  self.env.cr.execute('SELECT id FROM auction_lots WHERE auction_id in %s '\
           'AND state=%s AND obj_price > 0', (tuple(ids), 'draft',))
  auction_lots_ids = [x[0] for x in self.env.cr.fetchall()]
  
  # 推荐的写法
  auction_lots_ids = self.search([('auction_id','in',ids), ('state','=','draft'), ('obj_price','>',0)])

• 新增

  values = {
    'name': '',
  }
  obj = self.env['models'].create(values)
  

• 修改

  values = {
    'state': '已审核',
  }
  self.sudo().write(values)

• 删除

  self.unlink()

• 查询

  obj = self.env['models'].search([('name', '=', '')], order="sequence, id desc", limit=1)
  或
  model_data = self.env['model'].search_read([('module', '=', 'amos')], ['res_id'])

• 读取

  self.env['models'].browse(id)

• 计数

  domain = [('company_id', '=', self.env.ref('base.main_company').id)]
  rows_count = self.env['account.account'].search_count(domain)

• 防止注入

不要用python的+号连接符、%解释符来拼sql

# 错误的写法
self.env.cr.execute('SELECT distinct child_id FROM account_account_consol_rel ' +
           'WHERE parent_id IN ('+','.join(map(str, ids))+')')

# 推荐的写法
self.env.cr.execute('SELECT DISTINCT child_id '\
           'FROM account_account_consol_rel '\
           'WHERE parent_id IN %s',
           (tuple(ids),))

• 不要手动提交事务

DTCloud有自己的一套机制用于事务处理，如self._cr.commit(),特殊场景除外

• 符号和习惯

模型名-使用.分隔，模块名做前缀

1. 定义DTCloud模型时，使用单数形式的名字如res.user,res.partner
2. 定义wizard时，命名格式为<related_base_model>.<action>，related_base_model是关联模型名称，action是功能简称，如account.invoice.make
3. 定义报表模型时，使用<related_base_model>.report.<action>，和wizard一样
4. python类-使用驼峰命名方式AccountInvoice。 如果是DTCloud表对象使用account_invoice(小写)

• 变量名

1. 模型变量使用驼峰命名方式
2. 普通变量用下划线+小写字母

3. 由于新api中记录是集合形式，当变量不包含id时不以id作后缀

   ResPartner = self.env['res.partner']
   partners = ResPartner.browse(ids)
   partner_id = partners[0].id

4. One2Many， Many2Many字段一般以ids作为后缀如：sale_order_line_ids
5. Many2One 一般以_id为后缀如：partner_id, user_id

6. 方法命名

   计算字段 - 计算方法一般是_compute_<field_name>
   默认方法 - _default_<field_name>
   onchange方法 - _onchange_<field_name>
   约束方法 - _check_<constraint_name>
   action方法 - 一个对象的动作方法一般以action_开头，它的装饰器是@api.multi，如果它只使用单条计算，可在方法头添加self.ensure_one()

接口

• 工作流
  _api_my_workflow ：与系统中的事件名称一一对应，APP的按钮有后台接口提供动态显示
• 一条记录
  _api_one ：数据库中一条记录
• 列表
  _api_page ：带分页的数据集
• 排序
  _api_page_order：列表显示顺序
• 过滤
  _api_page_domain ：列表数据显示规则
• 置顶
  _api_top_time ：列表排序中加入

API接口常用

• 创建
  _api_create ：因为特殊原因要对数据做处理，所以要给前端提供后台处理
• 修改
  _api_write ：可以做更多判断操作，如果没有更多操作可以直接走系统修改
• 删除
  _api_unlink ：主要是提供删除判断，可以提供软删除
• 分配
  _api_distribution ：单据上绑定相操作人
• 领取
  _api_receive ：单据认领