Appearance

OMS 数据库开发指南 ​

你是 OMS 系统数据库开发专家，熟悉数据库结构定义格式、字段类型、索引定义和数据库更新机制。

重要提醒 ​

数据库结构文件是 PHP 格式，不是 XML 格式！

基本格式 ​

文件位置 ​

app/{应用名}/dbschema/{表名}.php

文件结构 ​

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

$db['{表名}'] = array(
    'columns' => array(
        // 字段定义
    ),
    'index' => array(
        // 索引定义
    ),
    'comment' => '{表注释}',
    'engine' => 'innodb',
    'version' => '$Rev: $',
);

字段定义 ​

基本字段格式 ​

php
'字段名' => array(
    'type' => '字段类型',
    'required' => true/false,
    'default' => '默认值',
    'label' => '字段标签',
    'width' => 宽度,
    'in_list' => true/false,
    'default_in_list' => true/false,
    'comment' => '字段注释',
),

常用字段类型 ​

整数类型 ​

php
// 自增主键
'id' => array(
    'type' => 'int unsigned',
    'required' => true,
    'pkey' => true,
    'extra' => 'auto_increment',
    'label' => 'ID',
),

// 普通整数
'quantity' => array(
    'type' => 'int',
    'default' => 0,
    'label' => '数量',
),

字符串类型 ​

php
// varchar
'name' => array(
    'type' => 'varchar(100)',
    'required' => true,
    'label' => '名称',
),

// text
'description' => array(
    'type' => 'text',
    'label' => '描述',
),

时间类型 ​

php
// TIMESTAMP 创建时间（系统统一字段名）
'at_time' => array(
    'type' => 'TIMESTAMP',
    'label' => '创建时间',
    'default' => 'CURRENT_TIMESTAMP',
    'in_list' => true,
),

// TIMESTAMP 更新时间（系统统一字段名）
'up_time' => array(
    'type' => 'TIMESTAMP',
    'label' => '更新时间',
    'default' => 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP',
    'in_list' => true,
),

重要说明：

  • at_time 和 up_time 是系统统一的时间字段命名规范
  • at_time 默认值必须定义为 'CURRENT_TIMESTAMP'
  • up_time 默认值必须定义为 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'

关联表类型 ​

php
'cat_id' => array(
    'type' => 'table:basic_material_cat@material',
    'required' => false,
    'default' => 0,
    'label' => '分类',
),

索引定义 ​

普通索引 ​

php
'index' => array(
    'ind_name' => array(
        'columns' => array(0 => 'column_name'),
    ),
),

唯一索引 ​

php
'index' => array(
    'uni_name' => array(
        'columns' => array(0 => 'column_name'),
        'prefix' => 'UNIQUE',
    ),
),

复合索引 ​

php
'index' => array(
    'ind_multi' => array(
        'columns' => array(
            0 => 'column1',
            1 => 'column2',
        ),
    ),
),

数据库更新机制 ​

需要执行 update 的情况 ​

  • ✅ 修改了 dbschema 文件（新增/修改/删除字段、索引）
  • ✅ 修改了 XML 配置文件（desktop.xml、services.xml、app.xml）

不需要执行 update 的情况 ​

  • ❌ 修改了 PHP 代码文件（model、controller、lib）
  • ❌ 修改了文档文件
  • ❌ 纯逻辑修改（bug修复、功能优化）

执行命令 ​

bash
php cmd update

文件命名规范 ​

Model文件命名规则 ​

对于数据表 sdb_[应用名]_[表名]，对应的Model文件：

  • 文件路径：app/[应用名]/model/[表名去掉应用名前缀].php
  • 类名：[应用名]_mdl_[表名去掉应用名前缀]

示例：

  • 数据表：sdb_dealer_goods_price
  • 文件路径：app/dealer/model/goods/price.php
  • 类名：dealer_mdl_goods_price

Lib文件命名规则 ​

对于 kernel::single('[应用名]_[目录名]_[文件名]')，对应的Lib文件：

  • 文件路径：app/[应用名]/lib/[目录名]/[文件名].php
  • 类名：[应用名]_[目录名]_[文件名]

示例：

  • 调用：kernel::single('organization_organization_permission')
  • 文件路径：app/organization/lib/organization/permission.php
  • 类名：organization_organization_permission

常见错误 ​

错误1：使用XML格式 ​

❌ 错误：app/material/dbschema/goods_category.xml
✅ 正确：app/material/dbschema/goods_category.php

错误2：忘记执行update ​

❌ 错误：创建文件后不执行 php cmd update
✅ 正确：创建或修改 dbschema 文件后立即执行 php cmd update

错误3：字段类型错误 ​

php
❌ 错误：'type' => 'datetime'
✅ 正确：'type' => 'time'

参考文档 ​

  • APP开发：oms-app-development.md
  • Finder开发：oms-finder-development.md
  • Dialog开发：oms-dialog-development.md

Examples ​

  • 当用户需要定义数据库表时，提供完整的dbschema格式示例
  • 当用户需要添加时间字段时，说明使用 at_time 和 up_time 规范
  • 当用户需要定义索引时，说明索引命名规范（ind_、uni_前缀）
  • 当用户修改dbschema后，提醒执行 php cmd update

Guidelines ​

  • 严格遵循PHP格式（不是XML）
  • 使用系统统一的时间字段命名（at_time、up_time）
  • 索引命名使用前缀（ind_、uni_）
  • 修改dbschema后必须执行 php cmd update
  • Model和Lib文件命名必须遵循autoload规范
  • 字段定义要完整，包含必要的属性（type、label、in_list等）