# 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）