Merge pull request 'feat: add backend catalog and review APIs' (#4) from feat/backend-knowledge-management into dev

README.md

@@ -1,9 +1,9 @@
-# 那拉提文旅智能问答：前后端基础壳子
+# 那拉提文旅智能问答
 
-基础工程骨架：Vue 3 + TypeScript + Vite 前端；FastAPI + Pydantic + SQLAlchemy 后端；PostgreSQL + pgvector 数据库配置。
+Vue 3 + TypeScript + Vite 前端；FastAPI + Pydantic + SQLAlchemy 后端；PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核和历史记录，问答仍为占位接口。
 
 ## 启动数据库
-需要 Docker Desktop，在项目根目录运行：
+需要可用的 Docker Engine（Windows 可使用 Docker Desktop），在项目根目录运行：
 ```bash
 docker compose up -d db
 ```
@@ -15,11 +15,25 @@ cd backend
 py -3.12 -m venv .venv
 .\.venv\Scripts\Activate.ps1
 pip install -r requirements.txt
-Copy-Item .env.example .env
+if (!(Test-Path .env)) { Copy-Item .env.example .env }
+alembic upgrade head
 uvicorn app.main:app --reload
 ```
 API 文档：http://127.0.0.1:8000/docs
 
+Linux / macOS 可使用以下等价命令（需要 Python 3.11+；`.env` 已存在时不要覆盖）：
+```bash
+cd backend
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+test -f .env || cp .env.example .env
+alembic upgrade head
+uvicorn app.main:app --reload --host 127.0.0.1
+```
+
+配置始终从 `backend/.env` 读取，环境变量优先。必须先迁移再启动；应用启动只检查数据库版本，不再执行 `create_all`。旧版 `knowledge_items` 会被非破坏性接管；首次迁移前仍须备份。迁移会保留原条目及导入快照，不推测缺失的采集时间。旧版 `verified` 条目因缺少完整审核记录，会转为 `pending`，原状态保存在导入日志中。
+
 ## 启动前端（另开终端）
 ```powershell
 cd frontend
@@ -30,13 +44,57 @@ Vite 通常使用 http://localhost:5173。
 
 ## 已有接口
 - GET `/api/health`
+- GET `/api/ready`：检查数据库连接
 - POST `/api/chat`：占位接口，尚未接入检索和 LLM
 - GET `/api/knowledge`
 - POST `/api/knowledge`
+- GET `/api/knowledge/page`、GET/PATCH/DELETE `/api/knowledge/{id}`
+- POST `/api/knowledge/{id}/review`、GET `/api/knowledge/{id}/history`
+- GET/POST `/api/sources`、GET/PATCH/DELETE `/api/sources/{id}`、GET `/api/sources/{id}/history`
+- GET/POST `/api/documents`、GET/PATCH/DELETE `/api/documents/{id}`、GET `/api/documents/{id}/history`
+
+### 阶段 2 接口约定
+
+- 所有日期均为带时区的 ISO 8601。输入拒绝未知字段，标题/正文不能全为空白，网址只接受 HTTP(S)；可选网址空字符串按未填写处理。
+- `GET /api/knowledge` 保留数组响应，支持 `q`、`category`、`verification_status`、`limit`（默认 100，最大 200）和 `offset`。新页面应使用 `/api/knowledge/page`，避免把首批条目数量当作总数。
+- 分页响应为 `{items, total, page, page_size}`；`page` 从 1 开始，`page_size` 默认 20、最大 100。来源、文档、知识分页和各类历史接口均支持分页。
+- 来源分页支持 `q`；文档分页支持 `q`、`source_id`、`category`；知识分页支持 `q`、`category`、`verification_status`、`source_id`、`document_id`。`q` 为字面文本子串搜索，尚非论文中的关键词检索基线。
+- 创建知识沿用 `title/category/content/source_url`，新增可选 `source_id/document_id/collected_at`；状态固定为 `pending`。关联文档时自动解析其来源，填写的来源或网址若冲突会报错。直接来源链接的旧调用仍受支持。
+- 来源创建字段：`name`、可选 `source_url`、`notes`。文档创建字段：`source_id/title/content/collected_at`，可选 `category/notes`。文档来源归属固定，换来源需新建文档。
+- PATCH 请求必须携带读取时获得的 `expected_version`，并至少提交一个修改字段；DELETE 使用查询参数 `expected_version`。版本过期返回 409，防止覆盖他人修改。
+- 审核请求字段见下方示例。`verification_status` 只允许 `pending/verified/rejected`；核验人和说明必填。通过审核前必须有来源网址及真实采集时间。这里只记录人工结论，不会自动核实网页。
+- 修改条目、关联来源或关联文档都会将相关知识转为 `pending`，清除当前审核字段并记录失效原因。历史快照保留当时的条目、来源和文档。
+- 删除采用软删除；被有效文档或知识引用的来源、被有效知识引用的文档不能删除（409）。已删除记录不出现在列表，但历史仍可查看。
+- 错误响应使用 `detail`：参数错误 422、记录不存在 404、版本/引用冲突 409、数据库暂不可用 503。
+
+审核请求示例（仅为占位测试数据）：
+```json
+{
+  "expected_version": 1,
+  "verification_status": "verified",
+  "reviewer": "test-reviewer",
+  "verification_notes": "示例审核说明，实际使用须填写真实核验依据"
+}
+```
+
+响应新增 `version/updated_at/is_deleted` 及关联、采集、审核字段；完整类型以 `/openapi.json` 和 `/docs` 为准。前端现有录入与数组列表可继续使用；来源、文档、审核及完整分页页面仍需按接口联调。
 
 前端包括问答、知识库管理、来源与更新、实验评估四个页面。实验评估页面没有虚构数据；所有页面明确标记当前功能状态。
 
-注意：当前没有实现 Embedding、RAG、网络搜索、后台更新任务、用户认证或生产级数据库迁移。下一步建议先验证前后端联通，再按模块实现。`.env` 不要提交到 Git。
+注意：当前没有实现 Embedding、RAG、网络搜索、后台更新任务或用户认证。审核人是本机开发环境输入字段，不是认证身份。服务保持仅本机访问；正式部署能力留到后续阶段。`.env` 不要提交到 Git。
+
+### 后端测试和迁移回滚
+
+在 `backend` 目录安装 `requirements-dev.txt` 后执行：
+```bash
+ruff check .
+ruff format --check .
+pytest -q
+```
+
+测试需要真实 PostgreSQL + pgvector：设置 `TEST_DATABASE_URL`（`postgresql+psycopg://...`），或另行 `pip install pgserver` 使用可选的本机临时实例。`pgserver` 仅用于测试，不是应用运行依赖；外部测试数据库账号需有建 Schema 权限且已启用 vector 扩展。每个测试使用独立 Schema，不会清空业务表。测试使用的占位正文和审核人不代表真实资料。
+
+迁移命令为 `alembic upgrade head`，可重复执行。需要撤回阶段 2 时，先备份，再执行 `alembic downgrade 0001_baseline`；它保留基础知识字段，但会删除新增来源、文档、审核字段与历史记录，软删除的基础条目也会重新可见。恢复完整数据应使用备份。不要在有业务数据的数据库执行 `downgrade base`。
 
 ## 团队协作文档