┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  单一事实来源       │◄─────│  提议的修改                   │   │
│   │  描述系统当前的     │ 合并 │  每个变更 = 一个文件夹        │   │
│   │  工作方式           │      │  包含制品 + 增量              │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

openspec/specs/
├── auth/
│   └── spec.md           # 认证行为
├── payments/
│   └── spec.md           # 支付处理
├── notifications/
│   └── spec.md           # 通知系统
└── ui/
    └── spec.md           # UI 行为和主题

### Requirement: User Authentication
系统 SHALL 在用户登录成功时签发 JWT Token<websource>source_group_web_1</websource>。

#### Scenario: Valid credentials (凭证有效)
- **GIVEN** 一个拥有正确账号密码的用户
- **WHEN** 用户提交登录表单
- **THEN** 系统返回 JWT token
- **AND** 用户被重定向到首页

#### Scenario: Invalid credentials (凭证无效)
- **GIVEN** 用户输入了错误的密码
- **WHEN** 用户提交登录表单
- **THEN** 系统显示“账号或密码错误”的提示
- **AND** 不签发任何 token

openspec/changes/add-dark-mode/
├── proposal.md           # 为什么和做什么
├── design.md             # 如何做（技术方案）
├── tasks.md              # 实施清单
├── .openspec.yaml        # 变更元数据（可选）
└── specs/                # 增量规范
    └── ui/
        └── spec.md       # ui/spec.md 中的更改内容

归档前：

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ 合并
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


归档后：

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # 现在包含 2FA 需求
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # 为历史保留
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

─[$] openspec init     
Cleaned up legacy files:
  ✓ Removed openspec/AGENTS.md

Migrated: custom profile with 4 workflows
New in this version: /opsx:propose. Try 'openspec config profile core' for the streamlined experience.

                        Welcome to OpenSpec
                        A lightweight spec-driven framework
                        
        ████            This setup will configure:
      ██    ██            • Agent Skills for AI tools
    ██  ████  ██          • /opsx:* slash commands
    ██  ████  ██        
    ██  ████  ██        Quick start after setup:
      ██    ██            /opsx:new      Create a change
        ████              /opsx:continue Next artifact
                          /opsx:apply    Implement tasks
                        
                        Press Enter to select tools...


## 回车
OpenSpec Setup Complete

Refreshed: Claude Code
4 skills and 4 commands in .claude/
Config: openspec/config.yaml (exists)

Getting started:
  Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

openspec/
├── specs/              # 单一事实来源（系统的行为）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的更新（每个变更一个文件夹）
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # 增量规范（正在变更的内容）
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

.openspec/
├── specs/                  # 已部署功能的权威基准（最终规范归档）
│   └── [capability]/       # 按功能模块划分（如返点单列表、返点单详情）
│       ├── spec.md         # 需求说明与场景描述（核心规格文档）
│       └── design.md       # 技术实现方案（可选，复杂功能补充）
├── changes/                # 正在进行的变更提案（开发中功能）
│   ├── [change-name]/      # 单个变更目录（如“rebate-order-list”，对应返点单列表）
│   │   ├── proposal.md     # 提案背景与核心内容（为什么做、做什么）
│   │   ├── design.md       # 技术设计文档（怎么做、技术选型）
│   │   ├── specs/          # 增量规格说明（功能细节、场景拆分）
│   │   └── tasks.md        # 实现任务清单（开发步骤、验收标准）
│   └── archive/            # 已完成变更的归档目录（开发完成后迁移至此）
└── config.yaml             # OpenSpec 核心配置文件（项目规范、技术栈等）

.openspec/
├── specs/                  # 已部署功能的权威基准（最终规范归档）
│   └── [capability]/       # 按功能模块划分（如返点单列表、返点单详情）
│       ├── spec.md         # 需求说明与场景描述（核心规格文档）
│       └── design.md       # 技术实现方案（可选，复杂功能补充）

/opsx:onboard


SHOW: ✅ 预检结果

✅ JoySpec CLI 已安装（版本 0.2.12）
✅ 项目已初始化（.joyspec/ 目录存在）
PAUSE: 预检通过！准备好继续了吗？

Phase 1: 欢迎
EXPLAIN:

什么是 JoySpec？
JoySpec 是一个规约驱动的开发工作流，帮助团队通过结构化的提案、规范和任务跟踪来管理代码变更。

核心工作流周期
Propose → Spec → Design → Task → Apply → Archive
  提案     规范     设计     任务     实施     归档

Propose（提案）: 描述问题和解决方案
Spec（规范）: 定义功能需求和行为
Design（设计）: 技术设计和架构决策
Task（任务）: 分解为可执行的小任务
Apply（实施）: 执行任务并跟踪进度
Archive（归档）: 完成后归档并更新规范
预期效果
本次上手体验约 15-20 分钟，我们将一起完成一个真实的、小型的代码改进，让您完整体验整个工作流。

PAUSE: 您准备好了吗？让我们进入下一阶段：选择一个实际任务来实践！


SHOW: 扫描结果 - 我发现了几个适合作为第一个 JoySpec 变更的候选任务：

📋 任务候选列表
| # | 任务类型 | 描述 | 预估时间 | 难度 |
|---|---------|------|---------|------|
| 1 | 文档完善 | 完善 README.md，添加项目结构、快速开始、技术栈等章节 | 10-15分钟 | ⭐ |
| 2 | 项目规约 | 完善 .joyspec/project.md，填写项目的实际信息（技术栈、架构模式等） | 10-15分钟 | ⭐ |
| 3 | 代码质量 | 为关键类添加完整的 JavaDoc 注释（如 DemoResourceImpl） | 15-20分钟 | ⭐⭐ |

💡 推荐
我推荐选择任务 1 或任务 2，因为：

✅ 足够小，可以在本次会话中完成
✅ 能展示完整的 JoySpec 工作流（提案 → 规范 → 设计 → 任务 → 实施 → 归档）
✅ 有实际价值，能帮助新成员快速了解项目
✅ 没有代码风险，适合作为第一次实践
PAUSE: 您想选择哪个任务？

         ┌───────────────────────────────────────────────────────┐
         │             核心行动指令 (Actions)                  │
         │                                                       │
         │ explore ◄──► new ◄──► continue ◄──► apply ◄──► verify ◄──► archive │
         │    │          │           │            │              │       │
         │    └──────────┴───────────┴────────────┴──────────────┘       │
         │                   任意顺序、自由穿梭                          │
         └───────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC 流程                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. 创建        │  /opsx:ff 或 /opsx:continue (expanded workflow)         │
│   │    制品         │  创建提案 → 规范 → 设计 → 任务                             │
│   │                │  （基于模式依赖关系）                                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. 实施        │  /opsx:apply                                            │
│   │    任务         │  处理任务，勾选完成项                                      │
│   │                │◄──── 学习时更新制品                                       │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. 验证        │  /opsx:verify（可选）                                    │
│   │    工作         │  检查实施是否匹配规范                                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. 归档        │────►│  增量规范合并到主规范                           │   │
│   │    变更         │     │  变更文件夹移动到 archive/                      │  │
│   └────────────────┘     │  规范现在是更新的单一事实来源                     │   │
│                          └──────────────────────────────────────────────┘   │
│                                                                             │
└──────────────────────────────────────────────────────────────────────────────┘

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            在学习过程中更新

rules:
  # ---- 提案（Proposal）规则 ----
  proposal:
    - 提案必须包含：背景、目标、非目标（Non-goals）、技术方案概要、影响范围
    - 必须标注影响的模块（common/domain/dao/manager/service/rpc/web）
    - 必须评估是否影响现有 JSF 接口契约
    - 必须说明缓存影响（Redis Key 变更/新增/删除）
    - 必须说明 MQ 消息变更（新增 Topic / 修改消息体）

## Why

<描述当前系统的不足/痛点，为什么需要这次变更。重点说明：>
- 现有架构的局限性（如：某维度缺失导致无法差异化处理）
- 业务诉求的优先级（如：仅少数场景需要新维度，大部分仍走默认逻辑）
- 对主路径性能的约束（如：新增维度不可退化核心查询性能）

## What Changes

- 数据库表（`<table_name>`）新增 `<new_column>` 字段，唯一键从 `<old_unique_key>` 调整为 `<new_unique_key>`，`<new_column>` 为 NULL 时表示默认规则
- **BREAKING** RPC 接口 `<RequestDto>` 新增 `<newField>` 字段（向前兼容，非必传）
- 缓存 Key `<CACHE_PREFIX>` 新增 `<newField>` 段；主路径采用"先查带新维度 Key，miss 后查默认 Key"策略，保证查询效率
- CRUD：创建/编辑时支持指定 `<newField>`，默认规则与新维度规则可独立并存
- 策略分配：入参透传 `<newField>`，分配结果按 `<existingKey>` 隔离存储，无需改动
- 规则生效/失效/预刷缓存：按 `<newField>` 维度独立刷缓存，默认规则与新维度规则各自维护
- 核心查询链路：三级查询（订单缓存→路由缓存→DB 兜底）均增加 `<newField>` 维度匹配
- 定时任务：查询与缓存预刷逻辑适配 `<newField>`
- 字典查询接口：新增新维度字典数据

## Capabilities

### New Capabilities
- `<capability-name>`: <一句话描述新能力——覆盖规则唯一性定义、缓存 Key 策略、查询链路适配、生效/失效/预刷缓存联动>

### Modified Capabilities
- `<existing-capability-name>`: <描述对该能力的修改，如字段新增、约束变更、接口扩展>

## Impact

- **影响模块**：common（缓存 Key/常量）、domain（PO/缓存对象）、dao（Mapper 查询条件）、manager（查询逻辑）、service（查询链路、写入逻辑、策略分配）、rpc（Provider 入参解析）、web（MQ Consumer/定时任务适配）
- **接口契约**：`<RequestDto>` 新增 `<newField>` 字段（非必传，默认 null 走原逻辑）；`<ResponseDto>` 新增 `<newField>` 字段
- **缓存影响**：`<CACHE_PREFIX>` Key 格式变更（新增字段段），需灰度切换；其他缓存 Key 依赖已有隔离键，无需变更
- **MQ 消息变更**：无新增 Topic，如有 `<newField>` 需透传

## Context

<描述当前系统的核心模型和查询链路。重点说明：>
- 当前唯一键定义（如二元组/三元组）
- 核心查询链路（如三级缓存结构）
- 核心约束（如缓存是一对一映射，新增维度后变为 1:N）

### 当前架构关键链路

```
核心查询(request)
  → 1. 一级缓存: <CACHE_KEY_PATTERN_1>
  → 2. 二级缓存: <CACHE_KEY_PATTERN_2> → <resultKey>
     → 详情缓存: <CACHE_KEY_PATTERN_3> → <resultDetail>
     → 关系缓存: <CACHE_KEY_PATTERN_4> → <relationResult>
  → 3. DB 兜底
```

## Goals / Non-Goals

**Goals:**
- <目标 1：新增维度支持差异化规则>
- <目标 2：主路径查询性能不退化>
- <目标 3：全链路覆盖：DB、缓存、CRUD、生效/失效、预刷、定时任务>
- <目标 4：向前兼容：现有数据新字段为 NULL，老调用方不传新字段时行为不变>

**Non-Goals:**
- <不做的事 1：不改造分配算法本身，仅透传新字段>
- <不做的事 2：不改造与新字段无关的缓存 Key 格式>
- <不做的事 3：不改造已有隔离键覆盖的缓存>

## Decisions

### D1: 缓存 Key 策略——"先精确后降级"保证主路径性能

**决策**：`<CACHE_PREFIX>` 缓存 Key 新增新维度段，格式为 `<CACHE_PREFIX>:<existingKey>:<newField>`。查询时先按传入的新字段查精确 Key，若未命中则查默认 Key（新字段为空段）。默认规则仍然使用原 Key，不搬迁旧数据。

**关键点**：如果为新维度配置了专属规则，则在专属 Key 下写入结果；同时默认 Key 下仍保留默认规则的结果。调用方传新字段时：

1. 先查 `<CACHE_PREFIX>:<existingKey>:<newFieldValue>` → 若命中，走专属规则
2. 若 miss，查 `<CACHE_PREFIX>:<existingKey>` → 命中默认规则

**主路径分析**：大部分请求传了新字段但仅有默认规则，步骤 1 miss，步骤 2 hit，总计 2 次查询。内网缓存延迟极低，2 次查询仍在可接受范围内。

**备选方案**：
- ❌ 合并 Key（Hash 结构）：1 次查询可同时获取，但需改造所有写入路径且需全量迁移数据
- ❌ 双写精确 Key + 默认 Key：主路径 1 次命中，但失效时需双删、一致性风险高

### D2: 数据库唯一约束设计

**决策**：`<table_name>` 表新增 `<new_column> VARCHAR(N) DEFAULT NULL`。唯一索引调整为包含新列。MySQL 中 NULL 不参与唯一索引冲突检测，由业务层保证同一条件下仅一条默认记录。

**备选方案**：
- ❌ 使用空字符串代替 NULL：可行但语义不清，且需全量刷历史数据

### D3: 核心查询链路改造

**决策**：在缓存查询和 DB 兜底中增加新维度。

缓存查询伪代码：
```java
// 1. 尝试精确 Key（带新维度）
String result = null;
if (StringUtils.isNotBlank(req.getNewField())) {
    String preciseKey = CacheKeyHelper.getKey(req.getExistingKey1(), req.getExistingKey2(), req.getNewField());
    result = cacheService.get(preciseKey);
}
// 2. 精确 Key 未命中或无新维度，查默认 Key
if (StringUtils.isBlank(result)) {
    String defaultKey = CacheKeyHelper.getKey(req.getExistingKey1(), req.getExistingKey2());
    result = cacheService.get(defaultKey);
}
```

DB 兜底伪代码：
```java
// 1. 先查带新维度的记录
Entity record = null;
if (StringUtils.isNotBlank(req.getNewField())) {
    record = queryByCondition(req.getExistingKey1(), req.getExistingKey2(), req.getNewField(), status);
}
// 2. 未查到则查默认记录
if (record == null) {
    record = queryByCondition(req.getExistingKey1(), req.getExistingKey2(), null, status);
}
```

### D4: 规则生效/失效缓存联动

**决策**：规则生效时，根据自身的 `<newField>` 决定写入哪个 Key：
- `<newField>` 非空 → 写入 `精确 Key`
- `<newField>` 为空 → 写入 `默认 Key`

规则失效时，删除对应的 Key 即可。默认规则失效不影响专属规则，反之亦然。

### D5: 审批通过时同维度规则作废逻辑

**决策**：审批通过后将同维度下的"待生效"记录置为作废。作废范围限定为**同一新维度**：默认规则的新版本只作废默认规则的旧版本，专属规则同理。

### D6: 缓存 Key 工具类扩展

**决策**：`CacheKeyHelper.getKey()` 新增重载方法，接受新维度参数。保持原方法签名不变（向前兼容），新重载方法在 Key 末尾追加新维度段。

## Risks / Trade-offs

- **[主路径 2 次缓存查询]** → 可接受，内网缓存延迟极低。若后续有极端性能要求，可引入空值标记优化
- **[缓存 Key 灰度切换]** → 旧 Key 不删除、不搬迁，新代码先查新 Key 再查旧 Key，天然兼容。待全部切换完成后旧 Key 自然过期
- **[新字段=NULL 唯一约束]** → 需业务层保证同条件下仅一条默认记录，在保存方法中增加校验
- **[接口兼容性]** → 新增字段为非必传，默认 null。老调用方不传时等价于查默认逻辑，行为不变
- **[定时任务查询范围]** → 按 status 查询时不限新维度，逐条处理时根据规则的新维度决定缓存 Key

## Migration Plan

1. **DDL 变更**（先行）：
   ```sql
   ALTER TABLE <table_name> ADD COLUMN <new_column> VARCHAR(32) DEFAULT NULL COMMENT '<字段说明，NULL表示默认>' AFTER <after_column>;
   ALTER TABLE <table_name> DROP INDEX <old_unique_index>;
   ALTER TABLE <table_name> ADD UNIQUE INDEX <new_unique_index> (<col1>, <col2>, <new_column>);
   ```
2. **代码发布**（export JAR 先行 → 主应用后行）：
   - Step 1: 发布 export 新版 JAR（新增字段，非必传）
   - Step 2: 通知调用方升级 export JAR（可渐进式）
   - Step 3: 发布主应用
3. **回滚策略**：代码回滚至旧版本即可，新列均为 NULL 不影响旧逻辑

## Open Questions

- <新维度枚举值由哪方定义？是否需要对接上游系统？>
- <MQ 消息体是否已包含新字段？需确认消息生产方是否同步改造。>

## ADDED Requirements

### Requirement: <实体>支持<新维度>维度
<实体> SHALL 新增 `<newField>` 字段，用于标识规则的新维度。`<newField>` 为空（NULL）时表示默认规则。同一条件下，`<uniqueKey组合>` SHALL 唯一确定一条记录。

#### Scenario: 创建默认记录（不传新维度）
- **WHEN** 用户创建记录时未指定 `<newField>`
- **THEN** 系统将 `<newField>` 存储为 NULL，该记录作为默认记录

#### Scenario: 创建专属记录
- **WHEN** 用户创建记录时指定 `<newField>` 为 "<value>"
- **THEN** 系统存储 `<newField>="<value>"`，该记录仅对匹配该维度的请求生效

## 1. 数据库变更

- [ ] 1.1 编写 DDL 脚本：`<table_name>` 表新增 `<new_column>` 列，删除旧唯一索引，创建新唯一索引 【模块：dao | 预估：0.5h】

## 2. Export 模块

- [ ] 2.1 `<RequestDto>` 新增 `<newField>` 字段（非必传，默认 null）【模块：export | 预估：0.5h】
- [ ] 2.2 `<ResponseDto>` 新增 `<newField>` 字段【模块：export | 预估：0.5h】
- [ ] 2.3 其他相关 DTO 新增 `<newField>` 字段【模块：export | 预估：0.5h】
- [ ] 2.4 发布 export 新版 JAR，通知调用方升级【模块：export | 预估：0.5h】

## 3. Domain 层变更

- [ ] 3.1 PO 新增 `<newField>` 字段【模块：domain | 预估：0.5h】
- [ ] 3.2 缓存对象新增 `<newField>` 字段【模块：domain | 预估：0.5h】
- [ ] 3.3 Query 对象新增 `<newField>` 查询条件字段【模块：domain | 预估：0.5h】

## 4. Common 层变更

- [ ] 4.1 缓存 Key 工具类新增重载方法，接受 `<newField>` 参数；原方法签名保持不变【模块：common | 预估：0.5h】
- [ ] 4.2 新增维度枚举类，定义常量值【模块：common | 预估：1h】

## 5. DAO 层变更

- [ ] 5.1 Mapper XML：列定义、动态列、查询条件、更新列、insertOrUpdate 均适配 `<new_column>`【模块：dao | 预估：1h】
- [ ] 5.2 Mapper XML：核心查询增加 `<new_column>` 条件支持（精确匹配 + NULL 默认匹配）【模块：dao | 预估：1h】

## 6. Manager 层变更

- [ ] 6.1 Manager 查询方法增加 `<newField>` 参数重载，支持降级查询默认规则【模块：manager | 预估：1h】
- [ ] 6.2 对象转换器：转换方法透传 `<newField>` 字段【模块：manager | 预估：1h】

## 7. Service 层——核心查询链路

- [ ] 7.1 缓存查询：实现"先精确后降级"策略【模块：service | 预估：1.5h】
- [ ] 7.2 DB 兜底：实现降级查询策略【模块：service | 预估：1h】
- [ ] 7.3 核心查询方法：增加 `<newField>` 参数【模块：service | 预估：0.5h】
- [ ] 7.4 响应 DTO 设置 `<newField>` 字段【模块：service | 预估：0.5h】

## 8. Service 层——规则写入与缓存联动

- [ ] 8.1 生效缓存切换：根据 `<newField>` 决定写入的 Key；作废时限定同维度【模块：service | 预估：1.5h】
- [ ] 8.2 缓存预刷：根据 `<newField>` 决定续期的 Key【模块：service | 预估：1h】
- [ ] 8.3 状态更新：审批通过后作废同维度规则，查询条件增加 `<newField>` 限定【模块：service | 预估：1h】
- [ ] 8.4 保存前校验：同条件+同维度下是否已存在默认记录（业务层唯一约束兜底）【模块：service | 预估：1h】

## 9. Service 层——字典接口

- [ ] 9.1 字典接口：返回结果新增新维度选项列表【模块：service | 预估：1h】
- [ ] 9.2 字典 DTO 新增字段（如需在 export 模块添加）【模块：export | 预估：0.5h】

## 10. RPC 层适配

- [ ] 10.1 核心查询方法：透传 `<newField>` 至 Service【模块：rpc | 预估：0.5h】
- [ ] 10.2 写入方法：透传 `<newField>`【模块：rpc | 预估：0.5h】

## 11. 定时任务适配

- [ ] 11.1 生效 Job：验证逐条处理时 `<newField>` 正确透传【模块：web | 预估：0.5h】
- [ ] 11.2 缓存预刷 Job：验证按 `<newField>` 正确写入缓存 Key【模块：web | 预估：0.5h】
- [ ] 11.3 其他相关 Job：验证内部逻辑适配后行为正确【模块：web | 预估：0.5h】

## 12. MQ Consumer 适配

- [ ] 12.1 消息处理器：确认消息体中 `<newField>` 字段透传【模块：web | 预估：1h】

## 13. 单元测试

- [ ] 13.1 核心查询 Service 测试：新增传入 `<newField>` 的用例（专属命中、降级默认、不传兼容）【模块：service | 预估：1.5h】
- [ ] 13.2 写入 Service 测试：新增按维度生效/失效的用例【模块：service | 预估：1h】
- [ ] 13.3 缓存 Key 工具类测试：新增带 `<newField>` 重载方法的用例【模块：common | 预估：0.5h】
- [ ] 13.4 Manager 测试：新增按维度查询和降级查询的用例【模块：manager | 预估：1h】

## 14. 集成验证与发布

- [ ] 14.1 执行 DDL 脚本到测试环境，验证历史数据兼容性【模块：dao | 预估：0.5h】
- [ ] 14.2 端到端验证：创建默认规则 + 专属规则 → 分别查询 → 验证缓存 Key 和返回结果【模块：全链路 | 预估：1.5h】
- [ ] 14.3 性能验证：主路径缓存查询次数与延迟基线对比【模块：service | 预估：1h】
- [ ] 14.4 发布 export JAR，通知调用方渐进式升级【模块：export | 预估：0.5h】

# 列出活动变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 验证规范格式
openspec validate add-dark-mode

# 交互式仪表盘
openspec view

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply──► /opsx:verify ──► /opsx:archive

┌─────────────────────────────────────────────────────────────────┐
  │                     Claude Code 会话生命周期                      │
  │                                                                 │
  │  ┌──────────────────────────────────────────────────────┐       │
  │  │  Phase 0: 会话启动（自动，无需任何命令）                │       │
  │  │                                                      │       │
  │  │  AGENTS.md  ──── 自动加载到系统上下文                  │       │
  │  │  (Claude Code 读取 .claude/commands/ 时连带加载)      │       │
  │  └──────────────────────────────────────────────────────┘       │
  │                          │                                      │
  │                          ▼                                      │
  │  ┌──────────────────────────────────────────────────────┐       │
  │  │  Phase 1: 任务理解（AI 按 AGENTS.md §0 的指示执行）    │       │
  │  │                                                      │       │
  │  │  README.md ──→ specs/具体模块/spec.md ──→ 子文档       │       │
  │  │  (按需读取，由 AGENTS.md 的知识库加载顺序驱动)         │       │
  │  └──────────────────────────────────────────────────────┘       │
  │                          │                                      │
  │                          ▼                                      │
  │  ┌──────────────────────────────────────────────────────┐       │
  │  │  Phase 2: 产物生成（/opsx:propose 触发）               │       │
  │  │                                                      │       │
  │  │  config.yaml ──→ context（注入项目背景）               │       │
  │  │              ──→ rules.proposal（约束提案写法）         │       │
  │  │              ──→ rules.spec（约束规格写法）             │       │
  │  │              ──→ rules.change / tasks / review         │       │
  │  │  (通过 openspec CLI 的 instructions 命令注入)          │       │
  │  └──────────────────────────────────────────────────────┘       │
  │                          │                                      │
  │                          ▼                                      │
  │  ┌──────────────────────────────────────────────────────┐       │
  │  │  Phase 3: 代码实施（/opsx:apply 触发）                 │       │
  │  │                                                      │       │
  │  │  AGENTS.md   ──→ 编码规约（分层、命名、注解...）       │       │
  │  │  config.yaml ──→ review 规则（代码审查检查项）          │       │
  │  │  specs/      ──→ 模块知识（接口签名、数据结构、流程）   │       │
  │  │  tasks.md    ──→ 任务清单（做什么、什么顺序）           │       │
  │  └──────────────────────────────────────────────────────┘       │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

  ┌───────────────────────┬─────────────────────────────────────────────────────────┐
  │    Delta Spec 类型    │                        合并操作                         │
  ├───────────────────────┼─────────────────────────────────────────────────────────┤
  │ ADDED Requirements    │ 直接追加到主 spec 的 ## Requirements 末尾               │
  ├───────────────────────┼─────────────────────────────────────────────────────────┤
  │ MODIFIED Requirements │ 找到主 spec 中同名的 ### Requirement:，整体替换为新内容 │
  ├───────────────────────┼─────────────────────────────────────────────────────────┤
  │ REMOVED Requirements  │ 从主 spec 中删除对应 Requirement 块                     │
  ├───────────────────────┼─────────────────────────────────────────────────────────┤
  │ 新建能力模块          │ 创建新 spec.md，直接就是 Delta Spec 风格，不需要再翻译  │
  └───────────────────────┴─────────────────────────────────────────────────────────┘

openspec/
├─ specs/               # 主规约（稳定、已归档、按领域分层）
│  ├─ domain-user/      # 领域1：用户域
│  │  ├─ entity.md      # 领域实体：User、Address、Account
│  │  ├─ api-auth.md    # 需求/能力子集：登录、注册、验证码接口
│  │  ├─ api-user-info.md # 能力子集：用户信息CRUD
│  │  └─ common-enum.md # 领域通用枚举、常量、校验规则
│  ├─ domain-order/     # 领域2：订单域
│  │  ├─ entity.md
│  │  ├─ api-order-create.md
│  │  ├─ api-order-pay.md
│  │  └─ rule-discount.md # 领域专属业务规则
│  └─ common-base/      # 全局公共领域（所有业务通用）
│     ├─ page-model.md  # 分页通用结构体
│     └─ error-code.md  # 全局错误码
└─ changes/              # 临时增量变更（按需求纬度，迭代完成归档合并到specs领域）
   ├─ login-v2-fix/
   ├─ order-discount-opt/
   └─ archive/          # 已归档历史变更包

┌─[zhangyujin1@ZBMac-J7H7T2943L] - [~/Desktop/] - [2526]
└─[$] openspec config profile                                                                                                            [11:07:57]

Current profile settings
  Delivery: both
  Workflows: 4 selected (custom)
  Delivery = where workflows are installed (skills, commands, or both)
  Workflows = which actions are available (propose, explore, apply, etc.)

✔ What do you want to configure? Workflows only
✔ Select workflows to make available: Propose change, Explore ideas, New change, Continue change, Apply tasks, Fast-forward, Sync specs, Archive 
change, Bulk archive, Verify change, Onboard

Config changes:
  workflows: added new, continue, ff, sync, bulk-archive, verify, onboard

✔ Apply changes to this project now? Yes

Updating 1 tool(s): claude (config sync)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.3.1)
Tools: Claude Code

Restart your IDE for changes to take effect.
Run `openspec update` in your other projects to apply.
┌─[zhangyujin1@ZBMac-J7H7T2943L] - [~/Desktop/] - [2527]
└─[$] openspec update                                                                                                                    [11:09:19]
✓ All 1 tool(s) up to date (v1.3.1)
  Tools: claude

Use --force to refresh files anyway.