# 那拉提文旅智能问答

Vue 3 + TypeScript + Vite 前端；FastAPI + Pydantic + SQLAlchemy 后端；PostgreSQL + pgvector。当前后端提供知识管理、来源、文档、人工审核和历史记录，问答仍为占位接口。

## 启动数据库
需要可用的 Docker Engine（Windows 可使用 Docker Desktop），在项目根目录运行：
```bash
docker compose up -d db
```
开发数据库默认仅绑定 127.0.0.1:5432。请在正式使用前修改默认密码。

## 启动后端（Windows PowerShell）
```powershell
cd backend
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
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
npm install
npm run dev
```
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。

### 后端测试和迁移回滚

在 `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`。

## 团队协作文档

- [项目章程](docs/PROJECT_CHARTER.md)
- [开发计划](docs/DEVELOPMENT_PLAN.md)
- [阶段 1 详细开发计划](docs/PHASE_1_DEVELOPMENT_PLAN.md)
- [共同开发规范](docs/CONTRIBUTING.md)
- [系统架构](docs/ARCHITECTURE.md)
- [任务分工](docs/TASKS.md)
- [三人团队工作计划](docs/TEAM_WORKPLAN.md)
- [技术决策](docs/DECISIONS.md)

目标 Gitea 仓库：`https://gitea.kronecker.cc/saint/border-red-post-nalati`。