saint/border-red-post-nalati
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: add phase one execution plan

Browse Source
This commit is contained in:
saint
2026-10-15 19:42:57 +08:00
parent da80fffebf
commit bca123303e
2 changed files with 182 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PHASE_1_DEVELOPMENT_PLAN.md
+181
View File
@@ -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 可直接开始的接口字段与资料台账模板。