3.9 KiB

Raw Permalink Blame History

Credit Service SQL 注释语法修复

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

问题描述

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

错误示例

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 语句。

修复前

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

修复后

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）：

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

修复的表

✅ credit_transactions - 算力积分流水表
✅ credit_consumption_logs - 积分消耗记录表
✅ credit_packages - 积分套餐表
✅ credit_pricing - 积分定价配置表
✅ credit_gifts - 积分赠送记录表

文档变更

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

验证

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

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

3.9 KiB Raw Permalink Blame History