kld-sdd 2.4.7

package/templates/openspec/design.md

@@ -0,0 +1,290 @@
+# 局部技术实现方案 - [Capability 名称]
+
+> **定位**：单一 Capability 的业务维度技术实现方案
+> 
+> **⚠️ 边界声明**：本设计仅服务于当前 Capability，严禁越权设计或覆盖其他模块逻辑。
+> 
+> **【质量红线】专注"本业务如何落地"；严禁写入全局中间件或框架选型；必须为任务拆解提供足够局部细节
+
+---
+
+## 1. 字段完整性追溯表
+
+> **⛔ 核心红线**：用户在 Spec 中输入的所有字段必须在此表中体现，严禁无故丢弃！
+
+### 1.1 字段映射表
+
+| 序号 | 用户输入字段 | 设计输出字段 | 字段类型 | 状态 | 理由说明 |
+|-----|-------------|-------------|---------|------|---------|
+| 1 | | | | ✅ 保留 | |
+| 2 | | | | ✅ 保留 | |
+| 3 | | | | ⚠️ 重命名 | |
+| 4 | | | | 🔀 合并 | |
+
+**状态说明**：
+- ✅ 保留：字段名和类型与用户输入一致
+- ⚠️ 重命名：字段重命名（必须说明理由）
+- 🔀 合并：多字段合并为一个（必须说明理由）
+- ❌ 移除：字段被移除（必须有充分理由且经用户确认）
+
+### 1.2 完整性自检
+
+- **用户输入字段总数**：[X] 个
+- **设计输出字段总数**：[X] 个
+- **差异说明**：[如有差异必须详细说明]
+- **完整性确认**：[ ] 已确认所有字段都有对应处理
+
+---
+
+## 2. 现有代码锚点
+
+> **⚠️ 重要**：大多数需求是在已有系统上改造/扩展，不是从零开始。
+> AI 无法知道“要改哪里”，如果本 Capability 涉及对现有代码的修改，**请用户补充完整**。
+> 纯新建项目可跳过此章节。
+
+### 2.1 需修改的现有文件
+
+| 文件路径 | 类/模块名 | 需修改的方法/函数 | 修改类型 | 说明 |
+|---------|----------|----------------|---------|------|
+| `src/xxx/XxxService.java` | XxxService | `processOrder()` | 扩展逻辑 | |
+| `src/xxx/XxxController.java` | XxxController | `handleRequest()` | 新增参数 | |
+| | | | | |
+
+**修改类型说明**：
+- 扩展逻辑：在现有方法中添加新逻辑分支
+- 新增参数：修改方法签名或请求/响应结构
+- 重构抽取：抽取公共逻辑为新方法
+- 替换实现：用新实现替换原有逻辑
+
+### 2.2 需新建的文件
+
+| 文件路径（建议） | 类/模块名 | 职责 | 继承/实现 | 说明 |
+|------------|----------|------|---------|------|
+| | | | | |
+
+### 2.3 现有逻辑约束
+
+> 影响本次设计的现有系统约束（如：已有事务边界、线程模型、日志规范、已有设计模式等）
+
+| 约束项 | 当前现状 | 对本设计的影响 | 应对策略 |
+|-------|---------|-------------|--------|
+| | | | 遵循/适配/协商修改 |
+
+---
+
+## 3. 局部前端设计
+
+> 仅针对当前 Capability 的前端设计
+
+### 3.1 页面/组件结构
+
+| 组件名 | 类型 | 职责 | 依赖组件 |
+|-------|------|------|---------|
+| | 页面/容器/展示 | | |
+
+### 3.2 状态管理
+
+| 状态名 | 数据类型 | 初始值 | 更新时机 |
+|-------|---------|-------|---------|
+| | | | |
+
+### 3.3 路由设计
+
+| 路由路径 | 页面组件 | 权限要求 | 说明 |
+|---------|---------|---------|------|
+| | | | |
+
+### 3.4 前后端交互
+
+| 前端操作 | 调用接口 | 请求参数 | 响应处理 |
+|---------|---------|---------|---------|
+| | | | |
+
+---
+
+## 4. 局部后端接口设计
+
+> 仅针对当前 Capability 的接口设计
+
+### 4.1 接口清单
+
+| 接口名称 | 路径 | 方法 | 说明 |
+|---------|------|------|------|
+| | `/api/v1/xxx` | GET/POST | |
+
+### 4.2 接口详细设计
+
+#### 接口 1：[接口名称]
+
+**基本信息**：
+- 路径：`/api/v1/xxx`
+- 方法：GET/POST
+- 认证：需要/不需要
+
+**请求参数**：
+| 参数名 | 类型 | 必填 | 说明 | 约束 |
+|-------|------|------|------|------|
+| | | | | |
+
+**响应结构**：
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    // 字段定义
+  }
+}
+```
+
+**业务逻辑**：
+1. 
+2. 
+3. 
+
+---
+
+## 5. 局部数据模型
+
+> 仅针对当前 Capability 的数据设计，遵循 overview.md 的全局约定
+
+### 5.1 数据表设计
+
+#### 表名：[table_name]
+
+| 字段名 | 数据类型 | 必填 | 默认值 | 说明 | 索引 |
+|-------|---------|------|--------|------|------|
+| id | 唯一标识 | 是 | 自动生成 | 主键 | PK |
+| | 字符串/数字/布尔/日期/枚举 | | | | |
+| created_at | 时间戳 | 是 | 当前时间 | 创建时间 | |
+| updated_at | 时间戳 | 是 | 当前时间 | 更新时间 | |
+
+**索引设计**：
+- 主键索引：id
+- 唯一索引：
+- 普通索引：
+
+### 5.2 缓存设计
+
+| 缓存 Key 模式 | 数据类型 | 过期时间 | 更新策略 | 说明 |
+|--------------|---------|---------|---------|------|
+| | | | | |
+
+### 5.3 数据流转图
+
+```
+[输入] --> [处理] --> [存储] --> [输出]
+```
+
+---
+
+## 6. 模块内部逻辑
+
+### 6.1 核心流程
+
+```
+[步骤1] --> [步骤2] --> [步骤3]
+```
+
+### 6.2 状态机（如有）
+
+```
+[状态A] --事件1--> [状态B]
+[状态B] --事件2--> [状态C]
+```
+
+### 6.3 关键算法（如有）
+
+<!-- 描述复杂算法的实现思路 -->
+
+---
+
+## 7. 外部依赖与集成
+
+> **⚠️ 必填**：列出本 Capability 依赖的所有外部系统、服务和基础设施，确保上下游关系透明、可追踪。
+> AI 无法自动推断项目的外部依赖，**请用户补充完整**。
+
+### 7.1 外部服务依赖
+
+| 依赖服务 | 用途 | 调用方式 | 超时设置 | 失败影响 | 降级方案 |
+|---------|------|---------|---------|---------|--------|
+| | | REST/RPC/SDK | | 阻塞/可降级 | |
+
+### 7.2 第三方 API / SDK
+
+| 名称 | 版本/文档链接 | 用途 | 鉴权方式 | 费用/限流 | 备注 |
+|------|-------------|------|---------|----------|------|
+| | | | API Key/OAuth/无 | | |
+
+### 7.3 中间件 & 基础设施
+
+| 组件 | 用途 | 使用方式 | 关键配置 | 备注 |
+|------|------|---------|---------|------|
+| | 消息队列/缓存/搜索/存储... | | | |
+
+### 7.4 内部跨模块依赖
+
+> 本 Capability 需要调用项目内其他模块的能力（注意：仅声明依赖，不设计对方逻辑）
+
+| 依赖模块 | 调用接口/方法 | 输入 | 预期输出 | 当前状态 |
+|---------|-------------|------|---------|--------|
+| | | | | 已有/待建 |
+
+### 7.5 环境 & 权限要求
+
+| 依赖项 | 说明 | 获取方式 |
+|-------|------|--------|
+| 环境变量 | | |
+| 密钥/证书 | | |
+| 网络策略 | | |
+| 权限/角色 | | |
+
+---
+
+## 8. 异常处理
+
+### 8.1 异常分类
+
+| 异常类型 | 触发条件 | 处理策略 | 用户感知 |
+|---------|---------|---------|---------|
+| 参数校验异常 | | 返回错误码 | |
+| 业务逻辑异常 | | | |
+| 外部依赖异常 | | 降级/重试 | |
+
+### 8.2 重试与降级
+
+- 重试次数：
+- 重试间隔：
+- 降级策略：
+
+---
+
+## 9. 局部配置
+
+### 9.1 业务配置
+
+| 配置项 | 配置 Key | 默认值 | 说明 |
+|-------|---------|-------|------|
+| | | | |
+
+### 9.2 开关配置
+
+| 开关 | 用途 | 默认状态 |
+|-----|------|---------|
+| | | |
+
+---
+
+> **质量红线检查清单**
+> - [ ] **现有代码锚点已标注**：需修改的文件、类、方法已明确（或确认为纯新建）
+> - [ ] **现有约束已识别**：影响设计的现有系统约束已列出并有应对策略
+> - [ ] **字段完整性**：字段追溯表已完成，无无故丢弃字段
+> - [ ] **边界遵守**：无越权设计其他 Capability 的逻辑
+> - [ ] **全局遵守**：遵循 overview.md 的数据字典和接口规范
+> - [ ] 前端设计已完成（组件、状态、路由、交互）
+> - [ ] 后端接口已完成（路径、参数、响应、逻辑）
+> - [ ] 数据模型已完成（表结构、索引、缓存）
+> - [ ] **外部依赖已明确**：所有外部服务、第三方 API、中间件、跨模块依赖已列出
+> - [ ] **环境权限已确认**：所需环境变量、密钥、网络策略已说明
+> - [ ] 异常处理策略已定义（含外部依赖失败的降级方案）
+> - [ ] 包含足够的局部细节支持任务拆解

package/templates/openspec/overview.md

@@ -0,0 +1,143 @@
+# 架构总览与全局契约
+
+> **定位**：全局宪法，所有局部设计都必须遵守
+> 
+> **⚠️ AI 读取指令**：在执行任何 `/opsx:design` 或 `/opsx:task` 时，必须首先读取本文档作为全局约束基线。
+
+---
+
+## 1. 全局数据字典
+
+> 强制约定核心数据类型，所有 Capability 的设计必须遵守
+
+### 1.1 主键与标识符规范
+
+| 标识符类型 | 数据类型 | 格式要求 | 示例 |
+|-----------|---------|---------|------|
+| 用户ID | 字符串 | UUID v4 | `550e8400-e29b-41d4-a716-446655440000` |
+| 业务主键 | 字符串/数字 | 根据业务定义 | |
+| 外部关联ID | 字符串 | 与外部系统一致 | |
+
+### 1.2 通用字段规范
+
+| 字段名 | 数据类型 | 精度/格式 | 说明 |
+|-------|---------|----------|------|
+| 金额字段 | 数字 | 精确到分（整数存储） | 以最小货币单位存储 |
+| 时间戳 | 字符串/数字 | ISO 8601 / Unix毫秒 | 统一时区处理 |
+| 逻辑删除 | 布尔 | `is_deleted` | 默认 false |
+| 创建时间 | 时间戳 | `created_at` | 自动填充 |
+| 更新时间 | 时间戳 | `updated_at` | 自动更新 |
+| 创建人 | 字符串 | `created_by` | 用户ID |
+| 更新人 | 字符串 | `updated_by` | 用户ID |
+
+### 1.3 枚举值规范
+
+| 枚举类型 | 可选值 | 说明 |
+|---------|-------|------|
+| 状态枚举 | | |
+| 类型枚举 | | |
+
+---
+
+## 2. 接口与通信规范
+
+### 2.1 统一返回体
+
+**成功响应**：
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": { /* 业务数据 */ }
+}
+```
+
+**失败响应**：
+```json
+{
+  "code": -1,
+  "msg": "错误描述",
+  "data": null
+}
+```
+
+### 2.2 分页请求/响应标准
+
+**请求参数**：
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|-----|------|------|-------|------|
+| page | 数字 | 否 | 1 | 页码（从1开始） |
+| pageSize | 数字 | 否 | 20 | 每页条数（最大100） |
+
+**响应结构**：
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "list": [],
+    "total": 100,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+### 2.3 错误码规范
+
+| 错误码范围 | 含义 |
+|-----------|------|
+| 0 | 成功 |
+| 1000-1999 | 参数校验错误 |
+| 2000-2999 | 业务逻辑错误 |
+| 3000-3999 | 权限错误 |
+| 4000-4999 | 外部服务错误 |
+| 5000-5999 | 系统内部错误 |
+
+---
+
+## 3. 共享跨域实体
+
+> 仅存放会被多个 Capability 跨域引用的极简核心实体
+
+### 3.1 用户基础信息
+
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| userId | 字符串 | 用户唯一标识 |
+| username | 字符串 | 用户名 |
+| avatar | 字符串 | 头像URL |
+
+### 3.2 其他共享实体
+
+<!-- 根据项目需要添加 -->
+
+---
+
+## 4. 跨能力域依赖约定
+
+### 4.1 模块间调用规范
+
+| 调用方式 | 适用场景 | 约束 |
+|---------|---------|------|
+| 内部API调用 | 同步依赖 | 必须走网关 |
+| 事件驱动 | 异步解耦 | 定义事件契约 |
+| 共享数据库 | 强一致性 | 仅限核心表 |
+
+### 4.2 模块依赖图
+
+```
+[Capability A] --> [Capability B]
+      |
+      v
+[Capability C]
+```
+
+---
+
+> **质量红线检查清单**
+> - [ ] 所有通用字段已定义类型和精度
+> - [ ] API 返回体结构已统一
+> - [ ] 分页标准已定义
+> - [ ] 错误码规范已制定
+> - [ ] 跨域共享实体已精简（仅保留必要字段）

package/templates/openspec/proposal.md

@@ -0,0 +1,108 @@
+---
+# 【用户选择配置 - 由 /opsx:propose 引导填写】
+mode: ""           # full=每个能力域独立文档(specs/<capability>/*), simple=单一文档(spec.md/design.md/tasks.md)
+test-strategy: "" # tdd=测试先行, impl-first=实现优先, none=无测试
+---
+
+# proposal.md - 业务意图与上下文总览
+
+> **定位**：变更的业务意图（Why）与上下文总览
+>
+> **可选性**：【可跳过，直入spec】若跳过，必须将"影响范围"在 specs 中补齐
+
+---
+
+## 1. 需求背景
+
+<!-- 描述本次变更的业务背景、痛点或机会 -->
+
+### 1.1 现状问题
+-
+
+### 1.2 业务诉求
+-
+
+---
+
+## 2. 业务目标
+
+<!-- 明确本次变更要达成的业务目标，建议用 SMART 原则描述 -->
+
+| 目标维度 | 具体描述 | 验收标准 |
+|---------|---------|---------|
+| 功能目标 | | |
+| 性能目标 | | |
+| 体验目标 | | |
+
+---
+
+## 3. 能力分解
+
+<!-- 【关键章节】此处定义的 capability 决定后续 specs/ 的文件结构 -->
+
+### 3.1 新增能力
+<!-- 每个能力会创建 specs/<name>/spec.md，使用 kebab-case 命名 -->
+- `<capability-name>`: <能力简要描述>
+
+### 3.2 修改能力
+<!-- 仅当已有能力的需求级别变更时填写，检查 openspec/specs/ 现有规格 -->
+- `<existing-name>`: <修改什么需求>
+
+---
+
+## 4. 影响范围
+
+<!-- 【质量红线】逻辑链路必须闭环，明确定义哪些模块受影响 -->
+
+### 4.1 涉及模块
+- [ ] 模块A：影响描述
+- [ ] 模块B：影响描述
+
+### 4.2 依赖关系
+```
+[上游依赖] --> [本变更] --> [下游影响]
+```
+
+### 4.3 数据影响
+- 数据库表变更：
+- 接口变更：
+- 配置变更：
+
+---
+
+## 5. 约束与假设
+
+### 5.1 业务约束
+-
+
+### 5.2 技术约束
+-
+
+### 5.3 前置依赖
+- [ ] 依赖项1：状态
+- [ ] 依赖项2：状态
+
+---
+
+## 6. 风险评估
+
+| 风险项 | 概率 | 影响 | 应对策略 |
+|-------|------|------|---------|
+| | | | |
+
+---
+
+## 7. 相关文档
+
+- 需求文档：
+- 原型链接：
+- 参考文档：
+
+---
+
+> **质量红线检查清单**
+> - [ ] 逻辑链路已闭环
+> - [ ] 受影响模块已明确
+> - [ ] 依赖关系已梳理
+> - [ ] 若跳过本文档，影响范围已在 specs 中补齐
+> - [ ] 能力分解章节已明确列出所有能力

package/templates/openspec/spec.md

@@ -0,0 +1,185 @@
+# spec.md - 能力规格定义
+
+> **定位**：单个能力（capability）的技术规格定义，用于 `specs/<capability>/spec.md`
+>
+> **【质量红线】严禁描述模糊；约束必须量化；缺失必要参数时 opsx-check 必须报错拦截
+>
+>> **【格式要求】** 需求项使用 `####`（4个#），场景必须使用 `#####`（5个#）
+
+---
+
+## 1. 需求规格（官方格式）
+
+<!-- 此章节遵循 openspec 官方格式，用于与 CLI 工具兼容 -->
+
+### 新增需求
+
+<!-- 新增的需求，使用「必须」强制要求 -->
+
+#### 需求项：<!-- 需求名称 -->
+
+<!-- 需求描述，使用「必须」而非「应该」「可以」 -->
+系统必须 ...
+
+##### 场景：<!-- 场景名称 -->
+- **当** <!-- 触发条件 -->
+- **预期** <!-- 预期结果 -->
+
+##### 场景：<!-- 另一个场景 -->
+- **当** <!-- 触发条件 -->
+- **预期** <!-- 预期结果 -->
+
+### 修改需求
+
+<!-- 仅当修改已有需求时使用，必须复制完整原需求内容再修改 -->
+
+#### 需求项：<!-- 已有需求名称 -->
+系统必须 ...
+
+##### 场景：<!-- 场景名称 -->
+- **当** <!-- 触发条件 -->
+- **预期** <!-- 预期结果 -->
+
+### 移除需求
+
+<!-- 仅当移除已有需求时使用 -->
+
+#### 需求项：<!-- 被移除的需求名称 -->
+**移除原因**：<!-- 移除原因 -->
+**迁移方案**：<!-- 迁移方案 -->
+
+---
+
+## 2. 技术契约（SDD 扩展）
+
+<!-- 【SDD 扩展】此章节定义具体的技术实现契约，代码生成的"唯一真理" -->
+
+### 2.1 接口定义
+
+#### 接口基本信息
+- **路径**：`/api/v1/xxx`
+- **方法**：GET/POST/PUT/DELETE
+- **内容类型**：application/json
+
+#### 请求参数
+<!-- 【质量红线】所有参数必须有类型、必填标识、取值范围/示例 -->
+
+| 参数名 | 类型 | 必填 | 说明 | 示例值 | 约束条件 |
+|-------|------|------|------|--------|----------|
+| | | | | | |
+
+#### 响应结构
+
+**成功响应 (200)**
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    // 详细字段定义
+  }
+}
+```
+
+**错误响应**
+```json
+{
+  "code": -1,
+  "message": "错误描述",
+  "data": null
+}
+```
+
+#### 错误码定义
+| 错误码 | 含义 | 触发条件 |
+|-------|------|----------|
+| | | |
+
+---
+
+## 3. 物理约束
+
+<!-- 【质量红线】所有约束必须量化 -->
+
+### 3.1 性能约束
+| 指标 | 约束值 | 说明 |
+|------|-------|------|
+| 响应时间 | < X 毫秒 (P99) | |
+| 吞吐量 | > X QPS | |
+| 并发数 | 最大 X | |
+
+### 3.2 资源约束
+| 资源 | 限制 | 说明 |
+|------|------|------|
+| 内存 | < X MB | |
+| CPU | < X% | |
+| 存储 | < X GB | |
+
+### 3.3 超时配置
+- 连接超时：X 毫秒
+- 读取超时：X 毫秒
+- 总超时：X 毫秒
+
+---
+
+## 4. 影响模块
+
+<!-- 若跳过 proposal.md，必须在此补齐影响范围 -->
+
+### 4.1 内部依赖
+- [ ] 服务A：调用方式、用途
+- [ ] 服务B：调用方式、用途
+
+### 4.2 外部依赖
+<!-- 【质量红线】技术选型必须包含版本信息 -->
+
+| 组件类型 | 组件名称 | 版本 | 用途 | 降级策略 |
+|---------|---------|------|------|---------|
+| 框架 | | | | |
+| 数据库 | | | | |
+| 缓存 | | | | |
+| 消息队列 | | | | |
+| 第三方 SDK | | | | |
+
+### 4.3 数据存储
+- [ ] 数据库（版本 X.x）：表名、操作类型
+- [ ] 缓存（版本 X.x）：Key 模式、过期时间
+
+---
+
+## 5. 安全与合规
+
+### 5.1 权限要求
+- 认证方式：
+- 授权范围：
+
+### 5.2 数据安全
+- 敏感字段：
+- 加密要求：
+
+### 5.3 审计要求
+- 日志记录：
+- 操作追踪：
+
+---
+
+## 6. 兼容性
+
+### 6.1 接口兼容性
+- 是否向后兼容：是/否
+- 版本控制策略：
+
+### 6.2 数据兼容性
+- 数据迁移方案：
+- 回滚策略：
+
+---
+
+> **质量红线检查清单**
+> - [ ] 每个需求项至少有一个场景
+> - [ ] 使用「必须」强制要求，而非「应该」「可以」
+> - [ ] 所有接口参数已量化（类型、必填、范围、示例）
+> - [ ] 物理约束已量化（并发、超时、性能指标）
+> - [ ] 错误码已定义
+> - [ ] **技术选型已包含版本信息**（框架、数据库、缓存、中间件等）
+> - [ ] 若跳过 proposal.md，影响范围已在此补齐