# zy_utils

**Repository Path**: cy0805851985/zy_utils

## Basic Information

- **Project Name**: zy_utils
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: version-16
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### Zy Utils

Frappe 实用工具集，提供命令行工具批量创建自定义字段和设置字段属性，无需安装应用到站点即可使用。

### 前提

确保 app 已存在于 `apps/` 目录下，bench 会自动识别命令，不需要 `bench install-app`。

---

### 命令一：批量创建自定义字段

```bash
# 创建所有自定义字段
bench zy-create-custom-fields --site <site_name>

# 只处理某个 JSON 文件
bench zy-create-custom-fields --site <site_name> --file customer.json
```

**JSON 文件位置：** `zy_utils/zy_utils/custom_fields/` 目录下，每个 JSON 文件对应一组字段定义，文件名随意。

**JSON 格式：**

```json
[
  {
    "doctype": "Item",
    "data": [
      {
        "fieldname": "custom_dwg_model_std",
        "fieldtype": "Data",
        "label": "Dwg. No. / Model / Std.",
        "insert_after": "stock_uom",
        "language": "zh",
        "translated_text": "图纸编号/型号/标准"
      },
      {
        "fieldname": "custom_specs_material",
        "fieldtype": "Data",
        "label": "Specs Material",
        "insert_after": "custom_dwg_model_std",
        "language": "zh",
        "translated_text": "规格/材料"
      }
    ]
  }
]
```

**必填字段（data 中每条）：**

| 字段 | 说明 |
|------|------|
| `fieldname` | 字段名（必须以 `custom_` 开头） |
| `fieldtype` | 字段类型 |
| `label` | 显示标签 |

**常用可选字段：**

| 字段 | 说明 |
|------|------|
| `insert_after` | 放在哪个字段后面 |
| `options` | Select 用 `\n` 分隔，Link 填 DocType 名 |
| `reqd` | 是否必填（1 / 0） |
| `in_list_view` | 列表视图显示（1 / 0） |
| `in_standard_filter` | 标准筛选器显示（1 / 0） |
| `default` | 默认值 |
| `hidden` | 是否隐藏（1 / 0） |
| `read_only` | 是否只读（1 / 0） |
| `description` | 提示文字 |
| `depends_on` | 条件显示，支持 `eval:` 表达式 |

**翻译功能（可选）：**

| 字段 | 说明 |
|------|------|
| `language` | 语言代码，如 `zh`、`zh-TW`、`en` |
| `translated_text` | label 对应的翻译文本 |

当 `language` 和 `translated_text` 同时存在时，会自动将 `label` 的翻译写入 Translation 表。已存在的翻译会跳过。不需要翻译的字段不写这两个字段即可。

**可用的 fieldtype：**

`Data`, `Int`, `Float`, `Currency`, `Select`, `Link`, `Date`, `Datetime`, `Small Text`, `Text`, `Text Editor`, `Check`, `Section Break`, `Column Break`, `Table`, `HTML`, `Button`, `Color`, `Password`, `JSON` 等。

**注意事项：**

- 同一表单中第二个自定义字段可以用 `insert_after` 指向第一个自定义字段
- JSON 文件按文件名排序读取，注意字段间的依赖顺序
- 已存在的字段会自动跳过，重复执行不会报错

---

### 命令二：批量设置字段属性

```bash
# 更新所有字段属性
bench zy-set-field-properties --site <site_name>

# 只处理某个 JSON 文件
bench zy-set-field-properties --site <site_name> --file customer.json
```

**JSON 文件位置：** `zy_utils/zy_utils/field_properties/` 目录下，每个 JSON 文件对应一组属性设置。

**JSON 格式：**

```json
[
  {
    "doctype": "Item",
    "doctype_properties": {
      "search_fields": "custom_dwg_model_std, custom_specs_material"
    },
    "data": [
      {
        "fieldname": "customer_name",
        "properties": {
          "in_list_view": 1,
          "in_standard_filter": 1,
          "reqd": 1,
          "bold": 1
        }
      },
      {
        "fieldname": "custom_vip_level",
        "properties": {
          "reqd": 0,
          "hidden": 0,
          "read_only": 0,
          "description": "客户VIP等级"
        }
      }
    ]
  }
]
```

`doctype_properties` 和 `data` 可以同时存在，也可以只用其中一个。

#### DocType 级别属性（doctype_properties）

通过 Property Setter 的 `DocType` 模式修改，不影响原始 DocType 定义。

| 属性 | 说明 |
|------|------|
| `search_fields` | 搜索字段（追加模式，不会覆盖已有值，自动去重） |
| `title_field` | 标题字段 |
| `image_field` | 图片字段 |
| `sort_field` | 排序字段 |
| `sort_order` | 排序方向（ASC / DESC） |
| `default_print_format` | 默认打印格式 |
| `default_view` | 默认视图 |
| `max_attachments` | 最大附件数 |
| `quick_entry` | 快速录入 |
| `track_changes` | 追踪修改 |
| `track_views` | 追踪查看 |
| `email_append_to` | 允许通过邮件创建文档 |
| `allow_copy` | 允许复制 |
| `istable` | 是否为表格 |
| `editable_grid` | 可编辑网格 |

#### 字段级别属性（data）

| 属性 | 说明 |
|------|------|
| `reqd` | 是否必填 |
| `hidden` | 是否隐藏 |
| `read_only` | 是否只读 |
| `in_list_view` | 列表视图显示 |
| `in_standard_filter` | 标准筛选器显示 |
| `in_global_search` | 全局搜索显示 |
| `bold` | 加粗显示 |
| `description` | 描述提示 |
| `default` | 默认值 |
| `insert_after` | 排列位置 |
| `depends_on` | 条件显示 |
| `collapsible` | 可折叠 |
| `collapsible_depends_on` | 折叠条件 |
| `mandatory_depends_on` | 条件必填 |
| `permlevel` | 权限级别 |
| `ignore_user_permissions` | 忽略用户权限 |
| `allow_on_submit` | 提交后可编辑 |
| `report_hide` | 报告中隐藏 |
| `no_copy` | 复制时不包含 |
| `print_hide` | 打印时隐藏 |
| `print_width` | 打印宽度 |
| `options` | 选项（Select/Link 等） |
| `fetch_from` | 自动填充来源 |
| `fetch_if_empty` | 仅空值时填充 |
| `translatable` | 可翻译 |
| `unique` | 唯一 |
| `set_only_once` | 仅设置一次 |
| `non_negative` | 非负数 |
| `hide_border` | 隐藏边框 |
| `allow_in_quick_entry` | 允许快捷录入 |

**说明：**

- 自定义字段（`custom_` 开头）：直接修改 Custom Field 文档
- 标准字段：通过 Property Setter 机制修改，不会改动原始 DocType 定义
- DocType 级别属性：通过 Property Setter 的 `DocType` 模式修改
- `search_fields` 是追加模式，不会覆盖已有搜索字段
- 不存在的字段会跳过并提示 `SKIP`
- property_type 会根据属性名自动匹配，无需手动指定
- 每次执行后会输出更新结果

---

### 命令三：批量创建用户

```bash
# 使用默认 Excel 文件（excel_files/user.xlsx）
bench zy-create-users --site <site_name>

# 指定 Excel 文件
bench zy-create-users --site <site_name> --file /path/to/users.xlsx
```

**Excel 文件位置：** `zy_utils/zy_utils/excel_files/user.xlsx`

**Excel 格式：**

- 第 1 行：中文标题（仅供参考，不会被读取）
- 第 2 行：字段名（作为列标题）
- 第 3 行起：数据

| 列名 | 必填 | 说明 |
|------|------|------|
| `first_name` | 是 | 用户名 |
| `email` | 是 | 邮箱（同时作为登录账号） |
| `password` | 否 | 密码 |
| `language` | 否 | 语言，如 `zh`、`en` |
| `roles` | 否 | 角色，多个用逗号分隔（中英文逗号均可） |
| `modules` | 否 | 可访问模块，多个用逗号分隔（中英文逗号均可） |

**示例：**

| 用户名 | 邮箱 | 密码 | 语言 | 角色 | 模块 |
|--------|------|------|------|------|------|
| first_name | email | password | language | roles | modules |
| 张三 | zhangsan@example.com | pass123 | zh | Sales User，Sales Manager | Core,Desk,Sales |
| 李四 | lisi@example.com | pass456 | zh | Accounts User | Core，Accounts |

**说明：**

- 已存在的用户会跳过，不会重复创建
- 角色必须是系统中已存在的 Role
- `modules` 指定允许访问的模块，未列出的模块将被屏蔽
- 以 Administrator 身份执行

---

### 命令四：导出报表/模块/角色中英文名称

```bash
# 默认导出中文翻译
bench zy-export-names --site <site_name>

# 指定其他语言
bench zy-export-names --site <site_name> --language zh-TW
```

**输出文件：** `zy_utils/zy_utils/excel_files/name_translations.xlsx`

文件包含三个 Sheet：

**Reports（报表）**

| 列 | 说明 |
|----|------|
| name | 系统标识 |
| report_name(EN) | 英文名称 |
| report_name(zh) | 中文名称 |
| ref_doctype | 关联 DocType |
| report_type | 报表类型 |
| module | 所属模块 |

**Modules（模块）**

| 列 | 说明 |
|----|------|
| name | 系统标识 |
| module_name(EN) | 英文名称 |
| module_name(zh) | 中文名称 |
| app_name | 所属应用 |

**Roles（角色）**

| 列 | 说明 |
|----|------|
| name | 系统标识 |
| role_name(EN) | 英文名称 |
| role_name(zh) | 中文名称 |
| desk_access | 是否有 Desk 访问权限 |

**说明：**

- 中文名称从 Frappe 翻译系统自动获取，若无对应翻译则为空
- 可通过 `--language` 参数指定任意语言代码（如 `zh`、`zh-TW`、`ja`）

---

### 典型工作流程

```bash
# 1. 编写字段定义（支持翻译）
vim apps/zy_utils/zy_utils/custom_fields/item.json

# 2. 创建字段
bench zy-create-custom-fields --site erp.example.com

# 3. 编写属性配置（字段属性 + DocType 属性）
vim apps/zy_utils/zy_utils/field_properties/item.json

# 4. 设置属性
bench zy-set-field-properties --site erp.example.com

# 5. 准备用户 Excel
vim apps/zy_utils/zy_utils/excel_files/user.xlsx

# 6. 批量创建用户
bench zy-create-users --site erp.example.com

# 7. 导出报表/模块/角色中英文名称
bench zy-export-names --site erp.example.com
```

---

### 目录结构

```
zy_utils/
├── zy_utils/
│   ├── commands.py               # 命令定义
│   ├── hooks.py                  # 注册命令
│   ├── api.py                    # API 接口
│   ├── utils/
│   │   ├── excel.py              # 通用 Excel 读取工具
│   │   └── user.py               # 用户创建核心逻辑
│   ├── custom_fields/            # 字段定义 JSON
│   │   └── item.json
│   ├── field_properties/         # 属性设置 JSON
│   │   └── item.json
│   └── excel_files/              # Excel 数据文件
│       ├── user.xlsx
│       └── name_translations.xlsx
├── setup.py
└── README.md
```

---

### License

agpl-3.0