BossAi/pmdocs/2-task-bossai-uiux.md

# BossAi UIUX 重构任务拆分

- **版本**：v1.0
- **状态**：已交付（三阶段全部完成）
- **日期**：2026-08-30
- **关联**：PRD v2.0、ADR-002、CHG-20260830-001
- **执行前读取顺序**：run.md → 本文档 → CHG-20260830-001 → 1-prd-bossai.md → ADR-001/002

---

## 总览

三阶段，每阶段可独立交付。任务编号一旦分配不复用。

| 阶段 | 周期 | 核心交付 | TASK 范围 |
|---|---|---|---|
| 一 | 2 周 | 老板台 + 案卡看板 + 移动端底部 Tab | TASK-001 ~ TASK-012 |
| 二 | 2 周 | 快捷指令 + 我的团队 + 语音输入 | TASK-013 ~ TASK-020 |
| 三 | 2 周 | 风险雷达 + 决策日志 + ChatPanel 升级 | TASK-021 ~ TASK-028 |

**依赖关系**：
```
阶段一 ──→ 阶段二 ──→ 阶段三
TASK-003(DB) → TASK-004(API) → TASK-005~008(前端)
TASK-006(案卡前端) → TASK-013(快捷指令)
TASK-010(团队后端) → TASK-011(团队前端)
```

---

## 阶段一：老板台 + 案卡看板（P0，2 周）

### TASK-001：DB migration — 案卡表

- **描述**：新增 `matters` 表，扩展 `sessions` 表关联案卡
- **依赖**：无
- **验收**：
  - [x] `matters` 表创建，字段见 PRD §7.1
  - [x] `matters.code` 唯一索引
  - [x] `matters.user_id` 索引
  - [x] `sessions` 表新增 `matter_id` nullable 外键
  - [x] migration 脚本 + rollback 脚本
  - [x] seed 1 条测试案卡
- **测试**：migration up/down 各跑一次，schema 校验

### TASK-002：DB migration — 专家关系表

- **描述**：新增 `expert_relations` 表
- **依赖**：无
- **验收**：
  - [x] `expert_relations` 表创建，字段见 PRD §7.3
  - [x] `(user_id, expert_id)` 联合唯一索引
  - [x] migration + rollback
- **测试**：migration up/down 校验

### TASK-003：后端 — 案卡 CRUD API

- **描述**：实现案卡增删改查端点
- **依赖**：TASK-001
- **端点**：
  - `GET /matters?status=xxx` — 按状态分组返回案卡看板
  - `POST /matters` — 创建案卡（绑定 session_id）
  - `GET /matters/{id}` — 案卡详情（含会话消息摘要）
  - `PATCH /matters/{id}/status` — 更新状态
  - `POST /matters/{id}/close` — 闭环（可选填 execution_result）
- **验收**：
  - [x] 租户隔离（user_id 校验）
  - [x] 状态机校验（非法转换 422）
  - [x] code 自动生成 `MTR_{YYYYMMDD}_{seq}`
  - [x] OpenAPI 同步
  - [x] 单元测试覆盖 CRUD + 权限 + 状态机
- **测试**：pytest 覆盖正常/越权/非法状态转换

### TASK-004：后端 — 案卡状态自动流转

- **描述**：在现有 `ask-analyze` 流程中自动推进案卡状态
- **依赖**：TASK-003
- **验收**：
  - [x] 首次提问时自动创建案卡（status=new）
  - [x] AI 返回 questions 时 → status=asking_facts
  - [x] 事实提交后 → status=pending_confirm
  - [x] 用户确认分析 → status=analyzing
  - [x] 流式分析完成 → status=analyzing（保持）
  - [x] 问专家 → status=pending_expert
  - [x] 不破坏无案卡的旧会话（matter_id nullable）
- **测试**：集成测试覆盖全状态流转

### TASK-005：后端 — 老板台聚合 API

- **描述**：新增 `/dashboard/today` 聚合端点
- **依赖**：TASK-003
- **端点**：`GET /dashboard/today`
- **返回**：
  ```json
  {
    "greeting": "早上好，张总",
    "high_risks": [{ "matter_id": 1, "title": "...", "level": "red" }],
    "pending_confirm": [{ "matter_id": 2, "title": "...", "scene": "legal" }],
    "expert_replies": [{ "consultation_id": 1, "expert_name": "...", "snippet": "..." }],
    "health_score": { "legal": 80, "operation": 60, "compliance": 70 }
  }
  ```
- **验收**：
  - [x] 聚合高风险案卡（risk_level=red/orange）
  - [x] 聚合待确认案卡（status=pending_confirm）
  - [x] 聚合未读专家回复
  - [x] health_score 基于案卡风险分布计算
  - [x] 单元测试
- **测试**：pytest 覆盖空数据/正常数据

### TASK-006：前端 — 导航重构（共享 NavConfig）

- **描述**：合并 Sidebar/MobileNav 的重复常量为单一 `NavConfig`
- **依赖**：无
- **验收**：
  - [x] 新建 `src/lib/nav-config.ts`，导出 `USER_NAV`、`EXPERT_NAV`、`ADMIN_NAV`
  - [x] Sidebar 和 MobileNav 消费同一配置
  - [x] 补齐 MobileNav 缺失的"我的画像"入口
  - [x] 补齐 Header 标题映射（/history、/profile、/admin/*）
  - [x] 新增路由：/matters、/team、/decisions-log、/me
  - [x] lint + build 通过
- **测试**：手动验证导航一致性

### TASK-007：前端 — 老板台页面

- **描述**：重构 Dashboard 为"老板台"
- **依赖**：TASK-005、TASK-006
- **页面**：`src/pages/Dashboard.tsx`
- **验收**：
  - [x] 顶部问候语（按时段）
  - [x] 高风险提醒卡片（红/橙底，[立即处理]按钮）
  - [x] 待确认事项列表（[去确认]跳转案卡）
  - [x] 专家回复摘要（[查看回复]跳转）
  - [x] 经营健康度条形图（recharts）
  - [x] 加载/空态/错误状态覆盖
  - [x] 移动端适配
- **测试**：手动验证 + 响应式

### TASK-008：前端 — 事项看板页面

- **描述**：新增案卡看板
- **依赖**：TASK-003、TASK-006
- **页面**：`src/pages/Matters.tsx`
- **验收**：
  - [x] 看板分列：待补充事实 / 待确认 / 分析中 / 待专家 / 已闭环
  - [x] 案卡卡片：图标+标题+场景标签+时间+[继续/确认]按钮
  - [x] 点击案卡 → 跳转对应 ChatPanel 并恢复会话
  - [x] 移动端横向滚动看板列
  - [x] 案卡左滑归档（移动端手势）
  - [x] 加载/空态（引导完善画像）
- **测试**：手动验证 + 响应式

### TASK-009：前端 — 案卡组件抽取

- **描述**：抽取 `MatterCard` 公共组件
- **依赖**：TASK-008
- **组件**：`src/components/common/MatterCard.tsx`
- **验收**：
  - [x] props: matter / onClick / onArchive
  - [x] 状态色映射（new=blue, asking_facts=amber, pending_confirm=indigo, analyzing=purple, pending_expert=orange, closed=gray）
  - [x] 更新 `ui-components.md` 登记
- **测试**：组件渲染测试

### TASK-010：前端 — ChatPanel 接入案卡

- **描述**：ChatPanel 新建会话时创建案卡，状态随会话流转
- **依赖**：TASK-004、TASK-008
- **改动**：`src/components/common/ChatPanel.tsx`
- **验收**：
  - [x] 新建会话时调用 `POST /matters` 绑定
  - [x] 顶部显示案卡标题（可编辑）
  - [x] 状态流转时调用 `PATCH /matters/{id}/status`
  - [x] 分析完成后显示"闭环"按钮
  - [x] 闭环时弹窗可选填执行结果
  - [x] 不破坏无案卡的旧会话
- **测试**：集成测试覆盖创建→流转→闭环

### TASK-011：前端 — 移动端底部 Tab + FAB

- **描述**：移动端导航重构为底部 Tab + FAB
- **依赖**：TASK-006
- **组件**：`src/components/layout/BottomTab.tsx`、`src/components/layout/Fab.tsx`
- **验收**：
  - [x] 底部 4 Tab：老板台 / 事项 / 团队 / 我
  - [x] "我"页聚合 profile/history/settings/knowledge 入口
  - [x] FAB(+) 全局浮动，点击弹出快捷指令占位（阶段二实现）
  - [x] md 以上隐藏底部 Tab，显示 Sidebar
  - [x] 触控区 ≥ 44×44px
  - [x] 活跃 Tab 高亮
- **测试**：响应式手动验证

### TASK-012：阶段一构建验证

- **描述**：lint + typecheck + build + 手动冒烟
- **依赖**：TASK-001 ~ TASK-011
- **验收**：
  - [x] `npm run lint` 无 error
  - [x] `npm run build` 通过
  - [x] 后端 pytest 通过
  - [x] 手动冒烟：老板台→案卡→ChatPanel→闭环 全流程
  - [x] 移动端底部 Tab 全功能可达
  - [x] 更新 `run.md`（若有新命令）
  - [x] 更新 `ui-components.md`

---

## 阶段二：快捷指令 + 我的团队（P1，2 周）

### TASK-013：后端 — 快捷指令 API

- **描述**：新增 `/quick-commands` 画像驱动指令生成
- **依赖**：无
- **端点**：`GET /quick-commands`
- **返回**：
  ```json
  {
    "legal": [{ "id": "contract_review", "label": "查合同风险", "template": "我有一份合同，帮我看看..." }],
    "decision": [{ "id": "expand", "label": "该不该扩张", "template": "我在考虑开新店..." }],
    "life": [...]
  }
  ```
- **验收**：
  - [x] 基于画像行业/规模生成个性化指令
  - [x] 画像不全时返回通用指令 + 缺口提示
  - [x] 指令模板预填问题，留关键细节占位符
  - [x] 单元测试
- **测试**：pytest 覆盖画像完整/缺失

### TASK-014：前端 — 快捷指令面板

- **描述**：FAB 点击弹出底部抽屉
- **依赖**：TASK-011、TASK-013
- **组件**：`src/components/common/QuickCommandPanel.tsx`
- **验收**：
  - [x] 底部抽屉动画（300ms slide-up）
  - [x] 分组展示：法务/经营/生活
  - [x] 指令网格卡片（图标+标签）
  - [x] 点击指令 → 预填模板到 ChatPanel 输入框 → 跳转对应页面
  - [x] 底部语音输入按钮 + 文字输入框
  - [x] 画像不全时显示"完善画像解锁更精准建议"
  - [x] 抽屉可下拉关闭
- **测试**：手动验证 + 响应式

### TASK-015：前端 — 语音输入

- **描述**：快捷指令面板支持语音输入
- **依赖**：TASK-014
- **验收**：
  - [x] 使用 Web Speech API（webkitSpeechRecognition）
  - [x] 中文识别（lang='zh-CN'）
  - [x] 识别结果实时填入输入框
  - [x] Safari/不支持浏览器隐藏语音按钮（降级）
  - [x] 识别中状态动画
- **测试**：Chrome 验证，Safari 降级验证

### TASK-016：后端 — 我的团队 API

- **描述**：新增 `/team` 端点，聚合专家关系
- **依赖**：TASK-002
- **端点**：`GET /team`
- **返回**：
  ```json
  [{
    "expert_id": 1, "name": "王律师", "avatar": "...", "categories": ["劳动法"],
    "online": true, "consultation_count": 3, "last_consulted_at": "...",
    "last_topic": "用工纠纷"
  }]
  ```
- **验收**：
  - [x] 自动从 consultation 记录聚合关系
  - [x] 首次咨询自动创建 expert_relations 记录
  - [x] 后续咨询更新 count/last_consulted_at
  - [x] 单元测试
- **测试**：pytest 覆盖聚合逻辑

### TASK-017：前端 — 我的团队页面

- **描述**：重构 Experts 为"我的团队"
- **依赖**：TASK-016、TASK-006
- **页面**：`src/pages/Team.tsx`（替代/兼容 Experts）
- **验收**：
  - [x] "我的团队"列表：头像+姓名+擅长+在线状态+关系深度
  - [x] 每人卡片：[发消息] [新咨询] 按钮
  - [x] [新咨询] → 跳转 ChatPanel，自动带上历史上下文摘要
  - [x] 底部"找新专家"入口 → 跳转完整专家库
  - [x] 空态："你还没有咨询过专家，去逛逛专家库"
  - [x] 保留原有 Experts 页面作为完整专家库（/experts）
- **测试**：手动验证

### TASK-018：前端 — 团队一键咨询上下文

- **描述**：从"我的团队"发起咨询时自动带上历史
- **依赖**：TASK-017
- **验收**：
  - [x] 跳转 ChatPanel 时传入 `expertId` + `lastTopic`
  - [x] ChatPanel 顶部显示"咨询王律师·上次话题：用工纠纷"
  - [x] 首条消息自动带上"基于上次咨询..."上下文
  - [x] 问专家弹窗默认选中该专家
- **测试**：手动验证上下文传递

### TASK-019：前端 — 移动端"我"页面

- **描述**：新增移动端"我"聚合页
- **依赖**：TASK-011
- **页面**：`src/pages/Me.tsx`
- **验收**：
  - [x] 头像+姓名+行业规模标签
  - [x] 入口列表：我的画像 / 对话历史 / 知识库 / 设置
  - [x] 仅移动端底部 Tab 可达，桌面端无此路由
  - [x] 桌面端这些入口仍在 Sidebar
- **测试**：响应式验证

### TASK-020：阶段二构建验证

- **描述**：lint + typecheck + build + 手动冒烟
- **依赖**：TASK-013 ~ TASK-019
- **验收**：
  - [x] lint/build 通过
  - [x] 后端 pytest 通过
  - [x] 冒烟：FAB→快捷指令→预填→提问→问专家→我的团队
  - [x] 语音输入 Chrome 验证
  - [x] 更新 `ui-components.md`

---

## 阶段三：风险雷达 + 决策日志 + ChatPanel 升级（P1-P2，2 周）

### TASK-021：DB migration — 风险推送表

- **描述**：新增 `risk_alerts` 表
- **依赖**：无
- **验收**：
  - [x] `risk_alerts` 表创建，字段见 PRD §7.2
  - [x] `(user_id, read_at)` 索引
  - [x] migration + rollback
- **测试**：migration 校验

### TASK-022：后端 — 风险雷达扫描任务

- **描述**：定时扫描知识库新规 + 画像匹配，生成推送
- **依赖**：TASK-021
- **验收**：
  - [x] 定时任务（APScheduler 或简单轮询），每日 1 次
  - [x] 扫描知识库近 7 天新增文档，匹配用户画像行业
  - [x] 生成 risk_alerts 记录（level=blue/orange）
  - [x] 文档上传后触发即时扫描（level=red/orange/blue）
  - [x] 单元测试
- **测试**：pytest mock 定时任务

### TASK-023：后端 — 风险推送 API

- **描述**：风险推送查询与标记已读
- **依赖**：TASK-022
- **端点**：
  - `GET /risk-alerts?unread=true` — 未读推送列表
  - `POST /risk-alerts/{id}/read` — 标记已读
- **验收**：
  - [x] 租户隔离
  - [x] unread 过滤
  - [x] 单元测试
- **测试**：pytest

### TASK-024：前端 — 老板台风险推送卡片

- **描述**：老板台集成风险推送
- **依赖**：TASK-005、TASK-023
- **改动**：`src/pages/Dashboard.tsx`
- **验收**：
  - [x] 高风险推送置顶（红/橙底）
  - [x] [立即处理] → 跳转相关案卡或知识库文档
  - [x] [稍后] → 标记已读
  - [x] Header 铃铛角标显示未读数
  - [x] 点击铃铛 → 下拉推送列表
- **测试**：手动验证

### TASK-025：前端 — 决策日志页面

- **描述**：新增决策日志
- **依赖**：TASK-003
- **页面**：`src/pages/DecisionsLog.tsx`
- **验收**：
  - [x] 按月分组展示闭环案卡
  - [x] 每条：日期+场景图标+标题+决定摘要+执行情况标记
  - [x] [标记结果] → 弹窗选 顺利/受阻/未执行 + 备注
  - [x] 月度统计条：本月决策数、已执行率
  - [x] 空态："你还没有闭环的决策，去处理进行中的事项"
- **测试**：手动验证

### TASK-026：前端 — ChatPanel 风险卡置顶

- **描述**：风险卡从消息流提取为置顶固定卡片
- **依赖**：TASK-010
- **改动**：`src/components/common/ChatPanel.tsx`、`RiskCardView.tsx`
- **验收**：
  - [x] 分析完成后风险卡固定在对话区顶部
  - [x] 可折叠/展开
  - [x] [分享] 按钮 → 复制链接或文本
  - [x] [导出] 按钮 → 下载 PDF/Markdown
  - [x] 消息流中保留风险卡引用锚点
- **测试**：手动验证

### TASK-027：前端 — 起诉状三步向导

- **描述**：要素式起诉状改为三步向导
- **依赖**：TASK-010
- **组件**：`src/components/common/FilingWizard.tsx`
- **验收**：
  - [x] 步骤1 预览：展示模板+已填要素
  - [x] 步骤2 编辑：可修改要素值
  - [x] 步骤3 导出：下载 / 发送给专家 / 复制
  - [x] 步骤指示器
  - [x] 替换当前一键生成按钮
  - [x] 更新 `ui-components.md`
- **测试**：手动验证

### TASK-028：阶段三构建验证 + 三端视觉对齐

- **描述**：lint + typecheck + build + 三端视觉对齐
- **依赖**：TASK-021 ~ TASK-027
- **验收**：
  - [x] lint/build 通过
  - [x] 后端 pytest 通过
  - [x] C 端主色 indigo-600 落地
  - [x] Admin Header 深色 + amber-400 + ADMIN 徽章
  - [x] 冒烟：风险推送→老板台→决策日志→起诉状向导
  - [x] 更新 `run.md`（定时任务配置）
  - [x] 更新 `ui-components.md`
  - [x] 更新 `CHANGELOG.md`

---

## 执行规则

1. **按阶段顺序执行**，阶段内任务可并行（后端/前端分离）
2. **每个 TASK 完成后**：
   - 标记 `[x]`
   - 更新 `ui-components.md`（若涉及组件）
   - 更新 `run.md`（若涉及新命令/配置）
3. **DB 变更**必须先 migration 再 API 再前端
4. **不删无关代码**，旧页面保留为兼容入口直到新页面验证通过
5. **commit 前缀**：`feat(uiux)` / `feat(api)` / `feat(db)` / `fix` / `refactor`
6. **PR ≤ 400 行**，单一职责

---

## 验收检查清单（整体）

### 阶段一完成标准
- [x] 老板台展示今日要事
- [x] 案卡看板全状态流转
- [x] ChatPanel 接入案卡
- [x] 移动端底部 Tab 可用
- [x] build + pytest 通过

### 阶段二完成标准
- [x] FAB 快捷指令基于画像
- [x] 语音输入 Chrome 可用
- [x] 我的团队显示关系
- [x] 一键咨询带上上下文
- [x] build + pytest 通过

### 阶段三完成标准
- [x] 风险推送出现在老板台
- [x] 决策日志可标记结果
- [x] 风险卡置顶可分享
- [x] 起诉状三步向导
- [x] 三端视觉对齐
- [x] build + pytest 通过
- [x] CHANGELOG 同步