5.1 KiB

Raw Permalink Blame History

用户服务文档技术栈合规性修正

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

变更概述

修正用户服务文档中不符合 jointo-tech-stack 规范的问题，确保文档与项目技术栈标准完全一致。

修正内容

1. 时间与时区规范 ✅

问题

列注释未说明 TIMESTAMPTZ 自动记录时区
Model 层缺少完整的字段描述

修正

数据库列注释：

-- ✅ 修正后
COMMENT ON COLUMN users.created_at IS '创建时间（自动记录时区）';
COMMENT ON COLUMN users.updated_at IS '更新时间（自动记录时区）';
COMMENT ON COLUMN users.deleted_at IS '软删除时间（自动记录时区）';

Model 层字段描述：

# ✅ 修正后
created_at: datetime = Field(
    default_factory=lambda: datetime.now(timezone.utc),
    description="创建时间（UTC）"
)
updated_at: datetime = Field(
    default_factory=lambda: datetime.now(timezone.utc),
    description="更新时间（UTC）"
)
deleted_at: Optional[datetime] = Field(
    default=None,
    description="软删除时间（UTC）"
)

数据类型说明表：

| `TIMESTAMPTZ` | 带时区的时间戳（事件时间） | `created_at`, `updated_at` |

2. Relationship 配置补充 ✅

问题

文档未说明如何配置 SQLModel Relationship（因为无物理外键）

修正

补充 TYPE_CHECKING 导入：

from typing import Optional, TYPE_CHECKING
from sqlmodel import Relationship

if TYPE_CHECKING:
    from app.models.attachment import Attachment

补充 Relationship 配置：

class User(SQLModel, table=True):
    avatar_id: Optional[UUID] = Field(
        default=None,
        description="头像附件ID - 应用层验证，关联 attachments.attachment_id"
    )
    
    # ✅ Relationship 配置（使用 primaryjoin，因为无物理外键）
    avatar: Optional["Attachment"] = Relationship(
        sa_relationship_kwargs={
            "primaryjoin": "User.avatar_id == Attachment.attachment_id",
            "foreign_keys": "[User.avatar_id]",
        }
    )

3. 导入路径修正 ✅

问题

generate_uuid 导入路径错误

修正

# ❌ 错误
from app.core.id_generator import generate_uuid

# ✅ 正确
from app.utils.id_generator import generate_uuid

4. 迁移脚本注释优化 ✅

问题

迁移脚本注释未强调使用 TIMESTAMPTZ

修正

# ✅ 修正后
# 2. 创建用户表（无外键约束，使用 TIMESTAMPTZ）
CREATE TABLE IF NOT EXISTS users (
    ...
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    ...
);

技术栈合规性检查

✅ 完全符合规范

UUID v7 应用层生成 ✅
- Model 层使用 default_factory=generate_uuid
- 未使用数据库 server_default
禁止物理外键约束 ✅
- 所有关联字段无 FOREIGN KEY 约束
- 应用层验证引用完整性
- 补充 Relationship 配置说明
枚举类型使用 SMALLINT ✅
- wechat_platform 使用 SMALLINT (1=mp, 2=open)
- 提供完整的枚举转换方法
时间与时区规范 ✅
- 数据库使用 TIMESTAMPTZ 记录事件时间
- Model 层使用 datetime.now(timezone.utc)
- 列注释说明自动记录时区
COMMENT 语法 ✅
- 使用 COMMENT ON TABLE/COLUMN 语法
- 符合 PostgreSQL 标准
索引策略 ✅
- 所有关联字段创建索引
- 使用条件唯一索引优化性能
软删除 ✅
- 使用 deleted_at 字段
- 索引包含 WHERE deleted_at IS NULL 条件

影响范围

文档修正

✅ docs/requirements/backend/04-services/user/user-service.md

无需修改

实际代码实现已符合规范
仅文档示例需要更新

验证清单

时间戳字段使用 TIMESTAMPTZ
列注释说明自动记录时区
Model 层字段包含完整描述
补充 Relationship 配置示例
修正导入路径
数据类型说明表更新
迁移脚本注释优化

总结

本次修正确保用户服务文档完全符合 jointo-tech-stack 规范，主要改进：

时区处理规范化 - 明确说明 TIMESTAMPTZ 自动记录时区
Relationship 配置完善 - 补充无物理外键情况下的关联配置
导入路径修正 - 统一使用正确的工具函数路径
文档一致性提升 - 所有示例代码与项目标准保持一致

文档现已完全符合项目技术栈规范，可作为用户服务实现的标准参考。

5.1 KiB Raw Permalink Blame History