# Credit Service SQL 注释语法修复

**日期**：2026-01-28  
**类型**：Bug Fix  
**影响范围**：`docs/requirements/backend/04-services/user/credit-service.md`

---

## 问题描述

`credit-service.md` 文档中所有表定义使用了 **行内 `COMMENT '...'` 语法**，这在 PostgreSQL 中是不支持的。

### 错误示例

```sql
CREATE TABLE credit_transactions (
    transaction_id UUID PRIMARY KEY COMMENT '交易唯一标识',  -- ❌ PostgreSQL 不支持
    user_id UUID NOT NULL COMMENT '用户 ID - 应用层验证',
    ...
);
```

### 规范要求

根据 `.claude/skills/jointo-tech-stack/references/database.md` 规范：

- PostgreSQL **不支持行内 COMMENT 语法**
- 必须使用 `COMMENT ON TABLE/COLUMN` 语法
- 所有表和列都需要完整的中文注释

---

## 修复内容

### 1. 修复表定义注释

将所有表的行内 `COMMENT '...'` 语法改为独立的 `COMMENT ON COLUMN` 语句。

#### 修复前

```sql
CREATE TABLE credit_transactions (
    transaction_id UUID PRIMARY KEY COMMENT '交易唯一标识',
    user_id UUID NOT NULL COMMENT '用户 ID - 应用层验证',
    ...
);
```

#### 修复后

```sql
CREATE TABLE credit_transactions (
    transaction_id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    ...
);

-- 表级注释
COMMENT ON TABLE credit_transactions IS '算力积分流水表 - 应用层保证引用完整性';

-- 列级注释
COMMENT ON COLUMN credit_transactions.transaction_id IS '交易唯一标识';
COMMENT ON COLUMN credit_transactions.user_id IS '用户 ID - 应用层验证';
...
```

### 2. 补充完整的列注释

为所有表的所有列添加了完整的中文注释：

#### credit_transactions（11 个列注释）
- transaction_id, user_id, transaction_type, amount, balance_before, balance_after
- related_order_id, related_consumption_id, description, created_at, updated_at

#### credit_consumption_logs（16 个列注释）
- consumption_id, user_id, feature_type, credits_consumed, task_id, task_status
- ai_job_id, resource_id, resource_type, task_params, frozen_at, expires_at
- created_at, updated_at, completed_at, remark

#### credit_packages（12 个列注释）
- package_id, name, description, price, credits, bonus_credits
- display_order, is_recommended, badge_text, is_active, created_at, updated_at

#### credit_pricing（7 个列注释）
- pricing_id, feature_type, pricing_rules, description, is_active, created_at, updated_at

#### credit_gifts（9 个列注释）
- gift_id, user_id, credits, gift_type, related_user_id, activity_id
- description, created_at, expires_at

### 3. 修复迁移脚本注释

更新 `app/migrations/008_credit_service_tables.py` 中的字段注释，补充所有缺失的列注释（从 7 个增加到 55 个）。

### 4. 时区标注规范

所有时间字段注释统一标注 `（UTC）`：

```sql
COMMENT ON COLUMN credit_transactions.created_at IS '交易创建时间（UTC）';
COMMENT ON COLUMN credit_transactions.updated_at IS '交易更新时间（UTC）';
```

---

## 修复的表

1. ✅ `credit_transactions` - 算力积分流水表
2. ✅ `credit_consumption_logs` - 积分消耗记录表
3. ✅ `credit_packages` - 积分套餐表
4. ✅ `credit_pricing` - 积分定价配置表
5. ✅ `credit_gifts` - 积分赠送记录表

---

## 文档变更

- **文档版本**：v2.0 → v2.1
- **变更说明**：修复 SQL 注释语法（改为 COMMENT ON COLUMN），符合 PostgreSQL 规范

---

## 验证

修复后的 SQL 语法符合以下规范：

1. ✅ 使用 `COMMENT ON TABLE` 添加表级注释
2. ✅ 使用 `COMMENT ON COLUMN` 添加列级注释
3. ✅ 所有表和列都有完整的中文注释
4. ✅ 关联字段注释标注"应用层验证"
5. ✅ 时间字段注释标注时区（UTC）
6. ✅ 枚举字段注释说明取值范围

---

## 相关文档

- 技术栈规范：`.claude/skills/jointo-tech-stack/references/database.md`
- 参考示例：`docs/requirements/backend/04-services/user/user-service.md`