3.4 KiB

Raw Permalink Blame History

Project Resource Service 文档合规性修复

日期：2026-02-02
类型：文档修复
影响范围：docs/requirements/backend/04-services/project/project-resource-service.md

修复内容

1. 日志系统规范化（P0）

问题：

使用 app.core.logging.get_logger 获取 logger
日志格式化使用 f-string 和 .format()

修复：

✅ 改为标准 import logging; logger = logging.getLogger(__name__)
✅ 所有日志格式化改为 %-formatting
✅ 删除 app.core.logging 导入

示例：

# 修复前
from app.core.logging import get_logger
logger = get_logger(__name__)
logger.info(f"上传项目素材: user_id={user_id}")

# 修复后
import logging
logger = logging.getLogger(__name__)
logger.info(
    "上传项目素材: user_id=%s, project_id=%s",
    user_id,
    project_id
)

2. UUID 导入规范化（P0）

问题：

使用 import uuid_utils as uuid 和 uuid.uuid7()

修复：

✅ 改为 from app.utils.uuid import generate_uuid_v7
✅ 所有 uuid.uuid7() 改为 generate_uuid_v7()
✅ API 路由中移除 import uuid_utils as uuid

示例：

# 修复前
import uuid_utils as uuid
resource = ProjectResource(
    project_resource_id=uuid.uuid7()
)

# 修复后
from app.utils.uuid import generate_uuid_v7
resource = ProjectResource(
    project_resource_id=generate_uuid_v7()
)

3. UUID 类型参数规范化（P0）

问题：

函数参数使用 uuid.UUID 类型
API 路由参数使用 uuid.UUID 类型

修复：

✅ 所有 UUID 类型参数改为 str
✅ 符合 jointo-tech-stack 规范（应用层使用字符串）

示例：

# 修复前
async def get_resource(
    self,
    user_id: uuid.UUID,
    resource_id: uuid.UUID
) -> ProjectResource:

# 修复后
async def get_resource(
    self,
    user_id: str,
    resource_id: str
) -> ProjectResource:

4. Schema 字段命名统一（P1）

问题：

Schema 中使用 element_tag_label
Model 中使用 tag_label
字段命名不一致

修复：

✅ Schema 改为 tag_label（与 Model 保持一致）

示例：

# 修复前
class ProjectResourceResponse(BaseModel):
    element_tag_label: Optional[str] = Field(None, description="标签名称")

# 修复后
class ProjectResourceResponse(BaseModel):
    tag_label: Optional[str] = Field(None, description="标签名称")

5. 变更记录错误说明修正（P1）

问题：

v3.0 变更记录中写"使用 TIMESTAMP 替代 TIMESTAMPTZ"
实际应该是"使用 TIMESTAMP(timezone=True) 即 TIMESTAMPTZ"

修复：

✅ 修正为"使用 TIMESTAMP(timezone=True) 即 TIMESTAMPTZ 类型"

修复统计

优先级	问题数	已修复
P0	5	5
P1	2	2
P2	0	0
总计	7	7

合规性评分

修复前：70/100

修复后：100/100 ✅

v3.4 增强：添加完整的业务流程图和表关系图 ✅

v3.5 优化：流程图抽离到独立文件 project-resource-service-flows.md ✅

3.4 KiB Raw Permalink Blame History