adspecs 0.1.21 → 0.1.23
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/.adspecs/templates/05b-/345/211/215/347/253/257/344/273/273/345/212/241/346/270/205/345/215/225/346/250/241/346/235/277.md +583 -492
- package/.claude-plugin/marketplace.json +23 -23
- package/.claude-plugin/plugin.json +18 -18
- package/.qoder-plugin/plugin.json +31 -31
- package/package.json +4 -4
- package/src/lib/readme-gen.js +3 -8
|
@@ -1,492 +1,583 @@
|
|
|
1
|
-
---
|
|
2
|
-
description: "前端功能实现的 TDD
|
|
3
|
-
---
|
|
4
|
-
|
|
5
|
-
### 修订记录
|
|
6
|
-
|
|
7
|
-
| 版本号 | 修订日期 | 修订人 | 修订内容 |
|
|
8
|
-
| ------ | ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
| `
|
|
41
|
-
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
- [ ]
|
|
357
|
-
-
|
|
358
|
-
- [ ]
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
-
|
|
381
|
-
-
|
|
382
|
-
-
|
|
383
|
-
-
|
|
384
|
-
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
|
440
|
-
|
|
|
441
|
-
|
|
|
442
|
-
|
|
|
443
|
-
|
|
|
444
|
-
|
|
|
445
|
-
|
|
|
446
|
-
|
|
|
447
|
-
|
|
|
448
|
-
|
|
|
449
|
-
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
1
|
+
---
|
|
2
|
+
description: "前端功能实现的 TDD 任务列表模板。支持 Vue + Element Plus / React + Ant Design 技术栈自动检测"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
### 修订记录
|
|
6
|
+
|
|
7
|
+
| 版本号 | 修订日期 | 修订人 | 修订内容 |
|
|
8
|
+
| ------ | ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| v4.0 | 2026-07-28 | AI | 技术栈解耦改造：新增 Vue + React 双栈检测 + 双栈映射表；编码规范检查清单拆分为栈无关项 + Vue 专属项 + React 专属项；Phase 任务示例使用参数化占位符（`{EXT}`/`{PAGE_DIR}`/`{STORE_DIR}`/`{I18N_DIR}`/`{COMPONENT_PREFIX}`）；保留 M06-01 销售预测单业务场景 |
|
|
10
|
+
| v3.0 | 2026-06-13 | AI | 前端专项改造：ECP 后端模板 → Vue 3 + Element Plus 前端 TDD 模板 |
|
|
11
|
+
| v2.0 | 2026-06-13 | AI | ECP 平台专项改造：后端 Java Maven 三模块 TDD 模板 |
|
|
12
|
+
| v1.0 | 2026-06-12 | AI | 初始版本 |
|
|
13
|
+
|
|
14
|
+
# 前端任务清单：[功能名称]
|
|
15
|
+
|
|
16
|
+
**设计文档来源**：
|
|
17
|
+
- 前端设计文档：`docs/30-system-design/{crm|mom}/[功能名]_前端设计.md`（由 `adspecs-front-spec` 产出）
|
|
18
|
+
- 系统设计文档：`docs/30-system-design/{crm|mom}/[功能名]_system-design.md`（可选，API 端点 + 错误码参考）
|
|
19
|
+
- PRD 文档：`docs/20-prd/{crm|mom}/[模块]/[需求规格说明书].md`（可选，验收场景参考）
|
|
20
|
+
|
|
21
|
+
**前置条件**：
|
|
22
|
+
- 前端设计文档已由 `/adspecs-front-spec` 产出
|
|
23
|
+
- 前端设计文档包含：§1 页面菜单路由规划、§2 总体布局、§3~§N 核心功能区域、§N+1 用户输入、§N+2 错误处理、§N+3 状态管理、§8 US→FSD 对齐表
|
|
24
|
+
|
|
25
|
+
**TDD 约定**：先编写组件测试和 Store 单元测试并验证失败，再实施页面组件和 Store 实现。
|
|
26
|
+
|
|
27
|
+
**组织方式**：任务按用户故事分组，以支持每个故事的独立 TDD 实现。
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 技术栈检测（任务生成前置）
|
|
32
|
+
|
|
33
|
+
> **目的**：确定本项目的前端技术栈，后续所有术语、路径、示例均按检测到的栈展开。
|
|
34
|
+
> **输出变量**：`FRONTEND_STACK`（`vue` | `react`）和 `FRONTEND_PROJECT_DIR`（前端项目根目录名）。
|
|
35
|
+
|
|
36
|
+
按以下优先级依次尝试，命中任意一级即停止：
|
|
37
|
+
|
|
38
|
+
| 优先级 | 检测源 | 判定规则 |
|
|
39
|
+
| ------ | ------ | -------- |
|
|
40
|
+
| 1 | `.adspecs/project.json` | 读取 `frontend_stack` 字段（`vue` / `react`）。`/project-init` 在初始化时写入 |
|
|
41
|
+
| 2 | 项目根 `CLAUDE.md` §Frontend | 关键字命中：含 `Vue 3` / `Element Plus` / `Pinia` → `vue`；含 `React` / `Ant Design` / `Zustand` → `react` |
|
|
42
|
+
| 3 | 前端设计文档（`*_前端设计.md`）§1 | 文档开头"技术栈"或"项目路径"段落中声明的框架 |
|
|
43
|
+
| 4 | 项目目录结构启发式 | 存在 `src/views/**/*.vue` → `vue`；存在 `src/pages/**/*.tsx` → `react` |
|
|
44
|
+
| 5 | 回退：询问用户 | 使用 AskUserQuestion 让用户选择 `Vue + Element Plus` 或 `React + Ant Design` |
|
|
45
|
+
|
|
46
|
+
**`FRONTEND_PROJECT_DIR` 检测**：
|
|
47
|
+
- 优先从 `.adspecs/project.json` 的 `frontend_dir` 字段读取
|
|
48
|
+
- 其次从 `CLAUDE.md` §Frontend 中提取项目根目录名
|
|
49
|
+
- 默认值：`front-demo/`
|
|
50
|
+
|
|
51
|
+
检测完成后，在内部记录两个变量，后续章节按此展开：
|
|
52
|
+
```
|
|
53
|
+
FRONTEND_STACK = vue | react
|
|
54
|
+
FRONTEND_PROJECT_DIR = {前端项目根目录名}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 任务格式：`- [ ] [TaskID] [P?] [TDD?] [Story?] 描述 + 精确文件路径`
|
|
60
|
+
|
|
61
|
+
| 元素 | 说明 |
|
|
62
|
+
| --------------- | ------------------------------------------------------------------------------------- |
|
|
63
|
+
| `- [ ]` | Markdown 复选框（始终存在） |
|
|
64
|
+
| `[TaskID]` | 全局递增序号：T001, T002, T003... |
|
|
65
|
+
| `[P]` | 可并行执行标记（操作不同文件，无未完成依赖） |
|
|
66
|
+
| `[TDD]` | 测试任务标记（Store 单元测试 / 组件测试），**必须在同故事实现任务之前完成且验证失败** |
|
|
67
|
+
| `[Story]` | 用户故事标签：[US1], [US2]...。Phase 1/2/Final 无此标签 |
|
|
68
|
+
| 描述 + 文件路径 | 明确操作描述 + 从 `{FRONTEND_PROJECT_DIR}/src/` 开始的完整文件路径 |
|
|
69
|
+
|
|
70
|
+
**格式示例（按 `FRONTEND_STACK` 展开）**：
|
|
71
|
+
|
|
72
|
+
*Vue 技术栈示例*：
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
✅ 正确：
|
|
76
|
+
- [ ] T012 [TDD] [US1] 编写 ForecastOrderList 组件渲染测试（列表加载+分页+筛选），文件：
|
|
77
|
+
{FRONTEND_PROJECT_DIR}/src/views/sales-forecast/__tests__/ForecastOrderList.spec.ts
|
|
78
|
+
- [ ] T013 [US1] 创建 ForecastOrderList 页面组件（<script setup lang="ts"> + el-table/el-pagination/el-tag），文件：
|
|
79
|
+
{FRONTEND_PROJECT_DIR}/src/views/sales-forecast/ForecastOrderList.vue
|
|
80
|
+
|
|
81
|
+
❌ 错误：
|
|
82
|
+
- [ ] 创建预测单页面（缺少 TaskID + 文件路径 + Story 标签）
|
|
83
|
+
- T001 [US1] 创建列表页（缺少复选框 + 精确文件路径）
|
|
84
|
+
- [ ] T001 [US1] 创建页面（缺少文件路径）
|
|
85
|
+
- [ ] T010 [US1] 实现列表页组件（故事阶段内未先写 [TDD] 测试，违反 TDD 规则）
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
*React 技术栈示例*：
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
✅ 正确：
|
|
92
|
+
- [ ] T012 [TDD] [US1] 编写 ForecastOrderList 组件渲染测试（列表加载+分页+筛选），文件：
|
|
93
|
+
{FRONTEND_PROJECT_DIR}/src/pages/sales-forecast/__tests__/ForecastOrderList.spec.tsx
|
|
94
|
+
- [ ] T013 [US1] 创建 ForecastOrderList 页面组件（函数组件 + ProTable + Tag/Pagination），文件：
|
|
95
|
+
{FRONTEND_PROJECT_DIR}/src/pages/sales-forecast/ForecastOrderList.tsx
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 前端技术栈映射表
|
|
101
|
+
|
|
102
|
+
> 根据 §技术栈检测 得到的 `FRONTEND_STACK` 选择对应列。所有 Phase 任务中的占位符均按此表展开。
|
|
103
|
+
|
|
104
|
+
| 概念 | Vue 技术栈 (`FRONTEND_STACK=vue`) | React 技术栈 (`FRONTEND_STACK=react`) |
|
|
105
|
+
| ---- | -------------------------------- | ------------------------------------- |
|
|
106
|
+
| 框架 | Vue 3.5 + `<script setup lang="ts">` | React 19 + 函数组件 + Hooks |
|
|
107
|
+
| 类型 | TypeScript 5.8 | TypeScript 6 |
|
|
108
|
+
| UI 库 | Element Plus 2.9（`<el-*>` 前缀） | Ant Design 6 + ProComponents（`<a-*>` / `<ProTable>` 等） |
|
|
109
|
+
| 状态管理 | Pinia 3（`defineStore` setup 语法） | Zustand（`create<State>`） |
|
|
110
|
+
| 路由 | vue-router 4（`defineAsyncComponent` 懒加载） | react-router（`React.lazy` + `Suspense`） |
|
|
111
|
+
| i18n | vue-i18n 11（`$t()` / `useI18n()`） | react-i18next（`useTranslation()` / `t()`） |
|
|
112
|
+
| 图表 | ECharts 5（按需引入 `echarts/core`） | ECharts 5（按需引入 `echarts/core`） |
|
|
113
|
+
| 构建 | Vite 6（`vue-tsc --build` 类型检查） | Vite 6（`tsc --noEmit` 类型检查） |
|
|
114
|
+
| 单元测试 | vitest | vitest |
|
|
115
|
+
| 组件测试库 | @vue/test-utils | @testing-library/react |
|
|
116
|
+
| 组件扩展名 | `.vue` | `.tsx` |
|
|
117
|
+
| 页面目录 | `src/views/{module}/` | `src/pages/{module}/` |
|
|
118
|
+
| 状态目录 | `src/store/modules/{module}/` | `src/stores/{module}/` |
|
|
119
|
+
| API 目录 | `src/api/{module}/` | `src/api/{module}/` |
|
|
120
|
+
| 类型目录 | `src/types/{module}/` | `src/types/{module}/` |
|
|
121
|
+
| 路由目录 | `src/router/modules/` | `src/router/` |
|
|
122
|
+
| i18n 目录 | `src/i18n/{locale}/` | `src/locales/{locale}/` |
|
|
123
|
+
| 通用组件目录 | `src/components/` | `src/components/` |
|
|
124
|
+
| Hooks 目录 | `src/hooks/` | `src/hooks/` |
|
|
125
|
+
| 请求封装 | `src/utils/request.ts` | `src/utils/request.ts` |
|
|
126
|
+
| 错误处理 | `src/utils/errorHandler.ts` | `src/utils/errorHandler.ts` |
|
|
127
|
+
| 状态标签组件 | `StatusTag.vue` | `StatusTag.tsx` |
|
|
128
|
+
| 操作按钮组件 | `ActionButtons.vue` | `ActionButtons.tsx` |
|
|
129
|
+
| 测试命令 | `npx vitest run {test-file}` | `npx vitest run {test-file}` |
|
|
130
|
+
| 参考规范 | `references/front-demo/.claude/rules/` | `references/ant6-front-standard/` |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 前端项目路径约定
|
|
135
|
+
|
|
136
|
+
> 来源：CLAUDE.md §Frontend + 前端设计文档。下方目录树按 `FRONTEND_STACK` 展开，`{EXT}` 表示组件扩展名（Vue: `.vue`；React: `.tsx`）。
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
{FRONTEND_PROJECT_DIR}/ # 前端项目根目录
|
|
140
|
+
├── src/
|
|
141
|
+
│ ├── api/ # API 接口模块（HTTP 客户端封装）
|
|
142
|
+
│ │ └── {module}/ # 按业务模块组织
|
|
143
|
+
│ │ ├── {entity}.ts # 实体 CRUD 接口
|
|
144
|
+
│ │ └── ...
|
|
145
|
+
│ ├── {PAGE_DIR}/ # 页面组件（Vue: views/；React: pages/）
|
|
146
|
+
│ │ └── {module}/ # 按业务模块组织
|
|
147
|
+
│ │ ├── {page}List{EXT} # 列表页
|
|
148
|
+
│ │ ├── {page}Edit{EXT} # 创建/编辑页
|
|
149
|
+
│ │ ├── {page}Detail{EXT} # 详情页
|
|
150
|
+
│ │ ├── {page}Overview{EXT} # 概览/报表页
|
|
151
|
+
│ │ ├── components/ # 页面级私有组件
|
|
152
|
+
│ │ │ ├── {Entity}Form{EXT} # 表单组件
|
|
153
|
+
│ │ │ ├── {Entity}Table{EXT} # 表格组件
|
|
154
|
+
│ │ │ └── ...
|
|
155
|
+
│ │ └── __tests__/ # 页面组件测试
|
|
156
|
+
│ ├── router/ # 路由配置
|
|
157
|
+
│ │ └── modules/ # 按模块拆分路由
|
|
158
|
+
│ │ └── {module}.ts # 模块路由定义
|
|
159
|
+
│ ├── {STORE_DIR}/ # 状态管理（Vue: store/modules/；React: stores/）
|
|
160
|
+
│ │ └── {module}/
|
|
161
|
+
│ │ ├── {entity}Store.ts # 实体状态 Store
|
|
162
|
+
│ │ └── __tests__/ # Store 单元测试
|
|
163
|
+
│ ├── components/ # 全局共享组件
|
|
164
|
+
│ │ ├── StatusTag{EXT} # 状态标签通用组件
|
|
165
|
+
│ │ ├── SearchForm{EXT} # 通用搜索表单
|
|
166
|
+
│ │ ├── ActionButtons{EXT} # 动态操作按钮组
|
|
167
|
+
│ │ └── ...
|
|
168
|
+
│ ├── types/ # TypeScript 类型定义
|
|
169
|
+
│ │ └── {module}/
|
|
170
|
+
│ │ ├── {entity}.ts # 实体类型 + 枚举
|
|
171
|
+
│ │ └── api.ts # API 请求/响应类型
|
|
172
|
+
│ ├── utils/ # 工具函数
|
|
173
|
+
│ │ ├── request.ts # HTTP 客户端实例 + 拦截器
|
|
174
|
+
│ │ ├── errorHandler.ts # 错误码→用户提示文案映射
|
|
175
|
+
│ │ └── dateFormat.ts # 日期格式化工具
|
|
176
|
+
│ ├── {I18N_DIR}/ # 国际化（Vue: i18n/；React: locales/）
|
|
177
|
+
│ │ ├── zh-CN/
|
|
178
|
+
│ │ │ └── {module}.ts # 模块文案
|
|
179
|
+
│ │ └── en-US/
|
|
180
|
+
│ │ └── {module}.ts
|
|
181
|
+
│ └── hooks/ # Composition API 钩子 / React Hooks
|
|
182
|
+
│ └── use{Feature}.ts # 可复用业务逻辑钩子
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**路径命名约定**：
|
|
186
|
+
- 目录名：kebab-case（`sales-forecast`）
|
|
187
|
+
- 文件名：PascalCase（`{EXT}`/`.ts`）- `ForecastOrderList{EXT}`、`forecastOrderApi.ts`
|
|
188
|
+
- Store 名：`use{Entity}Store.ts`
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 前端任务类型速查表
|
|
193
|
+
|
|
194
|
+
> 按 `FRONTEND_STACK` 展开对应的框架/规范列。
|
|
195
|
+
|
|
196
|
+
| 任务类型 | Vue 栈框架/规范 | React 栈框架/规范 | 关键约束 | 文件路径模式 |
|
|
197
|
+
| -------- | -------------- | ---------------- | -------- | ------------ |
|
|
198
|
+
| **类型定义** | TypeScript interface/enum | TypeScript interface/enum | 字段对齐后端 DTO/Ro；枚举值与后端一致 | `src/types/{module}/{entity}.ts` |
|
|
199
|
+
| **API 接口模块** | axios + `src/utils/request.ts` | axios/fetch + `src/utils/request.ts` | 统一使用封装；请求/响应类型明确 | `src/api/{module}/{entity}.ts` |
|
|
200
|
+
| **状态管理** | Pinia `defineStore` (setup 语法) | Zustand `create<State>` | 对齐前端设计 §10 状态管理；camelCase 命名；初始值与设计一致 | Vue: `src/store/modules/{module}/{entity}Store.ts`<br>React: `src/stores/{module}/{entity}Store.ts` |
|
|
201
|
+
| **列表页组件** | Vue SFC + Element Plus (`<el-table>`) | React FC + ProComponents (`<ProTable>`) | 含搜索筛选区+数据表格+分页+操作列；状态标签使用组件库颜色语义 | Vue: `src/views/{module}/{Entity}List.vue`<br>React: `src/pages/{module}/{Entity}List.tsx` |
|
|
202
|
+
| **表单页组件** | Vue SFC + `<el-form>` rules | React FC + ProForm / `Form` | 含表单字段+校验规则+提交按钮；校验使用声明式规则 | Vue: `src/views/{module}/{Entity}Edit.vue`<br>React: `src/pages/{module}/{Entity}Edit.tsx` |
|
|
203
|
+
| **详情页组件** | Vue SFC + Element Plus | React FC + Ant Design | 含信息卡片+子表格+操作按钮区；操作按钮按状态+角色动态显示 | Vue: `src/views/{module}/{Entity}Detail.vue`<br>React: `src/pages/{module}/{Entity}Detail.tsx` |
|
|
204
|
+
| **图表/概览组件** | ECharts + Element Plus | ECharts + Ant Design | 图表按维度切换；下钻交互；导出功能 | Vue: `src/views/{module}/{Entity}Overview.vue`<br>React: `src/pages/{module}/{Entity}Overview.tsx` |
|
|
205
|
+
| **路由配置** | vue-router 4 动态路由 | react-router 动态路由 | 层级清晰；权限 guard；懒加载 | Vue: `src/router/modules/{module}.ts`<br>React: `src/router/{module}.ts` |
|
|
206
|
+
| **i18n 文案** | vue-i18n (`$t()` / `useI18n()`) | react-i18next (`useTranslation()`) | 消息码文案从前端设计 §9 错误处理表提取；最少中/英两种语言 | Vue: `src/i18n/{locale}/{module}.ts`<br>React: `src/locales/{locale}/{module}.ts` |
|
|
207
|
+
| **Hook** | Vue 3 Composition API | React Hooks | 提取可复用逻辑（分页/筛选/表单校验/乐观锁冲突处理） | `src/hooks/use{Feature}.ts` |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## Phase 1：项目初始化
|
|
212
|
+
|
|
213
|
+
**目的**：安装依赖、配置路由框架、创建基础目录结构
|
|
214
|
+
|
|
215
|
+
- [ ] T001 确保项目依赖就绪（`npm install`），按 `FRONTEND_STACK` 安装对应框架 + UI 库 + 状态管理 + 路由 + i18n
|
|
216
|
+
- [ ] T002 创建模块目录结构 `{PAGE_DIR}/sales-forecast/`、`src/api/sales-forecast/`、`{STORE_DIR}/sales-forecast/`、`src/types/sales-forecast/`、`src/router/modules/sales-forecast.ts`
|
|
217
|
+
- [ ] T003 创建模块路由配置文件，定义 7 个页面路由（含 meta 权限标记），文件：
|
|
218
|
+
`{FRONTEND_PROJECT_DIR}/src/router/modules/sales-forecast.ts`
|
|
219
|
+
- [ ] T004 [P] 创建/确认 `src/utils/request.ts`（HTTP 客户端实例 + 拦截器，含 token 注入、错误统一处理）
|
|
220
|
+
|
|
221
|
+
**检查点**：`npm run dev` 可启动，路由骨架就绪
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## Phase 2：基础设施（阻塞性前置依赖）
|
|
226
|
+
|
|
227
|
+
**目的**：TypeScript 类型定义、API 模块封装、通用组件、工具函数
|
|
228
|
+
|
|
229
|
+
**⚠️ 关键**：在此阶段完成之前，不得开始任何页面组件开发
|
|
230
|
+
|
|
231
|
+
### 2.1 类型定义（可并行）
|
|
232
|
+
|
|
233
|
+
- [ ] T005 [P] 创建 `ForecastOrder` 类型（接口字段对齐后端 Ro + Entity，含 status/moq/productType 等），文件：
|
|
234
|
+
`{FRONTEND_PROJECT_DIR}/src/types/sales-forecast/forecastOrder.ts`
|
|
235
|
+
- [ ] T006 [P] 创建 `ForecastChangeOrder` 类型（快照字段+变更字段+审批字段），文件：
|
|
236
|
+
`{FRONTEND_PROJECT_DIR}/src/types/sales-forecast/forecastChangeOrder.ts`
|
|
237
|
+
- [ ] T007 [P] 创建枚举类型（`ForecastOrderStatus` / `ChangeOrderStatus` / `ProductType` / `TransferStatus` / `DomesticForeign` — 值与后端枚举编码一致），文件：
|
|
238
|
+
`{FRONTEND_PROJECT_DIR}/src/types/sales-forecast/enums.ts`
|
|
239
|
+
- [ ] T008 [P] 创建 API 请求/响应泛型类型（`PaginationRequest<T>` / `PaginationResponse<T>` / `ResponseData<T>` / `RequestData<T>`），文件：
|
|
240
|
+
`{FRONTEND_PROJECT_DIR}/src/types/sales-forecast/api.ts`
|
|
241
|
+
|
|
242
|
+
### 2.2 API 模块 + 工具 + 通用组件（可并行）
|
|
243
|
+
|
|
244
|
+
- [ ] T009 创建 `forecastOrderApi`（getById/findPagination/save/update/delete/submit/withdraw/cancel/accept/reject/scheduleConfirm/transferToFO/forceRelease/overview — 14 个端点），文件：
|
|
245
|
+
`{FRONTEND_PROJECT_DIR}/src/api/sales-forecast/forecastOrder.ts`
|
|
246
|
+
- [ ] T010 [P] 创建 `forecastChangeOrderApi`（getById/save/update/delete/submit/approve/reject/withdraw/void — 9 个端点），文件：
|
|
247
|
+
`{FRONTEND_PROJECT_DIR}/src/api/sales-forecast/forecastChangeOrder.ts`
|
|
248
|
+
- [ ] T011 [P] 创建错误码映射表（后端 22 个错误码 → 用户提示文案 + 展示方式），文件：
|
|
249
|
+
`{FRONTEND_PROJECT_DIR}/src/utils/errorHandler.ts`
|
|
250
|
+
- [ ] T012 [P] 创建通用 `StatusTag{EXT}` 组件（接收 status 值 + 状态映射配置，自动渲染对应颜色标签），文件：
|
|
251
|
+
`{FRONTEND_PROJECT_DIR}/src/components/StatusTag{EXT}`
|
|
252
|
+
- [ ] T013 [P] 创建通用 `ActionButtons{EXT}` 组件（接收状态+角色，按前端设计 §5.1 规则动态渲染操作按钮组），文件：
|
|
253
|
+
`{FRONTEND_PROJECT_DIR}/src/components/ActionButtons{EXT}`
|
|
254
|
+
- [ ] T014 [P] 创建 `usePagination` hook（分页参数管理、查询触发、loading 状态），文件：
|
|
255
|
+
`{FRONTEND_PROJECT_DIR}/src/hooks/usePagination.ts`
|
|
256
|
+
|
|
257
|
+
**检查点**：类型定义完整、API 模块就绪、通用组件可用
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## Phase 3：US-01 — 预测单列表页（优先级：P1）🎯 MVP 起点
|
|
262
|
+
|
|
263
|
+
**目标**：销售人员可查看所有预测单列表，支持多条件筛选、分页、按状态+角色显示操作按钮
|
|
264
|
+
|
|
265
|
+
**独立测试**：导航到 /sales/forecast/list → 默认展示 20 条预测单 → 切换状态筛选 → 列表刷新 → 点击单号进入详情页
|
|
266
|
+
|
|
267
|
+
**来源**：前端设计 §3 核心功能区域 — 预测单列表页、§3.1 状态标签映射、§10.1 列表状态管理
|
|
268
|
+
|
|
269
|
+
### 用户故事 1 的 TDD 测试
|
|
270
|
+
|
|
271
|
+
- [ ] T015 [TDD] [US1] 编写 `useForecastOrderList` Store 单元测试（列表加载+分页+筛选+loading 状态），文件：
|
|
272
|
+
`{FRONTEND_PROJECT_DIR}/{STORE_DIR}/sales-forecast/__tests__/forecastOrderListStore.spec.ts`
|
|
273
|
+
- [ ] T016 [TDD] [P] [US1] 编写 `ForecastOrderList` 组件渲染测试（列表渲染+状态标签颜色+操作按钮按状态显示+分页交互），文件：
|
|
274
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderList.spec.{EXT_TS}`
|
|
275
|
+
|
|
276
|
+
### 用户故事 1 的实现
|
|
277
|
+
|
|
278
|
+
- [ ] T017 [US1] 创建 `useForecastOrderList` Store（list/pagination/filters/loading/selectedRows 状态 + fetchList/search/reset 方法，对齐前端设计 §10.1），文件：
|
|
279
|
+
`{FRONTEND_PROJECT_DIR}/{STORE_DIR}/sales-forecast/forecastOrderListStore.ts`
|
|
280
|
+
- [ ] T018 [US1] 创建 `ForecastOrderList{EXT}` 页面组件（搜索筛选区：状态多选+客户搜索+物料搜索+提报时间范围+内外销+创建人+查询/重置按钮；数据表格：单号/状态标签/客户/物料/需求量/入库时间/提报人；操作列：编辑/提交/撤回/详情/取消/转FO 按角色+状态动态显示；分页条），文件：
|
|
281
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/ForecastOrderList{EXT}`
|
|
282
|
+
|
|
283
|
+
**检查点**：列表页加载正常，筛选刷新正确，状态标签颜色匹配设计
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Phase 4：US-01 — 预测单创建/编辑页（优先级：P1）
|
|
288
|
+
|
|
289
|
+
**目标**：销售人员创建新预测单（输入 CTCT 自动回填），或编辑草稿/已驳回状态的预测单
|
|
290
|
+
|
|
291
|
+
**独立测试**：点击新增按钮 → 输入 CTCT 编码 → 失焦自动回填物料+客户信息 → 填写需求量/交期 → 保存草稿成功（无单号） → 提交成功（生成单号+状态已提交）
|
|
292
|
+
|
|
293
|
+
**来源**：前端设计 §4 核心功能区域 — 创建/编辑页、§8.1 输入表单
|
|
294
|
+
|
|
295
|
+
### TDD 测试 + 实现
|
|
296
|
+
|
|
297
|
+
- [ ] T019 [TDD] [US1] 编写 `ForecastOrderEdit` 组件测试（CTCT 自动回填+mock/保存草稿/提交成功/校验失败拦截/MOQ 警告），文件：
|
|
298
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderEdit.spec.{EXT_TS}`
|
|
299
|
+
- [ ] T020 [US1] 创建 `ForecastOrderForm{EXT}` 表单组件（CTCT 文本框+失焦自动查询；SAP物料号下拉+动态加载；数量单位/发货地点下拉；需求量数字输入+MOQ 提示；入库时间日期选择器+提前期校验；保税手册下拉+手册余量展示；来料加工开关；原因说明文本域；保存草稿+提交按钮），文件：
|
|
300
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/components/ForecastOrderForm{EXT}`
|
|
301
|
+
- [ ] T021 [US1] 创建 `ForecastOrderEdit{EXT}` 页面组件（新建模式：空表单；编辑模式：回填数据+状态校验仅草稿/已驳回可编辑；路由参数 id 判断模式；提交成功跳转列表），文件：
|
|
302
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/ForecastOrderEdit{EXT}`
|
|
303
|
+
- [ ] T022 [P] [US1] 创建 `useForecastOrderForm` hook（表单数据管理/校验错误管理/CTCT 查询 loading/submitting 状态），文件：
|
|
304
|
+
`{FRONTEND_PROJECT_DIR}/src/hooks/useForecastOrderForm.ts`
|
|
305
|
+
|
|
306
|
+
**检查点**：CTCT 编码输入自动回填物料+客户信息，保存草稿+提交流程正常
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Phase 5：US-02 + US-03 + US-04 + US-09 + US-08 — 预测单详情页（优先级：P1/P2 综合）
|
|
311
|
+
|
|
312
|
+
**目标**：详情页展示预测单完整信息+排产进度+变更历史+操作按钮区；集成接收/驳回/撤回/取消/删除/转FO 全部操作
|
|
313
|
+
|
|
314
|
+
**独立测试**：导航到 /sales/forecast/detail/{id} → 查看完整信息卡片 → 点击撤回 → 状态变草稿；计划部门登录 → 点击接收 → 填写答复 → 状态变计划接收
|
|
315
|
+
|
|
316
|
+
**来源**：前端设计 §5 详情页、§5.1 操作按钮规则、§8.2 转FO弹窗、§8.3 接收驳回表单
|
|
317
|
+
|
|
318
|
+
### TDD 测试 + 实现
|
|
319
|
+
|
|
320
|
+
- [ ] T023 [TDD] [US2] 编写 `ForecastOrderDetail` 组件测试（4 状态显示+操作按钮按角色+状态动态显示+排产进度正常+降级/接收/驳回交互），文件：
|
|
321
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderDetail.spec.{EXT_TS}`
|
|
322
|
+
- [ ] T024 [US2] 创建 `useForecastOrderDetail` Store（detail/changeOrderList/scheduleProgress/scheduleError/loading/actionButtons 状态，对齐前端设计 §10.3），文件：
|
|
323
|
+
`{FRONTEND_PROJECT_DIR}/{STORE_DIR}/sales-forecast/forecastOrderDetailStore.ts`
|
|
324
|
+
- [ ] T025 [US2] 创建 `ForecastOrderDetail{EXT}` 页面组件：
|
|
325
|
+
- 操作按钮区：ActionButtons 组件（按 §5.1 规则动态渲染）
|
|
326
|
+
- 基本信息卡片：单号/状态标签/类型/提报人/提报时间/内外销/销售组织
|
|
327
|
+
- 客户+物料+投料信息卡片
|
|
328
|
+
- 计划答复卡片：计划建议量/答复入库时间/答复意见/回复时间
|
|
329
|
+
- 转单信息卡片：转单状态标签/FO单号/已转单数量/剩余待转单/强制转FO时间
|
|
330
|
+
- APS 排产进度区：正常展示+超时降级"排产进度暂不可用"
|
|
331
|
+
- 变更历史子表 + 新增变更单按钮（计划接收/已排产/已部分转单可见）
|
|
332
|
+
- 接收弹窗（计划建议量+答复入库时间+答复意见）/ 驳回弹窗（驳回原因）
|
|
333
|
+
- 转FO弹窗（SO行项目选择+转单数量）
|
|
334
|
+
文件：`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/ForecastOrderDetail{EXT}`
|
|
335
|
+
- [ ] T026 [P] [US2] 创建 `TransferFoDialog{EXT}` 弹窗组件（SO行项目下拉+转单数量数字输入+确认/取消），文件：
|
|
336
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/components/TransferFoDialog{EXT}`
|
|
337
|
+
- [ ] T027 [P] [US2] 创建 `ReplyDialog{EXT}` 弹窗组件（接收模式：计划建议量+答复时间+答复意见；驳回模式：驳回原因；动态切换），文件：
|
|
338
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/components/ReplyDialog{EXT}`
|
|
339
|
+
- [ ] T028 [US2] 创建 `useApsSchedule` hook（APS 排产进度查询+超时降级+loading 管理），文件：
|
|
340
|
+
`{FRONTEND_PROJECT_DIR}/src/hooks/useApsSchedule.ts`
|
|
341
|
+
|
|
342
|
+
**检查点**：详情页全信息展示完整，操作按钮按角色+状态正确显示，接收/驳回/转FO 交互正常
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
346
|
+
## Phase 6：US-05 — 变更单新增/编辑/审批（优先级：P1）
|
|
347
|
+
|
|
348
|
+
**目标**：在详情页内新增变更单（自动快照原始信息），按需填写变更字段，提交审批，审批通过联动更新
|
|
349
|
+
|
|
350
|
+
**独立测试**：已排产预测单详情页 → 点击新增变更单 → 自动快照展示 → 填写变更后入库时间 → 提交 → 审批通过 → 详情页入库时间联动更新
|
|
351
|
+
|
|
352
|
+
**来源**：前端设计 §7 变更单新增/编辑、§7.1 快照信息、§8.5 变更单表单
|
|
353
|
+
|
|
354
|
+
### TDD 测试 + 实现
|
|
355
|
+
|
|
356
|
+
- [ ] T029 [TDD] [US5] 编写 `ChangeOrderEdit` 组件测试（自动快照展示+按需填写+提交校验/并发控制拦截+审批通过/驳回交互），文件：
|
|
357
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ChangeOrderEdit.spec.{EXT_TS}`
|
|
358
|
+
- [ ] T030 [P] [US5] 创建 `useChangeOrderForm` Store（snapshot+changeForm+submitting+errors 状态，对齐前端设计 §10.5），文件：
|
|
359
|
+
`{FRONTEND_PROJECT_DIR}/{STORE_DIR}/sales-forecast/changeOrderFormStore.ts`
|
|
360
|
+
- [ ] T031 [US5] 创建 `ChangeForm{EXT}` 表单组件（原始快照区灰色背景只读展示；变更后客户文本框+CTCT校验；变更后入库时间日期选择器；变更后保税手册下拉；释放资源量数字输入+剩余待转单约束；按需填写提示；保存草稿+提交按钮），文件：
|
|
361
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/components/ChangeForm{EXT}`
|
|
362
|
+
- [ ] T032 [US5] 创建 `ChangeOrderEdit{EXT}` 页面/弹窗（新增模式：自动加载快照；编辑模式草稿/已驳回：回填数据；提交校验:BR-05/BR-12/BR-13/BR-03；调用 forecastChangeOrderApi；成功后刷新详情页变更历史），文件：
|
|
363
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/ChangeOrderEdit{EXT}`
|
|
364
|
+
|
|
365
|
+
**检查点**：变更单新增自动快照正常，按需填写校验正确，审批通过联动更新
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
369
|
+
## Phase 7：US-06 — 预测单概览视图（优先级：P2）
|
|
370
|
+
|
|
371
|
+
**目标**：按时间/客户/品种维度聚合展示预测单数据，支持图表钻取和 Excel 导出
|
|
372
|
+
|
|
373
|
+
**独立测试**：导航到概览视图 → 选择时间维度 → 柱状图展示各月需求量 → 点击某月柱体 → 弹出该月明细列表
|
|
374
|
+
|
|
375
|
+
**来源**：前端设计 §6 概览视图、§1.4 图表交互、§10.4 概览状态管理
|
|
376
|
+
|
|
377
|
+
- [ ] T033 [TDD] [US9] 编写 `ForecastOrderOverview` 组件测试（维度切换+图表渲染+钻取弹窗），文件：
|
|
378
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderOverview.spec.{EXT_TS}`
|
|
379
|
+
- [ ] T034 [P] [US9] 创建 `useOverview` Store（activeDimension/chartData/tableData/filters/loading/drillDownVisible/drillDownData 状态，对齐前端设计 §10.4），文件：
|
|
380
|
+
`{FRONTEND_PROJECT_DIR}/{STORE_DIR}/sales-forecast/overviewStore.ts`
|
|
381
|
+
- [ ] T035 [US9] 创建 `ForecastOrderOverview{EXT}` 页面组件（筛选区：维度Tab+基地+周期；图表区：ECharts Bar/Pie/Line 按维度切换；聚合表格：维度值/条数/需求量合计/已转单合计/剩余；点击下钻弹窗展示明细列表；导出Excel 按钮），文件：
|
|
382
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/ForecastOrderOverview{EXT}`
|
|
383
|
+
- [ ] T036 [P] [US9] 创建 `OverviewDrillDown{EXT}` 钻取弹窗组件（展示某维度下的预测单明细列表+分页），文件：
|
|
384
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/components/OverviewDrillDown{EXT}`
|
|
385
|
+
- [ ] T037 [P] [US9] 创建 `useECharts` hook（ECharts 实例管理、响应式 resize、主题切换），文件：
|
|
386
|
+
`{FRONTEND_PROJECT_DIR}/src/hooks/useECharts.ts`
|
|
387
|
+
|
|
388
|
+
**检查点**：概览视图维度切换流畅，图表钻取正常，导出可用
|
|
389
|
+
|
|
390
|
+
---
|
|
391
|
+
|
|
392
|
+
## Phase 8：US-10 — 系统配置页（优先级：P2）
|
|
393
|
+
|
|
394
|
+
**目标**：系统管理员配置提报提前期天数（1~365）和强制转FO天数（1~90）
|
|
395
|
+
|
|
396
|
+
**来源**：前端设计 §8.4 系统配置页
|
|
397
|
+
|
|
398
|
+
- [ ] T038 [US10] 创建 `SystemConfig{EXT}` 页面组件（提报提前期数字输入 1~365+默认30；强制转FO天数数字输入 1~90+默认5；修改强制转FO天数字段时弹出风险提示弹窗；保存按钮+loading+成功Toast），文件：
|
|
399
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/SystemConfig{EXT}`
|
|
400
|
+
|
|
401
|
+
**检查点**：配置保存成功，Redis+DB 双写生效
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
|
|
405
|
+
## Phase 9：集成与收尾
|
|
406
|
+
|
|
407
|
+
**目的**：跨页面的质量保证、国际化、路由守卫、性能优化与构建验证
|
|
408
|
+
|
|
409
|
+
### E2E 测试
|
|
410
|
+
|
|
411
|
+
- [ ] T039 [TDD] 编写端到端测试（创建→提交→接收→排产确认→转FO 全流程），文件：
|
|
412
|
+
`{FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderE2E.spec.{EXT_TS}`
|
|
413
|
+
|
|
414
|
+
### 路由守卫与权限
|
|
415
|
+
|
|
416
|
+
- [ ] T040 完善路由守卫逻辑（销售人员/计划部门/审批人/管理员角色 → 菜单可见性+路由访问控制），文件：
|
|
417
|
+
`{FRONTEND_PROJECT_DIR}/src/router/modules/sales-forecast.ts`
|
|
418
|
+
|
|
419
|
+
### i18n 国际化
|
|
420
|
+
|
|
421
|
+
- [ ] T041 [P] 创建简体中文文案（页面标题/按钮文本/表单标签/状态文本/错误提示/placeholder 等，从错误码映射表提取），文件：
|
|
422
|
+
`{FRONTEND_PROJECT_DIR}/{I18N_DIR}/zh-CN/sales-forecast.ts`
|
|
423
|
+
- [ ] T042 [P] 创建英文文案（同上内容英文翻译），文件：
|
|
424
|
+
`{FRONTEND_PROJECT_DIR}/{I18N_DIR}/en-US/sales-forecast.ts`
|
|
425
|
+
|
|
426
|
+
### 代码评审与优化
|
|
427
|
+
|
|
428
|
+
- [ ] T043 执行前端编码规范合规检查（按 §编码规范检查清单 逐条确认，按 `FRONTEND_STACK` 执行对应列）
|
|
429
|
+
- [ ] T044 性能优化（列表页虚拟滚动/图表懒加载/路由懒加载/API 请求防抖/乐观锁冲突重试机制）
|
|
430
|
+
- [ ] T045 `npm run build` 构建验证（type-check + production build 通过）
|
|
431
|
+
- [ ] T046 `npm run lint` + `npm run format` 代码质量验证
|
|
432
|
+
|
|
433
|
+
---
|
|
434
|
+
|
|
435
|
+
## 依赖关系与执行顺序
|
|
436
|
+
|
|
437
|
+
### 阶段依赖
|
|
438
|
+
|
|
439
|
+
| 阶段 | 依赖 | 说明 |
|
|
440
|
+
| ----------------------------------- | ---------------------- | --------------------------------- |
|
|
441
|
+
| Phase 1（环境搭建） | 无 | 可立即开始 |
|
|
442
|
+
| Phase 2（基础设施） | Phase 1 | **阻塞所有页面开发** |
|
|
443
|
+
| Phase 3（US-01 列表页） | Phase 2 | P1 MVP 起点，产出列表Store+页面 |
|
|
444
|
+
| Phase 4（US-01 创建编辑） | Phase 2 + Phase 3 类型 | P1，可并行 |
|
|
445
|
+
| Phase 5（US-02/03/04/08/09 详情页） | Phase 2 + 全部 API | P1 综合，依赖列表页跳转 |
|
|
446
|
+
| Phase 6（US-05 变更单） | Phase 2 + 详情页 | P1，依赖详情页 ChangeHistory 区域 |
|
|
447
|
+
| Phase 7（US-06 概览） | Phase 2 | P2，独立页面 |
|
|
448
|
+
| Phase 8（US-10 配置） | Phase 2 | P2，独立页面 |
|
|
449
|
+
| Phase 9（集成收尾） | Phase 3~8 | E2E 需全功能就绪 |
|
|
450
|
+
|
|
451
|
+
### 并行机会
|
|
452
|
+
|
|
453
|
+
- **Phase 2**：类型定义 4 个文件完全并行（T005~T008）；API+工具+通用组件并行（T009~T014）
|
|
454
|
+
- **Phase 3+4**：列表页与创建编辑页可并行开发（不同文件、不同 Store）
|
|
455
|
+
- **Phase 7+8**：概览视图与系统配置页可并行（完全独立页面）
|
|
456
|
+
- **Phase 9**：i18n 2 文件并行（T041~T042）
|
|
457
|
+
- **跨 Phase 并行**：Phase 5（详情页+操作）与 Phase 6（变更单）按先详情再变更单顺序；Phase 7（概览）+Phase 8（配置）可并行
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
## 并行示例：US-01 预测单列表页 + 创建编辑页
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
# Step 1: 先编写测试（并行）→ 确保失败
|
|
465
|
+
Task T015: "[TDD] 编写列表 Store 单元测试"
|
|
466
|
+
Task T016: "[TDD] 编写列表页组件测试"
|
|
467
|
+
Task T019: "[TDD] 编写创建编辑页组件测试"
|
|
468
|
+
|
|
469
|
+
# 所有测试验证失败后 ↓
|
|
470
|
+
|
|
471
|
+
# Step 2: 并行创建 Store + Hook + API（互不依赖）
|
|
472
|
+
Task T017: "创建 useForecastOrderList Store"
|
|
473
|
+
Task T022: "创建 useForecastOrderForm hook"
|
|
474
|
+
|
|
475
|
+
# Step 3: 创建页面组件（依赖 Store+Hook）
|
|
476
|
+
Task T018: "创建 ForecastOrderList{EXT}"
|
|
477
|
+
Task T020+T021: "创建 ForecastOrderForm{EXT} + ForecastOrderEdit{EXT}"
|
|
478
|
+
|
|
479
|
+
# 运行测试 → 全部通过 ✅
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## 实现策略
|
|
485
|
+
|
|
486
|
+
### MVP 优先（P1 页面：列表/创建编辑/详情/变更单）
|
|
487
|
+
|
|
488
|
+
1. Phase 1+2 → 基础设施就绪
|
|
489
|
+
2. Phase 3 → 列表页 **← MVP 核心入口**
|
|
490
|
+
3. Phase 4 → 创建编辑页
|
|
491
|
+
4. Phase 5 → 详情页（含全部操作）
|
|
492
|
+
5. Phase 6 → 变更单
|
|
493
|
+
6. **STOP & VALIDATE**：全部 P1 页面端到端可走通
|
|
494
|
+
7. P1 MVP 就绪 → 部署/演示
|
|
495
|
+
|
|
496
|
+
### 增量交付
|
|
497
|
+
|
|
498
|
+
1. Phase 1+2 → 基座就绪
|
|
499
|
+
2. Phase 3 → 列表页独立可访问 → 部署
|
|
500
|
+
3. Phase 4 → 创建编辑页追加
|
|
501
|
+
4. Phase 5+6 → 详情页+变更单追加 → P1 MVP 完整
|
|
502
|
+
5. Phase 7+8 → P2 概览+配置追加
|
|
503
|
+
6. Phase 9 → 集成收尾
|
|
504
|
+
|
|
505
|
+
---
|
|
506
|
+
|
|
507
|
+
## 编码规范检查清单
|
|
508
|
+
|
|
509
|
+
> 生成 tasks.md 时必须逐条确认。按 `FRONTEND_STACK` 执行对应列的检查项。
|
|
510
|
+
|
|
511
|
+
### 栈无关项（两栈共检）
|
|
512
|
+
|
|
513
|
+
- [ ] 所有组件/Store/API/工具函数有完整 TypeScript 类型定义，禁用 `any`
|
|
514
|
+
- [ ] 统一使用项目封装的 HTTP 客户端（`src/utils/request.ts`），不直接调用 axios/fetch
|
|
515
|
+
- [ ] 路由层级清晰，页面组件懒加载，meta 含权限标记
|
|
516
|
+
- [ ] 错误码映射表集中管理（`utils/errorHandler.ts`），展示方式按前端设计（Message/Dialog/字段级）
|
|
517
|
+
- [ ] 通用状态标签组件，颜色语义严格遵循设计：蓝=进行中/绿=终态/红=驳回/橙=警告/灰=草稿取消
|
|
518
|
+
- [ ] 表单使用声明式校验规则，校验文案使用 i18n key
|
|
519
|
+
- [ ] 乐观锁操作携带版本号字段，冲突时友好提示
|
|
520
|
+
- [ ] 所有用户可见文案使用国际化函数，最少覆盖中/英两种语言
|
|
521
|
+
- [ ] `npm run build`（含类型检查 + 构建）零错误通过
|
|
522
|
+
- [ ] `npm run lint` + `npm run format` 无报错
|
|
523
|
+
|
|
524
|
+
### Vue 栈专属项（`FRONTEND_STACK=vue` 时检查）
|
|
525
|
+
|
|
526
|
+
- [ ] 所有组件使用 `<script setup lang="ts">` 语法，Props/Emits 类型声明
|
|
527
|
+
- [ ] 统一使用 `<el-*>` Element Plus 组件，状态标签使用 `<el-tag>` 颜色语义
|
|
528
|
+
- [ ] Store 使用 Pinia `defineStore` setup 语法，camelCase 命名
|
|
529
|
+
- [ ] 路由使用 `defineAsyncComponent` 懒加载
|
|
530
|
+
- [ ] 表单使用 `<el-form>` rules 声明式校验
|
|
531
|
+
- [ ] build 任务包含 `vue-tsc --build` + `vite build`
|
|
532
|
+
|
|
533
|
+
### React 栈专属项（`FRONTEND_STACK=react` 时检查）
|
|
534
|
+
|
|
535
|
+
- [ ] 所有组件为函数组件 + Hooks，Props 类型声明
|
|
536
|
+
- [ ] 统一使用 Ant Design 6 / ProComponents 组件
|
|
537
|
+
- [ ] Store 使用 Zustand `create<State>` 语法
|
|
538
|
+
- [ ] 路由使用 `React.lazy` + `Suspense` 懒加载
|
|
539
|
+
- [ ] 表单使用 ProForm / ModalForm / DrawerForm 标准模板
|
|
540
|
+
- [ ] build 任务包含 `tsc --noEmit` + `vite build`
|
|
541
|
+
|
|
542
|
+
---
|
|
543
|
+
|
|
544
|
+
## TDD 执行指南
|
|
545
|
+
|
|
546
|
+
### RED 阶段
|
|
547
|
+
|
|
548
|
+
```bash
|
|
549
|
+
# 1. 按 [TDD] 标记的任务编写测试代码
|
|
550
|
+
# 2. 运行并确认失败（路径按 FRONTEND_STACK 展开：Vue 栈 views/，React 栈 pages/）
|
|
551
|
+
npx vitest run {FRONTEND_PROJECT_DIR}/{PAGE_DIR}/sales-forecast/__tests__/ForecastOrderList.spec.{EXT_TS}
|
|
552
|
+
|
|
553
|
+
# 预期输出：Tests: 5 failed（组件/Store 未实现，预期失败）
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
### GREEN 阶段
|
|
557
|
+
|
|
558
|
+
```
|
|
559
|
+
Store 实现 → 组件实现 → 重新运行测试 → 全绿 ✅
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
### REFACTOR 阶段
|
|
563
|
+
|
|
564
|
+
```bash
|
|
565
|
+
# 不破坏测试前提下：
|
|
566
|
+
- 提取重复逻辑到 hooks
|
|
567
|
+
- 优化组件拆分粒度
|
|
568
|
+
- 添加 loading/empty/error 三态统一处理
|
|
569
|
+
npx vitest run # 全绿
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
## 注意事项
|
|
575
|
+
|
|
576
|
+
- 状态标签颜色严格遵循设计：蓝色=进行中(SUBMITTED/ACCEPTED/SCHEDULED)、绿色=终态(已变更/已全部转单完成)、红色=驳回(REJECTED)、橙色=已部分转单(PARTIAL_CONVERTED)、灰色=草稿/取消/释放/作废
|
|
577
|
+
- 操作按钮动态显示规则见前端设计 §5.1（9 状态×3 角色矩阵）
|
|
578
|
+
- CTCT 编码输入后失焦自动查询，查询过程展示 loading（禁用其他输入）
|
|
579
|
+
- APS 排产进度出站查询超时时降级展示，不阻塞详情页整体渲染
|
|
580
|
+
- 变更单自动快照在 `saveForecastChangeOrder` API 调用前由前端展示原始数据（从详情页 detail 对象读取）
|
|
581
|
+
- 所有乐观锁操作携带 versionNum，冲突时展示友好提示提供刷新操作
|
|
582
|
+
- i18n 至少覆盖中/英两种语言
|
|
583
|
+
- ECharts 图表组件按需引入（`import * as echarts from 'echarts/core'`），避免全量打包
|