# Attribution_Analysis

**Repository Path**: dddsm122/attribution-analysis

## Basic Information

- **Project Name**: Attribution_Analysis
- **Description**: 基于业务数据的实时分析平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 经营归因分析系统（Attribution Analysis System）

围绕经营业务问题的**多轮对话式归因分析系统**：用户在一个会话里持续追问、补充资料，系统每一轮执行查询与计算并实时展示分析过程，逐轮产出结构化的归因结论，最终沉淀为可导出的分析报告。

它要解决的是传统 BI 报表"单问单答"的问题——不保留上下文、无法延续上一轮结论、也无法把每轮查到的证据串成一份完整分析。

创建日期：2026-09-25
需求来源：《大模型项目实战》2.1 经营归因分析系统（2.1.1 – 2.1.13）

## 目录

1. [项目简介](#1-项目简介)
2. [当前状态](#2-当前状态)
3. [文档索引](#3-文档索引)
4. [交付范围与用户角色](#4-交付范围与用户角色)
5. [演示场景](#5-演示场景)
6. [系统架构](#6-系统架构)
7. [技术栈与端口](#7-技术栈与端口)
8. [领域模型与数据表](#8-领域模型与数据表)
9. [接口清单](#9-接口清单)
10. [实时消息协议](#10-实时消息协议)
11. [关键规则与约束](#11-关键规则与约束)
12. [目录结构](#12-目录结构)
13. [开发路线图](#13-开发路线图)
14. [环境准备与启动](#14-环境准备与启动)
15. [配置说明](#15-配置说明)
16. [验收标准](#16-验收标准)
17. [协作约定](#17-协作约定)
18. [交付物清单](#18-交付物清单)

## 1. 项目简介

| 维度 | 说明 |
| --- | --- |
| 系统形态 | 前端 SPA + FastAPI 单体后端 + 独立认证中心 + MySQL + 本地文件存储 |
| 核心交互 | 会话内多轮追问 → 每轮触发一次分析任务 → 实时推送分析过程 → 产出六部分结构化结果 |
| 核心复杂度 | 分析任务编排与实时推送，而非高并发水平扩展 |
| 项目定位 | 单人 / 小团队开发的教学实战项目，优先开发效率与可演示性 |

**明确不做的部分**：不面向公众注册（用户来自企业认证中心）、不做实时数据大屏、不做多人协同编辑。

## 2. 当前状态

| 项 | 状态 |
| --- | --- |
| 需求文档 / 设计文档 / 开发计划 | 已完成（2026-08-26） |
| OpenSpec 目录骨架 | 已初始化，`openspec/changes`、`openspec/specs` 尚为空 |
| 后端（阶段 0–8） | 已完成：骨架、十张表与迁移、认证接入、会话与消息、附件管理、WebSocket 实时通道、任务编排、模拟分析引擎、结果与导出、配置热更新、任务日志 |
| 认证中心（阶段 2） | 已完成：OAuth2 授权码流程 + 内置演示账号 |
| 前端（阶段 9） | 已完成：登录入口与回调过渡/失败重试、会话列表、对话流式渲染、实时任务区、附件侧栏、结果展示与历史轮回看、配置与日志入口、断线重连与重发 |
| 示例业务数据（阶段 6） | 已完成：六场景建表脚本 + 商品目录优化与退款模式分析两个场景的校准数据 |
| 端到端验收（阶段 11） | 已完成：见 `acceptance/README.md` 与 `acceptance/acceptance-report.md` |
| 真实大模型引擎（阶段 10） | 未开始（提案已备：`openspec/changes/add-real-llm-engine/`，等指令开工） |

> 后端与认证中心可直接启动，前端可在浏览器跑通"登录 → 会话 → 提问 → 实时分析 → 六部分结果 → 导出"的完整链路；启动方式见第 14 节。

## 3. 文档索引

三份文档构成一条完整链路：**做什么 → 怎么建 → 按什么顺序建**。

| 文档 | 定位 | 回答的问题 | 何时读 |
| --- | --- | --- | --- |
| [经营归因分析系统-需求文档.md](docs/经营归因分析系统-需求文档.md) | PRD | 做什么：背景、目标、角色、页面功能、结果格式、验收标准 | 想了解产品全貌时 |
| [经营归因分析系统-设计文档.md](docs/经营归因分析系统-设计文档.md) | 技术设计 | 怎么建：架构、模块边界、数据库、接口契约、实时协议、关键流程、部署 | 动手实现前 |
| [经营归因分析系统-开发计划.md](docs/经营归因分析系统-开发计划.md) | 执行计划 | 按什么顺序建：12 个阶段，每阶段以可执行的验证动作收尾 | 每个阶段开工前 |

### 引用约定

阅读文档时注意三条约定，否则容易找错章节：

- 开发计划中的 `§编号` 指**设计文档**的章节（如 `§7.2` = 设计文档第 7.2 节）
- 开发计划中的"验收条目编号"指 **PRD 第 9 节**的验收标准
- 设计文档第 1.2 节的"需求追溯"表把每个设计章节映射回源需求条目 2.1.x

## 4. 交付范围与用户角色

### 交付范围

| 能力类 | 内容 |
| --- | --- |
| 基础能力 | 认证中心登录、会话管理、附件管理、配置热更新、运行日志 |
| 分析能力 | 实时分析、数据库查询、文件读写、文本检索、命令执行、结果文件生成 |
| 交付能力 | 聊天工作台、结果保存、结果导出、至少两个业务分析场景的示例数据与完整演示链路 |

### 用户角色

| 角色 | 典型画像 | 核心操作 | 权限边界 |
| --- | --- | --- | --- |
| 分析用户（`analyst`） | 业务分析师 / 运营人员，熟悉业务指标但不写 SQL | 创建会话、提问、上传资料、查看历史、查看与下载结果 | 只能操作自己的会话、附件与结果 |
| 系统管理员（`admin`） | 负责运行维护的工程师 | 维护认证与系统配置、查看运行日志、管理数据源、启停功能开关 | 管理系统级配置与日志，不代用户执行分析 |

角色由认证中心返回的用户身份判定，本系统内不再单独维护注册流程。

## 5. 演示场景

系统需提供**六个场景**的建表脚本与演示数据，交付时**至少任选两个**完成全链路演示（提问 → 分析过程 → 结构化结果 → 导出报告）。

| 场景 | 数据表要求 | 演示 |
| --- | --- | --- |
| 商品目录优化 | 商品表、类目表、搜索曝光表、点击表、转化表 | **必做演示场景**（3C 类目转化率环比下降约 17.5%） |
| 退款模式分析 | 退款申请表、退款原因表、订单表、用户表 | **必做演示场景**（母婴类目退款率 5.7% → 9.5%） |
| 客户行为分析 | 用户表、访问事件表、加购事件表、下单事件表 | 候选 |
| 库存异常分析 | 库存表、入库表、出库表、销量表 | 候选 |
| 评论反馈分析 | 评论表、评分表、商品表、退款表 | 候选 |
| 市场表现分析 | 渠道表、投放表、订单表、销售汇总表 | 候选 |

演示数据要求：时间跨度覆盖至少两个统计周期（支撑环比 / 同比类问题）；数值可下钻（分价格段、分渠道、分退款原因存在明显差异），使结论有数据支撑而非叙事堆砌。

## 6. 系统架构

采用**单体分层架构**：前端 SPA + FastAPI 单体后端 + 独立认证中心 + MySQL + 本地文件存储，外部依赖 LLM 服务。

```mermaid
graph TB
    subgraph Client["浏览器"]
        FE["前端 SPA<br/>认证回调 / 会话 / 聊天 / 附件 / 结果 / 配置 / 日志"]
    end
    subgraph Server["FastAPI 单体服务（:8000）"]
        AUTH["认证接入模块"]
        CHAT["会话 / 消息模块"]
        ATT["附件模块"]
        WS["长连接模块（WebSocket）"]
        TASK["任务模块"]
        ANA["分析模块<br/>上下文拼装 + 工具执行"]
        RES["结果模块"]
        CFG["配置模块"]
    end
    subgraph Ext["外部依赖"]
        SSO["认证中心（:8100）"]
        LLM["LLM 服务<br/>或内置模拟引擎"]
        BIZDB[("业务示例库 MySQL")]
    end
    subgraph Storage["本地存储"]
        APPDB[("系统库 MySQL")]
        FS[("uploads / exports / workspace")]
    end
    FE -->|"REST"| AUTH
    FE -->|"REST"| CHAT
    FE -->|"REST"| ATT
    FE -->|"WSS"| WS
    AUTH --> SSO
    CHAT --> APPDB
    ATT --> FS
    TASK --> APPDB
    ANA --> LLM
    ANA -->|"数据库查询工具"| BIZDB
    ANA -->|"文件读写 / 检索 / 命令"| FS
    RES --> APPDB
    RES --> FS
    CFG --> APPDB
```

前端与后端之间有两条通道：**REST** 承担会话、附件、结果等常规操作；**WebSocket** 承担分析过程的实时推送。分析模块是唯一同时触达 LLM、业务示例库和文件存储的模块，也是系统边界最宽的组件。

后端九个模块的职责与边界、前端七个模块到后端的映射，见设计文档第 3 节。

## 7. 技术栈与端口

| 选项 | 决策 | 理由 |
| --- | --- | --- |
| Web 框架 | FastAPI | 原生 async 与 WebSocket 支持，一套框架同时覆盖 REST 与长连接，自动生成 OpenAPI 文档 |
| ORM / 迁移 | SQLAlchemy 2.x + Alembic | 管理十张表，初始化脚本可重复执行 |
| 数据库 | MySQL 8 | 既有技术栈约定；JSON 字段类型可直接承载结构化输出 |
| 环境管理 | uv | 依赖解析快、锁文件确定性好，配合 PyCharm 直接启动 |
| 前端 | Vue 3 + Vite | 与流式渲染、组件化工作台形态匹配 |
| 认证 | 独立认证中心 + OAuth2 授权码模式 | 对应"授权登录入口页 + 登录回调页"需求，认证能力可复用 |
| LLM | 内置模拟引擎 + 外部 API 双模式 | 未配置 `OPENAI_API_KEY` 时离线可演示；配置后切换真实模型，经适配层隔离 |

| 服务 | 端口 | 说明 |
| --- | --- | --- |
| 业务后端（FastAPI） | 8000 | REST + WebSocket，交互式接口文档见 `/docs` |
| 认证中心 | 8100 | OAuth2 授权码流程：授权页、授权码签发、令牌端点 |
| 前端（Vite 开发服务器） | 5173 | 开发模式；生产构建后为静态产物 |

三个服务独立进程启动，前端通过代理或环境变量指向后端与认证中心地址。

## 8. 领域模型与数据表

### 术语表

| 术语 | 定义 |
| --- | --- |
| 会话（conversation） | 围绕一个业务问题的多轮对话容器，聚合消息、附件、任务、结果与摘要 |
| 分析任务（task） | 由一条用户消息触发的一次分析执行，具有完整状态机 |
| 轮 | 一次"用户消息 → 分析任务 → 结构化结果"的完整循环 |
| 工具（tool） | 分析过程中可被调用的能力：数据库查询、文件读写、文本检索、命令执行、结果文件生成 |
| 上下文摘要（context summary） | 对会话早期消息的压缩文本，用于控制发送给模型的上下文长度 |
| 临时令牌（websocket token） | 一次性短时效令牌，用于 WebSocket 连接鉴权 |

### 十张系统表

| 分组 | 表 | 作用 | 关键约束 |
| --- | --- | --- | --- |
| 身份 | `users` | 认证中心用户的本地映射 | `external_user_id` 唯一，按此幂等同步 |
| 会话 | `conversations` | 会话元数据 | 状态 `active` / `archived` / `deleted`；删除为状态流转后再级联清理 |
| 会话 | `messages` | 消息流（用户 / AI / 工具） | `(conversation_id, seq_no)` 唯一，会话内 `seq_no` 单调递增 |
| 会话 | `attachments` | 附件元数据 | `parse_status`：`pending` / `parsing` / `success` / `failed` |
| 会话 | `context_summaries` | 早期消息的压缩摘要 | 记录覆盖区间 `start_seq_no` / `end_seq_no` |
| 任务 | `analysis_tasks` | 一次分析执行 | 状态 `queued` / `running` / `success` / `failed` / `cancelled` |
| 任务 | `task_logs` | 任务、工具、LLM 调用日志 | `log_level` + `log_type` 区分来源 |
| 任务 | `websocket_tokens` | 一次性连接令牌 | `token` 唯一；`expires_at` 短时效，建议 60 秒；`consumed_at` 标记一次性消费 |
| 结果 | `analysis_results` | 六部分结构化结果 | `task_id` 唯一（一任务一结果）；含 `key_metrics_json`、`evidence_list_json`、`result_markdown`、`result_file_path` |
| 配置 | `system_configs` | 系统配置键值 | `config_key` 唯一，按 `config_group` 分组；不含密钥类配置 |

字段级定义见设计文档第 4.2 节；索引策略见 4.3 节；ER 图见 4.1 节。

### 级联删除规则

删除会话在单个数据库事务内完成：清空该会话的 `messages`、`attachments`、`analysis_tasks`、`analysis_results`、`context_summaries`、`websocket_tokens` 记录，随后删除 `uploads` / `exports` / `workspace` 下该会话的三个目录。

- 若存在运行中任务，先置为 `cancelled` 再删除
- 文件删除失败只记录日志告警，不阻断库内删除（库记录是唯一事实源，孤儿文件可后台回收）

## 9. 接口清单

### 通用约定

- 基础路径：REST 接口统一前缀 `/api`，认证接口在 `/auth` 下
- 认证方式：授权回调后签发 HttpOnly 会话 Cookie，REST 与 WebSocket 均需登录态
- 响应包络：`{ "code": 0, "message": "ok", "data": { ... } }`，`code` 为 0 表示成功

### 错误码

| HTTP | code | 含义 |
| --- | --- | --- |
| 400 | 40001 | 参数缺失或格式错误 |
| 401 | 40101 | 未登录或登录态失效 |
| 403 | 40301 | 无权限访问该资源（如访问他人会话） |
| 404 | 40401 | 会话 / 附件 / 任务 / 结果不存在 |
| 409 | 40901 | 会话已有运行中的分析任务 |
| 409 | 40902 | WebSocket 令牌无效、已使用或已过期 |
| 413 | 41301 | 附件超过大小限制（限额可配置） |
| 500 | 50001 | 服务器内部错误 |
| 502 | 50201 | 上游服务（认证中心 / LLM）不可用 |

### 接口总表（十五个）

| 分组 | 方法与路径 | 说明 |
| --- | --- | --- |
| 认证 | `GET /auth/login` | 发起授权登录，302 跳转认证中心授权页 |
| 认证 | `GET /auth/callback` | 授权回调：换令牌 → 幂等同步用户 → 签发 Cookie → 跳工作台 |
| 会话 | `POST /api/chat/create` | 创建会话 |
| 会话 | `POST /api/chat/delete` | 批量删除会话（含级联删除） |
| 会话 | `POST /api/chat/update` | 重命名会话 |
| 会话 | `GET /api/chat/ls` | 会话列表，按最后消息时间倒序，过滤已删除 |
| 会话 | `GET /api/chat/ls/{conversation_id}` | 会话历史消息，按 `seq_no` 升序，携带关联附件 |
| 附件 | `POST /api/attachment/upload` | 上传附件（multipart），落盘后异步解析 |
| 附件 | `POST /api/attachment/delete` | 删除附件记录与文件 |
| 附件 | `GET /api/attachment/get` | 下载附件，文件流携带原始文件名 |
| 长连接 | `POST /api/chat/ws-token` | 签发一次性短时效 WebSocket 令牌 |
| 长连接 | `WS /api/chat/ws/chat` | 会话实时通道，见第 10 节 |
| 管理 | `POST /api/admin/reload` | 配置热更新，仅管理员 |
| 任务 | `GET /api/tasks/{task_id}` | 查询任务状态，用于断线兜底 |
| 结果 | `GET /api/results/{task_id}` | 查询六部分结构化结果 |

逐接口的请求体、响应字段与错误码见设计文档第 6.2 节；后端跑起来后 `/docs` 提供在线版。

> **设计要点**：发送分析问题走 WebSocket 上行消息（`send_message`），而不是独立 REST 接口。这样消息受理、任务创建与实时推送在同一条连接内闭环，避免 REST 受理后 WebSocket 错过 `message_start`。

## 10. 实时消息协议

### 连接建立

1. 前端 `POST /api/chat/ws-token` 申请一次性令牌（写入 `websocket_tokens`，建议 60 秒有效）
2. 携带 `websocket_token` + `conversation_id` 建立 `WS /api/chat/ws/chat`
3. 服务端校验令牌存在、未消费、未过期、归属匹配，通过后写入 `consumed_at`

令牌"一次性 + 短时效"双重限制，避免被复制后长期复用。

### 服务端下行消息（八种）

公共信封：`type`、`conversation_id`、`task_id`（连接级消息除外）、`ts`（毫秒时间戳）。

| type | 触发时机 | 专有字段 |
| --- | --- | --- |
| `message_start` | 本轮分析开始 | `message_id` |
| `message_delta` | 模型增量文本 | `delta_text` |
| `tool_start` | 某个工具开始执行 | `tool_name`、`tool_call_id` |
| `tool_finish` | 某个工具执行完成 | `tool_name`、`tool_call_id`、`tool_result_summary`、`tool_status` |
| `task_status` | 任务状态变化 | `task_status`、`current_step` |
| `result_ready` | 结构化结果已生成并落库 | `result_id` |
| `error` | 本轮分析失败 | `error_message` |
| `done` | 本轮分析结束 | `finished_at` |

### 客户端上行消息（三种）

| type | 字段 | 用途 |
| --- | --- | --- |
| `send_message` | `text` | 发送分析问题，触发一轮任务 |
| `cancel` | `task_id` | 取消当前运行中任务 |
| `ping` | — | 心跳，服务端回 `pong` |

### 连接管理

- 心跳：客户端每 30 秒 `ping`，服务端 60 秒未收到即关闭连接
- 断线重连：前端指数退避重连，重连需重新走令牌流程；重连后先调 `GET /api/tasks/{task_id}` 拉取当前状态再继续接收推送，避免状态空洞
- 会话删除时，服务端主动关闭该会话的全部连接

完整的一轮分析时序图（含工具循环与异常路径）见设计文档第 7.4 节。

## 11. 关键规则与约束

### 会话与任务一致性

- 一条用户消息对应一次分析任务
- **同一时间一个会话只允许存在一个运行中的分析任务**，冲突时返回 40901
- 取消分析后，本轮用户消息与已完成的部分输出保留，任务状态置 `cancelled`

### 上下文拼装与摘要压缩

发送给模型的上下文按固定顺序拼装：系统提示词 → 会话早期消息摘要 → 近期 N 条原始消息 → 附件解析摘要 → 本轮问题。

当消息总数超过阈值 M 时，把"已出摘要区间之外、仍在近期窗口之外"的最早一批消息压缩为一条新摘要写入 `context_summaries`，压缩动作在任务开始前的"拼装上下文"步骤完成。

### 结果输出格式

每轮分析产出六部分，前三部分为结构化数据，供前端分区渲染与二次利用：

| 部分 | 形式 | 字段要求 |
| --- | --- | --- |
| 问题定义 | 文本 | 当前分析要回答的业务问题 |
| 关键指标 | 数组 | `metric_name`、`metric_value`、`metric_unit`、`metric_period` |
| 证据列表 | 数组 | `source_type`、`source_name`、`evidence_text`、`related_metric`、`confidence` |
| 归因结论 | 文本 | 主要原因与影响范围 |
| 待补充数据 | 列表 | 当前分析仍缺失的数据项 |
| 下一步建议 | 列表 | 至少 2 条 |

### 文件存储

```
storage_root/
├── uploads/{user_id}/{conversation_id}/     # 用户上传的附件
├── exports/{user_id}/{conversation_id}/     # 导出的结果文件
└── workspace/{user_id}/{conversation_id}/   # 分析过程临时中间文件
```

- 存储文件名由服务端生成并保留原始扩展名，原始名记录在 `attachments.file_name`
- 结果导出写入 `exports/{user_id}/{conversation_id}/result_{task_id}.md`，保留至会话删除，支持随时重新下载

### 安全底线

| 项 | 约束 |
| --- | --- |
| 路径校验 | 所有文件读写、检索、下载先做规范化前缀校验，绝对路径必须落在该会话目录内，拒绝 `..` 与符号链接逃逸 |
| 命令执行 | 白名单命令 + 限定在 workspace 目录内 + 超时上限 + 禁止网络类命令，可通过功能开关整体关闭 |
| 数据库查询 | 仅访问业务示例库，使用只读账号，查询超时由配置控制 |
| 越权防护 | 所有按 ID 的访问校验资源归属当前用户，否则 40301 |
| WebSocket | 一次性 + 短时效令牌 |
| 密钥管理 | 密钥类配置一律走环境变量，不进入 `system_configs` 表 |

### 错误处理

| 故障点 | 策略 |
| --- | --- |
| LLM 调用超时 / 失败 | 按配置重试 N 次；仍失败则任务置 `failed`，推送 `error` |
| 工具执行失败 | 单工具失败不终止任务，结果中如实计入失败信息，由模型决定换路径或收敛结论 |
| 认证中心不可达 | 登录入口返回 50201 并提示重试 |
| WebSocket 推送失败 | 消息不丢：任务状态与结果均可通过任务 / 结果接口拉取兜底 |

## 12. 目录结构

```
analysis/
├── README.md                  # 本文件
├── docs/                      # 需求 / 设计 / 开发计划（已存在）
├── openspec/                  # OpenSpec 工作区（已初始化）
│   ├── config.yaml
│   ├── changes/archive/       # 变更提案与归档
│   └── specs/                 # 能力规格
├── .agents/skills/            # OpenSpec 相关技能定义（已存在）
├── backend/                   # 规划：FastAPI 后端（阶段 0 起）
│   ├── app/                   #   模块：认证接入 / 会话 / 消息 / 附件 / 长连接 / 任务 / 分析 / 结果 / 配置
│   ├── alembic/               #   数据库迁移
│   └── pyproject.toml         #   uv 依赖与锁文件
├── frontend/                  # 规划：Vue 3 + Vite 工作台（阶段 9 起）
├── auth-center/               # 规划：OAuth2 认证中心（阶段 2 起）
├── scripts/                   # 规划：建表脚本、种子数据（阶段 1 / 6 起）
└── storage_root/              # 规划：uploads / exports / workspace
```

标注"规划"的目录在当前提交中尚不存在，目录名以阶段 0 实际落地为准。

## 13. 开发路线图

单线顺序推进，一个阶段完成后才启动下一个；进度以**验证点**度量，不使用工期估算。

| 阶段 | 名称 | 关键产出 | 验证点 |
| --- | --- | --- | --- |
| 0 | 工程骨架与运行环境 | uv 虚拟环境、FastAPI 入口、数据库连接、存储目录 | `/docs` 可访问，数据库连通 |
| 1 | 系统数据库 | 十张表模型与迁移、基础配置种子 | 迁移可重复执行，表结构与设计一致 |
| 2 | 认证中心与登录链路 | :8100 认证服务、`/auth/*` 接口、演示账号 | 浏览器完成授权登录，`users` 落库 |
| 3 | 会话与消息 | 会话 / 消息五个 REST 接口、级联删除 | Swagger 走通 CRUD 与越权用例 |
| 4 | 附件管理 | 上传 / 删除 / 下载、路径校验、异步解析 | 落盘路径正确，目录穿越被拒 |
| 5 | WebSocket 实时通道 | 一次性令牌、连接鉴权、心跳 | 脚本客户端连接成功，令牌重用被拒 |
| 6 | 示例业务数据 | 六场景建表脚本、两个演示场景种子数据 | SQL 聚合结果与设计口径一致 |
| 7 | 任务与分析引擎（模拟） | 任务状态机、模拟引擎、八种下行消息 | 脚本客户端收齐一轮完整消息序列 |
| 8 | 结果、配置与日志 | 结果落库与导出、摘要压缩、热更新 | 六部分结果可查，导出文件可下载 |
| 9 | 前端聊天工作台 | 登录页、工作台四区、附件侧栏 | 浏览器演示账号全链路操作 |
| 10 | 真实 LLM 接入（增强） | 适配层、环境变量切换 | 配置 key 走真实模型，去掉 key 回落模拟 |
| 11 | 端到端验收与交付 | 验收截图、交付包 | PRD 八条验收逐条通过 |

阶段 0–8 为后端与数据线，阶段 9 为前端线，阶段 10–11 为增强与收尾线。阶段 10 不在前置依赖链上（验收不依赖真实模型），但建议交付前完成，使演示既可离线又可在线。

每阶段的详细工作内容见开发计划第 3 节。已识别的顺序风险：协议字段需在前端开工前用脚本客户端验证；种子数据口径需先用 SQL 复核；级联删除尽早实现并冻结语义；真实模型特有逻辑不得泄漏进模拟路径。

## 14. 环境准备与启动

### 依赖

| 依赖 | 版本要求 | 用途 |
| --- | --- | --- |
| Python | 3.11+（以阶段 0 锁定为准） | 后端与认证中心 |
| uv | 最新稳定版 | Python 依赖与虚拟环境管理 |
| MySQL | 8.x | 系统库 + 业务示例库 |
| Node.js | 18+（以阶段 9 锁定为准） | 前端构建与开发服务器 |

### 启动顺序

```
MySQL → 认证中心（:8100）→ 后端（:8000）→ 前端（:5173）
```

**1. 准备数据库与配置**（只需一次）

```powershell
# 建库与账号（口令自定，随后填入 backend/.env 的 DB_PASSWORD）
& 'D:\commonApp\Developing\SDKs\msql\mysql-8.0.45-winx64\bin\mysql.exe' --host=127.0.0.1 --port=3307 --user=root --password -e "SET @app_password='<应用账号口令>'; SET @reader_password='<只读账号口令>'; SOURCE scripts/init_databases.sql;"

cd backend
uv sync                                            # 安装后端依赖
uv run alembic upgrade head                        # 建系统库十张表
uv run python ../scripts/seed_system_configs.py    # 写入四组配置种子
```

`backend/.env` 需要 `DB_*`、`STORAGE_ROOT`、`AUTH_CENTER_BASE_URL`、`APP_SECRET`（随机串）等，字段说明见 `backend/.env.example`。

**2. 启动三个服务**（三个终端）

```powershell
cd auth-center; uv run uvicorn app.main:app --port 8100   # 认证中心
cd backend;     uv run uvicorn app.main:app --port 8000   # 后端（接口文档 http://127.0.0.1:8000/docs）
cd frontend;    npm install; npm run dev                  # 前端（浏览器打开 http://localhost:5173/）
```

**3. 使用**

- 打开 `http://localhost:5173/` → 点「授权登录」→ 演示账号 `analyst / analyst123`（管理员 `admin / admin123`）
- 新建会话 → 输入问题（如"上月 3C 类目转化率为什么下降"）→ 观察实时分析过程与六部分结果 → 复制或导出

**4. 自动化验证**

```powershell
cd backend;  uv run pytest -q                        # 后端全量测试
uv run python ../scripts/login_smoke.py              # 登录链路（需先启动 8000/8100）
uv run python ../scripts/ws_smoke.py                 # 完整分析链路 + 结果查询 + 导出
cd ../auth-center; uv run pytest -q                  # 认证中心测试
cd ../frontend;    npm run test                      # 前端单元测试
```

## 15. 配置说明

### 环境变量

| 变量 | 说明 |
| --- | --- |
| 数据库连接 | 系统库与业务示例库连接串，配置化以便后续 Docker 化 |
| 存储根目录 | `storage_root` 的绝对路径 |
| 认证中心地址 | 后端与前端对接认证中心（:8100）的基地址 |
| `OPENAI_API_KEY` | 存在则走真实大模型，不存在回落内置模拟引擎 |

### 系统配置（`system_configs` 表）

按四组管理，支持通过 `POST /api/admin/reload` 热更新（校验失败保留旧缓存并返回失败原因）：

| 分组 | 典型配置 |
| --- | --- |
| `auth` | 认证中心对接参数、会话有效期 |
| `llm` | 模型与超时、重试次数 |
| `analysis` | 近期消息条数 N、摘要阈值 M、心跳间隔、附件大小限额、工具超时 |
| `feature` | 功能开关，如命令执行工具的启停 |

## 16. 验收标准

对照 PRD 第 9 节，逐条通过即视为交付：

- [ ] 1. 能通过授权登录进入聊天工作台
- [ ] 2. 能创建会话、上传附件、发送消息并查看历史记录
- [ ] 3. 能通过实时连接看到分析过程中的状态变化、工具执行和最终结果
- [ ] 4. 能查询历史消息、切换旧会话并继续追问
- [ ] 5. 能在结果区看到六部分结构化输出
- [ ] 6. 能导出分析结果文件并重新下载
- [ ] 7. 能通过配置重载接口更新配置并即时生效
- [ ] 8. 能完成至少两个业务场景的完整演示

## 17. 协作约定

### 文档与代码同源

`docs/` 下的三份文档是设计与需求的**唯一事实源**，与代码放在同一仓库、同一批提交中维护。文档变更与代码变更应一起 review，避免文档滞后于实现。

文档之间的引用依赖章节号（如 `§7.2`、`§4.4`），调整章节结构时需同步更新引用它的其他文档。

### OpenSpec 工作流

仓库已初始化 OpenSpec（`schema: spec-driven`），用于管理变更提案与能力规格：

| 目录 | 用途 |
| --- | --- |
| `openspec/specs/` | 系统能力规格（当前为空，随实现逐步沉淀） |
| `openspec/changes/` | 变更提案（当前为空） |
| `openspec/changes/archive/` | 已完成变更的归档 |

`.agents/skills/` 下提供配套技能：`openspec-propose`（提出变更）、`openspec-apply-change`（实施）、`openspec-explore`（探索）、`openspec-update-change`（修订）、`openspec-sync-specs`（同步规格）、`openspec-archive-change`（归档）。

### 尚待约定

分支模型与提交信息格式尚未在文档中定义，建议在阶段 0 一并确定并补充到本节。

## 18. 交付物清单

| 交付物 | 来源阶段 |
| --- | --- |
| 可运行前端 | 阶段 9 |
| 可运行后端 | 阶段 0–8（接口全集） |
| 认证服务 | 阶段 2 |
| 数据库初始化脚本 | 阶段 1（系统库）+ 阶段 6（业务示例库） |
| 示例数据 | 阶段 6 |
| 接口说明 | 阶段 0 起的 OpenAPI 自动生成（`/docs`），可另存导出 |
| 至少两组完整分析示例 | 阶段 6（数据）+ 阶段 11（演示记录） |
| 验收截图与交付包 | 阶段 11 |

按源要求，交付文件夹按 `组名_姓名_项目_行业` 组织（如 `X组_姓名_经营归因_电商`）。