414 lines
16 KiB
Markdown
414 lines
16 KiB
Markdown
---
|
|
name: g3fo-db-ops
|
|
description: 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):
|
|
```sql
|
|
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):
|
|
```bash
|
|
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`**:
|
|
```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**:
|
|
```bash
|
|
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:**
|
|
```sql
|
|
-- 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:**
|
|
```sql
|
|
-- 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
|