yg-team-cli 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +882 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +4502 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +4329 -0
- package/dist/index.js.map +1 -0
- package/package.json +70 -0
package/README.md
ADDED
|
@@ -0,0 +1,882 @@
|
|
|
1
|
+
# team-cli
|
|
2
|
+
|
|
3
|
+
> AI-Native 团队研发脚手架 CLI 工具
|
|
4
|
+
|
|
5
|
+
一个统一团队工程初始化标准、利用 Claude Code 能力自动化生成代码的命令行工具。
|
|
6
|
+
|
|
7
|
+
## 功能概述
|
|
8
|
+
|
|
9
|
+
`team-cli` 是一个功能完善的 AI-Native 团队研发脚手架工具,提供从项目初始化到代码开发的全流程支持。
|
|
10
|
+
|
|
11
|
+
### 核心功能
|
|
12
|
+
|
|
13
|
+
| 命令 | 功能描述 |
|
|
14
|
+
|------|---------|
|
|
15
|
+
| `init` | 初始化标准化项目结构 |
|
|
16
|
+
| `split-prd` | 将 PRD 文档拆分为多个功能规格 |
|
|
17
|
+
| `breakdown` | 将 spec 拆分为 milestones 和 todos |
|
|
18
|
+
| `dev` | 选择并执行开发任务 |
|
|
19
|
+
| `add-feature` | 添加新功能 |
|
|
20
|
+
| `bugfix` | 创建 Bugfix 记录 |
|
|
21
|
+
| `hotfix` | 紧急修复 |
|
|
22
|
+
| `detect-deps` | 检测依赖关系 |
|
|
23
|
+
| `sync-memory` | 同步 AI_MEMORY.md |
|
|
24
|
+
| `check-api` | API 检查(冲突/变更/Registry) |
|
|
25
|
+
| `status` | 查看项目状态 |
|
|
26
|
+
| `lint` | 前后端代码质量检查 |
|
|
27
|
+
| `logs` | 查看 AI 开发会话历史 |
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 开发时间线
|
|
32
|
+
|
|
33
|
+
以下记录了 team-cli 的开发进展,按时间倒序排列。
|
|
34
|
+
|
|
35
|
+
### 2026-01-27 - 迭代开发与自动化
|
|
36
|
+
|
|
37
|
+
**Phase 3: API 管理功能**
|
|
38
|
+
- **提交**: `6a69bc5`
|
|
39
|
+
- **新增命令**: `check-api`
|
|
40
|
+
- **功能**:
|
|
41
|
+
- 自动扫描后端 Controller 生成 API 文档
|
|
42
|
+
- 维护 API 定义、版本和变更历史
|
|
43
|
+
- API 冲突检测(防止重复定义)
|
|
44
|
+
- API 变更检测(基于 Git diff)
|
|
45
|
+
- **新增文件**: `docs/api-registry.md`
|
|
46
|
+
- **代码量**: +360 行
|
|
47
|
+
|
|
48
|
+
**Phase 2: 自动化功能**
|
|
49
|
+
- **提交**: `a06c74f`
|
|
50
|
+
- **新增命令**: `sync-memory`, `detect-deps`
|
|
51
|
+
- **功能**:
|
|
52
|
+
- AI_MEMORY 自动同步(功能清单、API 列表、数据模型)
|
|
53
|
+
- 依赖关系自动检测(API 调用、实体关联、服务引用)
|
|
54
|
+
- 自动匹配 spec 文件
|
|
55
|
+
- **代码量**: +620 行
|
|
56
|
+
|
|
57
|
+
**Phase 1: 迭代开发支持**
|
|
58
|
+
- **提交**: `54685ab`
|
|
59
|
+
- **新增命令**: `add-feature`, `bugfix`, `hotfix`, `status`
|
|
60
|
+
- **功能**:
|
|
61
|
+
- 添加新功能(交互式选择依赖)
|
|
62
|
+
- Bugfix 规范化管理
|
|
63
|
+
- Hotfix 紧急修复(规范化 commit log)
|
|
64
|
+
- 项目状态查看
|
|
65
|
+
- **代码量**: +724 行
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
### 2026-01-26 - 模板仓库与 README
|
|
70
|
+
|
|
71
|
+
**模板仓库配置**
|
|
72
|
+
- **提交**: `95c134a`
|
|
73
|
+
- **变更**: 更新后端模板仓库地址
|
|
74
|
+
- **新地址**: `git@gitlab.yungu-inc.org:yungu-app/java-scaffold-template.git`
|
|
75
|
+
|
|
76
|
+
**README 文档**
|
|
77
|
+
- **提交**: `f3b70e7`
|
|
78
|
+
- **新增**: 完整的 README.md 文档
|
|
79
|
+
- **内容**: 功能介绍、使用指南、设计理念
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
### 2026-01-23 - 基础设施与初始化
|
|
84
|
+
|
|
85
|
+
**Session Log 优化**
|
|
86
|
+
- **提交**: `1825501`
|
|
87
|
+
- **修复**: 移除 session log 问题
|
|
88
|
+
|
|
89
|
+
**Gradle 支持**
|
|
90
|
+
- **提交**: `5265aca`
|
|
91
|
+
- **新增**: Gradle 构建支持
|
|
92
|
+
|
|
93
|
+
**项目初始化**
|
|
94
|
+
- **提交**: `a2ca717`
|
|
95
|
+
- **初始提交**: 项目首次初始化
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 技术栈
|
|
100
|
+
|
|
101
|
+
### 后端
|
|
102
|
+
- Java 17 (LTS)
|
|
103
|
+
- Spring Boot 3.x
|
|
104
|
+
- MyBatis Plus 3.5+
|
|
105
|
+
- MySQL 8.0
|
|
106
|
+
- Gradle 8.x
|
|
107
|
+
|
|
108
|
+
### 前端
|
|
109
|
+
- Next.js 14 (App Router)
|
|
110
|
+
- TypeScript 5.x
|
|
111
|
+
- Tailwind CSS 3.x
|
|
112
|
+
- Shadcn/UI
|
|
113
|
+
|
|
114
|
+
### 测试与质量
|
|
115
|
+
- 后端: JUnit 5, Checkstyle, SpotBugs
|
|
116
|
+
- 前端: Jest/Vitest, ESLint
|
|
117
|
+
|
|
118
|
+
## 安装
|
|
119
|
+
|
|
120
|
+
### 方式一:Git 仓库分发(推荐)
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# 克隆仓库
|
|
124
|
+
git clone https://github.com/your-org/team-cli.git
|
|
125
|
+
cd team-cli
|
|
126
|
+
|
|
127
|
+
# 添加到 PATH
|
|
128
|
+
echo 'export PATH=$PATH:'$(pwd)'' >> ~/.zshrc
|
|
129
|
+
source ~/.zshrc
|
|
130
|
+
|
|
131
|
+
# 赋予执行权限
|
|
132
|
+
chmod +x team-cli
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 方式二:直接下载
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# 下载脚本
|
|
139
|
+
curl -O https://raw.githubusercontent.com/your-org/team-cli/main/team-cli
|
|
140
|
+
|
|
141
|
+
# 赋予执行权限
|
|
142
|
+
chmod +x team-cli
|
|
143
|
+
|
|
144
|
+
# 添加到 PATH
|
|
145
|
+
sudo mv team-cli /usr/local/bin/
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## 使用指南
|
|
149
|
+
|
|
150
|
+
### 1. 初始化项目
|
|
151
|
+
|
|
152
|
+
创建一个新的标准化项目:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
team-cli init my-project
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**执行内容:**
|
|
159
|
+
- 环境检查(Claude Code CLI)
|
|
160
|
+
- 交互式输入项目名称
|
|
161
|
+
- 创建标准目录结构
|
|
162
|
+
- 生成"宪法"文件(TECH_STACK.md, CONVENTIONS.md, AI_MEMORY.md)
|
|
163
|
+
- 从模板仓库克隆前后端代码
|
|
164
|
+
- 初始化 Git 仓库
|
|
165
|
+
- 配置 pre-commit hook
|
|
166
|
+
|
|
167
|
+
**生成的目录结构:**
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
my-project/
|
|
171
|
+
├── TECH_STACK.md # 技术栈定义
|
|
172
|
+
├── CONVENTIONS.md # 开发规范
|
|
173
|
+
├── AI_MEMORY.md # 项目状态记录
|
|
174
|
+
├── backend/ # Spring Boot 后端
|
|
175
|
+
├── frontend/ # Next.js 前端
|
|
176
|
+
├── docs/
|
|
177
|
+
│ ├── specs/ # 需求规格文档
|
|
178
|
+
│ ├── api/ # API 文档
|
|
179
|
+
│ └── sessions/ # AI 会话日志
|
|
180
|
+
└── .git/hooks/pre-commit # Git 预提交钩子
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### 2. 拆分 PRD
|
|
184
|
+
|
|
185
|
+
将产品需求文档拆分为多个独立的功能规格:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
# 准备 PRD 文档
|
|
189
|
+
mkdir -p docs/prd-docs/{screenshots,demo-repo}
|
|
190
|
+
# 将 prd.md 放入 docs/prd-docs/
|
|
191
|
+
|
|
192
|
+
# 执行拆分
|
|
193
|
+
team-cli split-prd docs/prd-docs
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
**PRD 文档结构:**
|
|
197
|
+
```
|
|
198
|
+
docs/prd-docs/
|
|
199
|
+
├── prd.md # PRD 描述文档(必需)
|
|
200
|
+
├── screenshots/ # 功能截图(可选)
|
|
201
|
+
└── demo-repo/ # Demo 代码仓库(可选)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
**输出:** 在 `docs/specs/` 目录生成多个 kebab-case 命名的 markdown 文件。
|
|
205
|
+
|
|
206
|
+
### 3. 拆分 Spec
|
|
207
|
+
|
|
208
|
+
将功能规格拆分为可执行的 milestones 和 todos:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
team-cli breakdown docs/specs/user-authentication.md
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**输出的 Milestone 格式:**
|
|
215
|
+
|
|
216
|
+
```markdown
|
|
217
|
+
## 里程碑
|
|
218
|
+
|
|
219
|
+
### Milestone 1: 数据模型设计
|
|
220
|
+
**目标**: 设计用户认证相关的数据库表结构
|
|
221
|
+
**状态**: 待开始
|
|
222
|
+
**预估**: 1 天
|
|
223
|
+
|
|
224
|
+
**Todo List**:
|
|
225
|
+
- [ ] 设计 User 实体和表结构
|
|
226
|
+
- [ ] 定义 Role 和 Permission 枚举
|
|
227
|
+
- [ ] 创建 MyBatis Mapper 接口
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### 4. 开发功能
|
|
231
|
+
|
|
232
|
+
选择并执行开发任务:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
team-cli dev
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
**开发流程:**
|
|
239
|
+
|
|
240
|
+
**步骤 1/3** - 选择 spec 文件:
|
|
241
|
+
- 自动解析依赖关系
|
|
242
|
+
- 拓扑排序推荐开发顺序
|
|
243
|
+
- 显示状态图标:
|
|
244
|
+
- ✓ 已完成
|
|
245
|
+
- ⟳ 进行中
|
|
246
|
+
- ◉ 已拆分
|
|
247
|
+
- ○ 未开始
|
|
248
|
+
|
|
249
|
+
**步骤 2/3** - 选择 milestone:
|
|
250
|
+
- 列出所有 milestones
|
|
251
|
+
- 可选择实现整个 spec
|
|
252
|
+
|
|
253
|
+
**步骤 3/3** - 选择 todo:
|
|
254
|
+
- 列出选中 milestone 的 todos
|
|
255
|
+
- 可选择实现整个 milestone
|
|
256
|
+
|
|
257
|
+
**执行开发任务:**
|
|
258
|
+
- 构建 prompt 发送给 Claude
|
|
259
|
+
- Claude 按照 TDD 方式开发
|
|
260
|
+
- API 定义 → 测试 → 后端实现 → 前端集成
|
|
261
|
+
- 记录会话日志到 `docs/sessions/`
|
|
262
|
+
|
|
263
|
+
### 5. 代码检查
|
|
264
|
+
|
|
265
|
+
运行前后端代码质量检查:
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
team-cli lint
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
**检查内容:**
|
|
272
|
+
|
|
273
|
+
**前端:**
|
|
274
|
+
- ESLint 语法检查
|
|
275
|
+
- TypeScript 类型检查
|
|
276
|
+
|
|
277
|
+
**后端:**
|
|
278
|
+
- Checkstyle 代码规范检查
|
|
279
|
+
- SpotBugs 潜在 Bug 检查
|
|
280
|
+
- Gradle 编译检查
|
|
281
|
+
|
|
282
|
+
**退出码:**
|
|
283
|
+
- `0` - 检查通过
|
|
284
|
+
- `1` - 检查失败
|
|
285
|
+
|
|
286
|
+
### 6. 查看日志
|
|
287
|
+
|
|
288
|
+
查看 AI 开发会话历史:
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
# 查看今日日志
|
|
292
|
+
team-cli logs
|
|
293
|
+
|
|
294
|
+
# 查看指定日期日志
|
|
295
|
+
team-cli logs 2026-01-26
|
|
296
|
+
|
|
297
|
+
# 查看所有日志
|
|
298
|
+
team-cli logs --all
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
**日志存储位置:** `docs/sessions/YYYY-MM-DD/HH-MM_SS_<spec-name>.md`
|
|
302
|
+
|
|
303
|
+
**日志内容:**
|
|
304
|
+
- 时间戳
|
|
305
|
+
- 执行的 spec 文件
|
|
306
|
+
- Milestone/Todo 信息
|
|
307
|
+
- 耗时统计
|
|
308
|
+
- 用户 Prompt
|
|
309
|
+
- 变更文件列表
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## 新增功能使用样例 (2026-01-27)
|
|
314
|
+
|
|
315
|
+
以下命令是在今天开发迭代中新增的,用于支持项目的持续开发和维护。
|
|
316
|
+
|
|
317
|
+
### 7. 添加新功能
|
|
318
|
+
|
|
319
|
+
在已有项目中添加新功能,自动处理依赖关系:
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
cd my-project
|
|
323
|
+
team-cli add-feature payment-system
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
**交互流程:**
|
|
327
|
+
|
|
328
|
+
```
|
|
329
|
+
═══════════════════════════════════════════════════════
|
|
330
|
+
添加新功能: payment-system
|
|
331
|
+
═══════════════════════════════════════════════════════
|
|
332
|
+
|
|
333
|
+
▸ 扫描已有功能...
|
|
334
|
+
✓ 找到 2 个已有 specs
|
|
335
|
+
|
|
336
|
+
已有功能列表:
|
|
337
|
+
[1] user-authentication ✓
|
|
338
|
+
[2] user-profile ✓
|
|
339
|
+
|
|
340
|
+
➜ 选择此功能依赖的已有功能(已完成的功能):
|
|
341
|
+
依赖 user-authentication? (y/n): y
|
|
342
|
+
依赖 user-profile? (y/n): y
|
|
343
|
+
✓ 选择了 2 个依赖
|
|
344
|
+
|
|
345
|
+
▸ 创建 spec 文件...
|
|
346
|
+
✓ 创建 spec 文件: docs/specs/payment-system.md
|
|
347
|
+
|
|
348
|
+
▸ 更新 AI_MEMORY.md...
|
|
349
|
+
✓ AI_MEMORY.md 已更新
|
|
350
|
+
|
|
351
|
+
═══════════════════════════════════════════════════════
|
|
352
|
+
功能添加完成!
|
|
353
|
+
═══════════════════════════════════════════════════════
|
|
354
|
+
|
|
355
|
+
下一步:
|
|
356
|
+
1. 编辑 spec 文件完善需求:
|
|
357
|
+
vim docs/specs/payment-system.md
|
|
358
|
+
|
|
359
|
+
2. 拆分为 milestones 和 todos:
|
|
360
|
+
team-cli breakdown docs/specs/payment-system.md
|
|
361
|
+
|
|
362
|
+
3. 开始开发:
|
|
363
|
+
team-cli dev
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
**生成的 spec 文件自动包含依赖关系:**
|
|
367
|
+
```markdown
|
|
368
|
+
## 依赖关系
|
|
369
|
+
|
|
370
|
+
**前置依赖**:
|
|
371
|
+
- [x] user-authentication.md
|
|
372
|
+
- [x] user-profile.md
|
|
373
|
+
|
|
374
|
+
**被依赖于**:
|
|
375
|
+
- (自动生成,表示哪些 spec 依赖本功能)
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
### 8. 创建 Bugfix 记录
|
|
379
|
+
|
|
380
|
+
为发现的 bug 创建规范的修复记录:
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
team-cli bugfix
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
**交互流程:**
|
|
387
|
+
|
|
388
|
+
```
|
|
389
|
+
═══════════════════════════════════════════════════════
|
|
390
|
+
创建 Bugfix 记录
|
|
391
|
+
═══════════════════════════════════════════════════════
|
|
392
|
+
|
|
393
|
+
Bug 描述: 用户登录时特殊字符报错
|
|
394
|
+
关联 spec (可选,直接回车跳过): user-authentication
|
|
395
|
+
严重程度 (高/中/低,默认: 中): 高
|
|
396
|
+
|
|
397
|
+
✓ 创建 Bugfix 记录: docs/bugfixes/2026-01-27-login-special-char.md
|
|
398
|
+
✓ AI_MEMORY.md 已更新
|
|
399
|
+
|
|
400
|
+
═══════════════════════════════════════════════════════
|
|
401
|
+
Bugfix 记录创建完成!
|
|
402
|
+
═══════════════════════════════════════════════════════
|
|
403
|
+
|
|
404
|
+
下一步:
|
|
405
|
+
1. 完善 bugfix 文档:
|
|
406
|
+
vim docs/bugfixes/2026-01-27-login-special-char.md
|
|
407
|
+
|
|
408
|
+
2. 运行开发模式开始修复:
|
|
409
|
+
team-cli dev
|
|
410
|
+
|
|
411
|
+
3. 修复完成后更新 bugfix 状态
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
**生成的 Bugfix 文件结构:**
|
|
415
|
+
```markdown
|
|
416
|
+
# Bugfix: 用户登录时特殊字符报错
|
|
417
|
+
|
|
418
|
+
## Bug 信息
|
|
419
|
+
- **ID**: BUG-20260127-000
|
|
420
|
+
- **关联 Spec**: user-authentication
|
|
421
|
+
- **严重程度**: 高
|
|
422
|
+
- **状态**: 待修复
|
|
423
|
+
|
|
424
|
+
## 问题描述
|
|
425
|
+
用户登录时特殊字符报错
|
|
426
|
+
|
|
427
|
+
## 复现步骤
|
|
428
|
+
1. 输入用户名
|
|
429
|
+
2. 输入包含特殊字符的密码
|
|
430
|
+
3. 点击登录
|
|
431
|
+
|
|
432
|
+
## 根本原因
|
|
433
|
+
待分析
|
|
434
|
+
|
|
435
|
+
## 修复方案
|
|
436
|
+
- [ ] 分析根本原因
|
|
437
|
+
- [ ] 设计修复方案
|
|
438
|
+
- [ ] 编写测试用例
|
|
439
|
+
- [ ] 实现修复
|
|
440
|
+
- [ ] 验证修复
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
### 9. 紧急修复
|
|
444
|
+
|
|
445
|
+
对于需要立即修复的线上问题:
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
team-cli hotfix
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
**交互流程:**
|
|
452
|
+
|
|
453
|
+
```
|
|
454
|
+
═══════════════════════════════════════════════════════
|
|
455
|
+
创建 Hotfix
|
|
456
|
+
═══════════════════════════════════════════════════════
|
|
457
|
+
|
|
458
|
+
问题描述: 支付接口超时导致订单失败
|
|
459
|
+
影响范围: 所有使用支付宝的用户,约20%订单失败
|
|
460
|
+
严重程度 (高/中/低,默认: 高): 高
|
|
461
|
+
模块 (如: payment, user, order): payment
|
|
462
|
+
根本原因: 支付宝SDK超时时间设置过短
|
|
463
|
+
临时方案: 增加超时时间到15s
|
|
464
|
+
后续计划 (可选): 优化支付流程使用异步回调
|
|
465
|
+
|
|
466
|
+
▸ 创建 hotfix 分支: hotfix/HOTFIX-20260127-000
|
|
467
|
+
✓ 分支创建成功
|
|
468
|
+
✓ Commit message 模板已生成
|
|
469
|
+
✓ Hotfix 记录已添加到: docs/hotfixes.md
|
|
470
|
+
✓ AI_MEMORY.md 已更新
|
|
471
|
+
|
|
472
|
+
═══════════════════════════════════════════════════════
|
|
473
|
+
Hotfix 准备完成!
|
|
474
|
+
═══════════════════════════════════════════════════════
|
|
475
|
+
|
|
476
|
+
当前分支: hotfix/HOTFIX-20260127-000
|
|
477
|
+
|
|
478
|
+
下一步:
|
|
479
|
+
1. 进行代码修复
|
|
480
|
+
|
|
481
|
+
2. 添加修改的文件:
|
|
482
|
+
git add <files>
|
|
483
|
+
|
|
484
|
+
3. 使用预设的 commit message 提交:
|
|
485
|
+
git commit -F .git/HOTFIX_COMMIT_MSG
|
|
486
|
+
|
|
487
|
+
4. 推送到远程并创建 MR/PR:
|
|
488
|
+
git push -u origin hotfix/HOTFIX-20260127-000
|
|
489
|
+
|
|
490
|
+
5. 合并到 main 分支
|
|
491
|
+
|
|
492
|
+
提示: Hotfix 合并后,建议创建规范 Bugfix 进行彻底修复
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
**生成的 Commit Message 格式:**
|
|
496
|
+
```
|
|
497
|
+
hotfix(payment): 支付接口超时导致订单失败
|
|
498
|
+
|
|
499
|
+
HOTFIX-20260127-000
|
|
500
|
+
Severity: 高
|
|
501
|
+
Impact: 所有使用支付宝的用户,约20%订单失败
|
|
502
|
+
Root-Cause: 支付宝SDK超时时间设置过短
|
|
503
|
+
Temporary-Solution: 增加超时时间到15s
|
|
504
|
+
Permanent-Plan: 优化支付流程使用异步回调
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### 10. 查看项目状态
|
|
508
|
+
|
|
509
|
+
快速查看项目整体状态:
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
team-cli status
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
**输出示例:**
|
|
516
|
+
|
|
517
|
+
```
|
|
518
|
+
═══════════════════════════════════════════════════════
|
|
519
|
+
项目状态
|
|
520
|
+
═══════════════════════════════════════════════════════
|
|
521
|
+
|
|
522
|
+
功能清单:
|
|
523
|
+
|
|
524
|
+
No. 功能 状态 进度
|
|
525
|
+
─────────────────────────────────────────────────────────
|
|
526
|
+
[01] User Authentication ✅ 已完成 3/3
|
|
527
|
+
[02] User Profile ✅ 已完成 3/3
|
|
528
|
+
[03] Order Management ⟳ 进行中 2/3
|
|
529
|
+
[04] Payment System ○ 未开始 0/3
|
|
530
|
+
|
|
531
|
+
Bugfix 记录:
|
|
532
|
+
|
|
533
|
+
共 1 个 bugfix 记录
|
|
534
|
+
最新: 2026-01-27-login-special-char (待修复)
|
|
535
|
+
|
|
536
|
+
Git 状态:
|
|
537
|
+
|
|
538
|
+
当前分支: hotfix/HOTFIX-20260127-000
|
|
539
|
+
工作区: 有未提交的更改
|
|
540
|
+
- 未暂存: 2 个文件
|
|
541
|
+
- 已暂存: 1 个文件
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
### 11. 依赖关系自动检测
|
|
545
|
+
|
|
546
|
+
自动检测代码中的依赖关系:
|
|
547
|
+
|
|
548
|
+
```bash
|
|
549
|
+
# 检测单个 spec 的依赖
|
|
550
|
+
team-cli detect-deps docs/specs/payment-system.md
|
|
551
|
+
|
|
552
|
+
# 检测所有 specs 的依赖
|
|
553
|
+
team-cli detect-deps
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
**输出示例:**
|
|
557
|
+
|
|
558
|
+
```
|
|
559
|
+
═══════════════════════════════════════════════════════
|
|
560
|
+
检测依赖关系
|
|
561
|
+
═══════════════════════════════════════════════════════
|
|
562
|
+
|
|
563
|
+
▸ 自动检测依赖关系...
|
|
564
|
+
- 扫描后端 API 调用...
|
|
565
|
+
- 扫描后端实体关联...
|
|
566
|
+
- 扫描后端服务引用...
|
|
567
|
+
- 扫描前端 API 调用...
|
|
568
|
+
|
|
569
|
+
✓ 检测到 2 个潜在依赖:
|
|
570
|
+
- user-authentication.md
|
|
571
|
+
- order-management.md
|
|
572
|
+
|
|
573
|
+
是否自动更新依赖关系到 spec 文件? (y/n): y
|
|
574
|
+
✓ 依赖关系已更新到 docs/specs/payment-system.md
|
|
575
|
+
|
|
576
|
+
═══════════════════════════════════════════════════════
|
|
577
|
+
依赖检测完成
|
|
578
|
+
═══════════════════════════════════════════════════════
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
**检测维度:**
|
|
582
|
+
- 后端 API 调用
|
|
583
|
+
- 实体关联(@ManyToOne, @OneToMany 等)
|
|
584
|
+
- 服务引用(Service 注入)
|
|
585
|
+
- 前端 API 调用(fetch, axios)
|
|
586
|
+
|
|
587
|
+
### 12. 同步 AI_MEMORY
|
|
588
|
+
|
|
589
|
+
自动同步 AI_MEMORY.md,保持项目状态最新:
|
|
590
|
+
|
|
591
|
+
```bash
|
|
592
|
+
team-cli sync-memory
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
**输出示例:**
|
|
596
|
+
|
|
597
|
+
```
|
|
598
|
+
═══════════════════════════════════════════════════════
|
|
599
|
+
同步 AI_MEMORY.md
|
|
600
|
+
═══════════════════════════════════════════════════════
|
|
601
|
+
|
|
602
|
+
▸ 同步 AI_MEMORY.md...
|
|
603
|
+
- 扫描 specs 更新功能清单...
|
|
604
|
+
- 扫描 Controller 更新 API 列表...
|
|
605
|
+
- 扫描 Entity 更新数据模型...
|
|
606
|
+
- 更新最后同步时间...
|
|
607
|
+
|
|
608
|
+
✓ AI_MEMORY.md 已同步
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
**同步内容:**
|
|
612
|
+
- 功能清单(状态、进度、完成日期)
|
|
613
|
+
- API 列表(扫描 Controller 生成)
|
|
614
|
+
- 数据模型(表名、字段数、关联关系)
|
|
615
|
+
|
|
616
|
+
### 13. API 检查
|
|
617
|
+
|
|
618
|
+
检查 API 的冲突和变更:
|
|
619
|
+
|
|
620
|
+
```bash
|
|
621
|
+
team-cli check-api
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
**交互式菜单:**
|
|
625
|
+
|
|
626
|
+
```
|
|
627
|
+
═══════════════════════════════════════════════════════
|
|
628
|
+
API 检查
|
|
629
|
+
═══════════════════════════════════════════════════════
|
|
630
|
+
|
|
631
|
+
选择检查类型:
|
|
632
|
+
1) 检测 API 冲突
|
|
633
|
+
2) 检测 API 变更
|
|
634
|
+
3) 生成 API Registry
|
|
635
|
+
4) 全部执行
|
|
636
|
+
|
|
637
|
+
请选择 (1-4): 1
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
**选项 1: 检测 API 冲突**
|
|
641
|
+
```
|
|
642
|
+
▸ 检测 API 冲突...
|
|
643
|
+
✓ 未检测到 API 冲突
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
**选项 2: 检测 API 变更**
|
|
647
|
+
```
|
|
648
|
+
▸ 检测 API 变更...
|
|
649
|
+
✓ 检测到 API 变更:
|
|
650
|
+
- PaymentController.java
|
|
651
|
+
新增: 2 个 API
|
|
652
|
+
删除: 0 个 API
|
|
653
|
+
|
|
654
|
+
是否更新 API Registry? (y/n): y
|
|
655
|
+
✓ API Registry 已生成: docs/api-registry.md
|
|
656
|
+
```
|
|
657
|
+
|
|
658
|
+
**选项 3: 生成 API Registry**
|
|
659
|
+
```
|
|
660
|
+
▸ 扫描并生成 API Registry...
|
|
661
|
+
✓ API Registry 已生成: docs/api-registry.md
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
**生成的 API Registry 格式:**
|
|
665
|
+
```markdown
|
|
666
|
+
# API Registry
|
|
667
|
+
|
|
668
|
+
## Payment 模块
|
|
669
|
+
|
|
670
|
+
### POST /api/payment/create
|
|
671
|
+
|
|
672
|
+
**版本**: v1.0
|
|
673
|
+
**说明**: 创建支付订单
|
|
674
|
+
|
|
675
|
+
**请求**:
|
|
676
|
+
```json
|
|
677
|
+
{
|
|
678
|
+
"orderId": "string",
|
|
679
|
+
"amount": 0
|
|
680
|
+
}
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
**变更历史**:
|
|
684
|
+
| 日期 | 版本 | 变更类型 | 变更说明 | 作者 |
|
|
685
|
+
|------|------|---------|---------|------|
|
|
686
|
+
| 2026-01-27 | v1.0 | 新增 | 初始版本 | team-cli |
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
---
|
|
690
|
+
|
|
691
|
+
## 环境变量配置
|
|
692
|
+
|
|
693
|
+
```bash
|
|
694
|
+
# 后端模板仓库
|
|
695
|
+
export TEMPLATE_REPO=git@gitlab.yungu-inc.org:yungu-app/java-scaffold-template.git
|
|
696
|
+
|
|
697
|
+
# 本地后端模板(降级使用)
|
|
698
|
+
export LOCAL_BACKEND_TEMPLATE=/path/to/local/backend/template
|
|
699
|
+
|
|
700
|
+
# 前端模板仓库
|
|
701
|
+
export FRONTEND_TEMPLATE_REPO=https://gitlab.yungu-inc.org/static/fe-tpl-ai
|
|
702
|
+
|
|
703
|
+
# 本地前端模板(降级使用)
|
|
704
|
+
export LOCAL_FRONTEND_TEMPLATE=/path/to/local/frontend/template
|
|
705
|
+
|
|
706
|
+
# Git 网络超时时间(秒)
|
|
707
|
+
export GIT_TIMEOUT=5
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
## 开发规范
|
|
711
|
+
|
|
712
|
+
### 后端规范
|
|
713
|
+
|
|
714
|
+
**分层架构:**
|
|
715
|
+
```
|
|
716
|
+
Controller → Service → Mapper → Entity
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
**DTO 模式:**
|
|
720
|
+
- 所有 API 使用 DTO,禁止暴露 Entity
|
|
721
|
+
- Request DTO: `CreateXxxRequest`
|
|
722
|
+
- Response DTO: `XxxResponse`
|
|
723
|
+
|
|
724
|
+
**命名规范:**
|
|
725
|
+
- Entity: `User`, `Order`
|
|
726
|
+
- DTO: `UserDTO`, `CreateUserRequest`, `UserResponse`
|
|
727
|
+
- Service: `UserService`, `UserServiceImpl`
|
|
728
|
+
- Mapper: `UserMapper`
|
|
729
|
+
|
|
730
|
+
### 前端规范
|
|
731
|
+
|
|
732
|
+
- 函数式组件 + Hooks
|
|
733
|
+
- PascalCase 命名组件文件
|
|
734
|
+
- camelCase 命名工具文件
|
|
735
|
+
- 所有 props/state 必须有类型
|
|
736
|
+
|
|
737
|
+
### 开发流程
|
|
738
|
+
|
|
739
|
+
1. **TDD 优先** - 先写测试
|
|
740
|
+
2. **API First** - 先定义 API 契约
|
|
741
|
+
3. **小步提交** - 每个 commit 只做一件事
|
|
742
|
+
|
|
743
|
+
### Git 提交规范
|
|
744
|
+
|
|
745
|
+
```
|
|
746
|
+
<type>(<scope>): <subject>
|
|
747
|
+
|
|
748
|
+
feat: 新功能
|
|
749
|
+
fix: 修复
|
|
750
|
+
docs: 文档
|
|
751
|
+
style: 格式
|
|
752
|
+
refactor: 重构
|
|
753
|
+
test: 测试
|
|
754
|
+
chore: 构建/工具
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
## 完整工作流程
|
|
758
|
+
|
|
759
|
+
```bash
|
|
760
|
+
# 1. 初始化项目
|
|
761
|
+
team-cli init my-project
|
|
762
|
+
cd my-project
|
|
763
|
+
|
|
764
|
+
# 2. 准备并拆分 PRD
|
|
765
|
+
# 将 PRD 文档放入 docs/prd-docs/
|
|
766
|
+
team-cli split-prd docs/prd-docs
|
|
767
|
+
|
|
768
|
+
# 3. 拆分功能规格
|
|
769
|
+
team-cli breakdown docs/specs/feature-name.md
|
|
770
|
+
|
|
771
|
+
# 4. 开发功能
|
|
772
|
+
team-cli dev
|
|
773
|
+
# → 选择 spec → milestone → todo
|
|
774
|
+
|
|
775
|
+
# 5. 代码检查
|
|
776
|
+
team-cli lint
|
|
777
|
+
|
|
778
|
+
# 6. 查看开发日志
|
|
779
|
+
team-cli logs
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
## 核心特性
|
|
783
|
+
|
|
784
|
+
### 1. 依赖关系管理
|
|
785
|
+
- 自动解析 spec 之间的依赖关系
|
|
786
|
+
- 拓扑排序确定推荐开发顺序
|
|
787
|
+
- 防止循环依赖
|
|
788
|
+
- 视觉化显示依赖信息
|
|
789
|
+
|
|
790
|
+
### 2. 状态管理
|
|
791
|
+
每个 spec 维护状态:
|
|
792
|
+
- 未开始 → 已拆分 → 进行中 → 已完成
|
|
793
|
+
|
|
794
|
+
### 3. 模板降级机制
|
|
795
|
+
网络不可达时自动降级:
|
|
796
|
+
1. 尝试远程 Git 仓库(超时检测)
|
|
797
|
+
2. 降级到本地模板路径
|
|
798
|
+
3. 创建最小化目录结构
|
|
799
|
+
|
|
800
|
+
### 4. Git 集成
|
|
801
|
+
- 自动初始化 Git 仓库
|
|
802
|
+
- pre-commit hook 自动运行 lint
|
|
803
|
+
- 记录文件变更历史
|
|
804
|
+
|
|
805
|
+
### 5. 彩色输出
|
|
806
|
+
使用 ANSI 颜色代码:
|
|
807
|
+
- 绿色 - 成功信息
|
|
808
|
+
- 黄色 - 进行中/警告
|
|
809
|
+
- 红色 - 错误信息
|
|
810
|
+
- 蓝色 - 标题
|
|
811
|
+
- 青色 - 步骤提示
|
|
812
|
+
|
|
813
|
+
## 设计理念
|
|
814
|
+
|
|
815
|
+
### 核心思想
|
|
816
|
+
|
|
817
|
+
**团队-cli 的设计理念是"标准化 + 自动化 + 可追溯"**,通过三个维度解决团队研发中的协作效率问题:
|
|
818
|
+
|
|
819
|
+
#### 1. 标准化(Standardization)
|
|
820
|
+
|
|
821
|
+
**问题**: 团队成员技术栈选择、代码风格、项目结构不统一,导致协作成本高。
|
|
822
|
+
|
|
823
|
+
**解决方案**:
|
|
824
|
+
- **宪法文件**: TECH_STACK.md 定义技术栈,CONVENTIONS.md 定义开发规范
|
|
825
|
+
- **脚手架模板**: 统一的前后端项目结构,开箱即用
|
|
826
|
+
- **代码规范**: 集成 Checkstyle、ESLint 等工具,强制执行规范
|
|
827
|
+
- **Git Hook**: pre-commit 自动检查,防止不符合规范的代码提交
|
|
828
|
+
|
|
829
|
+
#### 2. 自动化(Automation)
|
|
830
|
+
|
|
831
|
+
**问题**: 重复性的初始化工作、代码生成工作浪费开发时间。
|
|
832
|
+
|
|
833
|
+
**解决方案**:
|
|
834
|
+
- **一键初始化**: `team-cli init` 自动生成完整项目结构
|
|
835
|
+
- **AI 辅助开发**: 集成 Claude Code,自动生成增删改查代码
|
|
836
|
+
- **智能拆分**: 自动将 PRD 拆分为 specs,再拆分为 milestones 和 todos
|
|
837
|
+
- **依赖分析**: 自动解析 spec 依赖关系,推荐开发顺序
|
|
838
|
+
|
|
839
|
+
#### 3. 可追溯(Traceability)
|
|
840
|
+
|
|
841
|
+
**问题**: 需求变更频繁,开发过程缺乏记录,难以回溯决策原因。
|
|
842
|
+
|
|
843
|
+
**解决方案**:
|
|
844
|
+
- **AI_MEMORY.md**: 记录项目状态、技术决策、已完成功能
|
|
845
|
+
- **会话日志**: 每次 AI 开发对话都记录到 `docs/sessions/`
|
|
846
|
+
- **Git 历史**: 结合 Git commit,可追溯每个功能的实现时间
|
|
847
|
+
- **Spec 模板**: 标准化的需求文档格式,便于查阅
|
|
848
|
+
|
|
849
|
+
### 设计原则
|
|
850
|
+
|
|
851
|
+
1. **约定优于配置** - 硬编码最佳实践,减少选择困难
|
|
852
|
+
2. **渐进式开发** - 支持 PRD → Spec → Milestone → Todo 的渐进式拆解
|
|
853
|
+
3. **失败友好** - 模板降级机制,网络不可达时仍可工作
|
|
854
|
+
4. **AI-Native** - 深度集成 Claude Code,最大化 AI 辅助能力
|
|
855
|
+
5. **单文件分发** - 所有逻辑封装在一个 Shell 脚本,方便分发
|
|
856
|
+
|
|
857
|
+
### 技术决策
|
|
858
|
+
|
|
859
|
+
| 决策点 | 选择 | 理由 |
|
|
860
|
+
|-------|------|------|
|
|
861
|
+
| 实现语言 | Shell 脚本 | 单文件分发,无依赖,适合 Mac/Linux |
|
|
862
|
+
| 构建工具 | Gradle | 比 Maven 更灵活,配置更简洁 |
|
|
863
|
+
| 前端框架 | Next.js 14 (App Router) | React 最新特性,服务端渲染 |
|
|
864
|
+
| ORM | MyBatis Plus | 比 JPA 更灵活,SQL 可控 |
|
|
865
|
+
| AI 集成 | Claude Code | Anthropic 官方 CLI,支持代码操作 |
|
|
866
|
+
|
|
867
|
+
## 项目状态
|
|
868
|
+
|
|
869
|
+
当前版本基于以下 Git 提交:
|
|
870
|
+
|
|
871
|
+
- `614c10d` - 添加 Docker 支持
|
|
872
|
+
- `1825501` - 移除 session log 问题
|
|
873
|
+
- `5265aca` - 更新到 Gradle
|
|
874
|
+
- `a2ca717` - 首次初始化
|
|
875
|
+
|
|
876
|
+
## 贡献指南
|
|
877
|
+
|
|
878
|
+
欢迎提交 Issue 和 Pull Request!
|
|
879
|
+
|
|
880
|
+
## 许可证
|
|
881
|
+
|
|
882
|
+
MIT License
|