# devTestPlat

**Repository Path**: sky-painting/devTestPlat-java

## Basic Information

- **Project Name**: devTestPlat
- **Description**: 云蝶AI产研平台的Java端
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2026-07-05
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 devTestPlat

> 面向研发全链路的 AI 研发测试平台：从需求生成、原型设计、验收交付，到技术方案、开发任务、接口测试与自动化回归，一条链路打通。

[English](README.en.md) | 简体中文

![Java](https://img.shields.io/badge/Java-17-blue?logo=java&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.5-green?logo=springboot&logoColor=white)
![Spring AI](https://img.shields.io/badge/Spring%20AI-1.0.5-purple)
![MySQL](https://img.shields.io/badge/MySQL-8.0+-4479A1?logo=mysql&logoColor=white)
![Redis](https://img.shields.io/badge/Redis-supported-DC382D?logo=redis&logoColor=white)
[![Maven](https://img.shields.io/badge/Maven-3.8+-lightgray?logo=maven&logoColor=black)](https://maven.apache.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)

---

## 📊 平台概述

**devTestPlat** 是一个基于 Spring Boot 3.5 + Spring AI 1.0 构建的研发测试一体化平台。它将「产品提需求 → AI 生成 PRD 与需求树 → 原型与流程图 → 验收 → 版本交付」「技术方案 → 仓库分支 → 开发任务 → 本地 Coding Agent 协作」和「接口文档 → 测试用例 → 自动化回归 → 报告告警」三条链路收敛到同一份数据模型上。AI 能力通过 Open API 与内部 API 双向接入，人负责决策与确认，AI 负责生成与重复劳动。

平台自身也是「被测对象」：内置的接口文档、用例生成、时序图能力可以直接作用于接入平台的任意应用。

### 项目架构

![Project Structure](assets/readme/project-structure.svg?raw=true)

---

## 🏗️ 模块划分

Maven 多模块工程，共 8 个模块：

| 模块 | 职责 |
|------|------|
| `api` | Web 层与应用入口。33 个 Controller、208 个接口端点，含拦截器、切面、定时任务、启动类 |
| `product` | 产品与研发管理域：需求、需求细化、原型、流程图、验收、交付、仓库、技术方案、开发任务、AI 会话 |
| `case` | 测试域：应用/端点/Token、测试用例、用例编排、定时回归任务、测试报告 |
| `user` | 用户域：用户、角色、权限、菜单模块、站内通知 |
| `interface_doc` | 接口文档域：接口文档、接口时序图 |
| `ai-core` | AI 能力底座：多模型路由、Prompt 管理、MCP Server 工具暴露 |
| `common` | 通用组件：统一响应、异常体系、操作日志枚举、Redis 缓存、Forest 调用器 |
| `example` | 示例应用（图书借阅系统），用于演示平台如何接入被测应用 |

依赖方向：`api` → (`product`, `case`, `user`, `interface_doc`, `ai-core`) → `common`

### 分层约定

```
controller (api 模块)
   └── manager   —— 跨域编排（可选层，仅复杂场景使用）
        └── service / service.impl   —— 业务逻辑，Web 与 Open API 共享
             └── dao (Mapper + dao/pojo) —— tk.mybatis BaseMapper + 35 份 Mapper XML
```

出入参统一放在各域的 `param/req`（DTO）与 `param/resp`（VO）包下，**不允许在 controller 层定义 VO/DTO**。

---

## ⚡ 核心能力

### 产品域：需求全链路

| 能力 | 说明 |
|------|------|
| **需求管理** | 需求支持 `parentId` 自关联形成需求树（单树 ≤ 100 节点）；通过 `demand_app` 关联表支持跨应用需求（N:N） |
| **AI 需求生成** | 输入原始需求描述，AI 产出 PRD Markdown + 需求树草稿，支持澄清问答、多版本草稿、审批落库、驳回重生成 |
| **需求细化** | 针对单个节点做定向修改，而非整树重生成。产出子树快照 + 变更清单（diff），由 Java 侧计算并在审批时本地事务应用 |
| **需求原型** | 三种类型：`AI_HTML`（AI 生成自包含 HTML）、`SCREENSHOT`（截图上传）、`EXTERNAL_LINK`（Figma 等外链）。支持从任意节点聚合查看其全部子孙节点的页面 |
| **原型微调** | 元素级自然语言指令定向修改页面，AI 只返回草稿，PM 确认后才事务替换；未涉及页面保证逐字节一致 |
| **业务流程图** | AI 生成 Mermaid 流程图 / 泳道图 / 时序图。泳道角色由 AI 按业务自由定义，判断不准时进入 `NEED_CLARIFY` 主动向 PM 提问 |
| **PRD 溯源** | 顶级需求节点保存完整 PRD 全文，并记录 `source_session_id` / `source_draft_version`，可回溯到具体 AI 草稿版本 |
| **验收管理** | 需求下挂验收项，支持简单通过/不通过、带结果说明、带附件证据三种粒度 |
| **交付管理** | 版本化交付，多需求打包发布，状态严格按状态机顺序推进，不可跳级或回退 |

### 测试域：用例与自动化

| 能力 | 说明 |
|------|------|
| **应用与端点管理** | 多应用、多环境端点、AppToken 自动保活 |
| **接口文档** | 接口文档录入与管理，支持 JSON 格式导入；配套 `skills/swaggerdoc` 上传器 |
| **接口时序图** | 基于接口调用链生成时序图，支持 PlantUML / JSON / ZIP 三种批量导入方式 |
| **测试用例** | 用例增删改查、导入导出、优先级/类型/期望结果建模，支持期望规则表达式 |
| **用例编排** | 多用例串成业务流程（`test_case_auto_flow`），节点间支持等待策略与数据转换（上游响应字段映射为下游入参） |
| **定时回归** | 定时任务批量执行用例，产出测试报告（`TestCaseAutoExeTask`，当前 `@Scheduled` 已注释，需按需开启） |
| **报告告警** | 报告异常时通过邮件 / 企业微信 / 钉钉 Webhook 推送（`TestCaseReportAlertTask`，可分渠道开关） |
| **AI 辅助** | 自然语言转期望表达式、测试结果 AI 判定 |

### 研发管理：技术方案到开发协作

| 能力 | 说明 |
|---|---|
| **Git 仓库管理** | 按应用维护 Git 仓库；已被技术方案分支引用的仓库不能删除。 |
| **技术方案管理** | 每个需求可按 `BACKEND`、`FRONTEND`、`MOBILE`、`MINI_PROGRAM`、`FULLSTACK`、`OTHER` 分别维护方案、版本、评审人与评审意见。 |
| **方案分支追溯** | 技术方案关联仓库、开发/基础分支、工程语言和 Commit SHA，形成需求到代码变更的追溯链。 |
| **开发任务管理** | 技术方案可拆分多个开发任务，支持负责人、优先级、工时、截止日期、看板状态流转与需求详情聚合。 |
| **AI 技术方案生成** | 依据需求、PRD、验收项、应用、仓库和接口上下文生成分端技术方案草稿；支持澄清、人工编辑、AI 微调、版本回溯、驳回重生成和审批事务落库。 |
| **技术方案交付包** | 正式方案沉淀 Markdown、接口文档、数据库 ER 图、核心流程图、SQL/配置/脚本、风险项和测试建议，并可导出 ZIP。 |
| **本地 Coding Agent 协作** | 本地 Agent 可拉取研发上下文，回写开发进度、自测、Commit 与 Review 结果；平台不直接操作开发者本地仓库。 |

### 平台能力

| 能力 | 说明 |
|------|------|
| **细粒度权限** | 菜单与按钮统一建模在 `module` 表（type: 0-目录 / 1-菜单 / 2-按钮）；`@RequiresPermission("demand:create")` 做按钮级校验；登录时只返回有权限的菜单树 |
| **权限缓存** | 用户/角色权限列表缓存到 Redis（`perm:user:{userId}:moduleIds`，TTL 300s），角色或用户变更时主动失效，Redis 故障自动降级查库 |
| **操作日志** | `@LogRecord` 注解 + SpEL 模板，业务代码零侵入，异步独立事务写入 `sys_operation_log`；当前 97 处注解覆盖全部写操作 |
| **实时推送** | SSE（`GET /userNotification/subscribe`）推送 `agent_status`、`prototype_status`、`new_notification` 事件，每用户单连接 |
| **统一响应** | 全局响应包装 + 全局异常处理，可按 URI 排除（流式接口、MCP 端点） |
| **API 文档** | Knife4j (OpenAPI3)，208 个端点全部带 `@ApiOperation(value, notes)` 与参数级 `@ApiParam` 描述 |

---

## 🔌 三通道 API 设计

同一套 Service 层，对外暴露三条职责与鉴权强度不同的通道：

| 维度 | Web 通道 | Open 通道 | 内部通道 |
|------|----------|-----------|----------|
| 面向 | 前端页面 | AI Agent / 外部系统 | Java ↔ Python Agent |
| 包路径 | `controller/web/**` | `controller/open/**` | — |
| 路径前缀 | `/product/**`、`/testcase/**` 等 | `/open/product/**`、`/open/interface-doc` | `/internal/agent/**`（Python 侧） |
| 鉴权注解 | `@ApiAuth(isWeb = true)` | `@ApiAuth(isOpen = true)` | Service Token |
| 鉴权方式 | 登录 Token（Header） | API Key 签名：`public-key` + `timestamp` + `sign`，5 分钟防重放窗口 | `Authorization: Bearer <service-token>` |
| 细粒度权限 | 支持 `@RequiresPermission` | 通过即放行 | 不适用 |
| 接口风格 | create/update 分离、分页查询 | saveOrUpdate 合并、全量列表、支持批量 | 会话与任务编排 |
| 幂等 | — | Header `Idempotency-Key` | — |

鉴权统一由 `ApiAuthInterceptor.preHandle()` 串联：无 `@ApiAuth` 放行 → 有 `@ApiAuth` 校验 Token → 有 `@RequiresPermission` 再校验权限，不通过返回 403。

---

## 🤖 AI 集成

### 多模型路由（ai-core）

通过 `ModelRouter` + `AiProviderAdapter` 抽象多家模型供应商，配置切换无需改代码：

- **DeepSeek** — `spring-ai-starter-model-deepseek`
- **阿里云通义千问 DashScope** — `spring-ai-alibaba-starter-dashscope` 1.0.0.2
- **Ollama** — 本地模型，另有 `OllamaNativeClient` / `OllamaInvoker`（Forest）作为原生调用兜底

### MCP Server

基于 `spring-ai-starter-mcp-server-webmvc`，以 SSE 传输把平台能力暴露为 MCP 工具，供外部 AI 客户端调用：

- `InterfaceDocMcpTools` — 接口文档查询
- `TestCaseMcpTools` — 测试用例查询与执行

端点：`/sse`（SSE 连接）、`/mcp/message`（消息通道）。

### Python Agent 协同

重活由独立的 Python Agent 工程承担，Java 负责会话管理、编排与审批落库。需求生成与技术方案生成分别使用独立会话和草稿模型，均遵循“草稿 → 人工确认 → 正式资产”的边界：

```
Java (product 模块)                        Python Agent
  AgentInternalApiClient  ──RestTemplate──▶  /internal/agent/**
  (Service Token + X-Trace-Id                  需求生成 / 需求细化
   + X-Operator-Id)                            原型生成 / 微调 / 流程图
                                                 技术方案 / 产物 / 风险 / 测试建议
                          ◀──Open API 签名──   /open/product/**（回写数据）
```

配置项：`agent.base-url`、`agent.service-token`、`agent.connect-timeout`、`agent.read-timeout`。

### 异步任务可靠性

AI 任务耗时长，采用四重兜底保证最终一致：

1. **SSE 实时推送** —— 加速前端感知
2. **前端轮询** —— 每 2~3s 查任务/会话状态，为主链路
3. **后端定时扫描** —— 兜底捞回超时的 `RUNNING` 任务（可配 `devplat.requirement-agent.poll-fixed-delay`，默认 15s）
4. **幂等键 + 唯一索引** —— `Idempotency-Key` 与 `uk_session_version(session_id, draft_version)` 防重复落库

### Skills 协作

`skills/` 目录下沉淀了三套可复用的 AI 工作流：

- `swaggerdoc` — 接口文档规范与上传器
- `interfaceSequence` — 接口时序图生成
- `testCaseGen` — 测试用例生成（每接口产出一个可解析 JSON，不绑定测试框架）

v1.2.0 还提供面向本地 Coding Agent 的平台协作 Skills，通过 Open API 读取或回写研发过程：

- `platform.fetch_dev_context` — 拉取需求、技术方案、任务、分支、验收项和研发规范，输出 `context.md` 与 `context.json`
- `platform.report_dev_progress` — 回写开发任务状态和进展
- `platform.report_self_test` — 回写本地自测命令、结论和报告
- `platform.report_commit` — 回写分支、Commit 与代码变更摘要
- `platform.report_review_result` — 回写 PR/MR、评审结论和意见

---

## 🔑 关键枚举与状态机

<details>
<summary>展开查看</summary>

**需求状态** `DemandStatusEnum`
`PENDING_REVIEW`(待评审) → `REVIEWED`(已评审) → `IN_DEVELOPMENT`(开发中) → `COMPLETED`(已完成)

**需求优先级** `DemandPriorityEnum`：`P0` 紧急 / `P1` 重要 / `P2` 一般（默认）/ `P3` 低 / `P4` 可延迟

**需求类型** `DemandTypeEnum`：`FEATURE` / `OPTIMIZATION` / `BUG` / `TECH_IMPROVEMENT`

**需求来源** `DemandSourceEnum`：`CUSTOMER_FEEDBACK` / `INTERNAL_PLAN` / `OPERATIONAL`

**验收项状态** `AcceptanceItemStatusEnum`：`PENDING` → `PASSED` | `FAILED`（仅允许从 PENDING 流转）

**交付版本状态** `DeliveryStatusEnum`（严格顺序，不可跳级/回退）
`PLANNING` → `IN_DEVELOPMENT` → `IN_TESTING` → `RELEASED` → `ARCHIVED`

**AI 会话状态** `RequirementAgentSessionStatusEnum`
```
draft ──run──▶ running ──▶ draft / awaiting_clarification / failed
awaiting_clarification ──提交澄清──▶ running
draft ──approve──▶ approved
draft ──reject──▶ rejected ──run──▶ running（草稿版本 +1）
```

**技术方案评审状态** `TechProposalReviewStatusEnum`
```
PENDING ──submit──▶ IN_REVIEW ──approve──▶ APPROVED
                         │
                         └──request changes──▶ CHANGES_REQUESTED ──submit──▶ IN_REVIEW
```

**开发任务状态** `DevTaskStatusEnum`
`TODO` → `IN_PROGRESS` → `IN_TESTING` → `DONE`

**AI 技术方案会话状态**
```
draft ──run──▶ running ──▶ awaiting_clarification / draft / failed
awaiting_clarification ──提交澄清──▶ running
draft ──reject──▶ rejected ──run──▶ running（草稿版本 +1）
draft ──approve──▶ approved（事务创建技术方案、产物、分支、任务、风险项与测试建议）
```

**原型类型**：`AI_HTML` / `SCREENSHOT` / `EXTERNAL_LINK`（NULL 表示无原型，创建后不可跨类型变更）

**原型任务类型**：`GENERATE` / `REGENERATE` / `FINETUNE` / `FLOW_GENERATE` / `FLOW_REGENERATE`

**原型任务状态**（微调链路）
```
PENDING → RUNNING → DRAFT ──apply──▶ DONE
                      │  └──cancel──▶ CANCELLED
                      └──失败──▶ FAILED
```
流程图链路额外引入 `NEED_CLARIFY`（等待 PM 澄清）。

**流程图类型**：`FLOWCHART` / `SWIMLANE` / `SEQUENCE`；生成范围 `NODE` / `SUBTREE`

**日志类型** `LogTypeEnum`：`user` / `app` / `endpoint` / `token` / `testcase` / `interface-doc` / `interface-uml` / `module` / `column-tags` / `auto-task` / `auto-flow` / `notification` / `demand` / `acceptance-item` / `delivery` / `demand-prototype` / `demand-prototype-flow` / `demand-refine`

**日志子类型** `LogSubTypeEnum`：`create` / `update` / `delete` / `updateStatus` / `execute` / `import` / `export` / `login`

</details>

---

## 🛠️ 快速开始

### 1. 环境要求

| 组件 | 版本 | 必需 |
|------|------|------|
| JDK | 17+ | ✅ |
| Maven | 3.8+ | ✅ |
| MySQL | 8.0+ | ✅ |
| Redis | 5.0+ | 权限缓存与登录态，建议开启 |
| Python Agent | — | AI 需求/原型能力所需，可选 |

### 2. 初始化数据库

```bash
mysql -uroot -p -e "CREATE DATABASE dev_plat DEFAULT CHARSET utf8mb4;"

# 基础表结构
mysql -uroot -p dev_plat < doc/v1.1.0/dev_plat.sql

# v1.2.0 研发管理、AI 技术方案与本地 Coding Agent 协作增量
mysql -uroot -p dev_plat < doc/v1.2.0/sql.sql
mysql -uroot -p dev_plat < doc/v1.2.0/20260903_add_tech_proposal_risk_test_tables.sql
mysql -uroot -p dev_plat < doc/v1.2.0/20260903_add_tech_proposal_agent_superpowers_fields.sql
mysql -uroot -p dev_plat < doc/v1.2.0/20260904_add_tech_proposal_type.sql
mysql -uroot -p dev_plat < doc/v1.2.0/local-coding-agent-skills.sql
mysql -uroot -p dev_plat < doc/v1.2.0/module-dev.sql
```

### 3. 修改配置

编辑 `api/src/main/resources/application-test.properties`：

```properties
# 数据库
spring.datasource.url=jdbc:mysql://localhost:3306/dev_plat?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
spring.datasource.username=<your-username>
spring.datasource.password=<your-password>

# Redis
spring.redis.host=localhost
spring.redis.port=6379

# AI 模型（按需选择其一或多个）
spring.ai.deepseek.api-key=<your-key>
spring.ai.dashscope.api-key=<your-key>
spring.ai.ollama.base-url=http://localhost:11434

# Python Agent（使用 AI 需求/原型能力时必填）
agent.base-url=http://localhost:8000
agent.service-token=<your-service-token>
```

> ⚠️ 密钥类配置请勿提交到仓库。建议通过环境变量或外部配置中心注入。

### 4. 构建与启动

```bash
# 全量构建
mvn clean install -DskipTests

# 启动主服务
cd api && mvn spring-boot:run

# 或启动示例应用（图书借阅系统，演示被测应用如何接入）
cd example && mvn spring-boot:run
```

### 5. 访问地址

主服务默认端口 `9080`，context-path 为 `/devplat`：

| 用途 | 地址 |
|------|------|
| API 文档 | `http://localhost:9080/devplat/doc.html` |
| OpenAPI JSON | `http://localhost:9080/devplat/v3/api-docs` |
| 登录接口 | `POST http://localhost:9080/devplat/userLogin` |
| MCP SSE 端点 | `http://localhost:9080/devplat/sse` |

> 提示：`WebConfig` 的鉴权拦截器目前拦截 `/**`，仅放行 `/login`、`/register`、`/public/**`、`/sse`、`/mcp/message`。若访问 `doc.html` 被拦截，需在拦截器排除列表中补充 `/doc.html`、`/v3/api-docs/**`、`/webjars/**`。

---

## 📦 技术栈

| 分类 | 选型 |
|------|------|
| 框架 | Spring Boot 3.5.5、Java 17 |
| AI | Spring AI 1.0.5（BOM）、Spring AI Alibaba DashScope 1.0.0.2、MCP Server WebMVC |
| 持久层 | MyBatis 3.0.5 + tk.mybatis 通用 Mapper、Druid 1.2.23、MySQL 8 |
| 缓存 | Redis（Lettuce 连接池） |
| 分页 | PageHelper 2.1.0 |
| HTTP 客户端 | Forest 1.6.4（`spring-boot3-starter`）、RestTemplate |
| 操作日志 | mzt bizlog-sdk 3.0.6（`@LogRecord` 注解） + 自定义 `LogRecordAspect` |
| API 文档 | Knife4j OpenAPI3 4.5.0 + Swagger Annotations 1.5.24 |
| 序列化 / 报表 | FastJSON 1.2.83、Apache POI 3.17 |
| 链路上下文 | Transmittable Thread Local 2.14.5 |
| 日志 | Log4j2 |
| 模板引擎 | FreeMarker |
| 消息 | Kafka Clients 2.4.0 |

> 注：`xxl-job-core` 已在父 POM 的 `dependencyManagement` 中声明版本，当前代码尚未接入；定时任务使用 Spring `@Scheduled`（`@EnableScheduling`）实现。

---

## 📁 目录结构

```
devTestPlat-java/
├── api/                    # Web 层与应用入口（33 Controller / 208 端点）
│   └── src/main/resources/
│       ├── application*.properties
│       └── template/       # AI Prompt 模板
├── product/                # 产品与研发管理域：需求/原型/交付/方案/任务/AI 会话
├── case/                   # 测试域：应用/用例/编排/回归/报告
├── user/                   # 用户域：用户/角色/权限/菜单/通知
├── interface_doc/          # 接口文档域：文档 + 时序图
├── ai-core/                # AI 底座：模型路由/Prompt/MCP 工具
├── common/                 # 通用组件：响应/异常/日志枚举/Redis/Forest
├── example/                # 示例应用（图书借阅系统）
├── doc/v1.1.0/             # v1.1.0 PRD、技术设计文档与 DDL 脚本
├── doc/v1.2.0/             # v1.2.0 研发管理、AI 技术方案与本地 Skills 文档
├── docs/                   # 集成方案与设计规格
├── skills/                 # 可复用 AI 工作流（Swagger/时序图/用例生成）
└── assets/readme/          # README 配图
```

---

## 📚 设计文档

| 文档 | 内容 |
|------|------|
| [doc/v1.1.0/prd.md](doc/v1.1.0/prd.md) | v1.1.0 产品需求文档 |
| [doc/v1.1.0/tech-design-product.md](doc/v1.1.0/tech-design-product.md) | 产品域技术设计（需求/验收/交付、三通道 API） |
| [doc/v1.1.0/tech-design-demand-prototype.md](doc/v1.1.0/tech-design-demand-prototype.md) | 需求原型技术设计 |
| [doc/v1.1.0/tech-design-prototype-finetune-flow.md](doc/v1.1.0/tech-design-prototype-finetune-flow.md) | 原型微调与流程图生成 |
| [doc/v1.1.0/tech-design-demand-refine.md](doc/v1.1.0/tech-design-demand-refine.md) | 需求细化技术设计 |
| [doc/v1.1.0/tech-design-permission.md](doc/v1.1.0/tech-design-permission.md) | 权限体系设计 |
| [doc/v1.1.0/tech-design-permission-cache.md](doc/v1.1.0/tech-design-permission-cache.md) | 权限缓存设计 |
| [doc/v1.1.0/operation-log-design.md](doc/v1.1.0/operation-log-design.md) | 操作日志设计 |
| [doc/v1.1.0/demand-prd-link-design.md](doc/v1.1.0/demand-prd-link-design.md) | 需求-PRD 关联设计 |
| [doc/v1.1.0/ai-requirement-frontend-integration.md](doc/v1.1.0/ai-requirement-frontend-integration.md) | AI 需求生成前端对接说明 |
| [docs/java-python-agent-integration-plan.md](docs/java-python-agent-integration-plan.md) | Java-Python Agent 集成方案 |
| [doc/v1.2.0/README.md](doc/v1.2.0/README.md) | v1.2.0 研发管理文档索引 |
| [doc/v1.2.0/prd.md](doc/v1.2.0/prd.md) | v1.2.0 研发端产品需求：仓库、技术方案、分支、开发任务与 AI 方案生成 |
| [doc/v1.2.0/tech-design-dev.md](doc/v1.2.0/tech-design-dev.md) | 研发管理后端设计与 Web/Open API |
| [doc/v1.2.0/tech-design-ai-tech-proposal.md](doc/v1.2.0/tech-design-ai-tech-proposal.md) | AI 技术方案会话、草稿、产物与审批设计 |
| [doc/v1.2.0/tech-proposal-agent-artifacts-export-risk-sync-design.md](doc/v1.2.0/tech-proposal-agent-artifacts-export-risk-sync-design.md) | 技术方案产物增强、ZIP 导出、风险与测试建议落库 |
| [doc/v1.2.0/tech-design-local-coding-agent-skills.md](doc/v1.2.0/tech-design-local-coding-agent-skills.md) | 本地 Coding Agent Skills 协作与 Open API 设计 |

---

## ✅ 当前能力

- [x] 测试域：接口文档、测试用例、用例编排、定时回归、报告告警
- [x] 产品域：需求树、验收项、交付版本
- [x] AI 需求生成（PRD + 需求树 + 澄清问答 + 审批落库）
- [x] 需求原型（AI_HTML / 截图 / 外链）与元素级微调
- [x] 业务流程图生成（流程图 / 泳道图 / 时序图）
- [x] 需求细化（节点级定向修改 + diff 审批）
- [x] 细粒度权限 + Redis 权限缓存
- [x] 零侵入操作日志
- [x] 研发管理：Git 仓库、技术方案、方案分支、开发任务与需求详情聚合
- [x] AI 技术方案生成：澄清、草稿编辑/微调、审批落库与方案产物
- [x] 技术方案交付包：风险项、测试建议与 ZIP 导出
- [x] 本地 Coding Agent Skills：上下文拉取、进度/自测/Commit/Review 回写

---

## 🤝 参与贡献

1. Fork 本仓库
2. 新建分支：`git checkout -b feat/your-feature`
3. 提交代码，遵循 [Conventional Commits](https://www.conventionalcommits.org/)：`feat:` / `fix:` / `docs:` / `refactor:` / `test:` / `chore:`
4. 提交前确保编译通过：`mvn clean install -DskipTests`
5. 创建 Pull Request

### 编码约定

- 出入参 VO/DTO 统一放在各域模块的 `param/req`、`param/resp` 包，**不在 controller 层定义**
- Web 与 Open 接口共享同一 Service 层，不重复业务逻辑
- 所有接口需带 `@ApiOperation(value, notes)`；参数需带 `@ApiParam`；VO 字段需带 `@ApiModelProperty`
- 所有写操作接口需标注 `@LogRecord`；需要权限控制的写接口再加 `@RequiresPermission("域:模块:操作")`
- 数据实体统一包含 `id`、`createdBy`、`createdTime`、`lastUpdatedTime` 公共字段
- 数据通过 `appId` 做应用级隔离

---

## 📄 许可证

[Apache License 2.0](LICENSE)

---

*Made with ❤️ using Spring Boot 3 · Spring AI · Java 17*