324 lines
11 KiB
Markdown
324 lines
11 KiB
Markdown
# PRD: Service API Publish & Edit Enhancement
|
||
|
||
## Background
|
||
|
||
Service API（`/api/service/`）是 ephron.ren 各服务的程序化管理接口，通过 Bearer Token 认证。当前 Service API 只能创建和编辑「由自己创建、未发布、未被人工修改过的草稿」，发布操作必须通过浏览器登录 Admin 面板完成。
|
||
|
||
这导致自动化工作流（如 AI Agent 内容发布）效率极低：每次创建草稿后都要浏览器登录→找到文章→点击发布按钮。
|
||
|
||
## Goals
|
||
|
||
1. Service API 支持发布/取消发布操作，消除浏览器依赖
|
||
2. Service API 可编辑任意草稿（不限 created_by 和 ownership_type）
|
||
3. 保持已发布内容的安全性：已发布内容不可通过 Service API 直接修改或删除
|
||
|
||
## Non-Goals
|
||
|
||
- Service API 直接删除已发布内容（先取消发布再删除）
|
||
- Service API 直接编辑已发布内容（先取消发布再编辑再发布）
|
||
- 新增 Collection CRUD API（P2，后续单独做）
|
||
- 修改 Admin 面板功能
|
||
|
||
## Affected Services
|
||
|
||
| Service | Storage | Service API File | Admin File |
|
||
|---------|---------|-----------------|------------|
|
||
| Blog | Markdown files + frontmatter | `blog/src/routes/service_api.py` | `blog/src/routes/admin.py` |
|
||
| Prompt | SQLite | `prompt/src/routes/service_api.py` | `prompt/src/routes/admin.py` |
|
||
| Canvas | Markdown files + frontmatter | `canvas/src/routes/service_api.py` | `canvas/src/routes/admin.py` |
|
||
|
||
## Current State Analysis
|
||
|
||
### Permission System
|
||
|
||
权限已在 `auth/src/services/db.py` 的 seed data 中定义：
|
||
|
||
```
|
||
blog.post.publish # 发布博客
|
||
blog.post.edit_own_draft # 编辑自己的草稿
|
||
blog.post.edit_any # 编辑任意博客
|
||
blog.post.delete_own_draft
|
||
prompt.entry.publish
|
||
prompt.entry.edit_own_draft
|
||
prompt.entry.edit_any
|
||
canvas.item.publish
|
||
canvas.item.edit_own_draft
|
||
canvas.item.edit_any
|
||
```
|
||
|
||
Admin 面板的 `toggle-draft` 已在使用 `*.publish` 权限。Service API 未接入。
|
||
|
||
### Current Guard Functions
|
||
|
||
Blog/Canvas 的 `_is_manageable_post` / `_is_manageable_canvas` 检查四个条件：
|
||
|
||
```python
|
||
def _is_manageable_post(meta, actor_id: str) -> bool:
|
||
return (
|
||
meta.created_by == actor_id # 必须是自己创建的
|
||
and meta.ownership_type == "service" # 必须是 service 创建的
|
||
and meta.draft # 必须是草稿
|
||
and not meta.handoff_to_human # 不能已移交人工
|
||
)
|
||
```
|
||
|
||
Prompt 的 `_can_manage_own_draft` 逻辑相同。
|
||
|
||
### Storage Details
|
||
|
||
**Blog/Canvas（frontmatter）：**
|
||
- `draft`, `created_by`, `ownership_type`, `handoff_to_human` 存储在 markdown 文件的 YAML frontmatter 中
|
||
- `update_post()` 函数可修改 frontmatter 字段
|
||
|
||
**Prompt（SQLite）：**
|
||
- `draft`, `created_by`, `ownership_type`, `handoff_to_human` 存储在 `prompts` 表的列中
|
||
- `update_prompt()` 函数可修改这些字段
|
||
|
||
## Requirements
|
||
|
||
### R1: Publish Endpoint
|
||
|
||
**Endpoint:** `POST /api/service/{type}/{id}/publish`
|
||
|
||
| Field | Blog | Prompt | Canvas |
|
||
|-------|------|--------|--------|
|
||
| Path param | `{id}` = slug | `{id}` = key | `{id}` = slug |
|
||
| Permission | `blog.post.publish` | `prompt.entry.publish` | `canvas.item.publish` |
|
||
|
||
**Behavior:**
|
||
1. 验证 Bearer Token → 获取 actor
|
||
2. 检查权限：actor 必须拥有 `{type}.post.publish` 或 `{type}.entry.publish`
|
||
3. 查找资源（包含草稿）
|
||
4. 如果资源不存在 → 404
|
||
5. 如果 `handoff_to_human == true` → 403，提示「已移交人工，无法操作」
|
||
6. 如果 `draft == false`（已经是发布状态）→ 返回成功（幂等）
|
||
7. 设置 `draft = false`，记录 `updated_by = actor_id`
|
||
8. 记录审计日志
|
||
9. 返回 `{"success": true, "slug": "...", "draft": false}`
|
||
|
||
**Request:** 无 body
|
||
|
||
**Response:**
|
||
```json
|
||
{"success": true, "slug": "my-post", "draft": false}
|
||
```
|
||
|
||
### R2: Unpublish Endpoint
|
||
|
||
**Endpoint:** `POST /api/service/{type}/{id}/unpublish`
|
||
|
||
与 Publish 对称，将 `draft` 设为 `true`。
|
||
|
||
**Behavior:**
|
||
1. 验证 Bearer Token → 获取 actor
|
||
2. 检查权限：`{type}.post.publish` / `{type}.entry.publish`
|
||
3. 查找资源（包含草稿）
|
||
4. 如果资源不存在 → 404
|
||
5. 如果 `handoff_to_human == true` → 403
|
||
6. 如果 `draft == true`（已经是草稿状态）→ 返回成功（幂等）
|
||
7. 设置 `draft = true`，记录 `updated_by = actor_id`
|
||
8. 记录审计日志
|
||
9. 返回 `{"success": true, "slug": "...", "draft": true}`
|
||
|
||
### R3: Relax PATCH Guard
|
||
|
||
**Current:** `_is_manageable_post` / `_can_manage_own_draft` 检查 4 个条件
|
||
|
||
**New:** 放宽为 2 个条件：
|
||
|
||
```python
|
||
def _is_manageable_post(meta, actor_id: str) -> bool:
|
||
return (
|
||
meta.draft # 必须是草稿
|
||
and not meta.handoff_to_human # 不能已移交人工
|
||
)
|
||
```
|
||
|
||
移除 `created_by == actor_id` 和 `ownership_type == "service"` 限制。
|
||
|
||
**影响范围：**
|
||
- Blog `service_api.py`：`_is_manageable_post`, `_can_manage_own_draft`
|
||
- Canvas `service_api.py`：`_is_manageable_canvas`, `_can_manage_own_draft`
|
||
- Prompt `service_api.py`：`_can_manage_own_draft`
|
||
|
||
**权限检查调整：**
|
||
- PATCH 端点当前使用 `edit_own_draft` 权限 → 改为同时接受 `edit_own_draft` 或 `edit_any`
|
||
- DELETE 端点保持不变（仍然需要 `delete_own_draft` 或 `delete_any`）
|
||
|
||
### R4: GET Endpoint Enhancement (P1)
|
||
|
||
**Current:** `GET /api/service/{type}` 只返回 `created_by == actor_id && ownership_type == "service"` 的草稿
|
||
|
||
**New:** 增加可选查询参数 `status`：
|
||
- `status=draft`（默认）：只返回自己的草稿（现有行为）
|
||
- `status=all`：返回所有内容（含已发布），但只有草稿可编辑
|
||
|
||
## Implementation Details
|
||
|
||
### Blog Service API Changes
|
||
|
||
```python
|
||
# === R3: Relax guard ===
|
||
|
||
# BEFORE
|
||
def _is_manageable_post(meta, actor_id: str) -> bool:
|
||
return (
|
||
meta.created_by == actor_id
|
||
and meta.ownership_type == "service"
|
||
and meta.draft
|
||
and not meta.handoff_to_human
|
||
)
|
||
|
||
# AFTER
|
||
def _is_manageable_post(meta, actor_id: str) -> bool:
|
||
return meta.draft and not meta.handoff_to_human
|
||
|
||
|
||
# === R1/R2: New endpoints ===
|
||
|
||
@router.post("/posts/{slug}/publish")
|
||
async def publish_service_post(
|
||
slug: str,
|
||
actor: dict = Depends(_require_service_actor_dep),
|
||
):
|
||
if not _has_any_service_permission(actor, ("blog.post.publish",)):
|
||
raise HTTPException(status_code=403, detail="Missing permission")
|
||
|
||
post = get_post_by_slug(slug, include_drafts=True)
|
||
if post is None:
|
||
raise HTTPException(status_code=404, detail="Post not found")
|
||
|
||
if post.meta.handoff_to_human:
|
||
raise HTTPException(status_code=403, detail="Post handed off to human")
|
||
|
||
if not post.meta.draft:
|
||
return {"success": True, "slug": slug, "draft": False}
|
||
|
||
success = update_post(slug=slug, draft=False, updated_by=actor["actor_id"])
|
||
if not success:
|
||
raise HTTPException(status_code=500, detail="Failed to publish")
|
||
|
||
_record_service_audit(
|
||
actor_id=actor["actor_id"],
|
||
action="publish",
|
||
result="success",
|
||
resource_id=slug,
|
||
)
|
||
return {"success": True, "slug": slug, "draft": False}
|
||
|
||
|
||
@router.post("/posts/{slug}/unpublish")
|
||
async def unpublish_service_post(
|
||
slug: str,
|
||
actor: dict = Depends(_require_service_actor_dep),
|
||
):
|
||
if not _has_any_service_permission(actor, ("blog.post.publish",)):
|
||
raise HTTPException(status_code=403, detail="Missing permission")
|
||
|
||
post = get_post_by_slug(slug, include_drafts=True)
|
||
if post is None:
|
||
raise HTTPException(status_code=404, detail="Post not found")
|
||
|
||
if post.meta.handoff_to_human:
|
||
raise HTTPException(status_code=403, detail="Post handed off to human")
|
||
|
||
if post.meta.draft:
|
||
return {"success": True, "slug": slug, "draft": True}
|
||
|
||
success = update_post(slug=slug, draft=True, updated_by=actor["actor_id"])
|
||
if not success:
|
||
raise HTTPException(status_code=500, detail="Failed to unpublish")
|
||
|
||
_record_service_audit(
|
||
actor_id=actor["actor_id"],
|
||
action="unpublish",
|
||
result="success",
|
||
resource_id=slug,
|
||
)
|
||
return {"success": True, "slug": slug, "draft": True}
|
||
```
|
||
|
||
Prompt 和 Canvas 同理，路径参数和函数名对应替换。
|
||
|
||
### PATCH Endpoint Changes
|
||
|
||
```python
|
||
# BEFORE
|
||
@router.patch("/posts/{slug}")
|
||
async def update_service_post(...):
|
||
if not _can_manage_own_draft(actor["actor_id"], slug):
|
||
raise HTTPException(status_code=403, detail="Cannot edit this draft")
|
||
|
||
# AFTER
|
||
@router.patch("/posts/{slug}")
|
||
async def update_service_post(...):
|
||
post = get_post_by_slug(slug, include_drafts=True)
|
||
if post is None:
|
||
raise HTTPException(status_code=404, detail="Post not found")
|
||
if not _is_manageable_post(post.meta, actor["actor_id"]):
|
||
raise HTTPException(status_code=403, detail="Cannot edit this post")
|
||
# check edit permission
|
||
if not _has_any_service_permission(actor, ("blog.post.edit_own_draft", "blog.post.edit_any")):
|
||
raise HTTPException(status_code=403, detail="Missing permission")
|
||
```
|
||
|
||
### Audit Events
|
||
|
||
新增审计事件类型：
|
||
- `service.publish` — 通过 Service API 发布
|
||
- `service.unpublish` — 通过 Service API 取消发布
|
||
|
||
复用现有 `record_audit_event` 函数，`action` 字段使用新值。
|
||
|
||
## Testing
|
||
|
||
### Unit Tests
|
||
|
||
每个服务的 Service API 测试文件需要新增：
|
||
|
||
1. **Publish 测试：**
|
||
- 正常发布草稿 → 成功，draft=false
|
||
- 发布已发布的内容 → 幂等，返回 success
|
||
- 无 publish 权限 → 403
|
||
- 不存在的 slug → 404
|
||
- handoff_to_human=true → 403
|
||
|
||
2. **Unpublish 测试：**
|
||
- 正常取消发布 → 成功，draft=true
|
||
- 取消已取消的内容 → 幂等，返回 success
|
||
- 无 publish 权限 → 403
|
||
|
||
3. **PATCH 放宽测试：**
|
||
- 编辑由其他 service account 创建的草稿 → 成功
|
||
- 编辑由 human 创建的草稿 → 成功（如果有 edit_any 权限）
|
||
- 编辑已发布内容 → 403
|
||
- 编辑 handoff_to_human=true 的内容 → 403
|
||
|
||
### Integration Test
|
||
|
||
完整工作流：
|
||
```
|
||
1. POST /api/service/posts → 创建草稿 (draft=true)
|
||
2. PATCH /api/service/posts/{slug} → 编辑内容
|
||
3. POST /api/service/posts/{slug}/publish → 发布 (draft=false)
|
||
4. PATCH /api/service/posts/{slug} → 403 (已发布不可编辑)
|
||
5. POST /api/service/posts/{slug}/unpublish → 取消发布 (draft=true)
|
||
6. PATCH /api/service/posts/{slug} → 成功 (草稿可编辑)
|
||
7. POST /api/service/posts/{slug}/publish → 重新发布
|
||
8. POST /api/service/posts/{slug}/unpublish → 取消发布
|
||
9. DELETE /api/service/posts/{slug} → 删除草稿
|
||
```
|
||
|
||
## Migration
|
||
|
||
无需数据库迁移。权限已存在于 seed data 中。
|
||
|
||
需要确认 Service Account 的 Role 是否已绑定 `*.publish` 和 `*.edit_any` 权限。如果没有，需要通过 Admin 面板手动绑定。
|
||
|
||
## Rollout
|
||
|
||
1. 先在 Blog 服务实现并测试
|
||
2. 复制到 Prompt 和 Canvas 服务
|
||
3. 验证 Service Account 权限配置
|
||
4. 更新文档（content-ops-agent skill）
|