From 7b614397bdfc1bff90cd721e05f9fe303ad8a39f Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 17:19:09 +0800 Subject: [PATCH 1/7] docs: add team work plan --- README.md | 1 + docs/TASKS.md | 24 ++++++++-------- docs/TEAM_WORKPLAN.md | 66 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 12 deletions(-) create mode 100644 docs/TEAM_WORKPLAN.md diff --git a/README.md b/README.md index f55a393..7cd647c 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ Vite 通常使用 http://localhost:5173。 - [共同开发规范](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`。 diff --git a/docs/TASKS.md b/docs/TASKS.md index 238a5a2..71b6f70 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -1,16 +1,16 @@ -# 共同开发任务板（初稿） +# 共同开发任务板 -> 负责人暂未指定。认领后在 Gitea Issue 中补充负责人、预计完成时间和验收记录。 +> 实名分工见 [团队工作计划](TEAM_WORKPLAN.md)。每项任务仍须在 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、鉴权与部署 | 待分配 | 待办 | +| 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、鉴权与部署 | 范涵宇（主）、全员 | 待办 | diff --git a/docs/TEAM_WORKPLAN.md b/docs/TEAM_WORKPLAN.md new file mode 100644 index 0000000..96d7d01 --- /dev/null +++ b/docs/TEAM_WORKPLAN.md @@ -0,0 +1,66 @@ +# 三人团队工作计划 + +> 项目：边疆红驿那拉提文旅智能问答系统 V1.0 +> 周期：2026 年 10 月 16 日—11 月 14 日 +> 本计划明确主责与交付边界；主责人对任务关闭负责，配合人对自身交付物负责。 + +## 一、成员职责与边界 + +| 成员 | 角色 | 主责范围 | 主要交付物 | 边界 | +|---|---|---|---|---| +| 范涵宇 | 后端、数据库与检索负责人 | FastAPI、PostgreSQL/pgvector、数据模型、检索、RAG、部署与后端测试 | 数据库表、API、检索服务、RAG 服务、运行/部署说明 | 数据库结构和 API 字段由其主责；变更前须通知吉海燕。不得将真实密钥提交到仓库。 | +| 吉海燕 | 前端与系统集成负责人 | Vue 页面、接口调用、交互体验、异常状态、浏览器验收、演示截图 | 问答、知识管理、来源更新、实验评估页面；接口联调记录 | 前端只能通过 `/api` 访问服务，不得直连数据库或保存服务端密钥。接口字段变化须先与范涵宇确认。 | +| 杨星萱 | 知识库、实验与文档负责人 | 资料收集/核验、来源登记、测试问题集、人工评分、项目与软著文档 | 可核验资料清单、审核规范、实验记录、使用说明、软著材料初稿 | 未审核资料不得进入正式检索。不得虚构来源、实验数据或结论；不直接修改数据库结构。 | + +## 二、协作约定 + +1. `main` 只放稳定可演示版本；`dev` 是团队集成分支；每人从 `dev` 创建 `feat/<模块>-<描述>` 分支。 +2. 每项工作先建 Gitea Issue，写明负责人、验收标准、分支名和预计完成日期；完成后提交合并请求。 +3. 数据库结构、Pydantic Schema、`/api` 接口字段、Embedding 模型和实验口径属于公共边界，修改前须在 Issue 中说明并通知相关成员。 +4. 合并请求至少由一名非作者审查。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 +5. 知识条目必须保留标题、分类、正文、来源链接、采集日期、核验状态和核验说明。杨星萱审核后，范涵宇才可纳入正式检索索引。 + +## 三、阶段工作与验收 + +| 阶段与时间 | 范涵宇：后端/数据库 | 吉海燕：前端/集成 | 杨星萱：知识库/实验/文档 | 阶段验收 | +|---|---|---|---|---| +| 阶段 1：环境联调（10/16—10/18） | 处理 Docker、WSL、PostgreSQL；验证建表、`/api/health`、知识新增/读取 | 启动 Vue，验证 API 连接和“新增知识—列表刷新”流程，补浏览器截图 | 建立资料登记模板、审核状态定义和验收记录模板 | 浏览器端可新增知识，刷新后数据仍存在；团队成员可按 README 启动 | +| 阶段 2：知识管理（10/19—10/23） | 设计并实现来源、文档、知识条目和审核相关表/API | 完成知识新增、列表、编辑、来源和审核状态页面 | 收集并登记首批 30—50 条可核验资料，完成初步分类与来源核验 | 可管理、查询并追溯首批知识；未审核条目有明确状态 | +| 阶段 3：关键词、向量与混合检索（10/24—10/29） | 实现关键词检索、Embedding Provider、pgvector 检索和 RRF 融合；记录排序与耗时 | 增加检索模式选择、检索结果/来源/耗时展示 | 编写 20—30 个测试问题，标注问题类别、期望证据与答案要点 | 同一问题能比较关键词、向量、混合三种模式，结果可复现 | +| 阶段 4：RAG 问答与来源追溯（10/30—11/3） | 接入 LLM API，完成上下文组装、提示词、知识不足提示、问答与检索日志 | 完成问答历史、引用来源卡片、加载和错误状态 | 审核回答是否受来源支持，整理正反例与失败案例 | 系统回答带来源；资料不足时不作确定性编造 | +| 阶段 5：前端完善与系统集成（11/4—11/7） | 修复接口问题，补基础自动化测试，整理配置和启动说明 | 完成四个页面的主要流程、空态、错误提示和演示路径 | 编写用户操作说明、接口验收清单和知识维护说明 | 可在浏览器完成“录入—审核—检索—问答—查看来源”主流程 | +| 阶段 6：实验与系统测试（11/8—11/11） | 固定模型/检索配置，导出检索、耗时与调用日志，修复重大缺陷 | 支持实验结果导入/展示，完成跨浏览器回归测试 | 主导 A/B/C 对照实验、人工评分、统计和案例分析 | 真实记录 LLM-only、关键词 RAG、混合检索 RAG 的正确性、可追溯性、响应时间和成本 | +| 阶段 7：软著材料与 V1.0 发布（11/12—11/14） | 清理源码、依赖、配置与部署脚本；准备发布版本 | 整理页面截图、演示流程和前端构建产物说明 | 完成用户手册、软著材料初稿、实验与资料归档 | 代码、文档、截图和实际功能一致；经全员核验后创建 `v1.0.0` 标签 | + +## 四、各成员持续工作清单 + +### 范涵宇 + +- 维护后端代码质量、数据库连接和接口文档。 +- 每次 API 或数据库变更后，在 Issue 中给出请求示例、响应示例和启动/迁移方式。 +- 保证关键词、向量、混合检索可独立调用，并保留检索日志。 +- 管理服务端环境变量，绝不提交 `.env`、API Key 或数据库真实密码。 + +### 吉海燕 + +- 所有前端请求集中在 `frontend/src/api.ts`，不在页面中散落重复请求逻辑。 +- 每个后端功能完成后进行浏览器联调，记录成功、异常和空数据状态。 +- 为知识管理、问答来源、实验页面保留可用于软著的清晰截图。 +- 每次页面改动在合并请求中说明访问路径、测试步骤和截图。 + +### 杨星萱 + +- 建立资料来源台账，至少记录来源名称、URL、获取日期、类别、真实性判断和核验人。 +- 制定“可入库/待核验/不采用”的审核规则；不确定的资料保持待核验。 +- 建立测试问题集和人工评分表，实验结果必须能回溯到测试问题、检索日志和评分记录。 +- 维护项目说明、用户手册、软著材料和论文实验素材，确保表述不超出系统实际功能。 + +## 五、完成判定 + +一个任务只有同时满足以下条件才能标记完成： + +1. 代码或资料已进入相应分支，并有可追溯的提交和 Issue。 +2. 有明确的验收步骤、测试结果或可核验资料。 +3. 公共接口、文档和任务状态已同步更新。 +4. 无真实密钥、个人隐私数据和未经授权的材料。 +5. 合并请求通过非作者审查并合入 `dev`；阶段验收后再合入 `main`。 -- 2.43.0 From e374380ec063ba0f1de117cce93c7e9c99c0aa6d Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 17:23:55 +0800 Subject: [PATCH 2/7] docs: expand team execution guide --- docs/TEAM_WORKPLAN.md | 166 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 163 insertions(+), 3 deletions(-) diff --git a/docs/TEAM_WORKPLAN.md b/docs/TEAM_WORKPLAN.md index 96d7d01..e97b955 100644 --- a/docs/TEAM_WORKPLAN.md +++ b/docs/TEAM_WORKPLAN.md @@ -20,7 +20,167 @@ 4. 合并请求至少由一名非作者审查。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 5. 知识条目必须保留标题、分类、正文、来源链接、采集日期、核验状态和核验说明。杨星萱审核后，范涵宇才可纳入正式检索索引。 -## 三、阶段工作与验收 +## 三、开始工作前：所有成员照此执行 + +### 1. 首次拉取与分支 + +```powershell +git clone https://gitea.kronecker.cc/saint/border-red-post-nalati.git +cd border-red-post-nalati +git switch dev +git pull --ff-only origin dev +``` + +开始一个新任务前，先同步 `dev`，再创建自己的功能分支： + +```powershell +git switch dev +git pull --ff-only origin dev +git switch -c feat/<模块>-<简短描述> +``` + +示例：`feat/frontend-knowledge-page`、`feat/backend-source-api`、`docs/knowledge-review-rule`。不要在 `main` 或共享 `dev` 上直接修改功能代码。 + +### 2. 每个任务必须留下的记录 + +1. 在 Gitea 建立 Issue：写清目标、负责人、验收条件、分支名和预计完成日期。 +2. 开发完成后提交合并请求到 `dev`：说明改动文件、测试命令和结果；前端附截图，数据库附初始化/迁移说明。 +3. 由非作者成员审查；发现问题在合并请求讨论中处理，不私下覆盖他人提交。 +4. 合并后更新 `docs/TASKS.md` 的状态，并在 Issue 写明“已完成、阻塞原因或下一步”。 + +### 3. 公共边界速查 + +| 变更内容 | 发起人 | 必须通知 | 交付要求 | +|---|---|---|---| +| 数据库表、字段、迁移 | 范涵宇 | 吉海燕、杨星萱 | 字段说明、初始化或迁移方式、回滚说明 | +| `/api` 路径、请求/响应字段 | 范涵宇 | 吉海燕 | Pydantic Schema、请求示例、响应示例 | +| 前端页面字段和交互 | 吉海燕 | 范涵宇 | 页面截图、接口依赖、异常/空态说明 | +| 正式入库资料、审核规则 | 杨星萱 | 范涵宇 | 来源台账、核验结论、入库范围 | +| 实验问题、指标、评分规则 | 杨星萱 | 全员 | 问题集版本、评分表、实验配置 | + +## 四、成员执行手册 + +### 范涵宇：后端、数据库与检索 + +**日常工作目录**：`backend/`、`docker-compose.yml`、数据库相关文档。 +**对接对象**：接口字段先给吉海燕；可入库资料和审核状态由杨星萱确认。 + +#### 阶段 1 的第一天 + +1. 重启后启动 Docker Desktop，确认 `docker version` 同时显示 Client 和 Server。 +2. 在仓库根目录执行 `docker compose up -d db`；用 `docker compose ps` 确认 `nalati-postgres` 为运行状态。 +3. 进入 `backend/`，复制 `.env.example` 为 `.env`（若 `.env` 已存在则只检查，不覆盖），激活虚拟环境并运行 `uvicorn app.main:app --reload`。 +4. 用浏览器或 PowerShell 验证：`GET /api/health`、`GET /api/knowledge`、`POST /api/knowledge`。 +5. 将实际命令、接口响应、失败原因写入 T02/T03 的 Gitea Issue；数据库可用后通知吉海燕开展浏览器联调。 + +**阶段 1 交付物**：可启动的 PostgreSQL 容器、可默认启动的 FastAPI、知识新增与读取接口验收记录。 +**验收**：重启后数据仍存在；`/docs` 能看到四个基础接口；前端可调用新增和列表接口。 + +#### 阶段 2：知识管理接口 + +1. 根据杨星萱确认的资料字段，设计 `sources`、`documents`、知识条目/审核相关表，不删除已有 `knowledge_items` 数据。 +2. 使用 Pydantic 明确定义创建、查询、更新、审核输入输出；日期返回 ISO 8601，字段统一 `snake_case`。 +3. 实现来源、文档、知识条目的增删改查与分页/筛选所需接口；接口变更先在 Issue 给出示例。 +4. 为关键接口补充成功、参数错误、资料不存在三类验证；更新架构与接口文档。 + +**交给吉海燕**：稳定 API 路径、字段表和示例 JSON。 +**交给杨星萱**：可填写/导入的字段清单与审核状态含义。 + +#### 阶段 3—4：检索与 RAG + +1. 实现独立的关键词检索，返回文档 ID、片段、来源、排序分数和耗时。 +2. 定义统一 Embedding Provider；记录模型名、版本和向量维度，禁止混用不同向量空间。 +3. 建立 pgvector 向量存储与相似度检索；实现 RRF 混合排序，三种模式均可单独调用。 +4. 接入大模型前先固定上下文格式和“知识不足时不确定回答”的提示词；回答保存引用来源和检索日志。 +5. 将可复现实验配置、接口参数和日志导出方式交给杨星萱。 + +#### 阶段 5—7：稳定性、实验与发布 + +1. 修复联调问题，补充基础自动化测试、迁移方案和环境变量说明。 +2. 为实验导出检索模式、命中条目、耗时、模型版本和调用成本；冻结实验期间的配置。 +3. 发布前检查 `.env`、真实 API Key、测试数据和开发日志未进入 Git；提供可复现启动命令。 +4. 与全员核对功能、截图、说明书一致后，准备 `v1.0.0` 发布内容。 + +### 吉海燕：前端与系统集成 + +**日常工作目录**：`frontend/`，重点为 `frontend/src/App.vue`、`frontend/src/api.ts`、`frontend/src/style.css`。 +**对接对象**：只通过 `/api` 与范涵宇对接；接口字段变更未确认前不自行猜测后端行为。 + +#### 阶段 1 的第一天 + +```powershell +cd frontend +npm ci +npm run dev +``` + +1. 打开 `http://localhost:5173`，确认四个导航页可以切换，页面没有白屏或控制台构建错误。 +2. 执行 `npm run build`，构建失败优先修复 TypeScript、Vue 模板或依赖问题。 +3. 后端未启动时，确认界面明确显示“API 未连接/无法读取知识库”，不能伪装为成功数据。 +4. 后端数据库联通后执行真实流程：新增知识、保存、刷新列表、重新打开页面确认数据仍在。 +5. 截取问答页、知识管理页、来源与更新页、实验评估页的清晰截图，保留用于软著材料。 + +**阶段 1 交付物**：前端启动/构建记录、四页截图、知识新增与刷新联调记录。 +**验收**：`npm run build` 通过；Vite 可访问；后端可用时完成“新增—刷新—保留”闭环。 + +#### 阶段 2：知识管理页面 + +1. 将所有 HTTP 请求集中在 `src/api.ts`，为知识条目、来源、审核状态定义 TypeScript 类型；禁止使用 `any` 掩盖接口变化。 +2. 完成新增、列表、搜索、编辑、删除/撤销（以后端最终接口为准）、来源跳转与审核状态展示。 +3. 设计空数据、加载中、保存成功、字段校验、网络失败、后端错误五类状态。 +4. 新增字段先根据范涵宇提供的 Schema 修改 API 层，再修改页面；完成后附接口联调截图。 + +#### 阶段 3—4：检索与问答页面 + +1. 增加关键词、向量、混合检索模式选择；展示检索结果、排序、耗时与来源链接。 +2. 问答页面展示用户问题、回答、引用来源、知识不足提示、加载中和网络错误。 +3. 不把“待审核”资料显示为已核验依据；来源链接为空时不生成无效跳转。 +4. 保持移动端/窄窗口可用；每个重要交互给出可重复操作步骤。 + +#### 阶段 5—7：集成、实验与交付 + +1. 完成四个页面的主流程、空态和错误态，按杨星萱的实验字段展示结果但不填写虚构数值。 +2. 在每次后端变更后做回归：健康状态、知识管理、检索结果、问答来源。 +3. 输出软著所需页面截图、演示流程和前端依赖/构建说明。 +4. 发布前用干净环境执行 `npm ci && npm run build`，记录版本和构建结果。 + +### 杨星萱：知识库、实验与文档 + +**日常工作目录**：`docs/`、资料台账与实验记录；正式数据入库前先与范涵宇确认字段。 +**对接对象**：向范涵宇提供已审核资料与字段；向吉海燕提供页面文案、来源呈现规则和实验展示字段。 + +#### 阶段 1 的第一天 + +1. 建立资料台账，每条资料至少包含：标题、类别、来源名称、URL、获取日期、正文摘要、真实性判断、核验日期、核验人、状态和备注。 +2. 定义状态：`pending`（待核验）、`verified`（可正式使用）、`rejected`（不采用）；将判断标准写入 T04 对应 Issue。 +3. 建立验收记录，记录每次联调的日期、人员、环境、操作、预期结果、实际结果和截图/日志位置。 +4. 先收集资料，不把未经核验的网页内容直接当作那拉提事实写入系统。 + +**阶段 1 交付物**：资料台账模板、审核规则、联调验收记录模板。 +**验收**：另外两位成员能按模板登记一条资料和一次测试结果，无歧义。 + +#### 阶段 2：资料与审核 + +1. 按红色文化、旅游资源、民宿服务、交通出行等分类收集 30—50 条候选资料。 +2. 每条资料至少做一次来源核验；信息缺失、过期或来源不可靠时保持 `pending` 或标记 `rejected`。 +3. 向范涵宇提供“已核验可入库”清单，向吉海燕提供来源展示所需名称、链接和状态文案。 +4. 记录资料版本与更新时间，为后续向量重建和论文数据集说明保留依据。 + +#### 阶段 3—4：测试集、来源核验与案例 + +1. 编写 20—30 个覆盖四类主题的测试问题；每题记录预期知识点、允许引用来源和“资料不足”情形。 +2. 对关键词、向量、混合检索的结果检查是否命中正确资料，记录错误类型而非只写“好/不好”。 +3. 对 RAG 回答核对“回答是否正确”和“来源是否真正支持回答”，整理成功案例与失败案例。 +4. 任何实验分数必须来自实际运行、检索日志与人工评分，不得先写结论后补数据。 + +#### 阶段 5—7：文档、实验与软著 + +1. 编写用户手册：安装、启动、知识录入、审核、问答、来源查看和常见问题；与吉海燕截图逐一对应。 +2. 制定评分表，统计 A（LLM-only）、B（关键词 RAG）、C（混合检索 RAG）的正确性、可追溯性、无依据回答、响应时间和成本。 +3. 整理实验原始记录、统计结果、局限性和论文可用图表素材；不将原型功能描述为已实现功能。 +4. 整理软著材料初稿，逐项与范涵宇代码、吉海燕页面和最终演示核对。 + +## 五、阶段工作与验收 | 阶段与时间 | 范涵宇：后端/数据库 | 吉海燕：前端/集成 | 杨星萱：知识库/实验/文档 | 阶段验收 | |---|---|---|---|---| @@ -32,7 +192,7 @@ | 阶段 6：实验与系统测试（11/8—11/11） | 固定模型/检索配置，导出检索、耗时与调用日志，修复重大缺陷 | 支持实验结果导入/展示，完成跨浏览器回归测试 | 主导 A/B/C 对照实验、人工评分、统计和案例分析 | 真实记录 LLM-only、关键词 RAG、混合检索 RAG 的正确性、可追溯性、响应时间和成本 | | 阶段 7：软著材料与 V1.0 发布（11/12—11/14） | 清理源码、依赖、配置与部署脚本；准备发布版本 | 整理页面截图、演示流程和前端构建产物说明 | 完成用户手册、软著材料初稿、实验与资料归档 | 代码、文档、截图和实际功能一致；经全员核验后创建 `v1.0.0` 标签 | -## 四、各成员持续工作清单 +## 六、各成员持续工作清单 ### 范涵宇 @@ -55,7 +215,7 @@ - 建立测试问题集和人工评分表，实验结果必须能回溯到测试问题、检索日志和评分记录。 - 维护项目说明、用户手册、软著材料和论文实验素材，确保表述不超出系统实际功能。 -## 五、完成判定 +## 七、完成判定 一个任务只有同时满足以下条件才能标记完成： -- 2.43.0 From 8481b4a4032a6c34965a34af503bb7a890e0bf67 Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 17:26:57 +0800 Subject: [PATCH 3/7] docs: define pull request review policy --- docs/CONTRIBUTING.md | 8 ++++++++ docs/TEAM_WORKPLAN.md | 6 +++--- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 024a546..2104801 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -17,6 +17,14 @@ ## 4. 合并请求与代码审查 合并前说明：需求/Issue、改动范围、测试命令及结果、截图（界面改动）、数据库变更、风险和回滚方式。至少一位非作者成员审查；无成员可审查时由负责人确认并记录。发现冲突先沟通，不直接覆盖。 +### 审阅与合并权限 + +- 范涵宇、杨星萱完成工作后，必须从各自 `feat/...` 或 `docs/...` 分支向 `dev` 发起合并请求；作者不得自行合并。 +- 吉海燕负责审阅范涵宇、杨星萱提交的合并请求。只有吉海燕明确批准后，才可合并到 `dev`。 +- 吉海燕自己的前端分支须由范涵宇或杨星萱中至少一名非作者成员审阅；吉海燕在获得审阅意见后执行合并。 +- `dev` 合入 `main` 前，须完成对应阶段验收，并由吉海燕确认。任何成员不得直接向 `main` 推送功能改动。 +- 审阅意见、测试结果与最终批准结论应保留在 Gitea 合并请求中，便于项目验收和软著材料追溯。 + ## 5. 前后端协作 - 所有接口以 `/api` 开头；Pydantic 定义输入输出模型。 - 接口字段命名使用 `snake_case`，日期使用带时区的 ISO 8601；错误响应明确错误原因。 diff --git a/docs/TEAM_WORKPLAN.md b/docs/TEAM_WORKPLAN.md index e97b955..1e6fe80 100644 --- a/docs/TEAM_WORKPLAN.md +++ b/docs/TEAM_WORKPLAN.md @@ -17,7 +17,7 @@ 1. `main` 只放稳定可演示版本；`dev` 是团队集成分支；每人从 `dev` 创建 `feat/<模块>-<描述>` 分支。 2. 每项工作先建 Gitea Issue，写明负责人、验收标准、分支名和预计完成日期；完成后提交合并请求。 3. 数据库结构、Pydantic Schema、`/api` 接口字段、Embedding 模型和实验口径属于公共边界，修改前须在 Issue 中说明并通知相关成员。 -4. 合并请求至少由一名非作者审查。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 +4. 范涵宇、杨星萱的合并请求由吉海燕审阅批准后才能合并到 `dev`；吉海燕自己的合并请求须由范涵宇或杨星萱中至少一人审阅。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 5. 知识条目必须保留标题、分类、正文、来源链接、采集日期、核验状态和核验说明。杨星萱审核后，范涵宇才可纳入正式检索索引。 ## 三、开始工作前：所有成员照此执行 @@ -45,7 +45,7 @@ git switch -c feat/<模块>-<简短描述> 1. 在 Gitea 建立 Issue：写清目标、负责人、验收条件、分支名和预计完成日期。 2. 开发完成后提交合并请求到 `dev`：说明改动文件、测试命令和结果；前端附截图，数据库附初始化/迁移说明。 -3. 由非作者成员审查；发现问题在合并请求讨论中处理，不私下覆盖他人提交。 +3. 范涵宇、杨星萱的合并请求由吉海燕审阅并明确批准后才能合并；吉海燕自己的合并请求至少由一名非作者成员审阅。发现问题在合并请求讨论中处理，不私下覆盖他人提交。 4. 合并后更新 `docs/TASKS.md` 的状态，并在 Issue 写明“已完成、阻塞原因或下一步”。 ### 3. 公共边界速查 @@ -223,4 +223,4 @@ npm run dev 2. 有明确的验收步骤、测试结果或可核验资料。 3. 公共接口、文档和任务状态已同步更新。 4. 无真实密钥、个人隐私数据和未经授权的材料。 -5. 合并请求通过非作者审查并合入 `dev`；阶段验收后再合入 `main`。 +5. 合并请求按既定审阅权限获批后合入 `dev`；阶段验收并经吉海燕确认后再合入 `main`。 -- 2.43.0 From da80fffebfd0f78e3601463627d11bb2409eeaac Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 17:29:11 +0800 Subject: [PATCH 4/7] docs: assign Codex as frontend reviewer --- docs/CONTRIBUTING.md | 2 +- docs/TEAM_WORKPLAN.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2104801..1023f6d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -21,7 +21,7 @@ - 范涵宇、杨星萱完成工作后，必须从各自 `feat/...` 或 `docs/...` 分支向 `dev` 发起合并请求；作者不得自行合并。 - 吉海燕负责审阅范涵宇、杨星萱提交的合并请求。只有吉海燕明确批准后，才可合并到 `dev`。 -- 吉海燕自己的前端分支须由范涵宇或杨星萱中至少一名非作者成员审阅；吉海燕在获得审阅意见后执行合并。 +- 吉海燕自己的前端分支由 Codex 在本项目对话中进行代码审阅。吉海燕须提供合并请求链接或差异；只有在 Codex 明确回复“批准合并”后，才可执行合并。Codex 不代替 Gitea 平台账号点击批准按钮。 - `dev` 合入 `main` 前，须完成对应阶段验收，并由吉海燕确认。任何成员不得直接向 `main` 推送功能改动。 - 审阅意见、测试结果与最终批准结论应保留在 Gitea 合并请求中，便于项目验收和软著材料追溯。 diff --git a/docs/TEAM_WORKPLAN.md b/docs/TEAM_WORKPLAN.md index 1e6fe80..b48fa47 100644 --- a/docs/TEAM_WORKPLAN.md +++ b/docs/TEAM_WORKPLAN.md @@ -17,7 +17,7 @@ 1. `main` 只放稳定可演示版本；`dev` 是团队集成分支；每人从 `dev` 创建 `feat/<模块>-<描述>` 分支。 2. 每项工作先建 Gitea Issue，写明负责人、验收标准、分支名和预计完成日期；完成后提交合并请求。 3. 数据库结构、Pydantic Schema、`/api` 接口字段、Embedding 模型和实验口径属于公共边界，修改前须在 Issue 中说明并通知相关成员。 -4. 范涵宇、杨星萱的合并请求由吉海燕审阅批准后才能合并到 `dev`；吉海燕自己的合并请求须由范涵宇或杨星萱中至少一人审阅。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 +4. 范涵宇、杨星萱的合并请求由吉海燕审阅批准后才能合并到 `dev`；吉海燕自己的前端合并请求由 Codex 在本项目对话中审阅，只有收到明确的“批准合并”结论后才能合并。页面改动附截图；后端改动附测试命令和结果；数据库改动附迁移/初始化说明。 5. 知识条目必须保留标题、分类、正文、来源链接、采集日期、核验状态和核验说明。杨星萱审核后，范涵宇才可纳入正式检索索引。 ## 三、开始工作前：所有成员照此执行 @@ -45,7 +45,7 @@ git switch -c feat/<模块>-<简短描述> 1. 在 Gitea 建立 Issue：写清目标、负责人、验收条件、分支名和预计完成日期。 2. 开发完成后提交合并请求到 `dev`：说明改动文件、测试命令和结果；前端附截图，数据库附初始化/迁移说明。 -3. 范涵宇、杨星萱的合并请求由吉海燕审阅并明确批准后才能合并；吉海燕自己的合并请求至少由一名非作者成员审阅。发现问题在合并请求讨论中处理，不私下覆盖他人提交。 +3. 范涵宇、杨星萱的合并请求由吉海燕审阅并明确批准后才能合并；吉海燕自己的前端合并请求由 Codex 审阅，只有收到明确的“批准合并”结论后才能合并。发现问题在合并请求讨论中处理，不私下覆盖他人提交。 4. 合并后更新 `docs/TASKS.md` 的状态，并在 Issue 写明“已完成、阻塞原因或下一步”。 ### 3. 公共边界速查 -- 2.43.0 From bca123303efe759eef70177287b5df71e3240d81 Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 17:37:06 +0800 Subject: [PATCH 5/7] docs: add phase one execution plan --- README.md | 1 + docs/PHASE_1_DEVELOPMENT_PLAN.md | 181 +++++++++++++++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 docs/PHASE_1_DEVELOPMENT_PLAN.md diff --git a/README.md b/README.md index 7cd647c..6d1c91b 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ Vite 通常使用 http://localhost:5173。 - [项目章程](docs/PROJECT_CHARTER.md) - [开发计划](docs/DEVELOPMENT_PLAN.md) +- [阶段 1 详细开发计划](docs/PHASE_1_DEVELOPMENT_PLAN.md) - [共同开发规范](docs/CONTRIBUTING.md) - [系统架构](docs/ARCHITECTURE.md) - [任务分工](docs/TASKS.md) diff --git a/docs/PHASE_1_DEVELOPMENT_PLAN.md b/docs/PHASE_1_DEVELOPMENT_PLAN.md new file mode 100644 index 0000000..ae87b83 --- /dev/null +++ b/docs/PHASE_1_DEVELOPMENT_PLAN.md @@ -0,0 +1,181 @@ +# 阶段 1 详细开发计划：环境联调与需求冻结 + +> 计划周期：2026 年 10 月 16 日—10 月 18 日 +> 阶段目标：让团队三人都能按 README 启动项目，并完成“前端 → API → PostgreSQL”的一次真实知识条目持久化闭环。 +> 本阶段不实现 Embedding、向量检索、RAG、联网搜索或真实大模型调用。 + +## 1. 阶段完成标准 + +全部满足才可将阶段 1 标记为完成： + +1. Docker Desktop 引擎正常，`docker version` 同时显示 Client 和 Server；`nalati-postgres` 容器健康运行。 +2. 后端可通过默认生命周期启动，`http://127.0.0.1:8000/docs` 可访问，`GET /api/health` 返回 200。 +3. `POST /api/knowledge` 新增一条测试知识，`GET /api/knowledge` 能读取该条目；重启后端后数据仍存在。 +4. 前端 `npm run build` 通过，`http://localhost:5173` 可访问，页面显示 API 已连接。 +5. 在浏览器完成“新增知识 → 保存 → 列表刷新 → 重新打开页面仍存在”的完整流程。 +6. 三人分别在 Gitea Issue 中留下命令、结果、截图或日志位置；未提交真实密钥、真实密码和未授权资料。 + +## 2. 当前基线与阻塞 + +| 项目 | 当前状态 | 负责人 | 下一步 | +|---|---|---|---| +| Git 仓库、`main`、`dev` | 已准备 | 全员 | 每次工作从最新 `dev` 拉分支 | +| 前端依赖与生产构建 | 已通过 | 吉海燕 | 启动 Vite，做浏览器端验收 | +| 后端虚拟环境与依赖 | 已准备 | 范涵宇 | 数据库就绪后按默认生命周期启动 | +| `/api/health` 路由 | 已验证 | 范涵宇 | 数据库就绪后复验默认启动 | +| Docker Desktop/WSL | 受阻 | 范涵宇 | 在管理员 PowerShell 完成 WSL 前置、重启后启动 Docker Desktop | +| 资料台账、审核规则 | 待创建 | 杨星萱 | 建立模板并明确状态含义 | + +> Docker/WSL 未恢复前，可以完成前端构建、资料模板和文档工作；不得把数据库、新增知识持久化或“API 已连接”写成已通过。 + +## 3. 每日安排 + +### 10 月 16 日：环境恢复与单服务启动 + +| 成员 | 必做工作 | 交付物 | 验收证据 | +|---|---|---|---| +| 范涵宇 | 处理 Docker Desktop/WSL；启动 PostgreSQL；检查后端 `.env` 和 Python 环境 | 运行中的数据库容器、后端启动记录 | `docker compose ps`、`docker logs nalati-postgres`、后端启动日志 | +| 吉海燕 | 从 `dev` 拉前端分支；执行依赖安装、构建和 Vite 启动；检查四个页面切换 | 前端启动记录、四页初始截图 | `npm run build` 输出、浏览器截图 | +| 杨星萱 | 建立资料台账字段和审核规则；建立联调验收记录模板 | 台账模板、审核规则、验收记录模板 | 文档提交与 Issue 链接 | + +### 10 月 17 日：API 与浏览器端持久化闭环 + +| 成员 | 必做工作 | 交付物 | 验收证据 | +|---|---|---|---| +| 范涵宇 | 复验 `/docs`、健康检查、知识新增/读取；记录 API 请求和响应 | T02/T03 验收记录 | 201 创建响应、列表读取响应、数据库容器日志 | +| 吉海燕 | 按后端真实 Schema 调用新增与列表 API；处理加载、保存失败、API 未连接状态 | 前端联调截图或缺陷清单 | 新增后列表可见、刷新后仍存在的截图 | +| 杨星萱 | 用非敏感测试资料完成一条待审核知识的登记；核对前端字段是否满足资料追溯需要 | 测试条目内容、字段反馈 | 测试条目 ID、字段核对记录 | + +### 10 月 18 日：复现验收、问题冻结与交接 + +| 成员 | 必做工作 | 交付物 | 验收证据 | +|---|---|---|---| +| 范涵宇 | 重启后端或容器后复验数据；汇总未解决环境/接口问题 | 后端验收结论、遗留问题列表 | 重启后 `GET /api/knowledge` 结果 | +| 吉海燕 | 在干净浏览器会话复验问答页、知识管理页和错误状态；整理可用于软著的阶段截图 | 前端验收结论、截图清单 | 浏览器操作步骤和截图 | +| 杨星萱 | 汇总资料台账、审核规则与测试记录；确认阶段 2 所需字段和资料数量 | 阶段 2 知识收集清单 | Issue 中的验收记录与待办 | + +## 4. 范涵宇执行清单：后端、数据库 + +### 4.1 Docker 与 PostgreSQL + +在管理员完成 WSL/重启后，先执行： + +```powershell +cd E:\边疆红驿\border-red-post-nalati-ready +docker version +docker compose up -d db +docker compose ps +docker logs nalati-postgres +``` + +通过条件：`docker version` 存在 Server 信息；`docker compose ps` 显示 `nalati-postgres` 运行且健康检查通过。若失败，只在 T03 Issue 记录完整错误，不删除 Docker 卷或重置数据。 + +### 4.2 后端启动与接口验证 + +```powershell +cd E:\边疆红驿\border-red-post-nalati-ready\backend +if (-not (Test-Path .env)) { Copy-Item .env.example .env } +.\.venv\Scripts\Activate.ps1 +uvicorn app.main:app --reload +``` + +另开 PowerShell 验证： + +```powershell +Invoke-RestMethod http://127.0.0.1:8000/api/health +Invoke-RestMethod http://127.0.0.1:8000/api/knowledge +$body = @{ title = '阶段1联调测试条目'; category = '其他'; content = '仅用于验证知识新增与持久化，不是正式事实资料。' } | ConvertTo-Json +Invoke-RestMethod http://127.0.0.1:8000/api/knowledge -Method Post -ContentType 'application/json' -Body $body +``` + +通过条件：健康检查返回 `status: ok`；新增请求返回 201；列表能看到返回的 ID 和标题。将测试条目保留并标注为测试，不作为正式检索资料。 + +### 4.3 给前端的交接内容 + +在 T02/T03 Issue 粘贴以下内容后再通知吉海燕联调： + +- 后端地址、启动命令和 `/docs` 地址； +- 最终确认的知识条目请求/响应 JSON； +- 可用的 `verification_status` 状态值； +- 当前已知限制与错误响应格式。 + +## 5. 吉海燕执行清单：前端与浏览器联调 + +### 5.1 拉取、构建与启动 + +```powershell +cd E:\边疆红驿\border-red-post-nalati-ready +git switch dev +git pull --ff-only origin dev +git switch -c feat/frontend-phase1-validation +cd frontend +npm ci +npm run build +npm run dev +``` + +通过条件：构建命令退出码为 0；Vite 显示本地访问地址；浏览器可打开四个导航页。 + +### 5.2 浏览器检查顺序 + +1. 打开 `http://localhost:5173`，检查顶部/侧边导航能切换“智能问答、知识库管理、来源与更新、实验评估”。 +2. 后端未启动时，确认界面显示“API 未连接”或明确错误提示；不要修改前端来伪造连接成功。 +3. 后端启动后刷新页面，确认状态变为“API 已连接”。 +4. 在“知识库管理”点击“新增知识”，填写后端给出的测试条目，保存并确认列表出现该条目。 +5. 刷新浏览器页面，确认条目仍然存在；记录浏览器、时间和截图。 +6. 在“智能问答”发送一个测试问题，确认基础占位回答或后端错误能在页面被清楚展示，不白屏、不无限加载。 + +### 5.3 前端缺陷处理边界 + +- 请求、响应类型和错误信息统一维护在 `frontend/src/api.ts`；页面中不复制 `fetch` 逻辑。 +- 只按范涵宇确认的 API 字段改动；发现字段不一致时开 Issue，不在前端猜测字段或拼接数据库连接。 +- 每个修复独立提交，提交信息如 `fix: handle knowledge api error`；合并请求附构建结果与前后截图。 +- 当前阶段不实现检索模式选择、LLM 配置、真实实验图表或自动抓取来源，它们属于后续阶段。 + +## 6. 杨星萱执行清单：资料、审核与验收记录 + +### 6.1 资料台账字段 + +在 `docs/` 下的个人工作分支建立台账模板（Markdown、CSV 或学校统一表格均可），每条候选资料至少填写： + +| 字段 | 要求 | +|---|---| +| 标题、类别 | 可识别且分类明确，如红色文化、旅游资源、民宿服务、交通出行 | +| 来源名称、URL | 可回访来源；无 URL 时注明线下材料出处 | +| 获取日期、更新时间 | 使用 `YYYY-MM-DD` | +| 正文摘要 | 保留原意，不编造无法核实的具体事实 | +| 核验状态 | `pending`、`verified` 或 `rejected` | +| 核验依据、核验人、核验日期 | 说明为什么可以使用或拒绝使用 | + +### 6.2 审核与测试资料规则 + +1. `pending`：已收集但未完成核验；可用于界面演示，不得进入正式检索。 +2. `verified`：来源可定位、信息完整且已人工核验；可交给范涵宇入库。 +3. `rejected`：来源不明、过期、重复或不可靠；保留记录但不入库。 +4. 阶段 1 的测试条目必须写明“测试”，不得伪装为那拉提真实资料。 + +### 6.3 联调验收记录 + +每次测试至少记录：测试日期、测试人、Git 提交、运行环境、操作步骤、预期结果、实际结果、截图/日志、结论和待处理问题。阶段 1 最少记录一次“知识新增—读取—页面刷新”测试。 + +## 7. Issue、提交与审阅顺序 + +| 任务 | 建议分支 | 提交/合并目标 | 审阅与批准 | +|---|---|---|---| +| T01 前端启动与浏览器验收 | `feat/frontend-phase1-validation` | 合并请求 → `dev` | 吉海燕提交；Codex 审阅并明确回复“批准合并”后由吉海燕合并 | +| T02 健康检查与后端启动 | `feat/backend-phase1-api-validation` | 合并请求 → `dev` | 范涵宇提交；吉海燕审阅批准后合并 | +| T03 Docker 与知识持久化 | `feat/backend-phase1-database` | 合并请求 → `dev` | 范涵宇提交；吉海燕审阅批准后合并 | +| T04 审核规则与验收模板 | `docs/phase1-knowledge-governance` | 合并请求 → `dev` | 杨星萱提交；吉海燕审阅批准后合并 | + +阶段 1 的 `dev → main` 合并请求只能在本文件第 1 节全部满足后创建，由吉海燕发起并确认。若 Docker/WSL 仍受阻，保留阶段状态为“进行中”，先记录阻塞和恢复动作，不跳过持久化验收。 + +## 8. 阶段结束交接包 + +阶段 1 结束时，三人共同整理以下内容到 Issue 或 `docs/`： + +- 经过验证的启动命令与版本信息； +- 前端四页和知识新增闭环截图； +- API 请求/响应样例与已知限制； +- 测试资料与正式资料的区分说明； +- 未解决问题清单、负责人和预计恢复日期； +- 阶段 2 可直接开始的接口字段与资料台账模板。 -- 2.43.0 From 460f1203640a8486ba0a3279f0f88274202b9b18 Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Thu, 15 Oct 2026 21:29:08 +0800 Subject: [PATCH 6/7] feat: add auth API clients and view scaffolding --- docs/AUTH_API_REQUIREMENTS.md | 17 ++++++++++++++ frontend/src/services/auth.ts | 26 ++++++++++++++++++++++ frontend/src/types/auth.ts | 16 +++++++++++++ frontend/src/views/AccountSettingsView.vue | 8 +++++++ frontend/src/views/LoginView.vue | 7 ++++++ frontend/src/views/ProfileView.vue | 8 +++++++ frontend/src/views/RegisterView.vue | 7 ++++++ frontend/src/views/UserManagementView.vue | 8 +++++++ 8 files changed, 97 insertions(+) create mode 100644 docs/AUTH_API_REQUIREMENTS.md create mode 100644 frontend/src/services/auth.ts create mode 100644 frontend/src/types/auth.ts create mode 100644 frontend/src/views/AccountSettingsView.vue create mode 100644 frontend/src/views/LoginView.vue create mode 100644 frontend/src/views/ProfileView.vue create mode 100644 frontend/src/views/RegisterView.vue create mode 100644 frontend/src/views/UserManagementView.vue diff --git a/docs/AUTH_API_REQUIREMENTS.md b/docs/AUTH_API_REQUIREMENTS.md new file mode 100644 index 0000000..ac7af5e --- /dev/null +++ b/docs/AUTH_API_REQUIREMENTS.md @@ -0,0 +1,17 @@ +# 用户系统与角色权限：前后端接口清单 + +当前后端未注册认证或管理员路由；前端只提供真实请求封装，任何 404、401、403 或 5xx 都会如实抛出，绝不创建本地假身份。 + +| 目标接口 | 方法 | 前端用途 | 后端待实现要求 | +|---|---:|---|---| +| `/api/auth/register` | POST | 注册 | 只创建 `user`；不得接受角色字段 | +| `/api/auth/login` | POST | 登录 | 建立 HttpOnly、Secure、SameSite Cookie 会话 | +| `/api/auth/logout` | POST | 退出 | 作废会话并清除 Cookie | +| `/api/auth/me` | GET | 刷新恢复会话 | 返回用户资料与 `user`/`admin` 角色 | +| `/api/users/me` | PATCH | 修改昵称/邮箱 | 只允许修改当前用户自己的基本资料 | +| `/api/auth/change-password` | POST | 修改密码 | 验证旧密码并进行安全哈希 | +| `/api/admin/users` | GET | 用户管理 | 必须由后端校验 `admin` 角色 | + +## 前端待接入条件 + +现有工程尚未安装 `vue-router`。在用户安装该依赖并确认认证接口可用后，前端将接入路由守卫：未登录跳转登录页、成功后回跳、管理员路由额外检查 `role === 'admin'`。前端只用于体验层控制；知识库、来源、实验、用户管理的最终授权必须由 FastAPI 校验。 diff --git a/frontend/src/services/auth.ts b/frontend/src/services/auth.ts new file mode 100644 index 0000000..9d0cd4a --- /dev/null +++ b/frontend/src/services/auth.ts @@ -0,0 +1,26 @@ +import type { ChangePasswordPayload, CurrentUser, LoginPayload, RegisterPayload, UpdateProfilePayload } from '../types/auth' + +export class AuthApiUnavailableError extends Error { + constructor(public readonly status: number, message: string) { super(message) } +} + +async function authRequest(path: string, init: RequestInit = {}): Promise { + const response = await fetch(path, { + credentials: 'include', + headers: { Accept: 'application/json', 'Content-Type': 'application/json', ...init.headers }, + ...init, + }) + if (!response.ok) { + const body = await response.json().catch(() => null) + throw new AuthApiUnavailableError(response.status, body?.detail || `认证请求失败（${response.status}）`) + } + return response.status === 204 ? undefined as T : response.json() as Promise +} + +export const register = (payload: RegisterPayload) => authRequest('/api/auth/register', { method: 'POST', body: JSON.stringify(payload) }) +export const login = (payload: LoginPayload) => authRequest('/api/auth/login', { method: 'POST', body: JSON.stringify(payload) }) +export const logout = () => authRequest('/api/auth/logout', { method: 'POST' }) +export const getCurrentUser = () => authRequest('/api/auth/me') +export const updateMyProfile = (payload: UpdateProfilePayload) => authRequest('/api/users/me', { method: 'PATCH', body: JSON.stringify(payload) }) +export const changePassword = (payload: ChangePasswordPayload) => authRequest('/api/auth/change-password', { method: 'POST', body: JSON.stringify(payload) }) +export const getUsers = () => authRequest('/api/admin/users') diff --git a/frontend/src/types/auth.ts b/frontend/src/types/auth.ts new file mode 100644 index 0000000..9979d31 --- /dev/null +++ b/frontend/src/types/auth.ts @@ -0,0 +1,16 @@ +export type UserRole = 'user' | 'admin' + +export type CurrentUser = { + id: number + username: string + nickname: string | null + email: string | null + role: UserRole + created_at?: string + conversation_count?: number +} + +export type RegisterPayload = { username: string; password: string; email?: string; nickname?: string } +export type LoginPayload = { username: string; password: string } +export type UpdateProfilePayload = { nickname?: string; email?: string } +export type ChangePasswordPayload = { current_password: string; new_password: string } diff --git a/frontend/src/views/AccountSettingsView.vue b/frontend/src/views/AccountSettingsView.vue new file mode 100644 index 0000000..825440c --- /dev/null +++ b/frontend/src/views/AccountSettingsView.vue @@ -0,0 +1,8 @@ + + diff --git a/frontend/src/views/LoginView.vue b/frontend/src/views/LoginView.vue new file mode 100644 index 0000000..da2fcdf --- /dev/null +++ b/frontend/src/views/LoginView.vue @@ -0,0 +1,7 @@ + + diff --git a/frontend/src/views/ProfileView.vue b/frontend/src/views/ProfileView.vue new file mode 100644 index 0000000..5aca313 --- /dev/null +++ b/frontend/src/views/ProfileView.vue @@ -0,0 +1,8 @@ + + diff --git a/frontend/src/views/RegisterView.vue b/frontend/src/views/RegisterView.vue new file mode 100644 index 0000000..2abc046 --- /dev/null +++ b/frontend/src/views/RegisterView.vue @@ -0,0 +1,7 @@ + + diff --git a/frontend/src/views/UserManagementView.vue b/frontend/src/views/UserManagementView.vue new file mode 100644 index 0000000..96987c9 --- /dev/null +++ b/frontend/src/views/UserManagementView.vue @@ -0,0 +1,8 @@ + + -- 2.43.0 From b12f315cb33715259bc53aa7bcfddbb1cb6b6b93 Mon Sep 17 00:00:00 2001 From: jhy <184825448@qq.com> Date: Sat, 17 Oct 2026 00:02:47 +0800 Subject: [PATCH 7/7] feat: add knowledge management lifecycle --- frontend/src/api.ts | 5 +++++ frontend/src/router.ts | 1 + frontend/src/views/AdminView.vue | 2 +- frontend/src/views/KnowledgeManagementView.vue | 18 ++++++++++++++++++ 4 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 frontend/src/views/KnowledgeManagementView.vue diff --git a/frontend/src/api.ts b/frontend/src/api.ts index ad97bcb..49fe087 100644 --- a/frontend/src/api.ts +++ b/frontend/src/api.ts @@ -8,6 +8,11 @@ export const getKnowledge = () => apiRequest<{id:number;title:string;category:st export const createKnowledge = (payload:{title:string;category:string;content:string;source_url?:string;collected_at?:string}) => apiRequest('/api/knowledge',{method:'POST',body:JSON.stringify(payload)},true) export type VerificationStatus='pending'|'verified'|'rejected' +export type KnowledgeItem={id:number;version:number;title:string;category:string;content:string;source_url:string|null;source_id:number|null;document_id:number|null;collected_at:string|null;verification_status:VerificationStatus;reviewer:string|null;reviewed_at:string|null;verification_notes:string|null;created_at:string;updated_at:string;is_deleted:boolean} +export function getKnowledgePage(filters:{q?:string;category?:string;verification_status?:VerificationStatus;page?:number;page_size?:number}={}){const params=new URLSearchParams();for(const [key,value] of Object.entries(filters)){if(value!==undefined&&value!=='')params.set(key,String(value))}return apiRequest<{items:KnowledgeItem[];total:number;page:number;page_size:number}>(`/api/knowledge/page?${params}`)} +export function updateKnowledge(id:number,payload:{expected_version:number;title?:string;category?:string;content?:string;source_url?:string|null;collected_at?:string|null}){return apiRequest(`/api/knowledge/${id}`,{method:'PATCH',body:JSON.stringify(payload)},true)} +export function deleteKnowledge(id:number,expectedVersion:number){return apiRequest(`/api/knowledge/${id}?expected_version=${expectedVersion}`,{method:'DELETE'},true)} +export function getKnowledgeHistory(id:number,page=1,pageSize=20){return apiRequest<{items:AuditItem[];total:number;page:number;page_size:number}>(`/api/knowledge/${id}/history?page=${page}&page_size=${pageSize}`)} export type SourceItem={id:number;version:number;name:string;source_url:string|null;notes:string;created_at:string} export function getSources(q='',page=1,pageSize=20){return apiRequest<{items:SourceItem[];total:number;page:number;page_size:number}>(`/api/sources?q=${encodeURIComponent(q)}&page=${page}&page_size=${pageSize}`)} export function createSource(payload:{name:string;source_url?:string;notes:string}){return apiRequest('/api/sources',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(payload)},true)} diff --git a/frontend/src/router.ts b/frontend/src/router.ts index 50624ee..98c321c 100644 --- a/frontend/src/router.ts +++ b/frontend/src/router.ts @@ -12,6 +12,7 @@ const router=createRouter({history:createWebHistory(),routes:[ {path:'/settings',component:()=>import('./views/AccountSettingsView.vue')}, {path:'/indexes',component:()=>import('./views/IndexManagementView.vue'),meta:{role:'admin'}}, {path:'/reviews',component:()=>import('./views/KnowledgeReviewView.vue'),meta:{role:'admin'}}, + {path:'/knowledge',component:()=>import('./views/KnowledgeManagementView.vue'),meta:{role:'admin'}}, {path:'/documents',component:()=>import('./views/DocumentManagementView.vue'),meta:{role:'admin'}}, {path:'/sources',component:()=>import('./views/SourceManagementView.vue'),meta:{role:'admin'}}, {path:'/retrieval-exports',component:()=>import('./views/RetrievalExportView.vue'),meta:{role:'admin'}}, diff --git a/frontend/src/views/AdminView.vue b/frontend/src/views/AdminView.vue index 39ed9ce..5449d4d 100644 --- a/frontend/src/views/AdminView.vue +++ b/frontend/src/views/AdminView.vue @@ -29,7 +29,7 @@ onMounted(() => load(0))

管理员用户管理

用户数据由受服务端管理员权限保护的接口实时提供。

-

进入知识审核工作台　进入来源管理　进入文档管理　进入索引管理　导出检索历史

+

进入知识管理　进入知识审核工作台　进入来源管理　进入文档管理　进入索引管理　导出检索历史

{{ error }}

正在读取用户列表…