agent-skills/skills/g3fo-db-ops/SKILL.md

name, description

name	description
g3fo-db-ops	Comprehensive database operations guide for G3FO project. Use when updating G3FO database data, creating tables, modifying table structures, inserting system menus/routes, or managing database changes that require SQL generation, execution, and Git commit workflows. Includes automated workflows for i18n updates, version management, file naming conventions, and duplicate sequence number detection.

G3FO Database Operations

Guide for performing database operations in the G3FO project, including automated workflows for data updates, table management, and SQL file versioning.

Detailed documentation: See references/DATABASE_UPDATE_AUTOMATION_GUIDE.md for complete automation guide.

Core Principles

1. Use existing templates: Prioritize templates and tools in g3fo-db/common_sql/
2. Update i18n simultaneously: When updating tables requiring multilingual support, must also update m_system_i18n table
3. Automated workflow: Follow standardized automation including SQL generation, execution, and Git commit

Tables Requiring i18n Updates

When inserting or updating data in these tables, must simultaneously update m_system_i18n:

Table	i18n_id Format	Example
m_system_code	CODE-{4位数字ID}	CODE-0404
m_system_error_message	ERR-{error_code}	ERR-17100
m_market	MKT-{4位数字ID}	MKT-0001
m_currency	CURR-{currency_code}	CURR-USD
m_channel	CH-{channel_code}	CH-001
m_exchange	EXCH-{exchange_code}	EXCH-HKEX
m_country	CNTY-{country_code}	CNTY-HK
m_exchange_charge	EX_CHARGE-{id}	EX_CHARGE-1
m_company_charge	COM_CHARGE-{id}	COM_CHARGE-1

Automated Workflow

1. Data Input Phase

Request user input based on table type. For m_system_code:

• Code_type: [编码类型]
• Code_value: [编码值]
• Remark: [备注（用于生成多语言描述）]
• Sort: [排序号]

2. SQL Generation Phase

1. Get max ID (if applicable):

   SELECT COALESCE(MAX(id), 0) + 1 FROM {schema}.{table_name};
   

2. Generate i18n_id: Use format rules based on table type

3. Generate multilingual descriptions:

   • Extract or generate English, Simplified Chinese, Traditional Chinese from remark
   • Vietnamese and French optional

4. Generate complete SQL:

   • Main table INSERT/UPDATE
   • m_system_i18n INSERT/UPDATE (if applicable)

3. User Confirmation Phase

Display generated SQL and ask:

已生成以下 SQL 语句，请确认数据是否正确：

[显示SQL语句]

确认数据无误，是否继续下一步？(yes/no)

4. SQL Execution Phase

If user confirms:

1. Connect to database using MySQL MCP
   • Default database connection (automatically use when MySQL MCP or database connection is needed):
     • host: 192.168.3.233
     • user: root
     • password: afe123456
     • database: g3fo_base (for system tables like m_system_code, m_system_i18n, m_system_error_message, etc.)
     • database: g3fo_trade (for trade-related tables)
2. Execute SQL
3. Verify results
4. If failed, report error and stop

5. Git Commit Phase

After successful execution, ask:

SQL 执行成功！

是否需要将 SQL 提交到待执行文件夹中？(yes/no)

If confirmed, execute in this order to ensure remote repository and local data consistency:

1. Switch to g3fo-db directory and pull latest code (must execute first):

   cd g3fo-db
   git pull origin main
   

   • This step ensures getting latest file list and changes from remote repository
   • If pull fails (e.g., conflicts), report error and stop workflow

2. Determine target folder (based on latest pulled code):

   • Find latest "pending release {version}" folder in update_service_release
   • If not exists, create new folder:
     • View all version number folders in update_service_release (e.g., 1.5.1.0, 1.5.1.1, 1.5.1.17, etc.)
     • Find maximum version number
     • New version = max version + 0.0.0.1 (increment last digit)
     • Create folder: pending release {新版本号}
     • Auto-create set_version_01.sql:

       UPDATE `g3fo_base`.`m_system_setting`
       SET `param_value` = '1.5.1.0 M{版本号最后两位数字}',
           `update_on` = NOW()
       WHERE
           `param_name` = 'base.systemVersion';
       UPDATE `g3fo_base`.`m_system_setting`
       SET `param_value` = '0',
           `update_on` = NOW()
       WHERE
           `param_name` = 'base.patchNo';
       

     • Version mapping rules:
       • Extract last digit N from version number (format X.Y.Z.N)
       • Format as '1.5.1.0 M{N}'
       • Examples:
         • 1.5.1.17 → extract 17 → '1.5.1.0 M17'
         • 1.5.1.18 → extract 18 → '1.5.1.0 M18'
         • 1.5.1.10 → extract 10 → '1.5.1.0 M10'
         • 1.5.1.9 → extract 9 → '1.5.1.0 M9' (no zero padding)
   • Note: Folder list is now latest, avoiding filename conflicts

3. Generate filename (based on latest file list):

   • Format: {功能描述英文}_{序号}.sql
   • Sequence number rules:
     • View all .sql files in target folder (after git pull)
     • Calculate sequence number across all files uniformly, regardless of filename prefix
     • Extract sequence number method:
       1. Traverse all .sql files in folder
       2. Extract two-digit number after underscore from each filename (format: _XX.sql)
       3. Example: set_version_01.sql → extract 01, add_system_code_02.sql → extract 02
       4. Find maximum sequence number among all
       5. New sequence = max + 1
     • Use two-digit format (01-99)
     • Example:
       • If folder has: set_version_01.sql and add_system_code_02.sql
       • Extracted sequences: 01, 02
       • Max sequence: 02
       • New file sequence: 03
       • New filename: add_new_feature_03.sql
   • Important: Must generate after git pull to avoid conflicts

4. Detect and fix duplicate sequence numbers (before saving):

   • Scan all .sql files in target folder
   • Detect duplicates
   • If found, follow "Duplicate Sequence Detection and Auto-Fix" rules
   • Ensure all file sequences are unique and continuous

5. Save SQL file to target folder

6. Git commit and push:

   git add .
   git commit -m "feat: {简短描述}"
   git push origin main
   

   If push fails (remote has new commits):

   • Execute git pull origin main again
   • Resolve conflicts and push again

6. Completion Message

操作完成！

已执行的操作：
✓ SQL 语句已执行
✓ SQL 文件已保存到: update_service_release/pending release {version}/{filename}
✓ 已推送到 Git 仓库

Using Existing Templates

Insert System Menu and Route Permissions

Important: Adding menus and route permissions must use stored procedure files from common_sql folder.

Files to use:

• references/insert_system_menu_procedure.sql - Insert system menu
• references/insert_system_route_procedure.sql - Insert system route

Execution and commit rules:

1. SQL execution phase:

   • MySQL MCP doesn't support DELIMITER for stored procedures
   • Can use direct INSERT INTO or REPLACE INTO to insert same data
   • Ensure data matches stored procedure output exactly

2. Git commit phase:

   • Must use complete SQL from stored procedure file
   • Copy full stored procedure definition from common_sql folder
   • Add CALL statement at end to invoke procedure
   • Reference format in update_service_release/pending release 1.5.1.18

Insert system menu example:

-- Copy complete stored procedure definition from insert_system_menu_procedure.sql
-- ... (complete stored procedure code) ...

-- Add CALL statement at end
CALL InsertSystemMenu('菜单备注', 'menu-name', 'title_remark', 'ADMIN', NULL, 1);

Insert system route example:

-- Copy complete stored procedure definition from insert_system_route_procedure.sql
-- ... (complete stored procedure code) ...

-- Add CALL statement at end
CALL InsertSystemRoute('备注', '/route/path', '标题备注', 'ADMIN'|'USER');

File naming:

• Menu: insert_system_menu_procedure_{序号}.sql
• Route: insert_system_route_procedure_{序号}.sql

Create New Table

Reference references/create_table_template.sql format:

• Use CREATE TABLE IF NOT EXISTS
• Specify correct schema (e.g., g3fo_trade, g3fo_base)
• Include necessary fields, indexes, comments
• Use ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci

Table Structure Changes

Reference references/table_change_template.sql method:

• Use stored procedure to check if column exists
• Use IF EXISTS for idempotency checks
• Delete procedure after execution

Order Table Field Synchronization Rule

Important: When m_order table adds a field, must simultaneously add same field to:

1. m_order_actions - Order actions table
2. h_order - Order history table
3. h_order_actions - Order actions history table

Rules:

• Field name must be identical
• Field type must be identical
• Field constraints (NULL/NOT NULL, DEFAULT, etc.) must be identical
• Field comment must be identical
• Field position (AFTER clause) should be consistent

SQL generation requirements:

• Use stored procedure for idempotency checks (reference table_change_template.sql)
• Check field existence for each table separately, add if not exists
• Ensure all four tables' field changes in same SQL file

Example: If need to add field new_field VARCHAR(100) COMMENT '新字段' to m_order table, must simultaneously add same field to m_order_actions, h_order, h_order_actions tables.

SQL Statement Standards

1. Use REPLACE INTO instead of INSERT INTO for idempotency
2. Timestamp fields:
   • create_on: NOW()
   • update_on: NOW()
   • create_by: 'sys'
   • update_by: 'sys'
3. Add comments: Add function description comment at SQL file beginning

File Naming Standards

• Format: {功能描述英文}_{序号}.sql
• Sequence: Two-digit number (01-99), auto-increment
• Examples: add_system_code_02.sql, update_system_code_03.sql

Duplicate Sequence Detection and Auto-Fix

Important: Must detect and fix duplicate sequence numbers before generating new files or committing to Git

Detection Rules

1. Scan target folder: Check all .sql files in update_service_release/pending release {version}/
2. Extract sequence: Extract two-digit number after underscore from each filename
3. Detect duplicates: If multiple files use same sequence, trigger fix flow

Fix Rules

When duplicate sequences found (e.g., xxxxxx_03.sql and aaaaaaa_03.sql):

1. Analyze file dependencies:

   • Compare SQL content of both files
   • Check for dependencies:
     • File A references table/field/data created in File B
     • File A uses stored procedure/function defined in File B
     • File A updates data inserted in File B
   • Dependency detection methods:
     • Check if table names, field names, or data values in one file appear in another file
     • Check if CREATE/DROP operations in one file have corresponding references in another file
     • Check if INSERT/UPDATE operations in one file have corresponding queries in another file

2. Determine file order:

   • If dependencies exist:
     • Dependent file (referenced) keeps original sequence
     • Dependent file gets next available sequence
   • If no dependencies:
     • Order by file creation time (filesystem time)
     • Earlier file keeps original sequence
     • Later file gets next available sequence

3. Auto-extend subsequent files:

   • Find next available sequence (max + 1)
   • Rename file needing adjustment to new sequence
   • Check if subsequent files need extension:
     • If new sequence conflicts with subsequent files, auto-extend them
     • Recursively process until no conflicts

4. Execute fix:

   • Rename files (use git mv to preserve Git history)
   • Update Git index
   • Generate fix report

Fix Examples

Scenario 1: With dependencies

• Files: create_table_03.sql (creates table m_new_table), insert_data_03.sql (inserts data into m_new_table)
• Detection: insert_data_03.sql depends on create_table_03.sql
• Fix:
  • create_table_03.sql keeps 03
  • insert_data_03.sql → insert_data_04.sql

Scenario 2: No dependencies, order by creation time

• Files: add_system_code_03.sql (created: 2024-01-01), update_setting_03.sql (created: 2024-01-02)
• Detection: No dependencies
• Fix:
  • add_system_code_03.sql keeps 03 (earlier)
  • update_setting_03.sql → update_setting_04.sql (later)

Scenario 3: Need to extend subsequent files

• Files: file_a_03.sql, file_b_03.sql, file_c_04.sql, file_d_05.sql
• Detection: file_a_03.sql and file_b_03.sql duplicate, no dependencies, file_a_03.sql earlier
• Fix:
  • file_a_03.sql keeps 03
  • file_b_03.sql → file_b_04.sql
  • file_c_04.sql → file_c_05.sql (extended)
  • file_d_05.sql → file_d_06.sql (extended)

Scenario 4: Multiple duplicate sequences

• Files: file_a_03.sql, file_b_03.sql, file_c_04.sql, file_d_04.sql, file_e_05.sql
• Detection: 03 duplicate, 04 also duplicate
• Fix:
  • First handle 03 duplicate: file_a_03.sql keeps 03, file_b_03.sql → file_b_04.sql
  • Then handle 04 duplicate: file_c_04.sql keeps 04, file_d_04.sql → file_d_05.sql
  • Extend: file_e_05.sql → file_e_06.sql

Fix Report Format

After fix completion, generate report:

检测到重复序号，已自动修复：

修复的文件：
- file_b_03.sql → file_b_04.sql（原因：与 file_a_03.sql 重复，无依赖关系，按创建时间调整）
- file_c_04.sql → file_c_05.sql（原因：序号冲突，自动顺延）
- file_d_05.sql → file_d_06.sql（原因：序号冲突，自动顺延）

所有文件序号已修复，无重复。

Execution Timing

• Before generating new file: Detect and fix existing duplicate sequences
• Before committing to Git: Detect and fix again, ensure no duplicates
• Manual trigger: When user requests detection and fix

Error Handling

• SQL execution failure: Display error, don't execute Git operations
• Git operation failure: Display error, SQL file saved locally
• Data validation failure: Validate data format before generating SQL

Important Reminders

1. All table operations requiring i18n must simultaneously update m_system_i18n table
2. When m_order table adds field, must simultaneously add same field to m_order_actions, h_order, h_order_actions
3. When adding menus and route permissions, execution can use other methods, but Git commit must use complete SQL from stored procedure file
4. All SQL files must be saved to correct version folder
5. File sequences cannot be duplicated, must be incremental. Must detect and fix duplicates before generating new files and committing to Git
6. Use REPLACE INTO to ensure SQL can be executed repeatedly
7. Must get user confirmation before executing SQL

Continuous Improvement

This workflow is continuously updated and improved. If new tables requiring i18n are discovered, new naming conventions are needed, or process issues are found, update the DATABASE_UPDATE_AUTOMATION_GUIDE.md document.

Reference Files

For detailed templates and examples, see:

• references/DATABASE_UPDATE_AUTOMATION_GUIDE.md - Complete automation guide
• references/create_table_template.sql - Table creation template
• references/table_change_template.sql - Table structure change template
• references/insert_system_menu_procedure.sql - System menu insertion procedure
• references/insert_system_route_procedure.sql - System route insertion procedure
• references/system_code_update_template.sql - System code update template
• references/SQL_SITE_NAMING.md - SQL site naming conventions