docs: add two-step import+card generation design spec
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Saberlve
parent
b955d382e3
commit
5899e44791
180
docs/superpowers/specs/2026-04-15-import-card-two-step-design.md
Normal file
180
docs/superpowers/specs/2026-04-15-import-card-two-step-design.md
Normal file
@ -0,0 +1,180 @@
|
||||
# Import + Card Generation Two-Step Design
|
||||
|
||||
## Status
|
||||
|
||||
Draft — not yet approved.
|
||||
|
||||
## Overview
|
||||
|
||||
Split the current "import文献 + immediately generate cards" flow into two distinct steps:
|
||||
|
||||
1. **Import** — items are registered to a project, but cards are NOT generated yet. The system checks a global registry for existing cards.
|
||||
2. **Manual batch generate** — user manually selects pending items and triggers card generation. Same item across different projects reuses existing cards (hash-based deduplication).
|
||||
|
||||
## Data Model
|
||||
|
||||
### Global Registry (existing, unchanged)
|
||||
|
||||
- `library/index/items.json` — global item metadata registry, keyed by `item_key`
|
||||
- `library/index/cards.json` — global card index, keyed by `item_key`
|
||||
|
||||
### Project Registry (existing, extended)
|
||||
|
||||
- `projects/{project_id}/selected-items.json` — list of `item_key`s associated with the project
|
||||
- `projects/{project_id}/pending-items.json` — **removed** — pending status is computed dynamically as `selected_items` minus keys present in `cards.json`. No separate tracking file needed.
|
||||
|
||||
### Import State
|
||||
|
||||
For each item in a project, one of two states:
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| `pending` | item is imported but no card exists in `cards.json` |
|
||||
| `done` | card exists in `cards.json` for this item_key |
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### `GET /api/projects/{project_id}/import-state`
|
||||
|
||||
Returns the import state of all items in a project.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": "proj-123",
|
||||
"items": [
|
||||
{
|
||||
"item_key": "ABCD1234",
|
||||
"title": "Paper Title",
|
||||
"creators": ["Author A", "Author B"],
|
||||
"year": 2024,
|
||||
"item_type": "journalArticle",
|
||||
"card_status": "done"
|
||||
},
|
||||
{
|
||||
"item_key": "EFGH5678",
|
||||
"title": "Another Paper",
|
||||
"creators": ["Author C"],
|
||||
"year": 2023,
|
||||
"item_type": "conferencePaper",
|
||||
"card_status": "pending"
|
||||
}
|
||||
],
|
||||
"pending_count": 1,
|
||||
"done_count": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Logic:** Iterate `selected-items.json`, for each `item_key` check if it exists in `cards.json`. If yes → `done`, else → `pending`.
|
||||
|
||||
### `POST /api/projects/{project_id}/cards/generate`
|
||||
|
||||
Receives a list of item_keys to generate cards for. Generates cards one by one, updates `cards.json`.
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"item_keys": ["EFGH5678", "IJKL9012"]
|
||||
}
|
||||
```
|
||||
|
||||
**Response (streaming or incremental):**
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": "proj-123",
|
||||
"generated": ["EFGH5678"],
|
||||
"failed": [],
|
||||
"items": [
|
||||
{ "item_key": "EFGH5678", "title": "...", "creators": [...], "card_status": "done" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Logic:**
|
||||
|
||||
1. For each `item_key` in `item_keys`:
|
||||
- Read item metadata from `items.json` (or from Zotero reader if not yet in items.json)
|
||||
- Call `CardBuilder.build_or_update()` which computes `source_hash` and either creates or updates the card
|
||||
- Send incremental progress event (SSE or via callback)
|
||||
2. After all complete, return the updated item states.
|
||||
|
||||
### `POST /api/projects/{project_id}/imports/item-keys` (existing, extended)
|
||||
|
||||
When items are imported, they are added to `selected-items.json`. Cards are NOT generated immediately.
|
||||
|
||||
## Frontend: Import Window Layout
|
||||
|
||||
### Two-Column Layout
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ [title bar: 导入文献] [_] [□] [×] │
|
||||
├───────────────────────┬─────────────────────────────────┤
|
||||
│ LEFT (40%) │ RIGHT (60%) │
|
||||
│ ┌─────────────────┐ │ ┌───────────────────────────┐ │
|
||||
│ │ Search... │ │ │ Title: ... │ │
|
||||
│ └─────────────────┘ │ │ Authors: ... │ │
|
||||
│ ┌─────────────────┐ │ │ Year: ... │ │
|
||||
│ │ □ Paper A [✓] │ │ │ Type: journalArticle │ │
|
||||
│ │ ☑ Paper B │ │ │ Abstract: ... │ │
|
||||
│ │ ✓ Paper C │ │ │ Tags: tag1, tag2 │ │
|
||||
│ │ □ Paper D │ │ └───────────────────────────┘ │
|
||||
│ └─────────────────┘ │ │
|
||||
│ Pending (2) Done (1) │ │
|
||||
├───────────────────────┴─────────────────────────────────┤
|
||||
│ [生成选中卡片 (2)] │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Visual States
|
||||
|
||||
- **pending items** — light background, checkbox visible, unchecked by default
|
||||
- **done items** — green tint / checkmark, no checkbox, not selectable for generation
|
||||
- **selected pending** — highlighted border, checkbox checked
|
||||
- **generating** — spinner icon, row slightly dimmed
|
||||
|
||||
### Interactions
|
||||
|
||||
1. Click item in left list → right panel shows metadata preview
|
||||
2. Click checkbox on pending item → toggles selection
|
||||
3. "Select All Pending" link at top of list
|
||||
4. Click "生成选中卡片 (N)" button → triggers `POST .../cards/generate`
|
||||
5. During generation: button becomes progress bar "生成 X/Y"，completed items turn done in real time
|
||||
|
||||
### Card Status Legend
|
||||
|
||||
Shown at bottom of left panel:
|
||||
|
||||
```
|
||||
Pending (N) ● Done (N) ✓
|
||||
```
|
||||
|
||||
## Deduplication Logic
|
||||
|
||||
`CardBuilder.build_or_update()` computes `source_hash` from:
|
||||
|
||||
```
|
||||
{
|
||||
item_key, title, creators, year, item_type,
|
||||
abstract, tags, collection_paths, notes, attachment_texts
|
||||
}
|
||||
```
|
||||
|
||||
- If `cards.json` already has an entry for this `item_key` with the same `source_hash` → skip LLM call, card already up to date
|
||||
- If hash differs → regenerate (overwrite)
|
||||
- This means the same `item_key` imported into multiple projects will reuse the same card if the source hasn't changed
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If a single item fails to generate (LLM error, missing data), mark it as failed and continue with others
|
||||
- Failed items shown with error icon, can be retried individually or as batch
|
||||
- Return `failed` array in response with error reasons
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Streaming/SSE for real-time progress (use simple polling or single request for now)
|
||||
- Background job queue
|
||||
- Version history for regenerated cards
|
||||
Loading…
Reference in New Issue
Block a user