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/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