# 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**: 9
- **Forks**: 4
- **Created**: 2026-07-05
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 devTestPlat

> An AI-powered platform for the full software delivery lifecycle: requirement generation, prototyping, acceptance and release, plus API docs, test case management and automated regression — all on one connected pipeline.

English | [简体中文](README.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)

---

## 📊 Overview

**devTestPlat** is an integrated development-and-test platform built on Spring Boot 3.5 + Spring AI 1.0. It converges two pipelines onto a single data model:

- **Product pipeline** — raw requirement → AI-generated PRD and requirement tree → prototypes and flow diagrams → acceptance → versioned release
- **Test pipeline** — API docs → test cases → automated regression → reports and alerts

AI capabilities plug in through both an Open API and an internal API channel. Humans make the decisions and approvals; AI handles generation and repetitive work.

The platform is also its own test subject: the built-in API documentation, test case generation and sequence diagram features can be pointed at any application onboarded to it.

### Project Structure

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

---

## 🏗️ Modules

A Maven multi-module project with 8 modules:

| Module | Responsibility |
|--------|----------------|
| `api` | Web layer and application entry point. 33 controllers, 208 endpoints, plus interceptors, aspects, scheduled tasks and the main class |
| `product` | Product domain: requirements, requirement refinement, prototypes, flow diagrams, acceptance, delivery, AI requirement sessions |
| `case` | Test domain: apps/endpoints/tokens, test cases, case orchestration, scheduled regression, test reports |
| `user` | User domain: users, roles, permissions, menu modules, in-app notifications |
| `interface_doc` | API documentation domain: API docs and sequence diagrams |
| `ai-core` | AI foundation: multi-model routing, prompt management, MCP server tool exposure |
| `common` | Shared components: unified response, exception hierarchy, operation-log enums, Redis cache, Forest clients |
| `example` | Sample application (library lending system) demonstrating how a target app onboards to the platform |

Dependency direction: `api` → (`product`, `case`, `user`, `interface_doc`, `ai-core`) → `common`

### Layering Convention

```
controller (api module)
   └── manager   —— cross-domain orchestration (optional layer, complex cases only)
        └── service / service.impl   —— business logic, shared by Web and Open API
             └── dao (Mapper + dao/pojo) —— tk.mybatis BaseMapper + 35 Mapper XML files
```

Request and response types live in each domain's `param/req` (DTO) and `param/resp` (VO) packages. **Defining VOs/DTOs in the controller layer is not allowed.**

---

## ⚡ Core Capabilities

### Product Domain: End-to-End Requirements

| Capability | Description |
|------------|-------------|
| **Requirement management** | Requirements self-reference via `parentId` to form a tree (≤ 100 nodes per tree); the `demand_app` join table supports cross-application requirements (N:N) |
| **AI requirement generation** | Feed in a raw requirement description; AI produces a PRD in Markdown plus a requirement tree draft, with clarification Q&A, multi-version drafts, approval-to-persist and reject-and-regenerate |
| **Requirement refinement** | Targeted edits on a single node instead of regenerating the whole tree. Produces a subtree snapshot plus a change list (diff); the diff is computed on the Java side and applied in a local transaction at approval time |
| **Requirement prototypes** | Three types: `AI_HTML` (AI-generated self-contained HTML), `SCREENSHOT` (uploaded images), `EXTERNAL_LINK` (Figma and similar). Any node can aggregate and display the pages of all its descendants |
| **Prototype fine-tuning** | Element-level natural-language instructions for targeted page edits. AI returns only a draft; the transactional replace happens after the PM confirms, and untouched pages are guaranteed byte-for-byte identical |
| **Business flow diagrams** | AI generates Mermaid flowcharts, swimlane and sequence diagrams. Swimlane roles are defined freely by AI based on the business; when uncertain it enters `NEED_CLARIFY` and asks the PM rather than forcing a template |
| **PRD traceability** | The top-level requirement node stores the full PRD text along with `source_session_id` / `source_draft_version`, so any requirement traces back to the exact AI draft version |
| **Acceptance management** | Acceptance items hang off requirements at three levels of detail: simple pass/fail, with a result note, or with attached evidence |
| **Delivery management** | Versioned delivery bundling multiple requirements. Status advances strictly through the state machine — no skipping and no rollback |

### Test Domain: Cases and Automation

| Capability | Description |
|------------|-------------|
| **App and endpoint management** | Multiple applications, per-environment endpoints, automatic AppToken keep-alive |
| **API documentation** | API doc authoring and management with JSON import; ships with the `skills/swaggerdoc` uploader |
| **Sequence diagrams** | Generated from API call chains; supports PlantUML, JSON and ZIP batch import |
| **Test cases** | CRUD, import/export, modeling of priority, case type and expected results, with expression-based expectation rules |
| **Case orchestration** | Chain multiple cases into a business flow (`test_case_auto_flow`) with per-node wait strategies and data transformation (mapping upstream response fields into downstream inputs) |
| **Scheduled regression** | Scheduled batch execution of cases producing test reports (`TestCaseAutoExeTask`; its `@Scheduled` is currently commented out — enable as needed) |
| **Report alerting** | Pushes failures via email, WeCom or DingTalk webhooks (`TestCaseReportAlertTask`, per-channel toggles) |
| **AI assistance** | Natural language to expectation expression conversion, AI-based test result adjudication |

### Platform Capabilities

| Capability | Description |
|------------|-------------|
| **Fine-grained permissions** | Menus and buttons are modeled uniformly in the `module` table (type: 0-directory / 1-menu / 2-button); `@RequiresPermission("demand:create")` enforces button-level checks; login returns only the permitted menu tree |
| **Permission caching** | User and role permission lists cached in Redis (`perm:user:{userId}:moduleIds`, TTL 300s), actively invalidated on role or user changes, with automatic fallback to the database if Redis is down |
| **Operation logging** | `@LogRecord` annotation plus SpEL templates — zero intrusion into business code, written asynchronously in an independent transaction to `sys_operation_log`; 97 annotations currently cover every write operation |
| **Real-time push** | SSE (`GET /userNotification/subscribe`) delivers `agent_status`, `prototype_status` and `new_notification` events, one connection per user |
| **Unified response** | Global response wrapping and exception handling, excludable per URI (streaming endpoints, MCP endpoints) |
| **API documentation** | Knife4j (OpenAPI3); all 208 endpoints carry `@ApiOperation(value, notes)` and parameter-level `@ApiParam` descriptions |

---

## 🔌 Three-Channel API Design

One shared service layer exposed through three channels with distinct responsibilities and authentication strength:

| Aspect | Web channel | Open channel | Internal channel |
|--------|-------------|--------------|------------------|
| Consumer | Frontend pages | AI agents / external systems | Java ↔ Python Agent |
| Package | `controller/web/**` | `controller/open/**` | — |
| Path prefix | `/product/**`, `/testcase/**`, etc. | `/open/product/**`, `/open/interface-doc` | `/internal/agent/**` (Python side) |
| Auth annotation | `@ApiAuth(isWeb = true)` | `@ApiAuth(isOpen = true)` | Service token |
| Auth mechanism | Login token (header) | API key signature: `public-key` + `timestamp` + `sign`, 5-minute replay window | `Authorization: Bearer <service-token>` |
| Fine-grained perms | `@RequiresPermission` supported | Allowed once authenticated | N/A |
| API style | Separate create/update, paginated queries | Merged saveOrUpdate, full lists, batch support | Session and task orchestration |
| Idempotency | — | `Idempotency-Key` header | — |

Authentication is chained in `ApiAuthInterceptor.preHandle()`: no `@ApiAuth` → pass through; `@ApiAuth` present → validate token; `@RequiresPermission` present → also validate permission, returning 403 on failure.

---

## 🤖 AI Integration

### Multi-Model Routing (ai-core)

`ModelRouter` plus `AiProviderAdapter` abstract over multiple model vendors, switchable by configuration with no code changes:

- **DeepSeek** — `spring-ai-starter-model-deepseek`
- **Alibaba Cloud DashScope (Qwen)** — `spring-ai-alibaba-starter-dashscope` 1.0.0.2
- **Ollama** — local models, with `OllamaNativeClient` / `OllamaInvoker` (Forest) as a native-call fallback

### MCP Server

Built on `spring-ai-starter-mcp-server-webmvc`, exposing platform capabilities as MCP tools over SSE for external AI clients:

- `InterfaceDocMcpTools` — API documentation queries
- `TestCaseMcpTools` — test case queries and execution

Endpoints: `/sse` (SSE connection) and `/mcp/message` (message channel).

### Python Agent Collaboration

Heavy generation work runs in a separate Python Agent project. Java owns session management, orchestration and approval-time persistence:

```
Java (product module)                       Python Agent
  AgentInternalApiClient  ──RestTemplate──▶  /internal/agent/**
  (service token + X-Trace-Id                  requirement generation / refinement
   + X-Operator-Id)                            prototype generation / fine-tuning / flow diagrams
                        ◀──Open API signature── /open/product/** (writes results back)
```

Configuration keys: `agent.base-url`, `agent.service-token`, `agent.connect-timeout`, `agent.read-timeout`.

### Async Task Reliability

AI tasks are long-running, so four mechanisms combine to guarantee eventual consistency:

1. **SSE push** — accelerates frontend awareness
2. **Frontend polling** — every 2–3s for task/session status; the primary path
3. **Backend scheduled sweep** — recovers `RUNNING` tasks that timed out (configurable via `devplat.requirement-agent.poll-fixed-delay`, default 15s)
4. **Idempotency key + unique index** — `Idempotency-Key` and `uk_session_version(session_id, draft_version)` prevent duplicate writes

### In-Repo Skills

The `skills/` directory holds three reusable AI workflows:

- `swaggerdoc` — API documentation spec and uploader
- `interfaceSequence` — sequence diagram generation
- `testCaseGen` — test case generation (one parseable JSON per endpoint, framework-agnostic)

---

## 🔑 Key Enums and State Machines

<details>
<summary>Click to expand</summary>

**Requirement status** `DemandStatusEnum`
`PENDING_REVIEW` → `REVIEWED` → `IN_DEVELOPMENT` → `COMPLETED`

**Requirement priority** `DemandPriorityEnum`: `P0` urgent / `P1` important / `P2` normal (default) / `P3` low / `P4` deferrable

**Requirement type** `DemandTypeEnum`: `FEATURE` / `OPTIMIZATION` / `BUG` / `TECH_IMPROVEMENT`

**Requirement source** `DemandSourceEnum`: `CUSTOMER_FEEDBACK` / `INTERNAL_PLAN` / `OPERATIONAL`

**Acceptance item status** `AcceptanceItemStatusEnum`: `PENDING` → `PASSED` | `FAILED` (transitions only from PENDING)

**Delivery status** `DeliveryStatusEnum` (strict order, no skipping or rollback)
`PLANNING` → `IN_DEVELOPMENT` → `IN_TESTING` → `RELEASED` → `ARCHIVED`

**AI session status** `RequirementAgentSessionStatusEnum`
```
draft ──run──▶ running ──▶ draft / awaiting_clarification / failed
awaiting_clarification ──submit clarification──▶ running
draft ──approve──▶ approved
draft ──reject──▶ rejected ──run──▶ running (draft version +1)
```

**Prototype type**: `AI_HTML` / `SCREENSHOT` / `EXTERNAL_LINK` (NULL means no prototype; the type cannot be changed after creation)

**Prototype task type**: `GENERATE` / `REGENERATE` / `FINETUNE` / `FLOW_GENERATE` / `FLOW_REGENERATE`

**Prototype task status** (fine-tuning path)
```
PENDING → RUNNING → DRAFT ──apply──▶ DONE
                      │  └──cancel──▶ CANCELLED
                      └──failure──▶ FAILED
```
The flow-diagram path adds `NEED_CLARIFY` (awaiting PM clarification).

**Flow diagram type**: `FLOWCHART` / `SWIMLANE` / `SEQUENCE`; generation scope `NODE` / `SUBTREE`

**Log type** `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`

**Log sub-type** `LogSubTypeEnum`: `create` / `update` / `delete` / `updateStatus` / `execute` / `import` / `export` / `login`

</details>

---

## 🛠️ Getting Started

### 1. Prerequisites

| Component | Version | Required |
|-----------|---------|----------|
| JDK | 17+ | ✅ |
| Maven | 3.8+ | ✅ |
| MySQL | 8.0+ | ✅ |
| Redis | 5.0+ | For permission cache and login state — recommended |
| Python Agent | — | Needed for AI requirement/prototype features; optional |

### 2. Initialize the Database

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

# Base schema
mysql -uroot -p dev_plat < doc/v1.1.0/dev_plat.sql
mysql -uroot -p dev_plat < doc/v1.1.0/sql.sql
mysql -uroot -p dev_plat < doc/v1.1.0/log_sql.sql

# Product domain (requirements / acceptance / delivery / AI sessions)
mysql -uroot -p dev_plat < doc/v1.1.0/prodct_agent_sql.sql
mysql -uroot -p dev_plat < doc/v1.1.0/module-product.sql
mysql -uroot -p dev_plat < doc/v1.1.0/module-ai-requirement.sql

# Prototypes and flow diagrams
mysql -uroot -p dev_plat < doc/v1.1.0/demand-prototype.sql
mysql -uroot -p dev_plat < doc/v1.1.0/demand-prototype-flow.sql
mysql -uroot -p dev_plat < doc/v1.1.0/demand-prototype-finetune-flow.sql

# Requirement refinement and PRD linkage
mysql -uroot -p dev_plat < doc/v1.1.0/demand-refine.sql
mysql -uroot -p dev_plat < doc/v1.1.0/demand-prd-link.sql

# Permission system
mysql -uroot -p dev_plat < doc/v1.1.0/demand-permission.sql
mysql -uroot -p dev_plat < doc/v1.1.0/demand-permission-seed.sql
```

### 3. Configure

Edit `api/src/main/resources/application-test.properties`:

```properties
# Database
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 models (pick one or more)
spring.ai.deepseek.api-key=<your-key>
spring.ai.dashscope.api-key=<your-key>
spring.ai.ollama.base-url=http://localhost:11434

# Python Agent (required for AI requirement/prototype features)
agent.base-url=http://localhost:8000
agent.service-token=<your-service-token>
```

> ⚠️ Never commit secrets to the repository. Inject them via environment variables or an external config service.

### 4. Build and Run

```bash
# Full build
mvn clean install -DskipTests

# Start the main service
cd api && mvn spring-boot:run

# Or start the sample app (library lending system, showing how a target app onboards)
cd example && mvn spring-boot:run
```

### 5. Endpoints

The main service listens on port `9080` with context path `/devplat`:

| Purpose | URL |
|---------|-----|
| API documentation | `http://localhost:9080/devplat/doc.html` |
| OpenAPI JSON | `http://localhost:9080/devplat/v3/api-docs` |
| Login | `POST http://localhost:9080/devplat/userLogin` |
| MCP SSE endpoint | `http://localhost:9080/devplat/sse` |

> Note: the auth interceptor in `WebConfig` currently intercepts `/**` and only excludes `/login`, `/register`, `/public/**`, `/sse` and `/mcp/message`. If `doc.html` gets blocked, add `/doc.html`, `/v3/api-docs/**` and `/webjars/**` to the exclude list.

---

## 📦 Tech Stack

| Category | Choice |
|----------|--------|
| Framework | 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 |
| Persistence | MyBatis 3.0.5 + tk.mybatis generic Mapper, Druid 1.2.23, MySQL 8 |
| Cache | Redis (Lettuce pool) |
| Pagination | PageHelper 2.1.0 |
| HTTP client | Forest 1.6.4 (`spring-boot3-starter`), RestTemplate |
| Operation log | mzt bizlog-sdk 3.0.6 (`@LogRecord`) + custom `LogRecordAspect` |
| API docs | Knife4j OpenAPI3 4.5.0 + Swagger Annotations 1.5.24 |
| Serialization / reports | FastJSON 1.2.83, Apache POI 3.17 |
| Thread context | Transmittable Thread Local 2.14.5 |
| Logging | Log4j2 |
| Templating | FreeMarker |
| Messaging | Kafka Clients 2.4.0 |

> Note: `xxl-job-core` has a version declared in the parent POM's `dependencyManagement` but is not wired into the code yet; scheduled tasks currently use Spring `@Scheduled` (`@EnableScheduling`).

---

## 📁 Directory Layout

```
devTestPlat-java/
├── api/                    # Web layer and entry point (33 controllers / 208 endpoints)
│   └── src/main/resources/
│       ├── application*.properties
│       └── template/       # AI prompt templates
├── product/                # Product domain: requirements/prototypes/flows/acceptance/delivery/AI sessions
├── case/                   # Test domain: apps/cases/orchestration/regression/reports
├── user/                   # User domain: users/roles/permissions/menus/notifications
├── interface_doc/          # API doc domain: docs + sequence diagrams
├── ai-core/                # AI foundation: model routing/prompts/MCP tools
├── common/                 # Shared: response/exceptions/log enums/Redis/Forest
├── example/                # Sample application (library lending system)
├── doc/v1.1.0/             # v1.1.0 PRD, technical designs and DDL scripts
├── docs/                   # Integration plans and design specs
├── skills/                 # Reusable AI workflows (swaggerdoc/sequence/test-case-gen)
└── assets/readme/          # README assets
```

---

## 📚 Design Documents

| Document | Content |
|----------|---------|
| [doc/v1.1.0/prd.md](doc/v1.1.0/prd.md) | v1.1.0 product requirements |
| [doc/v1.1.0/tech-design-product.md](doc/v1.1.0/tech-design-product.md) | Product domain design (requirements/acceptance/delivery, three-channel API) |
| [doc/v1.1.0/tech-design-demand-prototype.md](doc/v1.1.0/tech-design-demand-prototype.md) | Requirement prototype design |
| [doc/v1.1.0/tech-design-prototype-finetune-flow.md](doc/v1.1.0/tech-design-prototype-finetune-flow.md) | Prototype fine-tuning and flow diagram generation |
| [doc/v1.1.0/tech-design-demand-refine.md](doc/v1.1.0/tech-design-demand-refine.md) | Requirement refinement design |
| [doc/v1.1.0/tech-design-permission.md](doc/v1.1.0/tech-design-permission.md) | Permission system design |
| [doc/v1.1.0/tech-design-permission-cache.md](doc/v1.1.0/tech-design-permission-cache.md) | Permission cache design |
| [doc/v1.1.0/operation-log-design.md](doc/v1.1.0/operation-log-design.md) | Operation log design |
| [doc/v1.1.0/demand-prd-link-design.md](doc/v1.1.0/demand-prd-link-design.md) | Requirement-PRD linkage design |
| [doc/v1.1.0/ai-requirement-frontend-integration.md](doc/v1.1.0/ai-requirement-frontend-integration.md) | AI requirement generation frontend integration |
| [docs/java-python-agent-integration-plan.md](docs/java-python-agent-integration-plan.md) | Java-Python Agent integration plan |

---

## 🗺️ Roadmap

- [x] Test domain: API docs, test cases, orchestration, scheduled regression, report alerting
- [x] Product domain: requirement tree, acceptance items, delivery versions
- [x] AI requirement generation (PRD + requirement tree + clarification Q&A + approval)
- [x] Requirement prototypes (AI_HTML / screenshot / external link) with element-level fine-tuning
- [x] Business flow diagram generation (flowchart / swimlane / sequence)
- [x] Requirement refinement (node-level edits + diff approval)
- [x] Fine-grained permissions + Redis permission cache
- [x] Zero-intrusion operation logging
- [ ] Engineering domain: tech proposals and dev tasks (related aggregate fields in `DemandDetailVO` currently return empty)
- [ ] Data-level permissions (only functional permissions implemented today)
- [ ] Monthly sharding and archival for operation logs

---

## 🤝 Contributing

1. Fork the repository
2. Create a branch: `git checkout -b feat/your-feature`
3. Commit following [Conventional Commits](https://www.conventionalcommits.org/): `feat:` / `fix:` / `docs:` / `refactor:` / `test:` / `chore:`
4. Make sure the build passes before submitting: `mvn clean install -DskipTests`
5. Open a Pull Request

### Coding Conventions

- Request/response VOs and DTOs belong in each domain module's `param/req` and `param/resp` packages — **never in the controller layer**
- Web and Open endpoints share one service layer; do not duplicate business logic
- Every endpoint needs `@ApiOperation(value, notes)`; parameters need `@ApiParam`; VO fields need `@ApiModelProperty`
- Every write endpoint needs `@LogRecord`; write endpoints requiring authorization also need `@RequiresPermission("domain:module:action")`
- Entities uniformly carry `id`, `createdBy`, `createdTime` and `lastUpdatedTime`
- Data is isolated per application via `appId`

---

## 📄 License

[Apache License 2.0](LICENSE)

---

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