issuekit 0.1.0__py3-none-any.whl

issuekit/bundled_templates/technical-design.md

@@ -0,0 +1,279 @@
+# {Issue ID} - 技术方案
+
+> **状态**: 草稿 / 评审中 / 已确认
+> **作者**: {姓名}
+> **日期**: {YYYY-MM-DD}
+> **关联需求**: [需求文档](./requirement.md)
+
+---
+
+## 1. 概述
+
+{一段话描述技术方案要解决的问题、整体思路和关键技术选型}
+
+---
+
+## 2. 现状分析
+
+### 2.1 现有架构
+
+{描述相关模块的当前实现，配 Mermaid 图}
+
+### 2.2 现有问题
+
+{如果是优化/修复，描述现有问题。纯新功能可写"不适用"。}
+
+---
+
+## 3. 技术调研
+
+{如果方案涉及技术未知项或需要决策的选型，在此记录调研结论。如果方案清晰无未知项，注明"本次方案无技术未知项，跳过调研"。}
+
+### 3.1 {调研主题1}
+
+**背景**: {为什么需要调研}
+
+**结论**: {选择了什么}
+
+**理由**: {为什么选这个}
+
+**替代方案**:
+
+| 方案 | 优点 | 缺点 | 不选择的原因 |
+|------|------|------|------------|
+| {方案A} | {优点} | {缺点} | {原因} |
+| {方案B} | {优点} | {缺点} | {原因} |
+
+### 3.2 {调研主题2}
+
+{同上格式...}
+
+---
+
+## 4. 方案设计
+
+### 4.1 整体架构
+
+{整体技术方案描述，配 Mermaid 架构图}
+
+### 4.2 核心流程
+
+{用 Mermaid sequenceDiagram 展示关键处理路径的完整调用链}
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant Ctrl as Controller
+    participant Mgr as Manager
+    participant Svc as Service
+    participant DB as Database
+
+    C->>Ctrl: 请求
+    Ctrl->>Mgr: 调用业务
+    Mgr->>Svc: 查询数据
+    Svc->>DB: SQL
+    DB-->>Svc: 结果
+    Svc-->>Mgr: 数据
+    Mgr-->>Ctrl: 业务结果
+    Ctrl-->>C: 响应
+```
+
+### 4.3 组件设计
+
+#### 4.3.1 {组件名称1}
+
+**职责**: {一句话描述}
+
+**关键逻辑**:
+{详细描述处理流程、校验规则、状态变更等核心逻辑}
+
+**注意事项**:
+- {特殊点，如安全配置、拦截器排除、线程安全等}
+
+#### 4.3.2 {组件名称2}
+
+{同上格式...}
+
+### 4.4 接口设计
+
+#### `{METHOD} {PATH}` — {接口说明}
+
+**请求**:
+
+| 项目 | 说明 |
+|------|------|
+| Content-Type | application/json |
+| 认证 | 需要 / 不需要 |
+
+**Headers**（如有特殊 Header）:
+
+| Header | 说明 |
+|--------|------|
+| {header-name} | {说明} |
+
+**请求体**:
+
+```json
+{
+  "field1": "value1",
+  "field2": 123
+}
+```
+
+**响应**:
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "field1": "value1"
+  }
+}
+```
+
+**响应参数**:
+
+| 字段   | 类型    | 说明       |
+|--------|--------|------------|
+| field1 | string | 示例字段（枚举） |
+
+**错误处理**:
+
+| 场景 | 处理方式 | 响应码 | 日志级别 |
+|------|---------|--------|---------|
+| {场景1} | {处理} | {code} | INFO/WARN/ERROR |
+| {场景2} | {处理} | {code} | INFO/WARN/ERROR |
+
+**处理流程**:
+
+```mermaid
+flowchart TD
+    A[收到请求] --> B{校验参数}
+    B -->|通过| C[业务处理]
+    B -->|失败| D[返回错误]
+    C --> E[返回成功]
+```
+
+#### `{METHOD} {PATH2}` — {接口说明2}
+
+{同上格式...}
+
+### 4.5 数据模型
+
+#### 新增表: {table_name}
+
+| 列名 | 类型 | 可空 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | bigint | NO | auto_increment | 主键 |
+| {字段} | {类型} | {YES/NO} | {默认值} | {说明} |
+
+**索引**:
+
+| 索引名 | 列 | 类型 | 说明 |
+|--------|-----|------|------|
+| {idx_name} | {columns} | UNIQUE/NORMAL | {说明} |
+
+#### 修改表: {table_name}
+
+```sql
+ALTER TABLE {table_name} ADD COLUMN {column} {type} {constraints} COMMENT '{说明}';
+```
+
+#### 数据初始化
+
+```sql
+INSERT INTO {table_name} (...) VALUES (...);
+```
+
+### 4.6 配置变更
+
+> 同一功能的相关配置项建议合并为一个 json 字段；不相关的配置，使用不同key；{value}给出具体值。
+
+| 操作   | 配置项           | 值                                      | 说明                  |
+|--------|------------------|------------------------------------------|-----------------------|
+| 新增   | featureX_config  | {"paramA": "value1", "paramB": "value2"} | 功能 X 的相关配置合并 |
+| 修改   | unrelated_key    | true                                    | 其他不相关配置项      |
+
+### 4.7 项目结构
+
+**新增文件**:
+
+| 文件 | 模块 | 说明 |
+|------|------|------|
+| {文件名.java} | {web/controller} | {说明} |
+| {文件名.java} | {biz/manager} | {说明} |
+
+**修改文件**:
+
+| 文件 | 模块 | 变更内容 |
+|------|------|---------|
+| [文件名](path/File.java) | {模块} | {变更描述} |
+
+**SQL 文件**:
+
+| 文件 | 说明 |
+|------|------|
+| sql/{issue-id}.sql | {说明} |
+
+---
+
+## 5. 影响分析
+
+### 5.1 功能影响
+
+| 功能/流程 | 影响程度 | 说明 |
+|----------|---------|------|
+| {功能} | 无影响/需回归/有风险 | {说明} |
+
+### 5.2 性能影响
+
+{QPS 预估、DB 查询复杂度、缓存策略}
+
+### 5.3 兼容性
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| API 向后兼容 | 兼容/不兼容/不适用 | {说明} |
+| 数据库迁移安全 | 安全/有风险/不适用 | {说明} |
+| 客户端版本兼容 | 兼容/不兼容/不适用 | {说明} |
+
+---
+
+## 6. 风险评估
+
+| 风险 | 概率 | 影响 | 应对措施 |
+|------|------|------|---------|
+| {风险} | 高/中/低 | {影响} | {措施} |
+
+---
+
+## 7. 开发步骤
+
+*按执行顺序排列，可直接作为开发者的实操指南。*
+
+### Step 1: {步骤标题}
+
+{具体操作说明、代码片段、SQL 脚本等}
+
+### Step 2: {步骤标题}
+
+{具体操作说明}
+
+### Step N: 验证
+
+**本地验证**:
+1. {验证步骤1}
+2. {验证步骤2}
+
+**集成验证**:
+1. {验证步骤1}
+2. {验证步骤2}
+
+---
+
+## 变更记录
+
+| 版本 | 日期 | 变更人 | 变更内容 | 原因 |
+|------|------|--------|---------|------|
+| v1.0 | {日期} | {姓名} | 初稿 | - |

issuekit/bundled_templates/test-plan.md

@@ -0,0 +1,250 @@
+# {Issue ID} - 测试方案
+
+> **状态**: 草稿 / 评审中 / 执行中 / 已完成
+> **作者**: {姓名}
+> **日期**: {YYYY-MM-DD}
+> **关联需求**: [需求文档](./requirement.md)
+> **关联方案**: [技术方案](./technical-design.md)
+
+---
+
+## 1. 测试概览
+
+### 1.1 测试范围
+
+{描述本次测试覆盖的功能范围，基于需求文档和技术方案}
+
+### 1.2 需求-测试覆盖矩阵
+
+| # | 需求点 | 验收标准 | 黑盒用例 | 白盒用例 |
+|---|--------|---------|---------|---------|
+| R1 | {需求描述} | {验收条件} | BIZ-01,02 | UT-01, API-01 |
+| R2 | {需求描述} | {验收条件} | BIZ-03 | UT-02, API-02 |
+
+### 1.3 测试用例脑图
+
+{用 Mermaid mindmap 展示完整测试用例树状结构，一眼看清全貌}
+
+```mermaid
+mindmap
+  root(("{Issue ID} 测试方案"))
+    业务功能测试（黑盒）
+      场景1: {场景名称}
+        BIZ-01 {正常场景}
+        BIZ-02 {异常场景}
+        BIZ-03 {边界场景}
+      场景2: {场景名称}
+        BIZ-04 {正常流程}
+        BIZ-05 {异常分支}
+      场景N: ...
+    单测接口测试（白盒）
+      单元测试
+        {ClassName1}
+          UT-01 {场景}
+          UT-02 {场景}
+        {ClassName2}
+          UT-03 {场景}
+      接口测试
+        {METHOD PATH1}
+          API-01 {场景}
+          API-02 {场景}
+        {METHOD PATH2}
+          API-03 {场景}
+```
+
+---
+
+## 2. 业务功能测试（黑盒）
+
+从用户/运营人员的视角出发，验证每个功能的输入和可观察输出是否符合需求。
+
+> **用例数量策略**: 核心且复杂的场景 → 全面覆盖（所有分支/边界/并发/组合）；辅助场景 → happy path + 主要错误路径
+
+### 2.1 场景清单
+
+| # | 场景名称 | 用户角色 | 优先级 | 用例数 |
+|---|---------|---------|--------|--------|
+| 1 | {场景} | {角色} | P0/P1/P2 | {N} |
+
+### 2.2 业务功能测试用例
+
+> 格式说明：按用户场景分组。每个场景的所有用例（正常/异常/边界）放在同一张表中。
+> 「输入」列描述用户动作（点击按钮、打开页面、选择选项、提交表单等）。
+> 「预期结果」列描述所有可观察的输出（页面展示、提示信息、接口返回值、数据库记录、日志、推送通知等）。
+
+#### 场景 1: {场景名称}
+
+| # | 类型 | 前置条件 | 输入（用户操作） | 预期结果（可观察输出） | 验证点 |
+|---|------|---------|----------------|---------------------|--------|
+| BIZ-01 | 正常 | {用户/数据状态} | {操作描述：点击XX按钮/打开XX页面/提交XX表单} | {页面展示内容/Toast提示/接口返回/DB记录/推送消息} | {需要校验的关键点} |
+| BIZ-02 | 正常 | {状态} | {操作描述} | {预期结果} | {验证点} |
+| BIZ-03 | 异常 | {状态} | {操作描述} | {错误提示/阻止操作/降级行为} | {验证点} |
+| BIZ-04 | 边界 | {边界状态} | {操作描述} | {预期结果} | {验证点} |
+
+#### 场景 2: {场景名称} — 多步骤流程
+
+**完整流程**:
+
+| 步骤 | 操作者 | 输入（用户操作） | 预期结果（可观察输出） | 数据状态变化 |
+|------|--------|----------------|---------------------|-------------|
+| 1 | {角色} | {操作} | {结果} | {DB/缓存变化} |
+| 2 | {角色} | {操作} | {结果} | {DB/缓存变化} |
+| 3 | {角色} | {操作} | {结果} | {最终状态} |
+
+**异常分支**:
+
+| # | 在步骤X后 | 输入（异常操作） | 预期结果 | 验证点 |
+|---|----------|----------------|---------|--------|
+| BIZ-05 | 步骤{N}后 | {异常操作} | {错误提示/阻止} | {验证点} |
+| BIZ-06 | 步骤{N}后 | {并发/重复操作} | {幂等结果/提示} | {验证点} |
+
+{继续按场景分组列出所有业务功能测试用例...}
+
+### 2.3 业务功能测试汇总
+
+| 指标 | 数值 |
+|------|------|
+| 覆盖场景数 | {N} |
+| 正常路径用例 | {N} |
+| 异常路径用例 | {N} |
+| 边界条件用例 | {N} |
+| 多步骤流程用例 | {N} |
+
+---
+
+## 3. 单测接口测试（白盒）
+
+从代码实现的视角验证核心方法和 API 端点的正确性。
+
+### 3.1 可测试性重构建议
+
+{如果发现方法内部混合了业务逻辑和数据查询/外部调用，建议拆分为纯函数}
+
+| # | 现有方法 | 问题 | 重构建议 | 收益 |
+|---|---------|------|---------|------|
+| 1 | [Class#method](path/File) | 方法内部包含 DB 查询，无法独立测试 | 提取纯计算逻辑到 `calculateXxx(data)` 方法，接受预查询数据作为参数 | 可直接单元测试，无需 Mock |
+| 2 | [Class#method](path/File) | 循环内逐条查询数据库 | 改为循环外批量查询，传入 Map/List 到计算方法 | 性能提升 + 可测试 |
+
+### 3.2 单元测试
+
+核心业务方法的单元测试，优先测试纯函数和可隔离的业务逻辑。
+
+#### 测试对象清单
+
+| # | 类 | 方法 | 代码位置 | 职责说明 | 重要度 | 复杂度 | 用例数 |
+|---|-----|------|---------|---------|--------|--------|--------|
+| 1 | {ClassName} | {methodName} | [链接](path/File) | {职责} | 核心/辅助 | 高/中/低 | {N} |
+
+> **用例数量策略**: 核心+高复杂度 → 全面覆盖（≥8 用例，含所有分支/边界/并发/组合）；核心+中复杂度 → 标准覆盖（4-6 用例）；辅助/低复杂度 → 基础覆盖（2-3 用例，happy path + 主要错误路径）
+
+#### 测试代码注释规范
+
+> 生成测试代码时必须遵循以下注释规范：
+>
+> 1. **测试类 Javadoc**: 说明被测类、覆盖的核心方法列表、测试策略（纯函数直接测试 / Mock 集成测试）
+> 2. **分组注释**: 同一被测方法的用例用 `// ===== 方法名 — 职责描述 =====` 分隔
+> 3. **每个 @Test 方法**: 必须包含以下注释内容（写在方法体内部，不用 Javadoc）
+>    - **场景**: 一句话描述测试的业务场景
+>    - **前置条件**: Mock 设置或数据准备的业务含义（不是罗列代码）
+>    - **预期结果**: 期望的业务行为和关键断言点
+>    - **验证重点**: 需要 verify 的关键调用（如有）
+> 4. 辅助方法（buildXxx / mockXxx）需注释说明用途和参数含义
+
+#### 单元测试用例
+
+> 按被测方法分组，每个方法的所有用例放在同一个表格中。
+> 表格列根据方法签名动态调整：输入参数列 + 预期结果列。
+
+##### {ClassName}#{methodName1} — {职责描述}
+
+> 被测方法: `{methodName1}({参数类型列表})`
+> 用例数: {N}
+
+| # | 场景 | {参数1} | {参数2} | ... | 预期返回/状态 | 备注 |
+|---|------|---------|---------|-----|-------------|------|
+| UT-01 | {正常场景} | {值} | {值} | ... | {预期} | - |
+| UT-02 | {边界场景} | {值} | {值} | ... | {预期} | {说明} |
+| UT-03 | {异常场景} | null | {值} | ... | 抛出 {Exception} | - |
+
+##### {ClassName}#{methodName2} — Mock 集成测试
+
+> Mock 依赖: `{Service1}`, `{Service2}`
+> 用例数: {N}
+
+| # | 场景 | Mock 设置 | 调用参数 | 预期返回 | verify 断言 |
+|---|------|----------|---------|---------|------------|
+| UT-04 | {场景} | {Mock行为} | {参数} | {预期} | {verify调用} |
+
+{继续按方法分组列出所有单元测试用例表格...}
+
+#### 单元测试汇总
+
+| 指标 | 数值 |
+|------|------|
+| 覆盖核心方法数 | {N} |
+| 正常路径用例 | {N} |
+| 边界条件用例 | {N} |
+| 异常路径用例 | {N} |
+
+### 3.3 接口测试
+
+针对所有新增/修改的 API 端点，验证请求-响应契约和业务规则。
+
+#### API 端点清单
+
+| # | 方法 | 路径 | 说明 | 变更类型 |
+|---|------|------|------|---------|
+| 1 | POST | /api/xxx | {说明} | 新增/修改 |
+
+#### 接口测试用例
+
+> 按 API 端点分组，同一端点的所有测试场景放在同一个表格中。
+
+##### `{METHOD} {PATH}` — {接口说明}
+
+> 处理方法: [Controller#method](path/File)
+
+| # | 场景 | 前置数据 | 请求体（输入） | 预期 code | 预期 data（输出） | DB 断言 | 备注 |
+|---|------|---------|-------------|----------|-----------------|--------|------|
+| API-01 | 正常请求 | {数据} | `{json}` | 0 | {关键字段} | {断言} | - |
+| API-02 | 参数校验失败 | - | `{json}` | {错误码} | - | 无变更 | - |
+| API-03 | 业务规则违反 | {特定状态} | `{json}` | {错误码} | - | 无变更 | {说明} |
+| API-04 | 权限校验 | - | 无 token | 401 | - | - | - |
+
+{继续按端点分组列出所有接口用例表格...}
+
+#### 接口测试汇总
+
+| 指标 | 数值 |
+|------|------|
+| 覆盖 API 端点数 | {N} |
+| 成功路径用例 | {N} |
+| 参数校验用例 | {N} |
+| 业务规则用例 | {N} |
+| 权限校验用例 | {N} |
+
+---
+
+## 4. 测试执行计划
+
+### 4.1 执行优先级
+
+| 优先级 | 用例范围 | 执行时机 | 预估耗时 |
+|--------|---------|---------|---------|
+| P0 | 黑盒核心场景 + 白盒核心方法单测 | 开发中持续运行 | {N}h |
+| P1 | 黑盒全部场景 + 接口测试 | 功能开发完成后 | {N}h |
+| P2 | 黑盒边界/并发 + 回归测试 | QA 测试阶段 | {N}h |
+
+### 4.2 回归测试范围
+
+{列出需要回归验证的现有功能}
+
+| 功能 | 回归原因 | 验证方式 |
+|------|---------|---------|
+| {功能} | {受影响原因} | 黑盒场景 / 接口测试 |
+
+## 变更记录
+
+| 版本 | 日期 | 变更人 | 变更内容 | 原因 |
+|------|------|--------|---------|------|
+| v1.0 | {日期} | {姓名} | 初稿 | - |

issuekit/cli.py

@@ -0,0 +1,97 @@
+"""IssueKit 命令行入口。"""
+
+import os
+import sys
+
+os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+import typer
+
+from issuekit.commands.init import init as init_cmd
+from issuekit.agents import AGENT_REGISTRY
+
+SUPPORTED_AI = ", ".join(AGENT_REGISTRY.keys())
+
+INIT_USAGE = (
+    "\n用法示例:\n"
+    "  issuekit init --ai cursor\n"
+    "  issuekit init --ai claude\n"
+    "  issuekit init --ai cursor --force\n"
+)
+
+
+class ChineseErrorGroup(typer.core.TyperGroup):
+    """拦截 Click 层的参数解析错误，替换为中文提示。"""
+
+    def parse_args(self, ctx, args):
+        try:
+            return super().parse_args(ctx, args)
+        except SystemExit:
+            raise
+
+
+app = typer.Typer(
+    name="issuekit",
+    help="AI 辅助开发的 Issue 全生命周期工具。",
+    no_args_is_help=True,
+)
+
+
+@app.command("init")
+def init(
+    ai: str = typer.Option(
+        None,
+        help=f"指定 AI 助手：{SUPPORTED_AI}",
+    ),
+    issues_dir: str = typer.Option(
+        "issues",
+        "--issues-dir",
+        help="Issue 文档存放目录（相对项目根目录，默认：issues）",
+    ),
+    here: bool = typer.Option(
+        True,
+        "--here/--no-here",
+        help="在当前目录初始化（默认：是）",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="如果 .issuekit/ 已存在，强制覆盖",
+    ),
+):
+    """在项目中初始化 IssueKit。
+
+    安装文档模板、AI 助手命令和知识库配置。
+
+    用法示例:
+        issuekit init --ai cursor
+        issuekit init --ai cursor --issues-dir doc/issues
+        issuekit init --ai cursor --force
+    """
+    if not ai:
+        from rich.console import Console
+        console = Console()
+        console.print(
+            f"[red]错误:[/red] 缺少必需参数 --ai\n"
+            f"[dim]支持的选项:[/dim] {SUPPORTED_AI}"
+            f"{INIT_USAGE}"
+        )
+        raise typer.Exit(2)
+    init_cmd(ai=ai, issues_dir=issues_dir, here=here, force=force)
+
+
+@app.command("version")
+def version():
+    """显示 IssueKit 版本号。"""
+    from issuekit import __version__
+    typer.echo(f"issuekit {__version__}")
+
+
+def main():
+    app()