Skip to content
Merged

Dev #249

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,18 @@ cd flow-engine-example && mvn spring-boot:run
- **未经用户明确要求,任何情况下不得执行 `git commit` / `git push` / `git merge` 操作**
- 所有代码变更需经用户审核后再提交

### GitHub Issue 标准处理流程

处理任何来自 GitHub 的 issue 时,必须遵循 [docs/conventions/workflow/github-issue.md](./docs/conventions/workflow/github-issue.md):

1. **定位阶段**可只读代码分析,不必创建 worktree;
2. **定位完成后先回复 issue**,说明根因与处理方案;
3. **实际改代码必须使用 git worktree + 特性分支**(worktree 仅以 `dev` 代码为基线),不得在主工作区直接修改;
4. 修复需测试先行并完成本地编译/测试验证;
5. 完成后**只推送该 issue 的特性分支到 GitHub**:提交内容、推送与 issue 关联均以该特性分支为准,**不合并 `dev`**;是否合并 `dev` 由人工决定,任务完成时仅提示分支与 PR 链接;
6. 提交信息使用 `Closes #<issue编号>` 关联 issue;进入默认分支后自动关闭,未自动关闭时需用户确认后手动关闭;
7. **特性分支推送到 GitHub 后再回复 issue**,说明修复内容、验证结果与推送分支/提交;未推送前不得发布完成回复(定位回复不受此限)。

### 基本规范

- **与用户沟通及编写文档时,所有内容必须使用中文表述**
Expand Down
9 changes: 8 additions & 1 deletion docs/conventions/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,12 @@

> 🔄 此文件由 `rebuild_pkr_index.py` 自动生成,请勿手动编辑。

_暂无已注册的规范文档。_
## ✅ 已实现

| 名称 | 模块 | 描述 | 范围 | 来源 |
|------|------|------|------|------|
| [workflow/github-issue](./workflow/github-issue.md) | workflow | GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复 | 通用 | 项目自有 |

---

**统计**: 共 1 篇 — 已实现 1 / 计划中 0 / 已废弃 0
147 changes: 147 additions & 0 deletions docs/conventions/workflow/github-issue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
---
name: workflow/github-issue
module: workflow
description: GitHub Issue 标准处理流程 — 定位分析 → 回复 issue → worktree 修复 → 推送特性分支 → 推送后回复
status: 已实现
scope: 通用
source: 项目自有
---

## 解决什么问题

不遵守此流程会导致:

- 问题分析结论只留在本地,issue 参与者无法同步进展
- 直接在主干工作区改代码,污染工作区、难以回滚和并行处理多个 issue
- 修复完成后 issue 长期悬空,无法追溯「哪个提交解决了哪个 issue」
- 分支、worktree、合并目标不统一,发布时遗漏改动

## 适用范围

`codingapi/flow-engine` 及其关联仓库(如 `codingapi/flow-frontend`)的**所有 GitHub issue**。

## 核心原则

1. **分析可以不开 worktree,改代码必须开**:定位阶段只读代码即可;一旦确定要修改,必须新建 git worktree + 特性分支。
2. **先回复,再动手**:定位到问题后,先在对应 issue 回复根因与处理方案。
3. **dev 只作为基线,不参与交付**:worktree 基于 `dev` 代码创建;修复提交、推送与 issue 关联全部发生在该 issue 的特性分支上。完成后**不合并 `dev`**,是否合并由人工决定,助手只在任务完成时提示分支与 PR 链接。
4. **提交即关联 issue**:提交信息使用 `Closes #<id>` 关联;是否已真正关闭取决于是否进入默认分支,未自动关闭时由维护者确认后手动关闭。
5. **推送后再回复**:特性分支推送到 GitHub 之后,才在 issue 回复修复内容、提交与验证结果;**未推送前不得发布完成回复**。

## 标准步骤

### 1. 读取 issue

```bash
gh issue view <id> --repo codingapi/flow-engine \
--json number,title,state,labels,body,comments,author,createdAt
```

### 2. 定位问题(可不建 worktree)

- 使用代码搜索、LSP、文档(`docs/conventions`、`docs/capabilities`)定位根因;
- 明确影响范围(后端 / PC 端 / 移动端)、是否涉及前端子模块 `flow-frontend`;
- 判断是否属于已有能力缺陷,优先复用既有机制而非新增。

### 3. 回复 issue(定位结论)

将以下内容整理为中文评论:

- 问题原因(引用具体类/文件/方法);
- 影响范围(哪些动作、端、版本);
- 处理方案(改动点、交互变化、兼容性);
- 交付方式(基于 `dev` 的特性分支名,完成后由维护者合并)。

```bash
gh issue comment <id> --repo codingapi/flow-engine --body-file /tmp/issue-<id>-analysis.md
```

### 4. 创建 worktree 与特性分支

**后端主仓库**(`.worktrees/` 已被 `.gitignore` 忽略):

```bash
git worktree add .worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
cd .worktrees/issue-<id>
```

**前端子模块**(`flow-frontend/.claude/worktrees/` 已被忽略):

```bash
cd flow-frontend
git worktree add .claude/worktrees/issue-<id> -b feature/issue-<id>-<slug> dev
cd .claude/worktrees/issue-<id>
pnpm install --frozen-lockfile --prefer-offline # worktree 无 node_modules
```

命名约定:`feature/issue-<issue编号>-<简短英文描述>`。

> worktree 仅以 `dev` 代码为**基线**;创建之后的所有提交、推送与 issue 关联都只发生在该特性分支上,`dev` 不参与交付。

### 5. 修复与验证(TDD)

- 先补测试(红灯),再实现(绿灯),最后重构;
- 前端:`npx rstest run`(单包)、`pnpm run test:<package>`、`pnpm run build:<package>`;
- 后端:`./mvnw -pl <module> test`,必要时 `./mvnw clean install`;
- **修改代码后必须本地编译/测试通过**,失败项如实报告,不得声称已验证。

### 6. 推送特性分支到 GitHub(任务到此结束)

```bash
git push -u origin feature/issue-<id>-<slug>
```

- 只推送该 issue 的特性分支,`dev` 保持不动,是否合并由人工决定;
- 禁止推送到 `dev` / `main`,禁止在本地合并 `dev`;
- 任务完成提示中给出分支地址与 PR 链接即可,不代为合并;
- 前后端均有改动时,两个仓库各自推送自己的特性分支;
- 不更新主仓库记录的 `flow-frontend` 子模块指针,除非维护者明确要求;
- 推送后可清理本地 worktree(`git worktree remove <path>`),分支保留。

### 7. 提交信息与 issue 关闭

提交信息格式:

```
fix: <一句话描述> (<关联范围>)

<可选的改动说明>

Closes #<id>
```

- `Closes #<id>` 只在提交进入**默认分支**(`main`)时由 GitHub 自动关闭;
- 推送到特性分支不会关闭 issue;特性分支合并到 `dev` 后仍保持打开,待 `dev → main` 合并时自动关闭;
- 如需提前关闭,必须由维护者确认后执行 `gh issue close <id>`,不得擅自关闭。

### 8. 推送后回复 issue

**前置条件:特性分支已推送到 GitHub**。未推送前只可说明「修复已提交到本地特性分支,待推送」,不得发布完成结论。

回复内容包含:

- 根因与最终方案(与步骤 3 的差异);
- 变更文件/能力(新增公共 API、交互变化);
- 验证结果(测试用例数、构建结果);
- 推送分支与提交号、对应 PR/评审状态;
- 升级/兼容提示(如有行为变更)。

## 禁止事项

- 不得向 `dev` / `main` 推送,不得在本地合并 `dev`(是否合并由人工决定);
- 特性分支推送是标准步骤,但推送前必须确认远程分支名,避免误推;
- 不得在主工作区(非 worktree)直接修改业务代码;
- 不得跳过测试与编译验证;
- 不得在特性分支推送前发布完成回复(定位回复不受此限);
- 不得在代码未进入默认分支前擅自关闭 issue;
- 不得用相对路径跨 package 引用(前端规范)。

## 检查清单

- [ ] issue 已读取并确认现状
- [ ] 定位结论已在 issue 回复
- [ ] worktree + 特性分支已创建(基于 `dev`)
- [ ] 测试先行且全量通过,构建通过
- [ ] 特性分支已推送到 GitHub(`dev` 未改动)
- [ ] 提交信息包含 `Closes #<id>`
- [ ] 推送后已在 issue 回复修复与验证结果
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
package com.codingapi.flow.action;

import com.codingapi.flow.action.factory.FlowActionFactory;
import org.junit.jupiter.api.Test;

import java.util.HashMap;
import java.util.Map;

import static org.junit.jupiter.api.Assertions.assertEquals;

/**
* 动作展示(按钮样式)序列化测试
*/
class ActionDisplayTest {

@Test
void should_keep_button_style_when_action_round_trip() {
// given 设计器保存的按钮样式(issue #244):样式保存在 display.style 的 JSON 字符串中
String style = "{\"backgroundColor\":\"1677ff\",\"borderColor\":\"ff4d4f\",\"borderRadius\":\"4\",\"borderSize\":\"1\"}";

Map<String, Object> display = new HashMap<>();
display.put("title", "通过");
display.put("style", style);
display.put("icon", "");
display.put("script", "");

Map<String, Object> data = new HashMap<>();
data.put("id", "action-1");
data.put("type", "CUSTOM");
data.put("title", "通过");
data.put("enable", true);
data.put("display", display);

// when 保存(fromMap)后再加载(toMap)
IFlowAction action = FlowActionFactory.getInstance().createAction(data);
Map<String, Object> map = action.toMap();

// then 样式不丢失
@SuppressWarnings("unchecked")
Map<String, Object> result = (Map<String, Object>) map.get("display");
assertEquals(style, result.get("style"));
}
}
2 changes: 1 addition & 1 deletion flow-frontend
Submodule flow-frontend updated 31 files
+6 −0 packages/flow-approval-presenter/CHANGELOG.md
+1 −1 packages/flow-approval-presenter/package.json
+2 −0 packages/flow-core/CHANGELOG.md
+1 −1 packages/flow-core/package.json
+10 −0 packages/flow-design/CHANGELOG.md
+1 −1 packages/flow-design/package.json
+14 −2 packages/flow-design/src/components/design-editor/node-components/action/index.tsx
+9 −1 packages/flow-design/src/components/design-editor/node-components/action/presenter.ts
+115 −38 packages/flow-design/src/script-components/components/action/style.tsx
+88 −0 packages/flow-design/tests/components/design-editor/node-components/action/presenter.test.ts
+54 −0 packages/flow-design/tests/script/action_style.test.ts
+2 −0 packages/flow-icons/CHANGELOG.md
+1 −1 packages/flow-icons/package.json
+12 −0 packages/flow-mobile/flow-mobile-approval/CHANGELOG.md
+1 −1 packages/flow-mobile/flow-mobile-approval/package.json
+44 −22 packages/flow-mobile/flow-mobile-approval/src/components/flow-approval/components/custom-style-button.tsx
+48 −0 packages/flow-mobile/flow-mobile-approval/tests/custom-style-button.test.tsx
+6 −0 packages/flow-mobile/flow-mobile-form/CHANGELOG.md
+1 −1 packages/flow-mobile/flow-mobile-form/package.json
+2 −0 packages/flow-mobile/flow-mobile-ui/CHANGELOG.md
+1 −1 packages/flow-mobile/flow-mobile-ui/package.json
+11 −0 packages/flow-pc/flow-pc-approval/CHANGELOG.md
+1 −1 packages/flow-pc/flow-pc-approval/package.json
+45 −23 packages/flow-pc/flow-pc-approval/src/components/flow-approval/components/custom-style-button.tsx
+59 −0 packages/flow-pc/flow-pc-approval/tests/custom-style-button.test.tsx
+6 −0 packages/flow-pc/flow-pc-form/CHANGELOG.md
+1 −1 packages/flow-pc/flow-pc-form/package.json
+2 −0 packages/flow-pc/flow-pc-ui/CHANGELOG.md
+1 −1 packages/flow-pc/flow-pc-ui/package.json
+2 −0 packages/flow-types/CHANGELOG.md
+1 −1 packages/flow-types/package.json
Loading