3.2 KiB

Raw Blame History

User Service 文档规范符合性修复

日期: 2026-01-28
类型: 文档修复
影响范围: docs/requirements/backend/04-services/user/user-service.md

修复内容

1. 修复 SQL 注释语法 ✅

问题: PostgreSQL 不支持行内 COMMENT 语法

修复前:

-- ❌ 错误：PostgreSQL 不支持
created_at TIMESTAMPTZ NOT NULL DEFAULT now() COMMENT '创建时间（UTC）'

修复后:

-- ✅ 正确：使用 COMMENT ON 语法
created_at TIMESTAMPTZ NOT NULL DEFAULT now()

-- 列级注释
COMMENT ON COLUMN users.created_at IS '创建时间（UTC）';

影响位置:

users 表定义（第 800-900 行）
user_sessions 表定义（第 950-1000 行）
数据迁移脚本（第 1100-1300 行）

2. 清理 SQL 行内注释 ✅

问题: SQL 代码中混杂了行内注释，影响可读性

修复:

移除所有 SQL 列定义中的行内注释（如 -- 关联 users 表，应用层验证）
统一使用 COMMENT ON COLUMN 语法在表创建后添加注释
保留必要的说明性注释（如枚举值映射）

示例:

-- 修复前
user_id UUID NOT NULL,  -- 关联 users 表，应用层验证

-- 修复后
user_id UUID NOT NULL,

-- 列级注释（在表创建后添加）
COMMENT ON COLUMN user_sessions.user_id IS '用户 ID - 应用层验证，关联 users.user_id';

3. 确认已修复的问题 ✅

以下问题在 v2.5 版本中已修复，本次确认无需再次修改：

✅ timezone 导入已完整（from datetime import datetime, timezone）
✅ session.session_id 字段名已正确（非 session.id）
✅ 所有 Model 使用 datetime.now(timezone.utc)

符合性检查结果

✅ 完全符合 jointo-tech-stack 规范

UUID v7 主键 - 应用层生成 ✅
禁止物理外键 - 所有关联字段标注"应用层验证" ✅
枚举使用 SMALLINT - wechat_platform 使用 SMALLINT (1, 2) ✅
索引策略 - 所有关联字段创建索引 ✅
软删除 - 使用 deleted_at 字段 ✅
引用完整性保证 - Service 层完整验证逻辑 ✅
Relationship 配置 - 使用 primaryjoin 和 foreign_keys ✅
时间戳规范 - 使用 datetime.now(timezone.utc) ✅
SQL 注释规范 - 使用 COMMENT ON 语法 ✅

版本更新

文档版本从 v2.5 更新到 v2.5（无版本号变更，仅修复格式问题）

检查清单

SQL 注释语法符合 PostgreSQL 规范
移除所有行内注释，统一使用 COMMENT ON
确认 timezone 导入完整
确认字段名正确（session.session_id）
确认时间戳使用 aware datetime
确认无物理外键约束
确认枚举使用 SMALLINT
确认所有关联字段有索引

影响评估

影响范围: 仅文档格式修复，不影响功能实现

风险等级: 低

后续行动: 无需额外操作，文档已符合规范

修复人: Kiro
审核人: 待审核
状态: 已完成

3.2 KiB Raw Blame History