feat: 功能优化

2025-12-15 23:33:02 +08:00
parent 7f7551f74f
commit 870ea10351
36 changed files with 3289 additions and 40 deletions
--- a/openspec/AGENTS.md
+++ b/openspec/AGENTS.md
@@ -0,0 +1,456 @@
+# OpenSpec Instructions
+
+Instructions for AI coding assistants using OpenSpec for spec-driven development.
+
+## TL;DR Quick Checklist
+
+- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
+- Decide scope: new capability vs modify existing capability
+- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
+- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
+- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
+- Validate: `openspec validate [change-id] --strict` and fix issues
+- Request approval: Do not start implementation until proposal is approved
+
+## Three-Stage Workflow
+
+### Stage 1: Creating Changes
+Create proposal when you need to:
+- Add features or functionality
+- Make breaking changes (API, schema)
+- Change architecture or patterns  
+- Optimize performance (changes behavior)
+- Update security patterns
+
+Triggers (examples):
+- "Help me create a change proposal"
+- "Help me plan a change"
+- "Help me create a proposal"
+- "I want to create a spec proposal"
+- "I want to create a spec"
+
+Loose matching guidance:
+- Contains one of: `proposal`, `change`, `spec`
+- With one of: `create`, `plan`, `make`, `start`, `help`
+
+Skip proposal for:
+- Bug fixes (restore intended behavior)
+- Typos, formatting, comments
+- Dependency updates (non-breaking)
+- Configuration changes
+- Tests for existing behavior
+
+**Workflow**
+1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
+3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
+4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
+
+### Stage 2: Implementing Changes
+Track these steps as TODOs and complete them one by one.
+1. **Read proposal.md** - Understand what's being built
+2. **Read design.md** (if exists) - Review technical decisions
+3. **Read tasks.md** - Get implementation checklist
+4. **Implement tasks sequentially** - Complete in order
+5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
+6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
+7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
+
+### Stage 3: Archiving Changes
+After deployment, create separate PR to:
+- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
+- Update `specs/` if capabilities changed
+- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
+- Run `openspec validate --strict` to confirm the archived change passes checks
+
+## Before Any Task
+
+**Context Checklist:**
+- [ ] Read relevant specs in `specs/[capability]/spec.md`
+- [ ] Check pending changes in `changes/` for conflicts
+- [ ] Read `openspec/project.md` for conventions
+- [ ] Run `openspec list` to see active changes
+- [ ] Run `openspec list --specs` to see existing capabilities
+
+**Before Creating Specs:**
+- Always check if capability already exists
+- Prefer modifying existing specs over creating duplicates
+- Use `openspec show [spec]` to review current state
+- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
+
+### Search Guidance
+- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
+- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
+- Show details:
+  - Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
+  - Change: `openspec show <change-id> --json --deltas-only`
+- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
+
+## Quick Start
+
+### CLI Commands
+
+```bash
+# Essential commands
+openspec list                  # List active changes
+openspec list --specs          # List specifications
+openspec show [item]           # Display change or spec
+openspec validate [item]       # Validate changes or specs
+openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)
+
+# Project management
+openspec init [path]           # Initialize OpenSpec
+openspec update [path]         # Update instruction files
+
+# Interactive mode
+openspec show                  # Prompts for selection
+openspec validate              # Bulk validation mode
+
+# Debugging
+openspec show [change] --json --deltas-only
+openspec validate [change] --strict
+```
+
+### Command Flags
+
+- `--json` - Machine-readable output
+- `--type change|spec` - Disambiguate items
+- `--strict` - Comprehensive validation
+- `--no-interactive` - Disable prompts
+- `--skip-specs` - Archive without spec updates
+- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
+
+## Directory Structure
+
+```
+openspec/
+├── project.md              # Project conventions
+├── specs/                  # Current truth - what IS built
+│   └── [capability]/       # Single focused capability
+│       ├── spec.md         # Requirements and scenarios
+│       └── design.md       # Technical patterns
+├── changes/                # Proposals - what SHOULD change
+│   ├── [change-name]/
+│   │   ├── proposal.md     # Why, what, impact
+│   │   ├── tasks.md        # Implementation checklist
+│   │   ├── design.md       # Technical decisions (optional; see criteria)
+│   │   └── specs/          # Delta changes
+│   │       └── [capability]/
+│   │           └── spec.md # ADDED/MODIFIED/REMOVED
+│   └── archive/            # Completed changes
+```
+
+## Creating Change Proposals
+
+### Decision Tree
+
+```
+New request?
+├─ Bug fix restoring spec behavior? → Fix directly
+├─ Typo/format/comment? → Fix directly  
+├─ New feature/capability? → Create proposal
+├─ Breaking change? → Create proposal
+├─ Architecture change? → Create proposal
+└─ Unclear? → Create proposal (safer)
+```
+
+### Proposal Structure
+
+1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
+
+2. **Write proposal.md:**
+```markdown
+# Change: [Brief description of change]
+
+## Why
+[1-2 sentences on problem/opportunity]
+
+## What Changes
+- [Bullet list of changes]
+- [Mark breaking changes with **BREAKING**]
+
+## Impact
+- Affected specs: [list capabilities]
+- Affected code: [key files/systems]
+```
+
+3. **Create spec deltas:** `specs/[capability]/spec.md`
+```markdown
+## ADDED Requirements
+### Requirement: New Feature
+The system SHALL provide...
+
+#### Scenario: Success case
+- **WHEN** user performs action
+- **THEN** expected result
+
+## MODIFIED Requirements
+### Requirement: Existing Feature
+[Complete modified requirement]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason**: [Why removing]
+**Migration**: [How to handle]
+```
+If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
+
+4. **Create tasks.md:**
+```markdown
+## 1. Implementation
+- [ ] 1.1 Create database schema
+- [ ] 1.2 Implement API endpoint
+- [ ] 1.3 Add frontend component
+- [ ] 1.4 Write tests
+```
+
+5. **Create design.md when needed:**
+Create `design.md` if any of the following apply; otherwise omit it:
+- Cross-cutting change (multiple services/modules) or a new architectural pattern
+- New external dependency or significant data model changes
+- Security, performance, or migration complexity
+- Ambiguity that benefits from technical decisions before coding
+
+Minimal `design.md` skeleton:
+```markdown
+## Context
+[Background, constraints, stakeholders]
+
+## Goals / Non-Goals
+- Goals: [...]
+- Non-Goals: [...]
+
+## Decisions
+- Decision: [What and why]
+- Alternatives considered: [Options + rationale]
+
+## Risks / Trade-offs
+- [Risk] → Mitigation
+
+## Migration Plan
+[Steps, rollback]
+
+## Open Questions
+- [...]
+```
+
+## Spec File Format
+
+### Critical: Scenario Formatting
+
+**CORRECT** (use #### headers):
+```markdown
+#### Scenario: User login success
+- **WHEN** valid credentials provided
+- **THEN** return JWT token
+```
+
+**WRONG** (don't use bullets or bold):
+```markdown
+- **Scenario: User login**  ❌
+**Scenario**: User login     ❌
+### Scenario: User login      ❌
+```
+
+Every requirement MUST have at least one scenario.
+
+### Requirement Wording
+- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
+
+### Delta Operations
+
+- `## ADDED Requirements` - New capabilities
+- `## MODIFIED Requirements` - Changed behavior
+- `## REMOVED Requirements` - Deprecated features
+- `## RENAMED Requirements` - Name changes
+
+Headers matched with `trim(header)` - whitespace ignored.
+
+#### When to use ADDED vs MODIFIED
+- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
+- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
+- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
+
+Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
+
+Authoring a MODIFIED requirement correctly:
+1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
+2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
+3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
+4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
+
+Example for RENAMED:
+```markdown
+## RENAMED Requirements
+- FROM: `### Requirement: Login`
+- TO: `### Requirement: User Authentication`
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**"Change must have at least one delta"**
+- Check `changes/[name]/specs/` exists with .md files
+- Verify files have operation prefixes (## ADDED Requirements)
+
+**"Requirement must have at least one scenario"**
+- Check scenarios use `#### Scenario:` format (4 hashtags)
+- Don't use bullet points or bold for scenario headers
+
+**Silent scenario parsing failures**
+- Exact format required: `#### Scenario: Name`
+- Debug with: `openspec show [change] --json --deltas-only`
+
+### Validation Tips
+
+```bash
+# Always use strict mode for comprehensive checks
+openspec validate [change] --strict
+
+# Debug delta parsing
+openspec show [change] --json | jq '.deltas'
+
+# Check specific requirement
+openspec show [spec] --json -r 1
+```
+
+## Happy Path Script
+
+```bash
+# 1) Explore current state
+openspec spec list --long
+openspec list
+# Optional full-text search:
+# rg -n "Requirement:|Scenario:" openspec/specs
+# rg -n "^#|Requirement:" openspec/changes
+
+# 2) Choose change id and scaffold
+CHANGE=add-two-factor-auth
+mkdir -p openspec/changes/$CHANGE/{specs/auth}
+printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
+printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
+
+# 3) Add deltas (example)
+cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+Users MUST provide a second factor during login.
+
+#### Scenario: OTP required
+- **WHEN** valid credentials are provided
+- **THEN** an OTP challenge is required
+EOF
+
+# 4) Validate
+openspec validate $CHANGE --strict
+```
+
+## Multi-Capability Example
+
+```
+openspec/changes/add-2fa-notify/
+├── proposal.md
+├── tasks.md
+└── specs/
+    ├── auth/
+    │   └── spec.md   # ADDED: Two-Factor Authentication
+    └── notifications/
+        └── spec.md   # ADDED: OTP email notification
+```
+
+auth/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+...
+```
+
+notifications/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: OTP Email Notification
+...
+```
+
+## Best Practices
+
+### Simplicity First
+- Default to <100 lines of new code
+- Single-file implementations until proven insufficient
+- Avoid frameworks without clear justification
+- Choose boring, proven patterns
+
+### Complexity Triggers
+Only add complexity with:
+- Performance data showing current solution too slow
+- Concrete scale requirements (>1000 users, >100MB data)
+- Multiple proven use cases requiring abstraction
+
+### Clear References
+- Use `file.ts:42` format for code locations
+- Reference specs as `specs/auth/spec.md`
+- Link related changes and PRs
+
+### Capability Naming
+- Use verb-noun: `user-auth`, `payment-capture`
+- Single purpose per capability
+- 10-minute understandability rule
+- Split if description needs "AND"
+
+### Change ID Naming
+- Use kebab-case, short and descriptive: `add-two-factor-auth`
+- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
+- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
+
+## Tool Selection Guide
+
+| Task | Tool | Why |
+|------|------|-----|
+| Find files by pattern | Glob | Fast pattern matching |
+| Search code content | Grep | Optimized regex search |
+| Read specific files | Read | Direct file access |
+| Explore unknown scope | Task | Multi-step investigation |
+
+## Error Recovery
+
+### Change Conflicts
+1. Run `openspec list` to see active changes
+2. Check for overlapping specs
+3. Coordinate with change owners
+4. Consider combining proposals
+
+### Validation Failures
+1. Run with `--strict` flag
+2. Check JSON output for details
+3. Verify spec file format
+4. Ensure scenarios properly formatted
+
+### Missing Context
+1. Read project.md first
+2. Check related specs
+3. Review recent archives
+4. Ask for clarification
+
+## Quick Reference
+
+### Stage Indicators
+- `changes/` - Proposed, not yet built
+- `specs/` - Built and deployed
+- `archive/` - Completed changes
+
+### File Purposes
+- `proposal.md` - Why and what
+- `tasks.md` - Implementation steps
+- `design.md` - Technical decisions
+- `spec.md` - Requirements and behavior
+
+### CLI Essentials
+```bash
+openspec list              # What's in progress?
+openspec show [item]       # View details
+openspec validate --strict # Is it correct?
+openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
+```
+
+Remember: Specs are truth. Changes are proposals. Keep them in sync.
--- a/openspec/changes/add-ice-916-crop/design.md
+++ b/openspec/changes/add-ice-916-crop/design.md
@@ -0,0 +1,77 @@
+## Context
+
+混剪功能需要将多种比例的素材统一输出为 9:16 竖屏视频（720x1280）。
+阿里云 ICE 支持视频裁剪和缩放，需要在 Timeline 中配置正确的参数。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 支持横屏 (16:9) 素材自动裁剪为竖屏 (9:16)
+- 支持多种裁剪模式（居中、智能、填充）
+- 保持视频质量，避免过度拉伸
+
+**Non-Goals:**
+- 不实现自定义裁剪区域选择
+- 不实现实时预览
+
+## Decisions
+
+### 裁剪模式设计
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `center` | 居中裁剪，保持原始比例 | 主体在画面中央 |
+| `smart` | 智能裁剪（ICE AI 识别主体） | 人物/产品展示 |
+| `fill` | 填充黑边，不裁剪 | 保留完整画面 |
+
+### ICE 参数方案
+
+**方案 A：使用 CropX/CropY/CropW/CropH**
+```json
+{
+  "MediaURL": "xxx",
+  "CropX": 280,
+  "CropY": 0,
+  "CropW": 720,
+  "CropH": 1280
+}
+```
+
+**方案 B：使用 Effects + Crop**
+```json
+{
+  "Effects": [{
+    "Type": "Crop",
+    "X": 280,
+    "Y": 0,
+    "Width": 720,
+    "Height": 1280
+  }]
+}
+```
+
+### 裁剪计算公式
+
+对于 16:9 横屏素材 (1920x1080) 裁剪为 9:16：
+```
+目标比例 = 9/16 = 0.5625
+源比例 = 16/9 = 1.778
+
+// 居中裁剪
+cropHeight = sourceHeight = 1080
+cropWidth = cropHeight * (9/16) = 607.5 ≈ 608
+cropX = (sourceWidth - cropWidth) / 2 = (1920 - 608) / 2 = 656
+cropY = 0
+```
+
+## Risks / Trade-offs
+
+- **画面损失**：居中裁剪会丢失左右两侧内容
+- **缩放失真**：填充模式会缩小画面
+- **ICE 兼容性**：需确认 ICE 版本支持的参数
+
+## Open Questions
+
+1. ICE 是否支持智能主体识别裁剪？
+2. 是否需要前端预览裁剪效果？
+3. 默认裁剪模式选择哪种？
--- a/openspec/changes/add-ice-916-crop/proposal.md
+++ b/openspec/changes/add-ice-916-crop/proposal.md
@@ -0,0 +1,21 @@
+# Change: ICE 增加 9:16 竖屏裁剪支持
+
+## Why
+
+当前混剪功能输出固定为 720x1280 (9:16) 尺寸，但输入素材可能是横屏 (16:9) 或其他比例。
+需要支持自动裁剪/缩放，确保输出视频符合竖屏要求，避免黑边或变形。
+
+## What Changes
+
+- 新增视频裁剪模式配置（居中裁剪 / 智能裁剪 / 填充黑边）
+- ICE Timeline 增加 CropMode 参数
+- 后端支持不同比例素材的自动处理
+- 前端可选裁剪模式（默认居中裁剪）
+
+## Impact
+
+- Affected specs: `mix-task`
+- Affected code:
+  - `BatchProduceAlignment.java` - Timeline 构建逻辑
+  - `MixTaskSaveReqVO.java` - 新增 cropMode 参数
+  - `Mix.vue` - 可选裁剪模式
--- a/openspec/changes/add-ice-916-crop/specs/mix-task/spec.md
+++ b/openspec/changes/add-ice-916-crop/specs/mix-task/spec.md
@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: 9:16 竖屏裁剪支持
+
+混剪系统 SHALL 支持将不同比例的素材自动处理为 9:16 竖屏输出。
+
+系统 SHALL 提供以下裁剪模式：
+- `center`：居中裁剪，保持原始比例，裁剪超出部分
+- `smart`：智能裁剪，识别主体位置进行裁剪（依赖 ICE 能力）
+- `fill`：填充模式，缩放素材并填充黑边保留完整画面
+
+系统 SHALL 默认使用 `center` 居中裁剪模式。
+
+#### Scenario: 横屏素材居中裁剪
+- **WHEN** 用户上传 16:9 横屏素材（1920x1080）
+- **AND** 选择 `center` 裁剪模式
+- **THEN** 系统自动计算裁剪区域（居中取 608x1080）
+- **AND** 输出 720x1280 竖屏视频
+
+#### Scenario: 竖屏素材无需裁剪
+- **WHEN** 用户上传 9:16 竖屏素材（720x1280）
+- **THEN** 系统直接使用原素材
+- **AND** 不进行裁剪处理
+
+#### Scenario: 填充模式保留完整画面
+- **WHEN** 用户上传 16:9 横屏素材
+- **AND** 选择 `fill` 填充模式
+- **THEN** 系统缩放素材至竖屏宽度
+- **AND** 上下填充黑边
+- **AND** 输出 720x1280 竖屏视频
+
+### Requirement: 裁剪模式配置
+
+混剪任务创建 API SHALL 接受可选的 `cropMode` 参数。
+
+参数规格：
+- 字段名：`cropMode`
+- 类型：String
+- 可选值：`center` | `smart` | `fill`
+- 默认值：`center`
+
+#### Scenario: 指定裁剪模式
+- **WHEN** 用户创建混剪任务时指定 `cropMode: "fill"`
+- **THEN** 所有素材使用填充模式处理
+
+#### Scenario: 使用默认裁剪模式
+- **WHEN** 用户创建混剪任务未指定 `cropMode`
+- **THEN** 系统使用默认的 `center` 居中裁剪模式
--- a/openspec/changes/add-ice-916-crop/tasks.md
+++ b/openspec/changes/add-ice-916-crop/tasks.md
@@ -0,0 +1,18 @@
+## 1. 调研阶段
+- [ ] 1.1 确认阿里云 ICE 支持的裁剪参数（CropX/CropY/CropW/CropH 或 ScaleMode）
+- [ ] 1.2 测试横屏素材在 ICE 中的默认处理方式
+
+## 2. 后端实现
+- [ ] 2.1 MixTaskSaveReqVO 新增 cropMode 字段（center/smart/fill）
+- [ ] 2.2 BatchProduceAlignment 实现裁剪计算逻辑
+- [ ] 2.3 ICE Timeline 增加裁剪参数
+- [ ] 2.4 单元测试
+
+## 3. 前端实现
+- [ ] 3.1 Mix.vue 新增裁剪模式选择（默认居中裁剪）
+- [ ] 3.2 提交参数增加 cropMode
+
+## 4. 测试验证
+- [ ] 4.1 横屏素材混剪测试
+- [ ] 4.2 竖屏素材混剪测试
+- [ ] 4.3 混合比例素材测试
--- a/openspec/mix-logic-spec.md
+++ b/openspec/mix-logic-spec.md
--- a/openspec/professional-simple-mix-spec.md
+++ b/openspec/professional-simple-mix-spec.md
@@ -0,0 +1,135 @@
+# 混剪功能规格（简化版）
+
+## 核心需求
+
+- **输入**：用户选择素材 + 设定每个素材截取时长（3-15s）
+- **输出**：1-3个不同内容的混剪视频
+- **总时长**：15s-60s
+- **差异化**：同顺序 + 同时长 + **随机截取起点**
+
+## 多视频差异化算法
+
+### 核心原理
+
+**随机起点 + 容错机制**：
+- 每个视频使用**随机截取起点**，确保内容完全不同
+- 支持**不同长度的素材**，ICE自动容错处理
+- 容错：如果起点超出素材长度，ICE自动从0开始截取
+
+**随机种子**：使用 `素材ID×1000000 + 视频序号×10000 + URL哈希%1000` 确保可重现性
+
+### 算法实现
+
+**随机起点生成**：
+```java
+// 1. 先获取视频实际时长
+int actualDuration = getVideoDuration(videoUrl);
+
+// 2. 生成随机种子
+long randomSeed = (material.getFileId() * 1000000L) +
+                 (videoIndex * 10000L) +
+                 (material.getFileUrl().hashCode() % 1000);
+Random random = new Random(randomSeed);
+
+// 3. 根据实际时长计算起始范围
+int maxStartOffset = Math.max(0, actualDuration - duration);
+int startOffset = random.nextInt(maxStartOffset + 1);
+int endOffset = startOffset + duration;
+```
+
+**获取视频时长方案**：
+1. **数据库字段**：上传时预存duration字段（推荐）
+2. **FFprobe工具**：命令行获取视频元数据
+3. **ICE元数据API**：调用ICE查询接口
+4. **默认60秒**：保守值，兼容性最好
+
+**容错机制**：
+- 根据实际时长计算最大起始偏移，避免超出素材长度
+- 如果获取时长失败，使用默认值60秒
+- ICE自动处理边界情况
+
+### ICE Timeline构建
+
+每个素材片段包含参数：
+- `MediaURL`：素材地址
+- `In`：随机截取起始点（0到实际时长-duration之间）
+- `Out`：截取结束点 = `In + duration`
+- `TimelineIn/TimelineOut`：时间轴位置（顺序拼接）
+
+ICE自动处理超出素材长度的情况，无需额外判断。
+
+## API设计
+
+### 请求格式
+
+```http
+POST /api/mix/create
+{
+  "title": "美食视频",
+  "materials": [
+    { "fileId": 123, "fileUrl": "https://xxx/v1.mp4", "duration": 5 },
+    { "fileId": 456, "fileUrl": "https://xxx/v2.mp4", "duration": 8 },
+    { "fileId": 789, "fileUrl": "https://xxx/v3.mp4", "duration": 5 }
+  ],
+  "produceCount": 3
+}
+```
+
+### 后端处理流程
+
+1. 校验请求参数（总时长15-60s）
+2. 循环生成produceCount个视频：
+   - videoIndex = 0, 1, 2...
+   - 获取每个素材的实际时长（数据库/FFprobe/ICE API）
+   - 生成随机起点（基于素材ID×1000000 + videoIndex×10000 + URL哈希）
+   - 根据实际时长计算起始范围，避免超出素材长度
+   - 构建Timeline，传递随机In/Out参数给ICE
+   - 提交ICE任务
+3. 保存任务并返回任务ID
+
+## 校验规则
+
+| 规则 | 前端 | 后端 |
+|------|------|------|
+| 总时长 15-60s | ✅ | ✅ |
+| 单素材 3-15s | ✅ | ✅ |
+| 至少选1个素材 | ✅ | ✅ |
+| 生成数量 1-3 | ✅ | ✅ |
+
+## 实现清单
+
+### 已完成
+- [x] 前端时长选择和实时计算
+- [x] 后端VO（MaterialItem）实现
+- [x] 后端DO（materialsJson）字段
+- [x] 数据库迁移脚本
+- [x] 后端Controller（/api/mix/create）
+- [x] 后端Service（多视频生成逻辑）
+- [x] ICE Timeline构建（随机起点+实际时长+容错）
+- [x] 批量任务提交和状态跟踪
+
+### 测试验证
+- [ ] 编译验证
+- [ ] 端到端功能测试
+- [ ] 多视频差异化验证
+
+---
+
+## 代码修改清单
+
+### 核心修改
+1. **BatchProduceAlignment.java**
+   - 新增方法：`produceSingleVideoWithOffset(materials, videoIndex, userId)`
+   - 新增方法：`getVideoDuration(videoUrl)` - 获取视频实际时长
+   - 核心逻辑：先获取实际时长，再生成随机起点
+   - 容错机制：根据实际时长计算范围，避免超出长度
+
+2. **MixTaskServiceImpl.java**
+   - 循环生成produceCount个视频
+   - 每次传入不同的videoIndex，确保随机起点不同
+
+3. **数据库结构（可选改进）**
+   - 新增字段：`duration INTEGER COMMENT '视频时长（秒）'`
+   - 上传时预处理：使用FFprobe获取时长并存储
+
+*版本：v3.0 - 简化版（ICE自动容错）*
--- a/openspec/project.md
+++ b/openspec/project.md
@@ -0,0 +1,31 @@
+# Project Context
+
+## Purpose
+[Describe your project's purpose and goals]
+
+## Tech Stack
+- [List your primary technologies]
+- [e.g., TypeScript, React, Node.js]
+
+## Project Conventions
+
+### Code Style
+[Describe your code style preferences, formatting rules, and naming conventions]
+
+### Architecture Patterns
+[Document your architectural decisions and patterns]
+
+### Testing Strategy
+[Explain your testing approach and requirements]
+
+### Git Workflow
+[Describe your branching strategy and commit conventions]
+
+## Domain Context
+[Add domain-specific knowledge that AI assistants need to understand]
+
+## Important Constraints
+[List any technical, business, or regulatory constraints]
+
+## External Dependencies
+[Document key external services, APIs, or systems]