2026Technology-Competition/docs/plan-web-chat-project-config.md

Web 聊天前端改造 + 项目级配置 + 设计文档纳入影响（实施计划）

状态：已评审定稿（2026-08-26） 决策记录：

• 会话名称：自动取要件定义文件名（未上传前显示「新会话」），header 不显示会话 ID
• 历史：左侧会话列表侧边栏，可切换历史会话并加载聊天记录
• 配置单位：以项目为单位（服务端持久化，复用 SQLite），项目下多个会话共享配置
• 上传区：选定项目后只显示「要件定义 xlsx（必需）」，其余来自项目配置
• 设计文档入影响：A 确定性交叉引用（代码变更点标识符 × 设计文档文本命中 → design_references）

---

一、总体设计

维度	方案
会话名称	name 自动取要件定义文件名；默认「新会话」；header 显示 会话: <name>
历史	左侧会话列表侧边栏；点击切换并 GET /api/chat/{sid}/messages 加载；localStorage 记当前会话
配置单位	项目级（服务端 SQLite projects 表）；会话绑定 project 名，共享配置
上传区	选定项目后仅「要件定义 xlsx（必需）」；模板/规则/代码库/设计文档来自项目配置
设计文档入影响	做法 A：解析设计文档为文本，与代码变更点标识符交叉引用，命中写 design_references

---

二、数据模型与存储（src/genesis/server/store.py）

• SessionRecord 新增字段：
  • name: str = ""（会话显示名）
  • project: str = ""（绑定的项目名；为空表示无项目）
  • to_dict() / _from_dict() 同步。
• 新增 ProjectsStore（复用同一 SQLite 文件，新增 projects 表）：
  • 字段：name(PK)、display_name、template、write_instruction、rules(JSON list of paths)、existing_system_code_dir、design_docs_dir、created_at、updated_at。
  • 方法：
    • upsert(name, display_name, template, write_instruction, rules, existing_system_code_dir, design_docs_dir)
    • get(name) -> ProjectConfig | None
    • list() -> list[ProjectConfig]
    • delete(name) -> bool
  • 路径校验（_validate_project_paths）：
    • template / write_instruction：文件须存在且为 .docx。
    • rules / design_docs_dir：目录须存在，枚举其中 .docx（为空目录 → 空列表，不报错）。
    • existing_system_code_dir：目录须存在（代码库目录，直接交给 CodeParser）。
    • 越界/不存在 → 抛 ProjectConfigError（映射 API 400）。
• 异常：ProjectConfigError（新增，与 SessionNotFoundError 并列）。

---

三、服务层（src/genesis/server/service.py）

• GenesisService.__init__ 增加 projects: ProjectsStore | None = None。
• create_session(user_id, name=None, project=None)：落 name(默认「新会话」)/project。
• upload_file：上传 requirements 且当前 name 仍为默认「新会话」时，自动将 name 设为文件名（去扩展名）。
• _rebuild_source(rec) 合并逻辑（核心）：
  1. 若 rec.project 非空 → cfg = self.projects.get(rec.project)；从 cfg 取 template / write_instruction / rules（目录枚举）/ existing_system_code_dir / design_docs（目录枚举）。
  2. 用户 rec.files（要件定义等）覆盖同名类型（用户上传优先）。
  3. 汇总传入 SourceParser.parse：
     • requirement_paths ← 用户上传 requirements
     • template_path ← template（用户覆盖优先）
     • write_instruction_paths ← write_instruction
     • rule_paths ← rules 目录枚举的 .docx
     • existing_system_path ← existing_system_code_dir（用户上传 zip 覆盖优先）
     • design_doc_paths ← design_docs 目录枚举的 .docx
• 新增 has_file(rec, ftype) 同时查 rec.files 与项目配置，供 run_parse / ChatAgent 判断缺件。
• run_impact：_rebuild_source 已含 design_doc_paths → ImpactAgent 产出 design_references；影响摘要增加「设计文档关联 N 处」。

---

四、影响调查扩展（做法 A）

• src/genesis/data_models.py：
  • StructuredSource 增加 design_docs: list（设计文档解析文本块，元素含 name + text）。
  • ImpactReport 增加 design_references: list[dict]（每项为 {element_id, identifier, doc_name, snippet}）。
• src/genesis/parsers/source_aggregator.py：parse 增加 design_doc_paths 参数 → 用 RuleDocParser(category="design") 解析 Word 为文本块，挂到 StructuredSource.design_docs。
• src/genesis/impact/impact_agent.py：run(ss, ...) 在代码变更点分析后，对每个变更标识符（类名/方法名）在 ss.design_docs 文本中检索出现处，命中即记入 design_references（确定性，无 LLM）。
• 影响调查书 JSON 与聊天反问摘要体现 design_references 计数。

---

五、API（src/genesis/server/app.py）

• GET /api/projects → 列表（name, display_name）。
• POST /api/projects → upsert（body：display_name, template, write_instruction, rules[], existing_system_code_dir, design_docs_dir）；校验失败 400。
• DELETE /api/projects/{name}（可选）。
• POST /api/sessions 增 project、name；返回含 name、project。
• GET /api/sessions 增可选 project 过滤；返回含 name、project。
• GET /api/sessions/{sid} 已含 to_dict（含 name/project）。
• 聊天端点不变。

---

六、前端（src/genesis/server/static/chat.html）

• 项目配置面板（可折叠）：display_name、name、模板路径、做成说明书路径、记入·图表规则目录、既有系统代码库目录、既有设计文档目录；「保存项目」→ POST /api/projects；顶部「项目」下拉（GET /api/projects）。
• 主页：选活动项目 → 「新会话」在该项目下建会话并自动套用配置；上传区仅要件定义。
• 左侧会话侧边栏：GET /api/sessions 列（名称 + 项目名 + 状态），点击切换 → GET /api/chat/{sid}/messages 加载；「新会话」按钮。
• header 显示 会话: <name>（不含 ID）。
• 页面加载：localStorage 读上次 sid，有效则恢复历史，否则新建。

---

七、测试（保持 fail_under=99）

• tests/test_server_store.py：ProjectsStore CRUD + SessionRecord 新字段。
• tests/test_server_service.py：项目 upsert / 路径校验拒绝 / 目录枚举 / has_file / 会话绑定项目 / _rebuild_source 合并 / design_references 进影响。
• tests/test_server_api.py：projects 端点 / sessions 含 name+project / chat 历史。
• tests/test_impact_agent.py + tests/test_source_aggregator.py：design_doc_paths 与 design_references 命中。
• tests/test_chat_agent.py：项目绑定流程（仅传要件定义即可生成）。

---

八、文档与日志

• docs/design.md §12.6 补：会话命名 / 历史侧边栏 / 项目级配置 / 设计文档纳入影响。
• README.md Web 服务段更新（项目配置用法）。
• _AI_USAGE_LOG.md 追加（范式步骤=Agent 实现）。

---

九、提交规范红线自检

• 新增代码/表全 ASCII 文件名；无新前端文件（仅改 chat.html）。
• 配置路径运行时解析 + 越界拒绝，无硬编码绝对路径。
• .env 不入库；无 >50MB 二进制。
• 全量 pytest 保持 fail_under=99。