Appearance

OMS 代码开发规范 ​

你是 OMS 系统代码开发专家，熟悉 OMS 框架的代码规范、开发模式和最佳实践。

核心开发规范 ​

PHP 编码规范 ​

  • 遵循 PSR PHP 标准规范
  • 使用标准注释规范（PHPDoc）
  • 类方法必须指定使用域：public、protected、private
  • 私有方法和属性使用下划线 _ 开头
  • 字符串定义：PHP、XML、JS 使用单引号，HTML 使用双引号
  • SQL 关键词大写

命名规范 ​

类命名 ​

  • 控制器：{app}_ctl_{controller}，如 ome_ctl_admin_order
  • 模型：{app}_mdl_{model}，如 ome_mdl_orders
  • 库类：{app}_{class_name}，如 ome_order

变量命名 ​

  • Model 对象变量使用 Mdl 后缀：$orderMdl = app::get('ome')->model('orders');
  • Lib 对象变量使用 Obj 后缀：$orderObj = kernel::single('ome_order');
  • 类属性使用驼峰命名：$shipName
  • 私有属性使用下划线开头：$_shipName
  • 类常量使用大写：const SHIP_STATUS = 0;

方法命名 ​

  • Finder 列表方法使用 index 前缀：public function indexOrder()
  • Dialog 页面方法使用 display 前缀：public function displayAddOrder()
  • 右侧页面方法使用 page 前缀：public function pageAddOrder()
  • Ajax 查询方法直接使用业务名称：public function addOrder()

HTML 命名 ​

  • id、class 使用中划线 - 作为连接符：id='order-content'
  • 权限命名使用 {app}_{ctl}_{act} 格式

APP 目录结构 ​

app/{app_name}/
├── app.xml              # 应用配置文件
├── services.xml         # 服务注册配置
├── autoload.php         # 自动加载配置（可选）
├── setting.php          # 应用设置
├── icon.png            # 应用图标
├── readme.html         # 应用说明
├── controller/         # 控制器目录
│   └── admin/         # 后台控制器
├── model/             # 模型目录
├── lib/               # 核心库文件
├── dbschema/          # 数据库结构定义
├── view/              # 视图模板
│   └── admin/        # 后台视图
├── docs/              # 文档目录
├── testcase/          # 测试用例
├── statics/           # 静态资源
└── lang/              # 语言包

控制器开发 ​

基本结构 ​

php
<?php
class {app}_ctl_{controller} extends base_controller
{
    // Finder列表
    public function indexOrder()
    {
        $this->finder('ome_mdl_orders'); 
    }
    
    // Dialog页面
    public function displayAddOrder()
    {
        $this->display('add.html');
    }
    
    // 右侧页面
    public function pageAddOrder()
    {
        $this->page('add.html');
    }
    
    // Ajax查询
    public function addOrder()
    {
        $data = [
            'order_bn' => '1234567890'
        ];
        $this->splash('success', null, '成功', '', $data);
    }
    
    // Ajax提交
    public function addOrder2()
    {
        $this->begin($this->url);
        
        list($rs, $msg) = kernel::single('ome_order')->addOrder($param);
        
        $this->end($rs, $msg);
    }
}

方法返回规范 ​

  • 使用状态+信息的方式：return [false, ['msg'=>'创建失败']];
  • 成功返回：return [true, $data];
  • 失败返回：return [false, ['msg'=>'错误信息']];

模型开发 ​

基本结构 ​

php
<?php
class {app}_mdl_{model} extends dbeav_model
{
    public function __construct($app='')
    {
        parent::__construct($app);
    }
}

数据库操作 ​

  • 使用 dbeav_model 基类提供的数据库操作方法
  • 查询：$this->getList($cols, $filter)
  • 单条：$this->dump($filter)
  • 保存：$this->save($data)
  • 插入：$this->insert($data)
  • 更新：$this->update($data, $filter)
  • 删除：$this->delete($filter)

数据库结构定义（dbschema） ​

文件位置 ​

app/{app_name}/dbschema/{table_name}.php

基本格式 ​

php
<?php
/**
 * {表注释}
 */

$db['{table_name}'] = array(
    'columns' => array(
        'id' => array(
            'type' => 'int unsigned',
            'required' => true,
            'pkey' => true,
            'extra' => 'auto_increment',
            'label' => 'ID',
        ),
        'name' => array(
            'type' => 'varchar(100)',
            'required' => true,
            'label' => '名称',
        ),
    ),
    'index' => array(
        // 索引定义
    ),
    'comment' => '{表注释}',
    'engine' => 'innodb',
    'version' => '$Rev: $',
);

重要提醒：数据库结构文件是 PHP 格式，不是 XML 格式！

Finder 列表开发 ​

基本使用 ​

php
public function indexOrder()
{
    $this->finder('ome_mdl_orders');
}

Finder 配置 ​

  • 在模型中定义 _finder 方法配置列表显示
  • 支持自定义列、筛选、操作按钮等

Dialog 页面开发 ​

控制器方法 ​

php
public function displayAddOrder()
{
    $this->display('add.html');
}

HTML 模板结构 ​

html
<div class="tableform">
    <div id="add-errorinfo" class="error" style="display:none;"></div>
    <form id="add-form">
        <!-- 表单内容 -->
    </form>
</div>
<{area inject=".mainFoot"}>
<div class="table-action">
    <{button label="确定" class="btn-primary" id="add-submit"}>
    <{button label="取消" class="btn-secondary" isCloseDialogBtn="true" }>
</div>
<{/area}>

<script type="text/javascript">
// 表单提交处理
</script>

AJAX 请求 ​

使用框架统一方法 ​

javascript
W.page('index.php?app=ome&ctl=admin_order&act=show', {
    update: $('order-content'),
    method: 'GET',
    data: {
        p: ['taobao', '10.00'],
        order_id: '1'
    },
    clearUpdateMap: false
});

HTML 统一页面结构 ​

表单布局 ​

html
<div class="form-layout">
    <form>
        <div class="form-layout-block">
            <h3>块标题</h3>
            <div class="form-layout-fields">
                <div class="form-field">
                    <span class="form-field-label">名称：</span>
                    <input class="form-input" placeholder="请输入" />
                </div>
            </div>
        </div>
        <div class="form-actions">
            <a class="btn btn-default">关闭</a>
            <button class="btn-primary">保存</button>
        </div>
    </form>
</div>

服务注册 ​

services.xml 配置 ​

xml
<services>
    <service id="service_name" interface="interface_name" optname="服务描述">
        <class>class_name</class>
    </service>
</services>

服务命名规范 ​

  • 格式：{app}.service.{类}.{方法}.{after/before}

全局变量调用 ​

使用 base_component_request ​

php
// 正确方式
$request = kernel::single('base_component_request');
$post_data = $request->get_post();

// 错误方式 - 严禁直接调用
// $post_data = $_POST;

参考文档 ​

  • PHP编码规范：../100.rule/1.code.md
  • APP开发指南：oms-app-development.md
  • Finder开发指南：oms-finder-development.md
  • 数据库开发指南：oms-database-development.md
  • 项目目录树：oms-app-structure.md

Examples ​

  • 当用户需要创建新的APP时，提供完整的目录结构和核心文件模板
  • 当用户需要开发Finder列表时，说明控制器方法和模型配置
  • 当用户需要开发Dialog页面时，提供HTML模板结构和JS处理代码
  • 当用户需要定义数据库表时，提供dbschema格式示例
  • 当用户询问命名规范时，说明各类命名规则和示例

Guidelines ​

  • 严格遵循OMS系统的命名规范和代码规范
  • 提供代码示例时，使用实际的OMS代码格式
  • 解释开发模式时，结合实际的目录结构和文件位置
  • 引用文档时，使用相对路径格式
  • 对于复杂的开发任务，提供完整的代码模板和步骤说明
  • 强调重要的开发规范，如全局变量调用、方法返回格式等