新增内容引擎文章发布接口与详情页

docs/CONTENT_INGEST_API.md

@@ -0,0 +1,160 @@
+# 阿美巴 AI 官网内容发布 API
+
+用于“阿美巴内容判断引擎”将已经人工确认的终稿发布到 AI 官网知识中心。网站只保存和展示终稿，不会调用 AI 改写正文。
+
+## 发布目标配置
+
+```text
+base_url: https://www.aiameiba.com
+health_path: /api/internal/content/v1/health
+upsert_path: /api/internal/content/v1/articles/upsert
+auth_type: bearer
+token_environment_name: CONTENT_INGEST_TOKEN
+site_profile: ai
+public_url_rule: https://www.aiameiba.com/knowledge/{slug-or-content_id}
+```
+
+服务端环境变量：
+
+```dotenv
+CONTENT_INGEST_TOKEN=请设置独立的长随机密钥
+PUBLIC_SITE_URL=https://www.aiameiba.com
+```
+
+`CONTENT_INGEST_TOKEN` 只能存放在网站服务端环境变量中，不能放进前端环境变量、请求日志或 Git。
+
+## 健康检查
+
+```http
+GET /api/internal/content/v1/health
+Authorization: Bearer <CONTENT_INGEST_TOKEN>
+```
+
+成功响应：
+
+```json
+{
+  "status": "ok",
+  "service": "amaba-ai-website",
+  "site_profile": "ai",
+  "api_version": "v1"
+}
+```
+
+## 新增或更新文章
+
+```http
+POST /api/internal/content/v1/articles/upsert
+Authorization: Bearer <CONTENT_INGEST_TOKEN>
+Content-Type: application/json
+Idempotency-Key: <source_task_id>:<source_version_id>:ai
+```
+
+示例：
+
+```json
+{
+  "request_id": "publish-request-001",
+  "source_system": "amaba-content-core",
+  "source_task_id": "task-001",
+  "source_version_id": "version-002",
+  "source_version_number": 2,
+  "content_hash": "09d7e1cd4d3f8b3d3748bb8b4b3d6d4df97195d45d3e15f1d47dd38614c0fa11",
+  "site_profile": "ai",
+  "publish_mode": "publish",
+  "article": {
+    "title": "企业如何开始 AI 进化",
+    "body_plain": "第一自然段。\n\n第二自然段。",
+    "summary": "面向企业经营者的 AI 进化起步方法。",
+    "slug": "how-to-start-ai-evolution",
+    "primary_keyword": "企业AI进化",
+    "keywords": ["企业AI", "企业进化"],
+    "content_type": "methodology",
+    "direction": "方法论",
+    "target_audience": "企业经营者与管理者",
+    "author_name": "阿美巴",
+    "cover_image_url": null,
+    "canonical_url": "https://www.ameiba.cn/insights/how-to-start-ai-evolution"
+  },
+  "quality": {
+    "human_confirmed": true,
+    "confirmed_at": "2026-09-11T10:00:00+08:00",
+    "prompt_version": "AmAba-Audit-V1.2",
+    "judgment_version": "AmAba-Judgment-V1.1",
+    "model": "approved-model",
+    "remaining_issue_levels": ["P3"]
+  },
+  "provenance": { "knowledge_refs": [] },
+  "semantic": {
+    "entities": ["阿美巴", "企业进化"],
+    "questions": ["企业应该如何开始AI进化？"],
+    "facts": [],
+    "suggested_schema_type": "Article"
+  }
+}
+```
+
+首次成功发布返回 `201 Created`，更新返回 `200 OK`：
+
+```json
+{
+  "success": true,
+  "publication_id": "官网文章ID",
+  "status": "published",
+  "url": "https://www.aiameiba.com/knowledge/how-to-start-ai-evolution",
+  "revision": 1,
+  "content_hash": "09d7e1cd4d3f8b3d3748bb8b4b3d6d4df97195d45d3e15f1d47dd38614c0fa11",
+  "published_at": "2026-09-11T02:00:00.000Z"
+}
+```
+
+## 校验与限制
+
+- `source_system` 必须为 `amaba-content-core`，`site_profile` 必须为 `ai`。
+- `quality.human_confirmed` 必须为 `true`；`publish_mode` 仅支持 `draft` 和 `publish`。
+- 标题最长 255 字符，摘要最长 1,200 字符，正文最长 200,000 字符；数组最多 50 项。
+- 正文以纯文本保存并按空行渲染为段落，页面不会执行正文 HTML。
+- `canonical_url` 可指向传统官网的同文 URL；AI 官网仍会保留可访问正文。
+- 单个 IP 每分钟最多 30 次内部接口请求。
+
+## 幂等与更新规则
+
+- `Idempotency-Key` 必须唯一。相同键且相同 `content_hash` 会返回同一文章，不重复创建。
+- 相同键但不同哈希返回 `409 CONTENT_CONFLICT`。
+- 同一 `source_system + source_task_id + ai` 的新确认版本更新原文章，保持原详情 URL，并将 `revision` 加一。
+- 首次发布使用请求中的合法 `slug`；后续更新不会改变已有 URL。
+
+## 错误响应
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "字段不合法",
+    "retryable": false
+  }
+}
+```
+
+| HTTP | code | 含义 |
+| --- | --- | --- |
+| 400 | `VALIDATION_ERROR` | 请求字段不合法 |
+| 401 | `UNAUTHORIZED` | Token 缺失或错误 |
+| 409 | `CONTENT_CONFLICT` | 幂等键哈希冲突或 slug 冲突 |
+| 413 | `CONTENT_TOO_LARGE` | 正文或数组超出限制 |
+| 429 | `RATE_LIMITED` | 请求频率超限 |
+| 503 | `SERVICE_UNAVAILABLE` | 网站未配置发布 Token |
+| 500 | `INTERNAL_ERROR` | 临时服务故障，可重试 |
+
+## 公开读取
+
+不需要 Token：
+
+```text
+GET /api/public/articles
+GET /api/public/articles/{content_id-or-slug}
+GET /knowledge/{content_id-or-slug}
+```
+
+仅返回已发布文章；不暴露任务 ID、审核模型、提示词、来源内部日志或 Token。