feat: 封面模板 CRUD API #1323

Merged

auto-approve-bot merged 3 commits from feat/cover-templates-crud-api into develop 2026-08-09 18:26:00 +08:00

Conversation 5 Commits 3 Files Changed 12

+881

xiaoxia commented 2026-08-09 16:45:56 +08:00

Owner

Copy Link

Copy Source

变更内容

新增封面模板 CRUD API，对接前端封面设置 UI 改造。

API 接口

• GET /api/v1/cover-templates — 列出系统模板 + 用户自定义模板
• POST /api/v1/cover-templates — 创建自定义模板
• PUT /api/v1/cover-templates/{id} — 更新模板（系统模板不可改）
• DELETE /api/v1/cover-templates/{id} — 删除自定义模板（系统模板不可删）

技术实现

• 领域实体 CoverTemplate（packages/domain/cover_template.py）
• 仓储接口 + SQLAlchemy 实现 + InMemory 测试实现
• Schema 对齐前端 CoverTemplate 类型定义
• Alembic migration 055，含 8 个系统模板 seed 数据
• 28 个新单测，全量 13704 单测通过

权限控制

• 系统模板（is_system=true）：所有用户可见，但不可修改/删除
• 用户自定义模板：仅创建者可见，仅创建者可修改/删除

## 变更内容 新增封面模板 CRUD API，对接前端封面设置 UI 改造。 ### API 接口 - `GET /api/v1/cover-templates` — 列出系统模板 + 用户自定义模板 - `POST /api/v1/cover-templates` — 创建自定义模板 - `PUT /api/v1/cover-templates/{id}` — 更新模板（系统模板不可改） - `DELETE /api/v1/cover-templates/{id}` — 删除自定义模板（系统模板不可删） ### 技术实现 - 领域实体 `CoverTemplate`（packages/domain/cover_template.py） - 仓储接口 + SQLAlchemy 实现 + InMemory 测试实现 - Schema 对齐前端 `CoverTemplate` 类型定义 - Alembic migration 055，含 8 个系统模板 seed 数据 - 28 个新单测，全量 13704 单测通过 ### 权限控制 - 系统模板（`is_system=true`）：所有用户可见，但不可修改/删除 - 用户自定义模板：仅创建者可见，仅创建者可修改/删除

xiaoxia force-pushed feat/cover-templates-crud-api from ba7434cfec to 0bccd4fb60 2026-08-09 16:52:26 +08:00 Compare

gitea-actions bot commented 2026-08-09 16:54:02 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1323
预览链接	https://pr-1323.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1323 | | 预览链接 | [https://pr-1323.preview.xiaoxiajianji.com](https://pr-1323.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot approved these changes 2026-08-09 17:00:35 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-09 17:00:36 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-09 17:04:18 +08:00

feat: 封面模板 CRUD API ... 208deb4d39

新增 cover_templates 表及完整 CRUD 接口：
- GET    /api/v1/cover-templates       列出系统+用户模板
- POST   /api/v1/cover-templates       创建自定义模板
- PUT    /api/v1/cover-templates/{id}  更新模板（系统模板不可改）
- DELETE /api/v1/cover-templates/{id}  删除自定义模板（系统模板不可删）

技术实现：
- 领域实体 CoverTemplate（packages/domain/cover_template.py）
- 仓储接口 + SQLAlchemy 实现 + InMemory 实现
- Schema 对齐前端 CoverTemplate 类型定义
- Alembic migration 055，含 8 个系统模板 seed 数据
- 28 个新单测，全量 13704 单测通过

xiaoxia force-pushed feat/cover-templates-crud-api from c8779eb8b7 to 70e4d3e537 2026-08-09 17:04:18 +08:00 Compare

xiaoxia added 1 commit 2026-08-09 17:04:55 +08:00

fix: 修复 AI Code Review 阻塞级问题 ... 54c16765e9

- 迁移 seed 数据 ID 改用 UUID hex 格式，与领域模型一致
- 统一 InMemory 和 SQLAlchemy 排序逻辑（系统模板优先）

xiaoxia force-pushed feat/cover-templates-crud-api from 70e4d3e537 to 54c16765e9 2026-08-09 17:04:55 +08:00 Compare

xiaoxia referenced this pull request 2026-08-09 17:07:00 +08:00

feat: 封面模板对接后端 CRUD API，移除 mock 数据 #1324

auto-approve-bot commented 2026-08-09 17:09:48 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：是
• 阻塞级问题数量：2 个

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

1. [alembic/versions/055_cover_templates.py: 72] 数据迁移中 JSON 字段处理错误

   • 问题类型：数据损坏风险 / 逻辑bug
   • 问题描述：在预置系统模板数据时，使用了 json.dumps(config) 将字典转换为字符串。由于数据库列定义为 sa.JSON，SQLAlchemy 会自动处理 Python 字典到 JSON 类型的转换。手动 json.dumps 会导致数据库中存储的是 JSON 字符串（如 "{\"key\":\"value\"}"）而不是 JSON 对象（如 {"key":"value"}）。这会导致应用程序读取数据时得到字符串而非字典，从而引发类型错误或逻辑崩溃。
   • 修改建议：直接传入 config 字典对象，删除 json.dumps() 调用。

2. [packages/adapters/sqlalchemy_impl/cover_template_repository.py: 19, 55, 73] 仓储层破坏了事务边界

   • 问题类型：数据损坏风险
   • 问题描述：在 create、update 和 delete 方法中直接调用了 self.session.commit()。在 FastAPI 结合 SQLAlchemy 的标准实践中，Session 通常由请求作用域的依赖项（如 get_db_session）管理，并在请求结束时统一提交或回滚。在仓储内部提前提交会导致：1. 如果后续业务逻辑抛出异常，已提交的数据无法回滚，造成数据不一致；2. 破坏了 Unit of Work 模式。
   • 修改建议：移除仓储方法中的 self.session.commit()，将事务控制权交由上层的依赖项管理。

💡 改进建议（不阻塞合并）

1. [apps/api/app/api/routes/cover_templates.py: 20, 47] 依赖注入类型标注缺失

   • 具体内容：路由处理函数中 repo: Any = Depends(...) 使用了 Any 类型。建议将其标注为具体的接口类型 CoverTemplateRepository，以提高代码的可读性和 IDE 的支持度（如自动补全）。

2. [apps/api/app/api/routes/cover_templates.py: 79] 异常处理不够友好

   • 具体内容：在 update_cover_template 中调用了 repo.update(template)，如果该模板在 get 之后被删除（并发场景），仓储层会抛出 ValueError。目前未捕获该异常，FastAPI 会将其处理为 500 Internal Server Error。建议捕获 ValueError 并返回 404 或 400 错误，提升 API 用户体验。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-09 09:09:48 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：2 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 1. **[alembic/versions/055_cover_templates.py: 72] 数据迁移中 JSON 字段处理错误** - 问题类型：数据损坏风险 / 逻辑bug - 问题描述：在预置系统模板数据时，使用了 `json.dumps(config)` 将字典转换为字符串。由于数据库列定义为 `sa.JSON`，SQLAlchemy 会自动处理 Python 字典到 JSON 类型的转换。手动 `json.dumps` 会导致数据库中存储的是 JSON 字符串（如 `"{\"key\":\"value\"}"`）而不是 JSON 对象（如 `{"key":"value"}`）。这会导致应用程序读取数据时得到字符串而非字典，从而引发类型错误或逻辑崩溃。 - 修改建议：直接传入 `config` 字典对象，删除 `json.dumps()` 调用。 2. **[packages/adapters/sqlalchemy_impl/cover_template_repository.py: 19, 55, 73] 仓储层破坏了事务边界** - 问题类型：数据损坏风险 - 问题描述：在 `create`、`update` 和 `delete` 方法中直接调用了 `self.session.commit()`。在 FastAPI 结合 SQLAlchemy 的标准实践中，Session 通常由请求作用域的依赖项（如 `get_db_session`）管理，并在请求结束时统一提交或回滚。在仓储内部提前提交会导致：1. 如果后续业务逻辑抛出异常，已提交的数据无法回滚，造成数据不一致；2. 破坏了 Unit of Work 模式。 - 修改建议：移除仓储方法中的 `self.session.commit()`，将事务控制权交由上层的依赖项管理。 ### 💡 改进建议（不阻塞合并） 1. **[apps/api/app/api/routes/cover_templates.py: 20, 47] 依赖注入类型标注缺失** - 具体内容：路由处理函数中 `repo: Any = Depends(...)` 使用了 `Any` 类型。建议将其标注为具体的接口类型 `CoverTemplateRepository`，以提高代码的可读性和 IDE 的支持度（如自动补全）。 2. **[apps/api/app/api/routes/cover_templates.py: 79] 异常处理不够友好** - 具体内容：在 `update_cover_template` 中调用了 `repo.update(template)`，如果该模板在 `get` 之后被删除（并发场景），仓储层会抛出 `ValueError`。目前未捕获该异常，FastAPI 会将其处理为 500 Internal Server Error。建议捕获 `ValueError` 并返回 404 或 400 错误，提升 API 用户体验。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-09 09:09:48 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia added 1 commit 2026-08-09 18:16:42 +08:00

chore: trigger CI rerun [skip review] 891af21a25

auto-approve-bot merged commit 153b38a62f into develop 2026-08-09 18:26:00 +08:00

auto-approve-bot deleted branch feat/cover-templates-crud-api 2026-08-09 18:26:01 +08:00

gitea-actions bot commented 2026-08-09 18:26:42 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1323 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1323 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1323