chore: initialize fullstack starter and team guidelines

docs/ARCHITECTURE.md

@@ -0,0 +1,20 @@
+# 系统架构
+
+```text
+Vue 3 + TS 前端
+    | HTTP /api
+FastAPI + Pydantic
+    |-- 知识管理 API -- PostgreSQL
+    |-- 问答服务
+          |-- 关键词检索
+          |-- Embedding 查询向量 -> pgvector 检索
+          |-- 结果融合 -> 证据检查 -> LLM API
+          |-- 答案 + 来源
+    |-- 后台更新任务（后续）
+          |-- 来源获取 -> 人工核验 -> 文本切分 -> 生成向量 -> 发布版本
+```
+
+当前工程仅实现健康检查、知识条目新增/列表及问答占位接口；pgvector 扩展已在启动时启用，但未实现向量字段、索引和 RAG。前端来源管理与实验页为静态原型。
+
+## 安全边界
+当前无认证与权限控制，仅供本机开发；正式部署前须补充登录鉴权、接口限流、数据库迁移、密钥管理、日志脱敏、CORS 收敛和 HTTPS。

docs/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# 团队共同开发规范
+
+## 1. 基本原则
+所有代码、接口、配置、任务进度均以仓库为准。禁止直接在主分支上试验性开发；禁止提交真实密钥、个人数据、未经授权的数据集。每个任务有负责人、验收条件和关联 Issue。
+
+## 2. 分支管理
+- `main`：稳定可演示版本，仅通过合并请求更新。
+- `dev`：阶段集成分支（创建后使用）。
+- `feat/<模块>-<描述>`：新功能，如 `feat/backend-knowledge-api`。
+- `fix/<描述>`：修复；`docs/<描述>`：文档；`test/<描述>`：测试。
+
+从最新 `dev` 拉分支，完成后发 Pull Request（Gitea 可称合并请求），禁止覆盖他人提交或强制推送共享分支。初次初始化仓库时允许负责人向空仓库推送 `main`。
+
+## 3. 提交信息
+使用 `feat: ...`、`fix: ...`、`docs: ...`、`refactor: ...`、`test: ...`、`chore: ...`，例如 `feat: add knowledge CRUD API`。一次提交只处理一个相对独立的主题。
+
+## 4. 合并请求与代码审查
+合并前说明：需求/Issue、改动范围、测试命令及结果、截图（界面改动）、数据库变更、风险和回滚方式。至少一位非作者成员审查；无成员可审查时由负责人确认并记录。发现冲突先沟通，不直接覆盖。
+
+## 5. 前后端协作
+- 所有接口以 `/api` 开头；Pydantic 定义输入输出模型。
+- 接口字段命名使用 `snake_case`，日期使用带时区的 ISO 8601；错误响应明确错误原因。
+- 新增接口须同步更新 OpenAPI 文档和前端调用层。
+- 前端不直接连接数据库、不保存服务端 API 密钥。
+- 使用 `.env.example` 记录变量名称，真实 `.env` 不入库。
+
+## 6. 数据与知识质量
+- 知识须记录标题、分类、正文、来源、采集/核验时间、审核状态。
+- 未审核资料不得进入正式检索；网络搜索结果不自动等于可靠事实。
+- 模型向量按 `model/version/dimension` 管理，更新用后台任务和版本切换。
+- 测试数据与演示数据明确区分；禁止编造论文实验结果。
+
+## 7. 完成定义（DoD）
+代码能启动、主要功能有测试或可复现验收步骤、无明文密钥、文档同步、合并请求审查通过，才视为完成。
+
+## 8. 沟通与任务
+优先在 Gitea Issues 记录任务；每周更新已完成/阻塞/下一步。技术选型变更先在 `docs/DECISIONS.md` 留痕。公共接口或数据库结构变更必须提前通知前后端负责人。

docs/DECISIONS.md

@@ -0,0 +1,16 @@
+# 技术决策记录（ADR 简版）
+
+## ADR-001 前后端分离
+状态：已决定。前端 Vue 3 + TypeScript + Vite；后端 FastAPI + Pydantic。原因：团队并行开发、API 边界明确、原型可先行。
+
+## ADR-002 数据库
+状态：已决定。PostgreSQL + pgvector。原因：结构化业务数据与向量检索可统一管理。首版先实现知识表，再逐步加入版本、向量与检索日志。
+
+## ADR-003 Embedding
+状态：待评估。采用统一 Provider 接口，在开源本地模型与云端 API 间选择。严禁混用不同模型生成的向量。
+
+## ADR-004 网络搜索与 MCP
+状态：延期。首版默认使用经过审核的知识库；联网搜索作为可选扩展。优先封装已有 API，不因使用 MCP 而自研协议服务。
+
+## ADR-005 更新策略
+状态：设计确定、尚未实现。新文档版本后台生成向量，完成后原子发布；失败保留旧索引。

docs/DEVELOPMENT_PLAN.md

@@ -0,0 +1,23 @@
+# 开发规划与里程碑
+
+## 技术栈
+- 前端：Vue 3 + TypeScript + Vite
+- 后端：FastAPI + Pydantic + SQLAlchemy
+- 数据库：PostgreSQL + pgvector
+- Embedding：统一接口，首版选择一种中文/多语言模型；切换模型必须重建向量索引
+- 检索：关键词基线、向量语义检索、混合检索
+- LLM：API 接入，密钥仅在服务端环境变量中
+- 网络搜索：可选扩展；候选资料必须核验后方可正式入库
+
+## 阶段与验收
+| 阶段 | 交付物 | 验收标准 |
+|---|---|---|
+| 1 工程壳子 | 前后端、数据库、静态页面 | `/api/health` 可访问，页面正常展示，新增知识持久化 |
+| 2 知识管理 | 来源、文档、审核、版本 | 新增、编辑、审核和查询有日志与来源 |
+| 3 基础 RAG | 关键词检索、LLM 接口 | 可展示检索依据，知识不足时不强答 |
+| 4 混合检索 | Embedding、pgvector、融合排序 | 能复现 A/B/C 三种对照方案 |
+| 5 增量更新 | 后台任务、索引版本切换 | 新索引失败不影响旧版检索 |
+| 6 实验与交付 | 测试集、指标、结果、软著材料 | 数据真实、过程可复现、文档与代码一致 |
+
+## 实验设计
+A：直接大模型；B：关键词 RAG；C：混合检索 RAG。记录正确性、来源可追溯性、知识不足问题无依据回答率、响应时间、调用成本。不得预设实验结果。

docs/PROJECT_CHARTER.md

@@ -0,0 +1,13 @@
+# 项目章程
+
+## 项目定位
+项目：边疆红驿——那拉提文旅智能问答系统。论文研究方向为基于混合检索的那拉提文旅智能问答方法。以红色文化、旅游资源与民宿服务的可信知识问答为核心。
+
+## 第一阶段目标
+1. 完成 Vue 3 + TypeScript 静态原型；2. FastAPI + Pydantic 与 PostgreSQL 基础接口联通；3. 建立可追溯知识条目管理；4. 完成关键词检索、向量检索、混合检索；5. 使用真实数据开展对照实验。
+
+## 边界
+首版不承诺实时房态、实时价格、自动联网核验、模型训练、知识图谱或自研 MCP。演示数据必须标记，不得当作真实文旅信息或论文实验结果。
+
+## 成果
+可运行软件、代码仓库、部署说明、真实测试记录、论文材料及软件著作权申请材料。结项和发表以学校与主管机构要求为准。

docs/TASKS.md

@@ -0,0 +1,16 @@
+# 共同开发任务板（初稿）
+
+> 负责人暂未指定。认领后在 Gitea Issue 中补充负责人、预计完成时间和验收记录。
+
+| 编号 | 模块 | 任务 | 负责人 | 状态 |
+|---|---|---|---|---|
+| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 待分配 | 待办 |
+| T02 | 后端 | 验证 FastAPI `/docs`、`/api/health` | 待分配 | 待办 |
+| T03 | 数据库 | 启动 PostgreSQL 并验证知识入库 | 待分配 | 待办 |
+| T04 | 文档 | 明确接口字段、知识来源审核规则 | 待分配 | 待办 |
+| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 待分配 | 待办 |
+| T06 | 检索 | 实现关键词检索基线 | 待分配 | 待办 |
+| T07 | 向量 | 评估 Embedding 并实现 pgvector | 待分配 | 待办 |
+| T08 | RAG | 集成 LLM 与来源展示 | 待分配 | 待办 |
+| T09 | 实验 | 构建可核验问题集及评分规范 | 待分配 | 待办 |
+| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 待分配 | 待办 |