绝尘
998a2f243d
squash合并: - 意图识别层论证(8维度+10业界佐证) - 多主题上下文管理愿景+并存论证+补充论证(多轮agentic) - 架构设计文档物理分类(四子目录+INDEX+命名规范+引用同步+边界清晰化) - 前端架构技术债清单归档
454 lines
22 KiB
Markdown
454 lines
22 KiB
Markdown
# PERF-260619-01 查询效率优化方案
|
||
|
||
> **状态**：方案设计完成，待评审
|
||
> **日期**：2026-06-19
|
||
> **范围**：DevFlow 前后端数据查询链路
|
||
|
||
---
|
||
|
||
## 一、探索分析
|
||
|
||
### 1.1 问题全景
|
||
|
||
当前 DevFlow 的数据查询链路存在 **6 个核心问题**，分布在后端 SQL 层、前端 store 层、前端视图层三个层面。
|
||
|
||
### 1.2 问题清单
|
||
|
||
| # | 层 | 问题 | 严重度 | 代码位置 |
|
||
|---|---|---|---|---|
|
||
| P1 | 后端 SQL | `list_tasks` 全量查询后内存 `retain` 过滤 project_id | 中 | `commands/task.rs:32-37` |
|
||
| P2 | 前端视图 | `ProjectDetail.vue` 全量 `loadTasks()` 后 computed 过滤 | 中 | `ProjectDetail.vue onMounted` |
|
||
| P3 | 前端视图 | `TaskDetail.vue` 独立 `projectApi.list()` 拉全量项目仅解析单个项目名 | 低 | `TaskDetail.vue load()` |
|
||
| P4 | 前端视图 | `Dashboard.vue` 每次进入全量加载 projects+tasks+ideas | 低 | `Dashboard.vue loadAll()` |
|
||
| P5 | 前端 store | 无跨视图缓存/去重，路由切换重复 IPC | 中 | `stores/project.ts` 全局 |
|
||
| P6 | 后端 SQL | 无字段投影，列表场景返回完整 Record（含 description 大字段） | 低 | CRUD 层全局 |
|
||
|
||
### 1.3 问题详解
|
||
|
||
#### P1：`list_tasks` 内存过滤（中）
|
||
|
||
**现状**：
|
||
```rust
|
||
// commands/task.rs:32-37
|
||
pub async fn list_tasks(state, project_id: Option<String>) -> Result<Vec<TaskRecord>, String> {
|
||
let mut tasks = state.tasks.list_active().await.map_err(err_str)?; // SELECT * FROM tasks WHERE deleted_at IS NULL
|
||
if let Some(pid) = project_id {
|
||
tasks.retain(|t| t.project_id == pid); // 内存过滤
|
||
}
|
||
Ok(tasks)
|
||
}
|
||
```
|
||
|
||
**影响**：每次按项目筛选任务时，从 SQLite 拉取**全部未删除任务**（含 14 个字段含 description），然后在 Rust 端 `retain` 过滤。当前 6 个项目 ~15 个任务时影响极小，但随任务增长线性退化。
|
||
|
||
**注释中的判断**（task.rs:28）：*"任务量小，无需 SQL 下推，避免新增专用查询方法"* — 当前成立，但需提前规划。
|
||
|
||
#### P2：`ProjectDetail.vue` 全量 loadTasks（中）
|
||
|
||
**现状**：
|
||
```typescript
|
||
// ProjectDetail.vue onMounted
|
||
await store.loadProjects()
|
||
await store.loadTasks() // 无参 → 全量拉取所有项目的任务
|
||
// 然后 computed 前端过滤
|
||
const projectTasks = computed(() =>
|
||
store.tasks.filter(t => t.project_id === projectId.value)
|
||
)
|
||
```
|
||
|
||
**影响**：进入项目详情页时拉取**所有项目的全部任务**，仅为展示当前项目的任务。这与 `Tasks.vue` 的按项目筛选加载模式（B-260615-29 契约）不一致。
|
||
|
||
**根因**：`ProjectDetail.vue` 使用全局 `store.tasks` 单例 + computed 过滤，而非按 project_id 精确拉取。设计意图是"不覆盖全局 tasks 单例"（避免破坏 Tasks 视图的筛选状态），但代价是全量拉取。
|
||
|
||
#### P3：`TaskDetail.vue` 独立拉全量项目列表（低）
|
||
|
||
**现状**：
|
||
```typescript
|
||
// TaskDetail.vue load()
|
||
const [t, ps] = await Promise.all([
|
||
taskApi.get(taskId.value), // 拉单个任务 ✓
|
||
projectApi.list(), // 拉全部项目 ✗ 仅为解析 project_id → name
|
||
])
|
||
```
|
||
|
||
**影响**：TaskDetail 绕过 store 直接调 `projectApi.list()`，拉取全部项目（含 description 大字段），仅为从 `projects.find(p => p.id === task.project_id)` 解析一个项目名。
|
||
|
||
**根因**：TaskDetail 设计为"绕 store 独立入口"（有本地 `df-data-changed` 监听补偿），不依赖全局 store 的 projects 数组。
|
||
|
||
#### P4：`Dashboard.vue` 全量三实体加载（低）
|
||
|
||
**现状**：
|
||
```typescript
|
||
// Dashboard.vue loadAll()
|
||
await Promise.all([store.loadProjects(), store.loadTasks(), store.loadIdeas()])
|
||
```
|
||
|
||
**影响**：每次进入 Dashboard 全量拉取三个实体。Dashboard 只需要：
|
||
- 项目数 + 活跃任务数（统计）
|
||
- 项目列表（名称 + 状态 + updated_at）
|
||
- 灵感列表前 4 条（标题 + score + status）
|
||
|
||
但拉取了完整 Record（含 description / ai_analysis / scores 等大字段）。
|
||
|
||
**缓解因素**：store 是全局单例，如果用户先访问过其他页面（Tasks/Projects），数据已在 store 中。但 Dashboard 的 `loadAll` 无条件覆盖刷新。
|
||
|
||
#### P5：无跨视图缓存/去重（中）
|
||
|
||
**现状**：
|
||
- `Tasks.vue onMounted` → `loadProjects() + loadTasks()`
|
||
- `ProjectDetail.vue onMounted` → `loadProjects() + loadTasks()`
|
||
- `Dashboard.vue onMounted` → `loadProjects() + loadTasks() + loadIdeas()`
|
||
- `TaskDetail.vue load()` → `projectApi.list()`（绕 store）
|
||
|
||
**影响**：路由切换时（如 Tasks → ProjectDetail → Tasks），每次 onMounted 都重新发起 IPC 全量拉取。store 虽然是单例（数据在内存），但 `loadXxx` 方法无条件覆盖刷新，没有"数据未过期则跳过"的判断。
|
||
|
||
**根因**：store 的 load 方法无 dirty/timestamp 标记，无法判断"已有数据是否新鲜"。
|
||
|
||
#### P6：无字段投影（低）
|
||
|
||
**现状**：所有查询返回完整 Record。
|
||
|
||
- `ProjectRecord`：9 字段（含 description 可能很长）
|
||
- `TaskRecord`：14 字段（含 description + output_json 可能很长）
|
||
- `IdeaRecord`：13 字段（含 ai_analysis + scores + description）
|
||
|
||
列表场景（Tasks/Dashboard/Projects）只需要 id/name/status/priority 等少量字段，详情页才需要全字段。
|
||
|
||
**影响**：IPC 传输 + JSON 序列化开销。当前数据量小，影响不明显。
|
||
|
||
### 1.4 关键约束
|
||
|
||
| # | 约束 | 来源 | 影响 |
|
||
|---|---|---|---|
|
||
| C1 | `store.tasks` 必须反映 Tasks 视图当前筛选（activeProject），不能被无参 `loadTasks()` 覆盖为全量 | B-260615-29 契约 | P2 修复不能简单改为 `loadTasks(projectId)`，因为会覆盖全局 tasks 单例 |
|
||
| C2 | 后端 AI 工具执行后 emit `df-data-changed`，前端按 entity 刷新对应列表 | AR-11 事件机制 | 优化时需保留联动；缓存策略需响应此事件失效 |
|
||
| C3 | TaskDetail 绕 store 直接调 API，有本地 `df-data-changed` 监听补偿 | 设计决策 | P3 修复需考虑是否回归 store 或保持独立 |
|
||
| C4 | 任务 status 只能走 `advance_task_atomic` 状态机 | 状态机收口 | 不影响查询优化，但 update_task 白名单已移除 status |
|
||
| C5 | SQLite 本地存储，当前数据量小（~6 项目 ~15 任务） | 实际数据 | 短期性能影响极小，优化面向中长期数据增长 |
|
||
| C6 | CRUD 层（`impl_repo!` 宏）无 SELECT 列裁剪、无 LIMIT/OFFSET 支持 | 架构现状 | P6 需扩展宏或新增专用查询方法 |
|
||
|
||
---
|
||
|
||
## 二、方案设计
|
||
|
||
### 2.1 设计原则
|
||
|
||
1. **渐进式**：分阶段实施，每阶段独立可交付、可验证
|
||
2. **低风险**：优先做不改 API 契约的内部优化，外部行为不变
|
||
3. **数据量驱动**：当前数据量小，不做过度设计；预留扩展点但不提前实现
|
||
4. **不破坏 AR-11**：所有缓存/优化方案必须保留 `df-data-changed` 事件联动
|
||
|
||
### 2.2 分阶段实施计划
|
||
|
||
---
|
||
|
||
### Phase 1：SQL 下推 + 精确查询（低风险，高 ROI）
|
||
|
||
**目标**：消除后端全量查询 + 内存过滤，前端视图精确拉取所需数据。
|
||
|
||
**改动点**：
|
||
|
||
#### 1.1 TaskRepo 新增 `list_active_by_project`（后端）
|
||
|
||
```rust
|
||
// crates/df-storage/src/crud/task_repo.rs
|
||
impl TaskRepo {
|
||
/// 列出指定项目的未删除任务
|
||
pub async fn list_active_by_project(&self, project_id: &str) -> Result<Vec<TaskRecord>> {
|
||
let conn = self.conn.clone();
|
||
let project_id = project_id.to_owned();
|
||
tokio::task::spawn_blocking(move || {
|
||
let guard = conn.blocking_lock();
|
||
let mut stmt = guard
|
||
.prepare("SELECT id, project_id, title, description, status, priority, branch_name, assignee, workflow_def_id, base_branch, review_rounds, output_json, created_at, updated_at FROM tasks WHERE deleted_at IS NULL AND project_id = ?1 ORDER BY created_at DESC")
|
||
.map_err(storage_err)?;
|
||
let rows = stmt.query_map(params![project_id], |row| task_from_row(row)).map_err(storage_err)?;
|
||
// ...collect
|
||
}).await.map_err(storage_err)?
|
||
}
|
||
}
|
||
```
|
||
|
||
⚠️ **依赖注意（F-260619-01 idea_id）**：上方 SQL 硬编码 14 列，与 `list_active()` 完全重复。若 F-260619-01（TaskRecord 新增 `idea_id` 字段）先于本方案落地，`task_from_row` 会调 `row.get("idea_id")`，但 SQL 列表无此列 → rusqlite 报错。两案并行时须同步加列，或改用 `SELECT * FROM tasks WHERE ...`（rusqlite 允许结果集含 from_row 未消费的多余列）。
|
||
|
||
#### 1.2 `list_tasks` 命令层路由（后端）
|
||
|
||
```rust
|
||
// commands/task.rs
|
||
pub async fn list_tasks(state, project_id: Option<String>) -> Result<Vec<TaskRecord>, String> {
|
||
match project_id {
|
||
Some(pid) => state.tasks.list_active_by_project(&pid).await.map_err(err_str),
|
||
None => state.tasks.list_active().await.map_err(err_str),
|
||
}
|
||
}
|
||
```
|
||
|
||
**外部行为不变**：API 签名 + 返回类型一致，前端零改动。
|
||
|
||
#### 1.3 `ProjectDetail.vue` 按项目精确拉取（前端）
|
||
|
||
**问题**：不能直接 `store.loadTasks(projectId)`，因为会覆盖全局 tasks 单例（违反 C1）。
|
||
|
||
**方案**：ProjectDetail 不用全局 `store.tasks`，改为本地 ref + 精确拉取：
|
||
|
||
```typescript
|
||
// ProjectDetail.vue
|
||
const localTasks = ref<TaskRecord[]>([])
|
||
|
||
onMounted(async () => {
|
||
await store.loadProjects()
|
||
localTasks.value = await taskApi.list(projectId.value) // 精确拉取
|
||
// ...
|
||
})
|
||
```
|
||
|
||
**收益**：从全量拉取 → 仅拉取当前项目任务。
|
||
|
||
⚠️ **必须配套（评审升级）**：ProjectDetail 当前**没有** `df-data-changed` 监听——它靠全局 `store.tasks`（App.vue 的 `startDataChangedListener` 刷新 store → computed 自动响应）间接获得 AR-11 联动。改为本地 ref 后这条链路**断裂**。必须在 onMounted 中新增本地 `df-data-changed` 监听：
|
||
|
||
```typescript
|
||
// ProjectDetail.vue onMounted 新增（必须，非可选）
|
||
let _unlistenDataChanged: (() => void) | null = null
|
||
onMounted(async () => {
|
||
await store.loadProjects()
|
||
localTasks.value = await taskApi.list(projectId.value)
|
||
// AR-11 本地监听：entity=task 时按当前 projectId 精确刷新
|
||
_unlistenDataChanged = await listen<DfDataChangedPayload>('df-data-changed', (event) => {
|
||
if (event.payload.entity === 'task') {
|
||
taskApi.list(projectId.value).then(ts => { localTasks.value = ts })
|
||
}
|
||
})
|
||
})
|
||
onUnmounted(() => {
|
||
_unlistenDataChanged?.()
|
||
// ...existing unlisten cleanup
|
||
})
|
||
```
|
||
|
||
> **注意**：ProjectDetail 现有的 `store.startEventListener()` 是**工作流节点事件**监听（`workflowStore.startEventListener`），不是数据变更监听，两者不可混淆。
|
||
|
||
#### 1.4 `TaskDetail.vue` 改用 store 或 get_project（前端）
|
||
|
||
**方案 A**：改用 `store.projects` 复用全局缓存，不再独立 `projectApi.list()`：
|
||
|
||
```typescript
|
||
// TaskDetail.vue
|
||
const store = useProjectStore()
|
||
const projectName = computed(() =>
|
||
store.projects.find(p => p.id === task.value?.project_id)?.name ?? task.value?.project_id ?? '—'
|
||
)
|
||
// load() 只拉单个任务，不再拉全量项目
|
||
async function load() {
|
||
task.value = await taskApi.get(taskId.value)
|
||
}
|
||
```
|
||
|
||
⚠️ **前置条件（评审纠错）**：原方案声称"App.vue 根 onMounted 已有 projects 预加载"，经核验**不成立**——App.vue onMounted 只做 appSettings/migrate/theme/locale/Agentic 轮次恢复/AR-11 listener 启动，**未调用 `store.loadProjects()`**。当前 projects 加载分散在各视图 onMounted 中（Tasks/ProjectDetail/Dashboard 各自调）。
|
||
|
||
采用方案 A 必须二选一补齐前置：
|
||
- **A-1（推荐）**：App.vue onMounted 加 `await store.loadProjects()`（一行改动，全局受益，所有视图共享缓存）。
|
||
- **A-2（保守）**：TaskDetail load() 内加 `if (store.projects.length === 0) await store.loadProjects()` lazy 补偿，不依赖全局预加载。
|
||
|
||
**方案 B**：两步查询单个项目，替代全量 `projectApi.list()`：
|
||
|
||
```typescript
|
||
async function load() {
|
||
task.value = await taskApi.get(taskId.value)
|
||
// 拿到 task 后按 project_id 查单个项目
|
||
if (task.value?.project_id) {
|
||
const p = await projectApi.get(task.value.project_id)
|
||
projectName.value = p?.name ?? task.value.project_id
|
||
}
|
||
}
|
||
```
|
||
|
||
方案 B 无先后依赖问题（串行两步，先 task 后 project），IPC 开销为查 1 条 vs 查全量。**不依赖全局 store 状态**，保持 TaskDetail"绕 store 独立入口"的设计一致性。
|
||
|
||
**推荐**：
|
||
- 若同时实施 Phase 2 缓存 → **方案 A-1**（App.vue 预加载 + store 缓存，全链路最优）
|
||
- 若只实施 Phase 1 → **方案 B**（零全局依赖，改动最小，不引入 store 耦合）
|
||
|
||
---
|
||
|
||
### Phase 2：前端缓存 + 去重（中等风险，中 ROI）
|
||
|
||
**目标**：避免路由切换时的重复 IPC，引入脏标记/时间戳缓存。
|
||
|
||
**改动点**：
|
||
|
||
#### 2.1 store 加载方法增加新鲜度判断
|
||
|
||
⚠️ **评审补充 — tasks 缓存筛选维度冲突**：`loadTasks(projectId?)` 带筛选参数。若 Tasks 视图选了项目 A（`store.tasks` 只含项目 A），30s 内切到 Dashboard 调 `loadTasks()` 无参全量——缓存命中跳过，但 `store.tasks` 仍是项目 A 子集，Dashboard 的 `stats.activeTasks` 统计错误。
|
||
|
||
**解决方案**：tasks 缓存须记录筛选维度，筛选变化时强制刷新：
|
||
|
||
```typescript
|
||
// stores/project/state.ts 新增
|
||
export const state = reactive({
|
||
// ...existing...
|
||
_projectsLoadedAt: 0,
|
||
_tasksLoadedAt: 0,
|
||
_ideasLoadedAt: 0,
|
||
_tasksFilter: undefined as string | undefined, // 当前 tasks 缓存对应的筛选(undefined=全量)
|
||
})
|
||
|
||
// stores/project/projects.ts
|
||
const STALE_MS = 30_000 // 30s 内不重复拉取
|
||
|
||
async function loadProjects(force = false) {
|
||
if (!force && Date.now() - state._projectsLoadedAt < STALE_MS && state.projects.length > 0) {
|
||
return // 数据新鲜，跳过
|
||
}
|
||
state.loading = true
|
||
state.projects = await projectApi.list()
|
||
state._projectsLoadedAt = Date.now()
|
||
}
|
||
|
||
// stores/project/tasks.ts — 筛选维度 + TTL 双判断
|
||
async function loadTasks(projectId?: string, force = false) {
|
||
const filter = projectId // undefined=全量, string=按项目
|
||
// 筛选变化 → 强制刷新（防 Dashboard 拿到 Tasks 视图的子集）
|
||
const filterChanged = state._tasksFilter !== filter
|
||
if (!force && !filterChanged && Date.now() - state._tasksLoadedAt < STALE_MS) {
|
||
return // 数据新鲜 + 筛选一致，跳过
|
||
}
|
||
state.loading = true
|
||
state.tasks = await taskApi.list(filter)
|
||
state._tasksLoadedAt = Date.now()
|
||
state._tasksFilter = filter
|
||
}
|
||
```
|
||
|
||
#### 2.2 AR-11 事件联动失效缓存
|
||
|
||
⚠️ **评审补充 — AR-11 条件刷新与缓存交互**：当前 AR-11 listener 的 task 分支有 `_activeTaskProject !== undefined` 守卫（CR-260615-26）。若 Tasks 视图未挂载（undefined），entity=task 时不触发 load，缓存也不失效。用户之后进 Tasks 时 onMounted 调 `loadTasks`，若缓存未过期则命中跳过——拿到过期数据。
|
||
|
||
**解决方案**：AR-11 失效缓存与条件刷新分离——缓存时间戳无条件清零（下次 load 必拉新），load 调用仍守卫：
|
||
|
||
```typescript
|
||
// stores/project.ts startDataChangedListener
|
||
if (entity === 'project') {
|
||
state._projectsLoadedAt = 0 // 无条件失效缓存
|
||
void projectsStore.loadProjects(true) // force 刷新
|
||
} else if (entity === 'task') {
|
||
state._tasksLoadedAt = 0 // 无条件失效缓存（下次任意视图 loadTasks 必拉新）
|
||
if (_activeTaskProject !== undefined) {
|
||
void tasksStore.loadTasks(_activeTaskProject === 'all' ? undefined : _activeTaskProject)
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.3 Dashboard loadAll 利用缓存
|
||
|
||
⚠️ **评审补充 — Dashboard stats 对 tasks 全量的依赖**：Dashboard 的 `stats.activeTasks`（`project.ts:105`）从 `state.tasks` 算 `filter(t => t.status === 'in_progress').length`。若 `state.tasks` 是某项目子集（Tasks 视图留下的），统计偏小。Dashboard loadAll 须确保 tasks 全量：
|
||
|
||
```typescript
|
||
// Dashboard.vue
|
||
async function loadAll() {
|
||
await Promise.all([
|
||
store.loadProjects(), // 命中缓存则跳过
|
||
store.loadTasks(), // 无参=全量；筛选维度变化时强制刷新(2.1 逻辑保证)
|
||
store.loadIdeas(),
|
||
])
|
||
}
|
||
```
|
||
|
||
> Dashboard 调 `loadTasks()` 无参（filter=undefined），若 Tasks 视图留下的 filter 是某项目 id，`filterChanged=true` → 强制全量刷新，stats 正确。
|
||
|
||
**风险**：
|
||
- `df-data-changed` 必须可靠失效缓存（当前 AR-11 已覆盖 create/update/delete/restore/purge/bind_directory）
|
||
- 用户在外部修改 SQLite（如直接操作数据库）后缓存不新鲜 — 桌面应用场景概率极低
|
||
|
||
---
|
||
|
||
### Phase 3：字段投影（低优先级，远期）
|
||
|
||
**目标**：列表场景只返回需要的字段，减少 IPC 传输 + 序列化开销。
|
||
|
||
**现状评估**：当前数据量极小（6 项目 15 任务），description 字段平均 ~500 字节，全量传输 < 10KB。**Phase 3 在数据量达到百级之前不需要实施。**
|
||
|
||
**预留方案**（不实施，仅记录）：
|
||
|
||
```rust
|
||
// 方向：impl_repo! 宏扩展 columns 参数，或新增 list_summary 方法
|
||
pub async fn list_active_summary(&self) -> Result<Vec<ProjectSummary>> {
|
||
// SELECT id, name, status, created_at, updated_at FROM projects WHERE ...
|
||
}
|
||
```
|
||
|
||
前端新增 `ProjectSummary` / `TaskSummary` 类型，列表视图用 Summary，详情页用完整 Record。
|
||
|
||
**成本**：需新增 DTO 类型 + 前端类型同步 + 视图适配，复杂度较高。
|
||
|
||
---
|
||
|
||
### 2.3 优先级矩阵
|
||
|
||
| Phase | 问题覆盖 | 风险 | ROI | 建议时机 |
|
||
|-------|---------|------|-----|---------|
|
||
| Phase 1 | P1 + P2 + P3 | 低（不改 API 契约） | 高 | **立即实施** |
|
||
| Phase 2 | P4 + P5 | 中（缓存一致性） | 中 | Phase 1 验证后 |
|
||
| Phase 3 | P6 | 低（纯新增） | 低（当前数据量） | 数据量达百级时 |
|
||
|
||
### 2.4 涉及文件
|
||
|
||
| Phase | 文件 | 改动类型 |
|
||
|-------|------|---------|
|
||
| 1.1 | `crates/df-storage/src/crud/task_repo.rs` | 新增 `list_active_by_project` 方法 |
|
||
| 1.2 | `src-tauri/src/commands/task.rs` | `list_tasks` 路由分支 |
|
||
| 1.3 | `src/views/ProjectDetail.vue` | 改用本地 ref + 精确拉取 + **新增 df-data-changed 本地监听** |
|
||
| 1.4 | `src/views/TaskDetail.vue` | 方案 B：改用 `projectApi.get(id)` 单查；或方案 A-1/A-2 复用 store.projects |
|
||
| 1.4-A1 | `src/App.vue` | （方案 A-1）onMounted 新增 `store.loadProjects()` 预加载 |
|
||
| 2.1 | `src/stores/project/state.ts` | 新增时间戳 + `_tasksFilter` 字段 |
|
||
| 2.2 | `src/stores/project/projects.ts` | loadProjects 加新鲜度判断 |
|
||
| 2.3 | `src/stores/project/tasks.ts` | loadTasks 加筛选维度 + TTL 双判断 |
|
||
| 2.4 | `src/stores/project.ts` | AR-11 listener 无条件失效缓存 + 条件刷新分离 |
|
||
| 2.5 | `src/views/Dashboard.vue` | loadAll 利用缓存（筛选维度保证全量 tasks） |
|
||
|
||
### 2.5 验收标准
|
||
|
||
#### Phase 1
|
||
1. `list_tasks(Some(pid))` 走 SQL WHERE 下推，不再内存过滤
|
||
2. `ProjectDetail.vue` 不再全量 loadTasks，改为按 projectId 精确拉取
|
||
3. `ProjectDetail.vue` 新增本地 `df-data-changed` 监听，entity=task 时刷新 localTasks
|
||
4. `TaskDetail.vue` 不再独立 `projectApi.list()`（改用方案 B 单查或方案 A 复用 store）
|
||
5. B-260615-29 契约不破坏（store.tasks 仍反映 Tasks 视图筛选）
|
||
6. AR-11 事件联动正常（create/update/delete 后 ProjectDetail + Tasks 列表均刷新）
|
||
7. 若选方案 A-1：App.vue onMounted 成功预加载 projects，TaskDetail projectName 正确解析
|
||
8. 若 F-260619-01 已先行：`list_active_by_project` SQL 含 idea_id 列（或用 SELECT *）
|
||
9. `cargo check --workspace` EXIT 0 + `vue-tsc` EXIT 0
|
||
|
||
#### Phase 2
|
||
10. 30s 内路由切换不重复 IPC（store 缓存命中）
|
||
11. `df-data-changed` 事件正确失效缓存并刷新
|
||
12. Dashboard 统计数据准确（Tasks 视图筛选某项目后切 Dashboard，stats 不偏小）
|
||
13. Tasks 视图未挂载时 AR-11 entity=task 事件仍清零缓存（下次进 Tasks 拿新数据）
|
||
|
||
### 2.6 风险评估
|
||
|
||
| 风险 | 概率 | 影响 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| ProjectDetail 改本地 ref 后 AR-11 不刷新任务 | **高** | 中 | **必须配套**：onMounted 新增本地 `df-data-changed` 监听，entity=task 时重新 `taskApi.list(projectId)`（详见 1.3） |
|
||
| TaskDetail 改用 store.projects 时 projects 未加载 | 中 | 低 | App.vue onMounted **新增** `store.loadProjects()`（A-1），或 TaskDetail 内 lazy 补偿（A-2），或改用方案 B 完全规避 |
|
||
| Phase 2 缓存筛选维度冲突致 Dashboard stats 错误 | 中 | 中 | tasks 缓存记录 `_tasksFilter`，筛选变化时 `filterChanged=true` 强制刷新（详见 2.1） |
|
||
| Phase 2 AR-11 守卫 + 缓存致 Tasks 拿过期数据 | 中 | 低 | AR-11 无条件清零 `_tasksLoadedAt`（下次 load 必拉新），load 调用仍守卫（详见 2.2） |
|
||
| Phase 2 缓存导致用户看到过期数据 | 低 | 低 | 30s TTL 短 + AR-11 强制失效 + 手动刷新按钮兜底 |
|
||
| list_active_by_project SQL 列与 idea_id 不同步 | 中 | 中 | 两案并行时同步加列，或改用 `SELECT *`（详见 1.1） |
|
||
| list_active_by_project SQL 注入 | 极低 | 高 | 使用参数化查询 `params![project_id]`，不走 `query` 宏的 field 拼接 |
|
||
|
||
---
|
||
|
||
## 三、决策记录
|
||
|
||
### D1：Phase 1 先行，Phase 2 视需
|
||
|
||
**理由**：Phase 1 是纯内部优化（SQL 下推 + 精确拉取），不改 API 契约，风险极低，ROI 明确。Phase 2 引入缓存层有一致性风险，待 Phase 1 验证后再评估必要性。
|
||
|
||
### D2：不实施 Phase 3（字段投影）
|
||
|
||
**理由**：当前数据量极小（< 10KB 全量传输），字段投影需新增 DTO 类型 + 前端类型同步 + 视图适配，成本远高于收益。当任务数达到 ~200+ 或 description 平均长度 > 5KB 时再评估。
|
||
|
||
### D3：ProjectDetail 用本地 ref 而非改 store 契约
|
||
|
||
**理由**：store.tasks 全局单例 + B-260615-29 筛选契约是硬约束（C1）。改 store 支持"多任务列表"会引入复杂度（哪个视图的数据？切换时怎么办？）。ProjectDetail 用本地 ref + 精确拉取更简单清晰，且 AR-11 可通过本地监听补偿。
|