# WDS框架 - 数据库设计师智能体 使用指南

## Profile

* **author**: Wantsong
* **version**: V1.0
* **date**: 2025-06-07

## 1. 智能体概述

**数据库设计师与审计师智能体**是专为WDS框架打造的AI设计助手。它具备两大核心能力：

1. **设计新表**：根据您的业务需求，从零开始创建完全符合WDS规范的MySQL建表SQL。
2. **审查现有表**：审计您提供的SQL脚本，发现与WDS规范不符之处，并提供详细的优化报告。

它的价值在于**提升效率、保障规范、统一标准、发现隐患**。

## 2. 准备工作

在使用本智能体前，请确保您已完成以下准备工作。这对于智能体的正确运行至关重要。

- **方式一（推荐，长期使用）：知识库模式**
  1. **创建智能体**：在支持知识库功能的AI平台中，使用我们提供的**CCPE提示词**作为智能体的系统指令/角色定义。
  2. **上传知识**：将以下两个规范文档上传并关联到该智能体：
      - `15. 数据库设计规范.md`
      - `16. 数据库操作设计.md`
  这样，智能体就拥有了WDS框架的“长期记忆”。

- **方式二（临时测试）：上下文注入模式**
  在每次会话的开始，将**CCPE提示词**和上述两个**规范文档的全文**一并粘贴到输入框，然后再提出您的具体需求。

## 3. 如何提出有效需求

本智能体支持两种操作模式，它会根据您的输入自动判断。

### **3.1 模式A：设计新表**

向智能体提出清晰、具体的需求是获得高质量输出的关键。请遵循以下模板和原则。

#### 3.1.1 基本原则

- **明确具体**：避免使用模糊的描述。例如，不要只说“需要一个价格字段”，而应说明是“市场价”还是“销售价”，单位是“元”还是“分”。
- **提供上下文**：告知智能体这张表属于哪个业务模块，主要用途是什么。
- **描述查询场景**：**这是设计高效索引的最重要信息**。请明确告知哪些字段会经常被用作查询条件（`WHERE`）、排序（`ORDER BY`）或分组（`GROUP BY`）。

#### 3.1.2 需求模板

建议使用以下结构化模板向智能体提出需求，以确保信息的完整性。

```md
你好，数据库设计师。请为WDS系统设计一张新表。

- **业务模块**: [例如：商品中心、订单管理、会员系统]
- **表名建议**: [例如：商品信息表]
- **表的主要用途**: [例如：用于存储平台销售的商品基本信息]

- **字段列表**:
  - **商品名称**: 字符串类型，长度约50，不能为空。
  - **商品编码**: 字符串，唯一，不能为空，长度32。
  - **商品分类ID**: 关联商品分类表的主键。
  - **品牌名称**: 字符串，长度约50。
  - **市场价**: 金额，单位为元。
  - **库存数量**: 整数。
  - **商品主图**: 字符串，存储URL，长度255。
  - **商品详情**: 富文本内容，可能很长。
  - **上架状态**: 枚举类型，可选值为：1-已上架, 0-未上架。默认未上架。
  - **是否推荐**: 布尔类型，表示是否推荐到首页。

- **关键查询场景**:
  1. 经常需要根据 **商品编码** 精确查询商品。
  2. 经常需要根据 **商品名称**进行模糊搜索。
  3. 后台管理列表需要按 **商品分类ID** 筛选，并按 **创建时间** 倒序排序。
  4. 经常会查询 **上架状态** 为“已上架”的商品。
```

#### 3.1.3 优质示例

**示例一：简单的业务表**
> **用户输入**：
> “你好，请帮我设计一张‘系统公告表’。属于‘系统管理’模块。主要用于发布系统级通知。需要包含字段：公告标题（字符串，200）、公告类型（枚举：1-通知, 2-公告）、公告内容（富文本）、发布状态（枚举：0-草稿, 1-已发布）、发布人、发布时间。关键查询场景是：前台用户查询‘已发布’的公告，并按发布时间倒序排列。”

**示例二：包含关联关系的表**
> **用户输入**：
> “你好，我需要一张‘订单主表’，属于‘订单中心’模块。用于记录用户的订单信息。字段包括：订单号（唯一，字符串32）、用户ID（关联用户表）、订单总金额（单位分）、实际支付金额（单位分）、支付状态（枚举：WAIT_PAY-待支付, PAID-已支付, CANCELLED-已取消）、收货地址ID、订单备注。关键查询场景：1. 根据订单号查询。2. 查询某个用户的所有订单，按创建时间倒序。3. 查询所有‘待支付’的订单。”

### **3.2 模式B：审查现有SQL脚本**

当您已经手写了一份SQL脚本，或需要检查历史代码是否符合最新规范时，请向它提供**完整的`CREATE TABLE` SQL代码**。

#### 3.2.1 需求模板

```
你好，请帮我审查以下SQL脚本是否符合WDS数据库设计规范，并给出优化建议。

[将您的SQL代码粘贴在这里，并用```sql包裹]
```

#### 3.2.2 示例
>
> “你好，请帮我审查以下SQL脚本是否符合WDS数据库设计规范，并给出优化建议。”
>
> ```sql
> CREATE TABLE `t_product` (
>   `productId` INT AUTO_INCREMENT PRIMARY KEY,
>   `product_Name` VARCHAR(255) NOT NULL,
>   `Code` VARCHAR(50) UNIQUE,
>   `price` FLOAT,
>   `description` TEXT,
>   `created_at` DATETIME,
>   INDEX (product_Name)
> ) ENGINE=MyISAM CHARSET=utf8;
> ```

## 4. 理解智能体的输出

### 4.1 设计模式的输出内容

您将从智能体那里得到一份格式化好的`CREATE TABLE` SQL脚本。

- **SQL脚本**：一份可以直接在MySQL 8.0中执行的建表语句。
- **设计说明 (可选)**：在某些复杂情况下，智能体可能会在SQL代码前后附上简短的说明，解释其设计决策（例如，为什么创建了一个复合索引）。

### 4.2 审查模式的输出

您将得到一份结构化的**审计报告**，通常包含以下部分：

- **总体评价**：对脚本质量的简要总结。
- **[严重违规]**：必须修复的问题，通常违反了WDS的核心规范（如主键、审计字段等）。
- **[优化建议]**：强烈建议修改的问题，有助于提升性能和可维护性。
- **[代码风格]**：关于注释、命名等可读性方面的建议。

每个问题点都会清晰地指出**问题所在、违反的规范、以及如何修复**。

**示例审查报告片段：**
> **总体评价**: 该脚本存在多处严重违反WDS规范的问题，不建议直接使用。
>
> **[严重违规]**
>
> 1. **主键类型错误**: 字段 `productId` 使用 `INT AUTO_INCREMENT` 作为主键。
>     - **违反规范**: `15.3.2` 要求业务表主键必须为 `id VARCHAR(32)`。
>     - **修复建议**: 修改主键为 `id` `VARCHAR(32) NOT NULL`。
> 2. **审计字段缺失**: 脚本缺少 `create_by`, `update_by`, `update_time` 等标准审计字段。
>     - **违反规范**: `15.6` 业务表标准结构。
>     - **修复建议**: 在表中添加所有标准审计字段。
> ...

## 5. 常见问题与最佳实践

- **问：如果智能体的输出不完全符合我的想法怎么办？**
  **答**：这通常意味着您的初始需求不够具体。请根据输出结果，**优化并细化您的需求描述**，然后再次提交。例如，明确指出“市场价请使用`DECIMAL(10,2)`类型”或“请为‘用户ID’和‘支付状态’创建一个复合索引”。

- **问：智能体提示我的需求与规范冲突，怎么办？**
  **答**：这是智能体的**核心价值**所在。它在为您避免潜在的设计问题。请首先复查WDS设计规范。如果确实需要特例处理，请在需求中明确说明“**我知道这不符合常规规范，但业务要求必须如此，请按我的要求生成**”。

- **问：如何设计多个关联的表（如订单和订单项）？**
  **答**：建议**一次只设计一张表**。先完成主表（如`t_order_main`）的设计，然后在设计从表（如`t_order_item`）时，在需求中明确指出其外键关联，例如：“需要一个`order_id`字段，用于关联订单主表”。

- **问：审查报告太长，能直接给我最终的正确脚本吗？**
  **答**：可以。在智能体给出审查报告后，您可以继续追问：“**请根据你的审查报告，直接提供一份完全修正后的SQL脚本。**”

- **问：我只是想快速检查一个字段的命名是否合规，可以吗？**
  **答**：可以，但提供完整的`CREATE TABLE`上下文效果最好。因为规范是整体性的（例如，索引命名依赖于表名和字段名）。建议总是提供完整脚本进行审查。

- **最佳实践**：
  - **新人培训**: 让新团队成员使用**审查模式**来学习WDS的数据库规范。
  - **代码审查 (CR)**: 在代码合并前，将新加的DDL脚本交由智能体进行第一轮自动化审查。
  - **设计与审查结合**: 先用**设计模式**生成初版，然后根据业务微调，最后再用**审查模式**确认无误。