# 商城数据库设计文档总览

本文档是商城数据库的入口索引，提供各模块详细文档的链接与摘要。

## 核心文档

1. **数据库概览**
   - [00 概览](sql/00_overview.md): 数据库设计目标、核心概念与术语说明
   - [01 表清单](sql/01_tables_catalog.md): 按业务域划分的完整表结构说明
   - [02 实体关系](sql/02_relationships_er.md): 表间关系与ER图说明

2. **数据字典**
   - [03 状态字典](sql/03_enums_status_dict.md): 所有状态字段的枚举值与业务含义

3. **核心功能**
   - [04 触发器与函数](sql/04_triggers_and_functions.md): 数据库层实现的业务规则
   - [05 权限矩阵](sql/05_rls_permissions_matrix.md): Supabase RLS行级安全策略说明
   - [06 索引与查询](sql/06_indexes_and_query_patterns.md): 索引设计与典型查询模式

4. **业务流程**
   - [07 业务流](sql/07_business_workflows.md): 核心业务场景的完整数据流
   - [08 一致性边界](sql/08_data_consistency_boundaries.md): 数据库保证什么/应用层需要保证什么

5. **部署维护**
   - [09 迁移策略](sql/09_migrations_and_versions.md): 不同环境下的迁移指南
   - [10 质量检查](sql/10_quality_checks.md): 自检清单与验收标准

## 快速开始

### 新环境初始化

```bash
# 1. 执行基础迁移
psql -f doc_mall/database/mall_migration.sql

# 2. 应用安全策略
psql -f doc_mall/database/mall_seo_security.sql

# 3. 验证数据库状态
psql -f mall_sql/tests/mall_database_check.sql
```

### 核心表关系速查

- 用户: `ak_users` ↔ `ml_user_profiles` (1:1)
- 商品: `ml_products` (SPU) ↔ `ml_product_skus` (1:N)
- 订单: `ml_orders` ↔ `ml_order_items` (1:N)
- 店铺: `ak_users` (merchant) ↔ `ml_shops` (1:1)

## 设计原则

1. **Supabase优先**
   - 使用 `auth.uid()` + RLS 进行数据隔离
   - 前端可直接安全地访问数据库

2. **性能优化**
   - 高频查询字段都有索引
   - 使用触发器维护汇总字段
   - 合理使用JSONB存储非结构化数据

3. **可扩展性**
   - 所有核心表都有`cid`(自增ID)和`slug`用于SEO
   - 模块化设计，支持功能扩展

## 常见问题

Q: 如何添加新状态？
A: 需要更新CHECK约束、相关触发器和状态字典文档。

Q: 如何添加新表？
A: 参考现有表结构，确保包含`id`(UUID)、`cid`(SERIAL)、`created_at`等标准字段。

Q: 如何测试RLS策略？
A: 使用`set local request.jwt.claim.sub = 'user-id'`模拟不同用户访问。

## 贡献指南

1. 修改数据库前请先更新相关文档
2. 保持命名一致性
3. 提供回滚脚本
4. 更新版本号

## 版本历史

- v1.0.0 (2024-02-01): 初始版本
- v1.1.0 (2024-02-15): 新增订阅模块

## 联系

如有问题，请联系数据库管理员或提交issue。