本仓库旨在通过“代码约束 + 业务知识 + 模板”驱动，借助大模型生成交付文档（需求规格、用户手册、技术设计等），并保持与实现一致性。

• UI 原则：使用 Ant Design，简单清爽，不做酷炫动效。
• 文档能力：集中在“文档工作台”完成写作、对比（当前章节）、质检与发布；版本号采用时间戳。
• 详细用户指南：见 design_files/user_guide.md（本文也内嵌关键内容）。

• input_knowledge_base/：原始输入（业务背景、功能清单、Word 模板原件）
• context/：初始化与分析生成的结构化上下文（代码分析、映射、功能树、归一化模板等）
• outputs/：发布版本与草稿产物
• design_files/：设计文档与页面概念原型
• configs/：提示词与运行配置

• Python 环境
  • python -m venv .venv && source .venv/bin/activate
  • pip install -r requirements.txt
• 开发与运行
  • 后端：uvicorn docgen_server.application:app --reload
  • 前端：cd web && npm install && npm run dev
  • 单元测试：pytest（需安装 pyproject.toml 中的 dev 依赖）
  • 覆盖率：coverage run -m pytest && coverage report
• 一键启动：./scripts/start_dev.sh
  • 默认查找 python3.11，若虚拟环境旧于 3.11 会自动重建；可通过 PYTHON_BIN=/path/to/python3.11 指定解释器
  • 启动前检查端口 8000/5173，若被占用会列出具体进程并终止启动；失败日志保存在 .runtime/backend.log、.runtime/frontend.log
  • 支持离线安装：在联网环境运行 ./scripts/prepare_wheels.sh 准备 .wheels/，再在目标机执行启动脚本即可避免访问 PyPI
• 代码风格
  • Python 3.11；格式化 black（line length 100）、ruff 进行 Lint

1. 准备输入资料到 input_knowledge_base/：
   • business/background.md：填写项目总体背景与目标（仅此一份）。
   • feature_list/features.yaml 或 feature_list/feature_list.md：录入功能清单（二选一或同时维护）。
   • Word 模板原件（仅 .doc/.docx）放入：
     • templates/requirement-spec/raw/
     • templates/user-manual/raw/
     • templates/tech-design/raw/
   • 文件命名建议：kebab-case + -vYYYYMMDD-HHMM，如 requirement-spec-template-v20241029.docx。
2. 执行“一键初始化分析”（仅首次，管理员）：
   • 打开“代码分析结果预览（文件级）”页面，点击顶部 初始化分析（仅未初始化时显示）。
   • 流程会先梳理背景与功能清单，再逐文件调用 LLM 分析代码，并产出功能与代码的映射关系。
   • 成功后按钮隐藏，产物写入 context/；日志写入 sessions/init/<timestamp>.md，映射/索引文件供前端使用。
3. 开始写作：打开“文档工作台”，选择 doc_type 与范围 scope_id，按章节生成与修订、质检并发布。

• 目录结构
  • business/background.md：仅此文件，填写背景与目标。
  • feature_list/features.yaml：机器可读；feature_list.md：人工可读。
  • templates/<doc_type>/raw/：模板原件，仅接收 Word（.doc/.docx）。
• 功能清单最小 YAML 示例

project: your-project-id
systems:
  - id: sys-example
    name: 示例系统
    subsystems:
      - id: ss-example
        name: 示例子系统
        modules:
          - id: m-example
            name: 示例模块
            features:
              - id: f-sample-feature
                title: 示例功能
                description: 功能的简要说明
                subfeatures: []

• 命名与版本：文件名 kebab-case；统一时间戳版本后缀 -vYYYYMMDD-HHMM。

• 入口：代码分析结果预览页顶部 初始化分析（未初始化时显示）。
• 权限：项目管理员可执行；完成后按钮隐藏。
• 步骤（默认全部开启）：
  1. 结构校验与准备
  2. 模板归一化 → context/templates/normalized/<doc_type>/
  3. 知识梳理（LLM 摘要背景/功能清单）→ context/business/background_summary.md、context/systems/raw_overview.yaml
  4. 代码文件级分析（LLM 输出 Markdown + 元数据）→ context/code/analysis/*、context/code/analysis/_index.yaml

5. 功能-代码映射（LLM 验证并生成缺口提示）→ context/code/code_mapping.yaml
6. 结构树与索引 → context/tree.json、context/index.yaml、sessions/init/<timestamp>.md、context/.init_state.yaml

⚠️ 请先在“模型配置”页面填写 DeepSeek API Key。本流程依赖 LLM，若仅需验证流程可使用 ./scripts/start_dev.sh --dry-run（或在后端增加 dry_run=true）运行占位版本。 初始化页面会实时展示各阶段的执行进度（知识梳理、代码分析、功能映射），包括 LLM 调用数量、已完成文件数与失败原因。

• Web → 系统管理 → “数据清理” 卡片，可预览或执行清理。
• 清理内容：context/（保留 context/prompts）、outputs/、sessions/、.runtime 日志与缓存等系统生成数据。
• 保留内容：输入资料、提示词配置（configs/prompts.yaml、context/prompts/）、模型配置（.runtime/config/model_config.yaml）。
• 清理完成后需要重新执行“初始化分析”。

• 草稿：同一 doc_type+scope_id 仅允许一个草稿；发布后清空。
• 章节对比：仅“当前选中章节”；左=草稿或基线，右=历史版本；支持并排/统一、差异高亮、上一/下一处差异；可逐块采纳差异到草稿。
• QA 与发布：输出 qa/acceptance_checklist.yaml；发布生成 vYYYYMMDD-HHMM[-seq]，产物写入 outputs/<project>/<doc_type>/<scope_id>/<version>/，会话记录写入 sessions/<doc_type>/<scope_id>/<version>/<timestamp>.md。
• 导出：支持导出单章节 MD/PDF，落盘 sections/<section-id>/exports/。

• 访问前端：http://localhost:5173（运行 npm run dev 后），使用侧边导航进入各功能模块。
• 初始化分析：页面展示 6 步流程（当前为占位），执行后刷新状态并更新上下文目录。
• 代码分析：左侧浏览 input_code/ 目录，右侧查看占位 Markdown 分析，并可触发“重新分析”。
• 功能结构：展示 tree.json 的占位数据，节点详情提供映射占位信息与“跳转至文档工作台”指引。
• 文档工作台：选择 doc_type 与 scope_id，生成计划/章节占位内容、查看草稿并发布占位版本。
• 模型配置与提示词管理：读取/保存后端占位配置文件，后续将接入真实校验与安全存储方案。

• 左侧目录镜像 input_code/；右侧 Tabs：分析文档｜提取与映射。
• 仅支持“单文件重新分析”；不提供目录子树批量重分析。
• 可导出 MD/PDF；不展示源代码正文，只展示分析文档与衍生信息。

• 不展示文档、版本与会话；仅展示映射与证据；提供“在文档工作台中查看文档”跳转。

• 版本号：vYYYYMMDD-HHMM[-seq]
• 版本索引：outputs/<project>/<doc_type>/<scope_id>/_index.yaml
• 会话记录：sessions/<doc_type>/<scope_id>/<draft_or_version>/<timestamp>.md

• 提示词：configs/prompts.yaml，模板在 context/prompts/
• 模型配置：通过页面保存后，信息写入 .runtime/config/model_config.yaml，API Key 仅存本地并以 ******** 掩码回显；版本切换与连通性测试均走后端 DeepSeek API 封装
  • DeepSeek 预置模型：deepseek-chat（默认 4K / 最大 8K）、deepseek-reasoner（思考模式，默认 32K / 最大 64K），均采用 DeepSeek-V3.2-Exp 版本特性
• 提示词覆盖机制：基础模板保留在 configs/prompts.yaml，页面保存时写入 .runtime/config/prompts.local.yaml 做覆盖合并，便于版本化与回滚

• 格式与 Lint：black（100 列）、ruff
• 测试：pytest；覆盖率：coverage run -m pytest && coverage report
• 提交：主题行使用祈使语气；单一变更粒度；如适用附 Fixes #123/Refs #123

• 用户说明（完整版）：design_files/user_guide.md
• 页面概念原型：design_files/ 下各 ui_*.md
• 架构设计：design_files/system_architecture_plan.md