docs/v1.0/server/changelogs/2026-01-29-wechat-service-tech-stack-compliance.md

微信服务文档技术栈规范符合性修复

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

---

变更概述

修复微信登录服务文档，使其完全符合 jointo-tech-stack 技术栈规范。

---

修复内容

1. Model 层时间戳定义

问题: 缺少 timezone 导入

修复前:

from datetime import datetime

created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

修复后:

from datetime import datetime, timezone  # ✅ 必须导入 timezone

created_at: datetime = Field(
    default_factory=lambda: datetime.now(timezone.utc),
    description="创建时间（UTC）"
)

---

2. Schema 层枚举转换

问题: 在 Schema 层进行枚举转换，应该在 Service 层处理

修复前:

@field_validator('platform', mode='before')
@classmethod
def convert_platform_to_int(cls, v):
    from app.models.user import WechatPlatform
    if isinstance(v, str):
        return WechatPlatform.from_string(v).value
    return v

修复后:

# Schema 层：保持字符串类型
class WechatBindRequest(BaseModel):
    platform: Literal["mp", "open"] = Field(...)
    # 不在 Schema 层转换，转换逻辑在 Service 层处理

---

3. 响应 Schema 序列化

问题: wechatPlatform 字段类型声明错误

修复前:

wechatPlatform: Optional[str] = Field(None, alias="wechat_platform")

修复后:

from pydantic import field_serializer

wechatPlatform: Optional[int] = Field(None, alias="wechat_platform")

@field_serializer('wechatPlatform')
def serialize_platform(self, value: Optional[int]) -> Optional[str]:
    if value is None:
        return None
    from app.models.user import WechatPlatform
    return WechatPlatform(value).to_string()

---

4. Repository 层基类继承

问题: 未继承 BaseRepository

修复前:

class UserRepository:
    def __init__(self, session: AsyncSession):
        self.session = session

修复后:

from app.repositories.base_repository import BaseRepository

class UserRepository(BaseRepository[User]):
    def __init__(self, session: AsyncSession):
        super().__init__(session, User)

---

5. Service 层事务处理

问题: _create_user_from_wechat 方法未使用事务

修复前:

async def _create_user_from_wechat(self, wechat_data: Dict[str, Any]) -> User:
    user = User(...)
    self.session.add(user)
    await self.session.commit()  # ❌ 直接 commit
    await self.session.refresh(user)
    return user

修复后:

async def _create_user_from_wechat(self, wechat_data: Dict[str, Any]) -> User:
    async with self.session.begin():  # ✅ 使用事务
        user = User(...)
        self.session.add(user)
        await self.session.flush()  # ✅ 使用 flush 获取 ID
    
    await self.session.refresh(user)
    return user

---

6. API 响应格式统一

问题: 响应格式缺少 success 和 timestamp 字段

修复前:

{
  "code": 200,
  "message": "Success",
  "data": {...}
}

修复后:

{
  "success": true,
  "code": 200,
  "message": "Success",
  "data": {...},
  "timestamp": "2026-01-29T08:00:00Z"
}

---

7. 配置类完善

问题: 缺少 extra = "ignore" 配置

修复前:

class Settings(BaseSettings):
    # ...
    class Config:
        env_file = ".env"
        case_sensitive = True

修复后:

class Settings(BaseSettings):
    # ...
    class Config:
        env_file = ".env"
        case_sensitive = True
        extra = "ignore"  # ✅ 忽略额外字段

---

技术栈规范符合性

✅ 已符合规范

1. UUID v7 生成: 应用层生成 UUID
2. 枚举类型: SMALLINT + IntEnum
3. 无外键约束: 应用层验证引用完整性
4. 索引创建: 所有关联字段创建索引
5. 注释语法: 使用 COMMENT ON 语法
6. 异步编程: 使用 AsyncSession 和 async/await
7. 软删除: 使用 deleted_at 字段
8. 时间戳: 使用 TIMESTAMPTZ 记录事件时间

✅ 本次修复

1. 时间戳定义: 添加 timezone 导入
2. Schema 层: 移除不必要的枚举转换
3. 响应序列化: 添加 field_serializer 装饰器
4. Repository 继承: 继承 BaseRepository
5. 事务处理: 使用 async with self.session.begin()
6. 响应格式: 统一添加 success 和 timestamp
7. 配置类: 添加 extra = "ignore"

---

影响范围

• 文档: docs/requirements/backend/04-services/user/wechat-service.md
• 版本: v2.1 → v2.2
• 代码: 无（仅文档修复）

---

验证清单

• Model 层导入 timezone
• Schema 层保持字符串类型
• 添加 field_serializer 装饰器
• Repository 继承 BaseRepository
• Service 层使用事务处理
• API 响应格式统一
• 配置类完善
• 所有代码示例符合规范

---

相关文档

• 后端技术栈规范
• 数据库设计规范
• API 设计规范
• 微信登录服务文档

---

创建时间: 2026-01-29
作者: Kiro AI Assistant