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

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

---

## 变更概述

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

---

## 修正内容

### 1. 时间与时区规范 ✅

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

#### 修正

**数据库列注释**：
```sql
-- ✅ 修正后
COMMENT ON COLUMN users.created_at IS '创建时间（自动记录时区）';
COMMENT ON COLUMN users.updated_at IS '更新时间（自动记录时区）';
COMMENT ON COLUMN users.deleted_at IS '软删除时间（自动记录时区）';
```

**Model 层字段描述**：
```python
# ✅ 修正后
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）"
)
```

**数据类型说明表**：
```markdown
| `TIMESTAMPTZ` | 带时区的时间戳（事件时间） | `created_at`, `updated_at` |
```

---

### 2. Relationship 配置补充 ✅

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

#### 修正

**补充 TYPE_CHECKING 导入**：
```python
from typing import Optional, TYPE_CHECKING
from sqlmodel import Relationship

if TYPE_CHECKING:
    from app.models.attachment import Attachment
```

**补充 Relationship 配置**：
```python
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` 导入路径错误

#### 修正

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

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

---

### 4. 迁移脚本注释优化 ✅

#### 问题
- 迁移脚本注释未强调使用 TIMESTAMPTZ

#### 修正

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

---

## 技术栈合规性检查

### ✅ 完全符合规范

1. **UUID v7 应用层生成** ✅
   - Model 层使用 `default_factory=generate_uuid`
   - 未使用数据库 `server_default`

2. **禁止物理外键约束** ✅
   - 所有关联字段无 `FOREIGN KEY` 约束
   - 应用层验证引用完整性
   - 补充 Relationship 配置说明

3. **枚举类型使用 SMALLINT** ✅
   - `wechat_platform` 使用 SMALLINT (1=mp, 2=open)
   - 提供完整的枚举转换方法

4. **时间与时区规范** ✅
   - 数据库使用 `TIMESTAMPTZ` 记录事件时间
   - Model 层使用 `datetime.now(timezone.utc)`
   - 列注释说明自动记录时区

5. **COMMENT 语法** ✅
   - 使用 `COMMENT ON TABLE/COLUMN` 语法
   - 符合 PostgreSQL 标准

6. **索引策略** ✅
   - 所有关联字段创建索引
   - 使用条件唯一索引优化性能

7. **软删除** ✅
   - 使用 `deleted_at` 字段
   - 索引包含 `WHERE deleted_at IS NULL` 条件

---

## 影响范围

### 文档修正
- ✅ `docs/requirements/backend/04-services/user/user-service.md`

### 无需修改
- 实际代码实现已符合规范
- 仅文档示例需要更新

---

## 验证清单

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

---

## 相关文档

- [jointo-tech-stack/database.md](../../../.claude/skills/jointo-tech-stack/references/database.md) - 数据库设计规范
- [jointo-tech-stack/backend.md](../../../.claude/skills/jointo-tech-stack/references/backend.md) - 后端技术栈规范
- [datetime-timezone-standards.md](../../architecture/datetime-timezone-standards.md) - 时间与时区规范
- [ADR-006: TIMESTAMPTZ for Event Timestamps](../../architecture/adrs/006-timestamptz-for-event-timestamps.md) - TIMESTAMPTZ 架构决策

---

## 总结

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

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

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