LiuZhengYu/ciyon_ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ciyon_ai/aiskill/ciyon-数据字典设计.md
2026-04-15 17:28:46 +08:00

11 KiB
Raw Permalink Blame History

ciyon 数据字典设计 Skill 文档

参考zc_cata表，未指定新字典表，则复用该表。

数据库表结构

zc_cata 表定义

CREATE TABLE `zc_cata` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `upid` int(11) NOT NULL COMMENT '上级,DB,zc_cata',
  `csort` int(11) NOT NULL DEFAULT 10 COMMENT '排序',
  `isuse` int(11) NOT NULL DEFAULT 1 COMMENT '|行为|,BOOL',
  `cbid` int(11) NOT NULL DEFAULT 0 COMMENT '库,DB,zc_cata',
  `codeid` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '值',
  `name` varchar(30) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '名称',
  `clas` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '样式类',
  `extdata` varchar(180) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL DEFAULT '' COMMENT '使用表',
  PRIMARY KEY (`id`) USING BTREE,
  INDEX `cbid`(`cbid`) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 12001701 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci COMMENT = '字典表' ROW_FORMAT = Dynamic;

字段说明

字段 类型 说明
id int(11) 主键ID
upid int(11) 上级ID，支持树形结构，多级字典使用
csort int(11) 排序字段
isuse int(11) 是否启用，1=启用，2=禁用。是否使用开关。已被使用不能被删除，可操作关闭。关闭后前端组件不可选该字典项。
cbid int(11) cbid=0为字典集合，cbid>0为某个字典的字典项集合
codeid varchar(20) 字典集合的codeid为字典代码，通常英文命名，一般与列名相同。字典项集合的codeid一般为数字。
name varchar(30) 显示名称
clas varchar(20) 一般用于给前端元素标记class名，仅在前端页面需用不同颜色显示的情况设置样式类，其余不设置
extdata varchar(180) 使用表列表，一行一个

字典项编号

一般从10开始编号

  • 进行中过程一般设置10/20/30
  • 失败一般设置90/91等
  • 成功一般设置100
  • 归档/完成等一般设置110/120等。

重要规范：在前端选项卡筛选等场景中，字典项标识应从1开始编号，避免使用0。例如：

  • 变动类型：10=类型1，20=类型2，30=类型3
  • 数据状态：1=公开，2=订阅

数据组织结构

字典采用双层结构：

  • 库层级：cbid=0 的记录为字典库
  • 值层级：cbid>0 的记录为字典值，cbid 指向所属库的 id

示例数据：

id=10, cbid=0, codeid='sex', name='性别'  → 字典库
id=1000, cbid=10, codeid='10', name='男'  → 字典值
id=1001, cbid=10, codeid='20', name='女'  → 字典值

字典类型

固定字典（small data）

特点：

  • 库和值都存储在 zc_cata 表中
  • 支持多级树形结构（通过 upid）
  • 登录时自动加载到前端缓存

适用场景：

  • 数据量小（< 1000条）
  • 需要频繁修改
  • 需要多级树形结构

管理方式：

  • 使用 /web/admin/rigger/cataindex.php 管理字典库
  • 使用 /web/admin/rigger/cata.php 管理字典值

大数据量静态字典（large data）

特点：

  • 数据存储为独立的 JS 文件
  • 按需加载，减少初始加载时间
  • PC端和移动端均可使用

适用场景：

  • 数据量大（> 1000条）
  • 数据相对固定
  • 不需要频繁修改

文件格式：

var ciy_arearpc=[
  {"id":"110000","upid":"0","name":"北京市"},
  {"id":"110100","upid":"110000","name":"市辖区"},
  {"id":"110101","upid":"110100","name":"东城区"}
];

文件位置：

  • PC端：/web/ud/dict/
  • 移动端：通过远程URL加载

PC端实现

登录时加载字典

后端接口：/web/admin/login.php 中的 json_login() 方法

static function getsync($userrow, $oid = 0, $sid = '') {
    // ... 认证代码 ...
    
    $ret['storage'] = array();
    $csql = new \ciy\sql('zc_cata');
    $csql->order('csort,id');
    $ret['storage']['cata'] = $db->get($csql);  // 加载所有字典
    
    // ... 其他数据 ...
    
    return succjson($ret);
}

前端缓存字典

前端函数：/web/jscss/ciy.js 中的 savedict() 函数

存储格式：

  • 键名：cata_{codeid}，例如：cata_sex
  • 值格式：数组，每个元素包含 id, name, upid, clas, isuse

查询字典

ccode - 单值查询：

// 根据id查询name
var name = ciyfn.ccode('sex', '10');  // 返回 '男'

// 查询其他字段
var item = ciyfn.ccode('sex', '10', '_obj');  // 返回完整对象
var clas = ciyfn.ccode('sex', '10', 'clas');  // 返回样式类

scode - 多值查询：

var names = ciyfn.scode(sexArray, '10,20');  // 返回 ['男', '女']

mcode - 多级查询：

// 查询从当前节点到根节点的所有名称
var path = ciyfn.mcode(areaArray, '110101');  // 返回 ['东城区', '市辖区', '北京市']

bcode - 位标记查询：

// 假设使用位标记存储多个状态
var flags = ciyfn.bcode(statusArray, 5);  // 5 = 1 + 4，返回对应的状态数组

移动端实现

字典加载

登录时加载：

// /fapp/ciyon_ap/util/ciy.js
ciyfn.pageload(function () {
    this.me = this.getme();
    // 字典存储在 this.g 中
    this.g = this.getstorage('g', {});
});

设置字典：

// 登录成功后
ciyfn.setstorage(ciy_vars.tokenfield, json.me);
if (json.storage)
    ciyfn.savedict(json.storage);

字典查询

在页面中使用：

<view>{{ccode(g.sex, sexcode)}}</view>
<ciy-select :range="g.sex" ></ciy-select>

export default {
    methods: {
        getSexName(code) {
            return this.ccode(this.g.sex, code);
        }
    }
}

核心函数： ccode(arr, value, field, nonestr) - 单值查询 scode(arr, ids, field) - 多值查询 mcode(arr, value, field) - 多级查询

按需加载静态字典

加载函数：

async load_ciydict(url) {}

使用示例：

// 按需加载地区字典
var [err, res] = await this.go(this.load_ciydict('/dict/ciy_arearpc.js'));
if (!err) {
    this.g.arearpc = res.arr;  // 存储到全局变量
}

字典管理

创建新字典库

方式一：通过管理界面

  1. 访问 /web/admin/rigger/cataindex.html
  2. 点击"批量添加"
  3. 填写格式： 
    性别,sex
男,10
女,20
其他,90

方式二：直接SQL插入

-- 插入库
INSERT INTO zc_cata (upid, csort, isuse, cbid, codeid, name) 
VALUES (0, 10, 1, 0, 'education', '学历');

-- 获取库ID（假设为102）
-- 插入库值
INSERT INTO zc_cata (upid, csort, isuse, cbid, codeid, name, clas) 
VALUES 
(0, 10, 1, 102, '10', '小学', ''),
(0, 20, 1, 102, '20', '初中', ''),
(0, 30, 1, 102, '30', '高中', '');

管理字典值

访问字典管理页面：

/web/admin/rigger/cata.html?cbid=10

支持的URL参数：

  • cbid: 字典库ID
  • issub=yes: 支持子码
  • ismulti=yes: 支持批量添加
  • ext=扩展名: 显示扩展字段

字典刷新

当字典数据变更后，需要刷新前端缓存：

方式一：管理界面刷新

  • 访问字典管理页面，点击"刷新缓存"按钮

方式二：API刷新

POST /web/admin/login.php
参数: action=restorage

AI生成字典和代码的指导原则

生成固定字典的步骤

步骤一：定义库

INSERT INTO zc_cata (upid, csort, isuse, cbid, codeid, name, extdata) 
VALUES (0, 10, 1, 0, 'orderstatus', '订单状态', 'ap_order');

步骤二：定义值

INSERT INTO zc_cata (upid, csort, isuse, cbid, codeid, name, clas)
VALUES
(0, 10, 1, [库ID], '10', '待支付', 'def'),
(0, 20, 1, [库ID], '20', '已支付', 'warn'),
(0, 30, 1, [库ID], '30', '已发货', 'man'),
(0, 100, 1, [库ID], '100', '已完成', 'succ');
  • 开关类字段：如是否启用、是否公开等，直接使用数据库字段存储，不需要定义为字典

步骤三：定义哪些表使用了该字典 extdata：表名1.不相同的字段名\n表名2\n表名3 删除字典项时，检索每个表的字段是否已引用。已引用的禁止删除。

步骤四：前端使用

// 查询单个值
var name = ciyfn.ccode('orderstatus', '10');  // '待支付'

// 查询带样式
var item = ciyfn.ccode('orderstatus', '10', '_obj');  // {id:'10', name:'待支付', clas:'def'}

生成业务代码的规范

表字段设计：

CREATE TABLE ap_order (
  id INT PRIMARY KEY,
  orderstatus INT COMMENT '订单状态,CATA,orderstatus',
  -- ...
);

前端展示：

<template>
  <view>
    <text>{{ ccode(g.orderstatus, order.orderstatus) }}</text>
  </view>
</template>

<script>
export default {
  data() {
    return {
      order: { orderstatus: '10' }
    }
  }
}
</script>

代码生成检查清单

生成字典相关代码时，必须检查：

  • 字典库是否已创建（cbid=0 的记录）
  • 字典值是否已插入（cbid 指向库ID）
  • extdata 是否定义了引用表（如需要）
  • clas 字段是否根据字典类型合理设置（前端需用不同颜色显示时设置样式，其余不设置）
  • isuse 字段是否设置为1（启用）
  • 前端是否正确调用 ccode/scode/mcode/bcode
  • 修改字典后是否刷新了缓存

常见问题

问题一：哪些场景不适合使用字典？

答案:

  • 需要用户自主设置的类型/状态，不适合
  • 开关类字段（如是否启用、是否公开等），直接使用数据库字段存储，不需要定义为字典

问题二：字典修改后为什么前端没有更新？

答案: 需要刷新缓存： 控制台右上角 点击"刷新缓存"按钮

问题三：如何支持多级字典？

答案: 使用 upid 字段：

-- 一级：省
INSERT INTO zc_cata VALUES (..., 0, ..., '110000', '北京市');

-- 二级：市
INSERT INTO zc_cata VALUES (..., [省ID], ..., '110100', '市辖区');

-- 三级：区
INSERT INTO zc_cata VALUES (..., [市ID], ..., '110101', '东城区');

查询多级路径：

var path = ciyfn.mcode('area', '110101');  // ['东城区', '市辖区', '北京市']

问题四：如何在移动端使用字典？

答案:

  1. 登录后字典自动加载到 this.g
  2. 在页面中直接使用 this.ccode()
  3. 大数据量字典使用 this.load_ciydict() 按需加载

附录

样式类说明

clas 说明 颜色
dag 失败 红色
warn 警告 橙色
succ 成功 绿色
def 灰色 灰色
man 主色 蓝色

核心函数速查

函数 平台 说明
ccode(arr, value, field, nonestr) 全 单值查询
scode(arr, ids, field) 全 多值查询
mcode(arr, value, field) 全 多级查询
bcode(arr, value, field) 全 位标记查询

文档版本: v1.0
更新日期: 2026-03-20
维护者: ciyon开发团队