创建仓库

2025-12-11 07:24:36 +08:00
commit 0d81c1792d
128 changed files with 15104 additions and 0 deletions
--- a/Go项目实战/01_数据模型建立/AI
+++ b/Go项目实战/01_数据模型建立/AI
@@ -0,0 +1,169 @@
+---
+tags: []
+aliases:
+  - 🛡️ AI 辅助数据建模通用 SOP (v1.0)
+date created: 星期日, 十二月 7日 2025, 9:16:59 晚上
+date modified: 星期二, 十二月 9日 2025, 11:27:28 晚上
+---
+
+# 🛡️ AI 辅助数据建模通用 SOP (v1.0)
+
+**核心理念:**
+
+1. **DBA 思维优先:** 永远先设计 SQL (Source of Truth)，再生成代码 (ORM)。
+2. **可视逻辑验证:** 在写代码前，必须通过 ER 图确认业务逻辑闭环。
+3. **对抗性评审:** 利用 AI 的多重人格（架构师/攻击者）自我找茬。
+
+---
+
+## 📋 准备工作：定义变量
+
+在使用以下 Prompt 前，请先在脑海或记事本中替换以下占位符：
+
+- `{技术栈}`: 例如 PostgreSQL 15, MySQL 8.0, TiDB
+- `{ORM框架}`: 例如 GORM (Go), TypeORM (Node), Hibernate (Java)
+- `{业务模块}`: 例如 用户中心, 订单交易, 库存管理
+- `{具体需求}`: 粘贴你的 PRD 片段或业务规则描述
+
+---
+
+## 阶段一：上下文注入与规范确立 (Context & Standards)
+
+**目的:** 确立“宪法”。防止 AI 自由发挥导致命名风格混乱或忽略关键字段。
+
+### 🤖 通用 Prompt (复制使用)
+
+```markdown
+你现在是我的 **Senior DBA (首席数据库管理员)** 和 **后端架构师**。
+我们将基于 `{技术栈}` 和 `{ORM框架}` 进行 `{业务模块}` 的数据库设计。
+
+在开始具体设计前，请牢记并遵守以下 **[设计宪法]**:
+
+1.  **命名规范:**
+    - 表名: 复数形式，snake_case (如 `user_orders`).
+    - 字段: snake_case (如 `is_verified`).
+    - 索引: `idx_表名_字段` (普通), `uniq_表名_字段` (唯一).
+    - 外键: `fk_本表_关联表`.
+
+2.  **基础字段 (Base Model):**
+    - 所有业务表必须包含: `id` (主键), `created_at`, `updated_at`.
+    - 需要软删除的表必须包含: `deleted_at`.
+    - 乐观锁(如有需要): `version`.
+
+3.  **类型约束:**
+    - 金额: 严禁使用 Float/Double，必须使用 `DECIMAL` 或 `BigInt` (存分).
+    - 枚举: 尽量在应用层处理，数据库存 `SmallInt` 或 `String`，避免使用 DB 级 ENUM.
+    - 时间: 统一使用带时区的 `TIMESTAMPTZ` (PostgreSQL) 或 `DATETIME`.
+
+4.  **安全与性能:**
+    - 必填字段显式标记 `NOT NULL`。
+    - 外键必须加索引。
+    - 物理外键约束建议使用 `ON DELETE RESTRICT` 防止误删，除非明确需要级联。
+
+收到请回复：“DBA 模式已就绪，请提供具体业务需求。”
+```
+
+---
+
+## 阶段二：概念验证 (Conceptual Modeling - ER Diagram)
+
+**目的:** 宏观排雷。通过可视化图表快速识别逻辑错误（如：1 对多搞成了多对多，或者环状依赖）。
+
+### 🤖 通用 Prompt (复制使用)
+
+```Markdown
+请根据以下 `{具体需求}`，绘制 **Mermaid 格式** 的 ER 关系图 (Entity Relationship Diagram)。
+
+**需求输入:**
+"""
+(在此处粘贴你的业务逻辑，例如：一个用户可以有多个角色，文章必须属于一个分类…)
+"""
+
+**绘图要求:**
+1.  展示实体(Entity)及其核心属性。
+2.  精准标注关系基数 (Cardinality):
+    - `||--o{` (1 对多)
+    - `}|--|{` (多 对 多，需画出中间表)
+    - `||--||` (1 对 1)
+3.  在图表下方简要说明关键关系的业务含义。
+```
+
+---
+
+## 阶段三：物理建模 (Physical Schema - SQL DDL)
+
+**目的:** 产出真理。这是最关键的一步，SQL DDL 定义了数据的最终形态。
+
+### 🤖 通用 Prompt (复制使用)
+
+```Markdown
+ER 图确认无误。请生成 **生产级 (Production-Ready) 的 SQL DDL 建表脚本**。
+
+**执行要求:**
+1.  **完整性:** 包含 `CREATE TABLE`, `CREATE INDEX`, 以及必要的 `COMMENT ON` 语句。
+2.  **字段细节:**
+    - 针对 JSON 数据使用数据库原生类型 (如 PG 的 `JSONB`)。
+    - 针对长文本使用 `TEXT`。
+    - 默认值 `DEFAULT` 处理到位 (如 `DEFAULT 0`, `DEFAULT FALSE`, `DEFAULT NOW()`).
+3.  **约束定义:**
+    - 明确定义 `PRIMARY KEY`。
+    - 显式定义 `CONSTRAINT` 名称 (便于排错)。
+4.  **索引策略:**
+    - 除了主键，请根据业务查询场景（如“按状态查询”、“按时间范围排序”）主动添加辅助索引。
+    - 解释每个索引添加的理由。
+
+请直接输出 SQL 代码块。
+```
+
+---
+
+## 阶段四：代码映射 (Code Generation - ORM Struct)
+
+**目的:** 翻译。将 SQL 完美映射为代码，利用 AI 自动处理繁琐的 Tag。
+
+### 🤖 通用 Prompt (复制使用)
+
+```Markdown
+基于上述生成的 SQL 脚本，请编写对应的 `GORM (Go)` 模型代码 (Entity/Model)。
+
+**代码要求:**
+1.  **Tag 映射:** 完整包含 DB 列名映射、主键定义、默认值定义。
+    - (若为 GORM): 使用 `gorm:"column:xyz;type:…"`.
+2.  **JSON 序列化:**
+    - 所有字段添加 `json:"camelCaseName"`.
+    - **敏感字段** (如密码、盐值) 必须设为 `json:"-"` 以防接口泄露。
+3.  **类型安全:**
+    - 数据库允许 NULL 的字段，在代码中请使用 指针类型 (如 `*string`) 或 专用 Null 类型 (如 `sql.NullString`)。
+4.  **文件结构:** 不需要 `gorm.Model` 继承，请显式写出字段，以保证对 JSON Tag 的控制权。
+
+请输出 Go/Java/TS 代码块。
+```
+
+---
+
+## 阶段五：红队测试与评审 (Critique & Optimization)
+
+**目的:** 找茬。让 AI 模拟极端的架构师，攻击当前设计，发现隐患。
+
+### 🤖 通用 Prompt (复制使用)
+
+```Markdown
+现在，请切换角色为 **Google 首席架构师 (Principal Architect)**。
+请对上述 SQL 设计进行 **“红队测试” (Red Teaming)** 评审。
+
+**评审维度:**
+1.  **扩展性瓶颈:** 如果单表数据量达到 5000 万行，目前的索引设计是否会失效？哪个查询会最慢？
+2.  **数据一致性:** 是否存在业务逻辑上需要事务保证，但当前 Schema 难以支持的场景？
+3.  **反范式建议:** 是否有过度规范化导致查询需要 Join 太多表？是否建议增加冗余字段？
+4.  **边缘情况:** `NULL` 值的处理是否会在聚合查询时导致 Bug？
+
+请列出 top 3 风险点，并给出具体的 **优化建议** (如：修改索引、增加冗余字段、修改类型)。
+```
+
+---
+
+### 💡 使用小贴士
+
+1. **不要一次性发完:** 强烈建议**分步执行**。AI 的上下文窗口虽然大，但分步确认能极大提高准确率。
+2. **迭代修改:** 在“阶段三”生成 SQL 后，如果你发现不满意，手动修改 SQL，然后把修改后的 SQL 发给 AI 进入“阶段四”。**永远以 SQL 为准**。
+3. **保留对话:** 把这个对话保留为一个独立的 Session，后续增加字段时，回到这个 Session 继续操作，保持上下文连贯。
--- a/Go项目实战/01_数据模型建立/Mermaid
+++ b/Go项目实战/01_数据模型建立/Mermaid
@@ -0,0 +1,65 @@
+---
+tags: []
+date created: 星期日, 十二月 7日 2025, 1:31:36 下午
+date modified: 星期日, 十二月 7日 2025, 1:32:46 下午
+---
+
+```mermaid
+erDiagram
+    users ||--o{ user_roles : "assigns"
+    roles ||--o{ user_roles : "assigned to"
+    roles ||--o{ role_permissions : "grants"
+    permissions ||--o{ role_permissions : "granted to"
+    
+    users {
+        bigint id PK "主键 (BigSerial)"
+        string username "用户名 (唯一)"
+        string password_hash "哈希密码 (Argon2/Bcrypt)"
+        string email "邮箱 (可选，唯一)"
+        string nickname "昵称"
+        string avatar_url "头像URL"
+        text bio "简介"
+        string status "状态 (active/inactive/banned)"
+        timestamptz created_at "创建时间"
+        timestamptz updated_at "更新时间"
+        timestamptz deleted_at "软删除时间"
+    }
+    
+    roles {
+        bigint id PK "主键 (BigSerial)"
+        string code "角色代码 (admin/editor/user)"
+        string name "角色名称"
+        text description "角色描述"
+        boolean is_system "系统角色（不可删除）"
+        timestamptz created_at "创建时间"
+        timestamptz updated_at "更新时间"
+        timestamptz deleted_at "软删除时间"
+    }
+    
+    permissions {
+        bigint id PK "主键 (BigSerial)"
+        string code "权限代码 (module:action:scope)"
+        string name "权限名称"
+        text description "权限描述"
+        string category "权限分类"
+        timestamptz created_at "创建时间"
+        timestamptz updated_at "更新时间"
+        timestamptz deleted_at "软删除时间"
+    }
+    
+    user_roles {
+        bigint id PK "主键 (BigSerial)"
+        bigint user_id FK "用户ID"
+        bigint role_id FK "角色ID"
+        timestamptz created_at "关联时间"
+        timestamptz updated_at "更新时间"
+    }
+    
+    role_permissions {
+        bigint id PK "主键 (BigSerial)"
+        bigint role_id FK "角色ID"
+        bigint permission_id FK "权限ID"
+        timestamptz created_at "关联时间"
+        timestamptz updated_at "更新时间"
+    }
+```
--- a/Go项目实战/01_数据模型建立/规范数据库设计
+++ b/Go项目实战/01_数据模型建立/规范数据库设计
@@ -0,0 +1,183 @@
+---
+tags: []
+aliases:
+  - 🛠️ Database Engineering & Migration Standard (v1.0)
+date created: 星期日, 十二月 7日 2025, 10:31:59 晚上
+date modified: 星期二, 十二月 9日 2025, 10:14:44 晚上
+---
+
+# 🛠️ Database Engineering & Migration Standard (v1.0)
+
+文档用途: 规范数据库设计、变更管理及工程流操作。
+
+适用范围: 所有涉及 Schema 变更的后端开发任务。
+
+核心原则: Code First (Logic) but SQL First (Schema). 严禁生产环境使用 ORM 自动建表。
+
+---
+
+## 1. 基础设施与工具链 (Infrastructure & Tools)
+
+本项目采用 **“容器化数据库 + 版本化迁移工具”** 的架构。
+
+| **组件**          | **选型**             | **说明**                                    |
+| --------------- | ------------------ | ----------------------------------------- |
+| **Database**    | **PostgreSQL 15+** | 运行于 Docker 容器中，保证开发/生产环境一致。               |
+| **Schema Mgmt** | **Golang-Migrate** | CLI 工具，用于生成和执行版本化 SQL 脚本。                 |
+| **GUI Client**  | **Navicat**        | 推荐 Navicat / DataGrip / DBeaver，仅用于设计和验证。 |
+| **Automation**  | **Make**           | 封装常用命令，屏蔽底层复杂参数。                          |
+
+### 1.1 目录结构规范
+
+Plaintext
+
+```bash
+project-root/
+├── migrations/                 # [Source of Truth] 存放所有 SQL 变更文件
+│   ├── 000001_init_users.up.sql
+│   └── 000001_init_users.down.sql
+├── internal/
+│   └── {domain}/               # 领域包
+│       └── entity.go           # [Code Mapping] GORM 结构体定义
+├── docker-compose.yml          # 定义本地 DB 容器
+└── Makefile                    # 集成迁移命令
+```
+
+---
+
+## 2. 数据库设计规范 (Design Standards)
+
+### 2.1 命名约定
+
+- **表名:** 必须使用**复数**形式，`snake_case` (e.g., `users`, `order_items`).
+- **字段名:** 全小写，`snake_case` (e.g., `created_at`, `user_id`).
+- **索引名:**
+    - 普通索引: `idx_tablename_column`
+    - 唯一索引: `uniq_tablename_column`
+- **外键名:** `fk_tablename_ref_tablename`
+
+### 2.2 关键字段约束
+
+所有业务表**必须**包含以下基础字段：
+
+```SQL
+id          BIGSERIAL PRIMARY KEY, -- 或 UUID
+created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+deleted_at  TIMESTAMPTZ            -- 仅在需要软删除时添加
+```
+
+### 2.3 设计禁忌
+
+1. **严禁** 使用物理外键的级联删除 (`ON DELETE CASCADE`)，除非是关联性极强的子表（如文章标签关联）。核心业务数据必须使用 `ON DELETE RESTRICT`。
+2. **严禁** 在涉及金额的字段使用 `FLOAT` 或 `DOUBLE`，必须使用 `DECIMAL` 或 `BIGINT` (分)。
+3. **严禁** 将 `NULL` 作为布尔值的第三种状态。布尔字段必须设置 `NOT NULL DEFAULT FALSE`。
+
+---
+
+## 3. 标准作业流程 (SOP)
+
+开发人员需严格遵循以下 **5 步闭环** 进行数据库变更：
+
+### Step 1: 启动环境
+
+确保本地 Docker 数据库正在运行。
+
+```Bash
+make network  # 对应 docker-compose up -d
+```
+
+### Step 2: 创建迁移文件 (Create)
+
+使用 Makefile 生成成对的 `.sql` 文件（up/down）。
+
+- `name` 参数应简短描述变更内容（如 `add_avatar_to_users`）。
+
+```Bash
+make new_migration name=init_schema
+# 输出:
+# Created migrations/000001_init_schema.up.sql
+# Created migrations/000001_init_schema.down.sql
+```
+
+### Step 3: 编写 SQL (Edit)
+
+- **UP 文件:** 填入 `CREATE TABLE`, `ALTER TABLE`, `CREATE INDEX` 等正向操作。
+    - _技巧:_ 可在 GUI 工具中设计好表结构，复制生成的 DDL 语句粘贴至此。
+- **DOWN 文件:** 填入对应的回滚操作（如 `DROP TABLE`, `DROP INDEX`）。
+
+### Step 4: 执行变更 (Apply)
+
+将 SQL 应用到本地数据库。
+
+```Bash
+make migrate_up
+```
+
+_验证:_ 使用 GUI 工具连接数据库，确认表结构已更新。
+
+### Step 5: 代码映射 (Mapping)
+
+在 `internal/{domain}/entity.go` 中编写对应的 Go Struct。
+
+- 确保 `gorm` tag 与数据库定义一致。
+- 确保 `json` tag 符合 API 契约。
+
+---
+
+## 4. 自动化配置 (Automation)
+
+将以下内容固化到项目根目录的 `Makefile` 中。
+
+> **注意:** 确保 `DB_DSN` 与 `docker-compose.yml` 中的配置完全一致。
+
+```Makefile
+# ==============================================================================
+# Database & Migration Logic
+# ==============================================================================
+
+# Database Connection String
+# 格式: postgres://user:password@host:port/dbname?sslmode=disable
+DB_DSN := postgres://postgres:secret@localhost:5432/cms_core?sslmode=disable
+
+.PHONY: network new_migration migrate_up migrate_down migrate_force
+
+# 1. 启动本地环境
+network:
+	docker-compose up -d
+
+# 2. 创建新的迁移文件 (Usage: make new_migration name=create_users)
+new_migration:
+	@if [ -z "$(name)" ]; then echo "Error: name is required"; exit 1; fi
+	migrate create -ext sql -dir migrations -seq $(name)
+
+# 3. 执行所有未执行的迁移 (Up)
+migrate_up:
+	migrate -path migrations -database "$(DB_DSN)" up
+
+# 4. 回滚上一次迁移 (Down 1 step)
+migrate_down:
+	migrate -path migrations -database "$(DB_DSN)" down 1
+
+# 5. 强制修复版本 (当 dirty database 时使用, version 为具体的版本号)
+migrate_force:
+	migrate -path migrations -database "$(DB_DSN)" force $(version)
+```
+
+---
+
+## 5. 故障排查 (Troubleshooting)
+
+**Q: 执行 migrate_up 时报错 "Dirty database version x".**
+
+- **原因:** 上一次迁移执行到一半失败了（可能是 SQL 语法错误），导致版本锁死。
+- **解决:**
+    
+    1. 手动修复 SQL 文件中的语法错误。
+    2. 执行 `make migrate_force version=x` (x 是失败前的那个版本号)。
+    3. 再次执行 `make migrate_up`。
+
+**Q: 多人协作时产生版本冲突。**
+
+- **现象:** 你有一个 `0003_add_xx.up.sql`，同事提交代码后也有一个 `0003_add_yy.up.sql`。
+- **解决:** 重命名你的迁移文件编号为 `0004`，确保序列号在时间轴上是递增且唯一的。