border-red-post-nalati/docs/PHASE_1_DEVELOPMENT_PLAN.md

阶段 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/重启后，先执行：

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 后端启动与接口验证

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 验证：

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 拉取、构建与启动

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 可直接开始的接口字段与资料台账模板。