Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
b80d2160 1 parent 32d02f6f

docs: 重组文档目录结构，分类整理所有文档 

主要变更：
- 创建分类目录：architecture/development/testing/tools/tasks
- 移动文档到对应分类目录
- 新增文档导航索引：docs/README.md
- 新增文档编写规范：docs/DOCUMENTATION_STANDARDS.md
- 新增任务管理索引：docs/tasks/README.md
- 更新主 README 文档链接

文档分类：
- architecture/: 架构设计（ARCHITECTURE.md, COMPONENTS.md）
- development/: 开发配置（ESLINT_PRETTIER.md, HUSKY_LINT_STAGED.md, WORKFLOW.md）
- testing/: 测试文档（PLAYWRIGHT.md, E2E_*.md）
- tools/: 工具指南（SKILLS_GUIDE.md）
- tasks/: 任务管理（done/plan/TODO）

文档规范：
- 使用英文大写+下划线命名（如 E2E_AUTH_GUIDE.md）
- 任务文档格式：[日期]_[类型]_[描述].md
- 新增文档时必须更新 docs/README.md 索引

详见：docs/DOCUMENTATION_STANDARDS.md
Expand all
Inline Side-by-side
Showing 25 changed files with 1134 additions and 312 deletions
...@@ -59,12 +59,37 @@ src/ ...@@ -59,12 +59,37 @@ src/
59 59
60 ## 文档索引 60 ## 文档索引
61 61
62 -- 近期功能更新记录：[/docs/CHANGELOG.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/CHANGELOG.md) 62 +📚 **完整文档导航**: [docs/README.md](./docs/README.md) - 所有文档的分类索引
63 -- 架构实现与工程配置：[/docs/ARCHITECTURE.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/ARCHITECTURE.md) 63 +
64 -- /src/components 组件目录索引：[/docs/COMPONENTS.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/COMPONENTS.md) 64 +### 快速链接
65 -- 代码风格与最佳实践：[/VUE_CODE_STYLE_GUIDE.md](file:///Users/huyirui/program/itomix/git/mlaj/VUE_CODE_STYLE_GUIDE.md) 65 +
66 -- 已知问题与改进建议：[/ISSUES_TO_FIX.md](file:///Users/huyirui/program/itomix/git/mlaj/ISSUES_TO_FIX.md) 66 +**架构设计**:
67 -- 协作说明（较长）：[/CLAUDE.md](file:///Users/huyirui/program/itomix/git/mlaj/CLAUDE.md) 67 +
68 +- [架构文档](./docs/architecture/ARCHITECTURE.md) - 应用架构与工程配置
69 +- [组件索引](./docs/architecture/COMPONENTS.md) - /src/components 组件目录索引
70 +
71 +**开发配置**:
72 +
73 +- [ESLint + Prettier](./docs/development/ESLINT_PRETTIER.md) - 代码规范与格式化
74 +- [Husky + lint-staged](./docs/development/HUSKY_LINT_STAGED.md) - Git Hooks 配置
75 +- [开发工作流](./docs/development/WORKFLOW.md) - 团队开发流程
76 +
77 +**测试文档**:
78 +
79 +- [Playwright 指南](./docs/testing/PLAYWRIGHT.md) - E2E 测试框架
80 +- [E2E 认证指南](./docs/testing/E2E_AUTH_GUIDE.md) - 测试登录认证
81 +- [E2E 代理配置](./docs/testing/E2E_PROXY_SETUP.md) - 测试服务器代理
82 +
83 +**工具指南**:
84 +
85 +- [Claude Skills](./docs/tools/SKILLS_GUIDE.md) - Claude Code 技能完全指南
86 +
87 +**其他**:
88 +
89 +- [更新日志](./docs/CHANGELOG.md) - 功能更新记录
90 +- [代码风格指南](./VUE_CODE_STYLE_GUIDE.md) - Vue 代码最佳实践
91 +- [已知问题与改进建议](./ISSUES_TO_FIX.md) - 待优化项列表
92 +- [项目协作说明](./CLAUDE.md) - Claude Code 开发指南（详细）
68 93
69 ## 业务系统架构 94 ## 业务系统架构
70 95
......
1 -# /src/components 组件目录索引
2 -
3 -## 目录划分
4 -
5 -| 目录 | 代表组件 | 说明 |
6 -| --- | --- | --- |
7 -| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
8 -| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
9 -| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件（弹窗、列表、卡片、上传） |
10 -| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件（确认、头部、搜索、协议） |
11 -| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
12 -| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
13 -| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
14 -| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件（精选/活动/推荐等） |
15 -| infoEntry/ | formPage.vue | 信息录入相关组件 |
16 -| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
17 -| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
18 -| payment/ | WechatPayment.vue | 微信支付相关组件 |
19 -| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
20 -| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
21 -| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
22 -
23 -## 备注
24 -
25 -- 布局目录已归一：统一使用 [/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts
1 +# 📖 文档编写规范
2 +
3 +本文档定义了项目中编写和维护文档的标准规范，确保文档质量、一致性和可维护性。
4 +
5 +## 📑 目录
6 +
7 +- [文档分类规则](#文档分类规则)
8 +- [文件命名规范](#文件命名规范)
9 +- [文档结构模板](#文档结构模板)
10 +- [Markdown 编写规范](#markdown-编写规范)
11 +- [文档更新流程](#文档更新流程)
12 +- [审查与发布](#审查与发布)
13 +
14 +---
15 +
16 +## 文档分类规则
17 +
18 +所有文档必须放在对应分类目录下：
19 +
20 +```
21 +docs/
22 +├── architecture/ # 🏗️ 架构设计类
23 +├── development/ # 💻 开发配置类
24 +├── testing/ # 🧪 测试文档类
25 +├── tools/ # 🛠️ 工具指南类
26 +├── tasks/ # 📋 任务管理类
27 +│ ├── done/ # 已完成任务
28 +│ ├── plan/ # 计划中任务
29 +│ └── TODO/ # 待办事项
30 +├── CHANGELOG.md # 📝 变更记录（根目录）
31 +└── README.md # 📚 文档导航索引（根目录）
32 +```
33 +
34 +### 如何选择分类
35 +
36 +| 如果文档是关于... | 放在... |
37 +| ------------------------------------ | ------------------------ |
38 +| 系统架构、组件设计、目录结构 | `architecture/` |
39 +| 开发工具配置、代码规范、Git Hooks | `development/` |
40 +| 测试框架、测试指南、测试配置 | `testing/` |
41 +| 外部工具使用指南（如 Claude Skills） | `tools/` |
42 +| 任务、计划、待办事项 | `tasks/` |
43 +| 版本更新历史 | `CHANGELOG.md`（根目录） |
44 +
45 +---
46 +
47 +## 文件命名规范
48 +
49 +### 基本规则
50 +
51 +1. **使用英文命名**
52 + - ✅ `ARCHITECTURE.md`
53 + - ❌ `架构文档.md`
54 +
55 +2. **使用大写字母和下划线**
56 + - ✅ `E2E_AUTH_GUIDE.md`
57 + - ❌ `e2e-auth-guide.md`
58 +
59 +3. **名称清晰描述内容**
60 + - ✅ `ESLINT_PRETTIER.md`
61 + - ❌ `CODE_STYLE.md`
62 +
63 +4. **避免空格和特殊字符**
64 + - ✅ `WORKFLOW.md`
65 + - ❌ `工作流.md`
66 +
67 +### 任务文档命名
68 +
69 +格式：`[日期]_[类型]_[简短描述].md`
70 +
71 +| 类型标识 | 说明 | 示例 |
72 +| ---------- | -------- | ----------------------------------- |
73 +| `feature` | 新功能 | `20260128_feature_打卡草稿缓存.md` |
74 +| `bugfix` | Bug 修复 | `20260128_bugfix_视频播放器修复.md` |
75 +| `optimize` | 性能优化 | `20260128_optimize_首页加载优化.md` |
76 +| `refactor` | 代码重构 | `20260128_refactor_组件拆分.md` |
77 +| `docs` | 文档更新 | `20260128_docs_API文档补充.md` |
78 +| `config` | 配置变更 | `20260128_config_Vite配置优化.md` |
79 +
80 +---
81 +
82 +## 文档结构模板
83 +
84 +### 标准模板
85 +
86 +每个文档应遵循以下结构：
87 +
88 +````markdown
89 +# 文档标题
90 +
91 +> 一句话描述文档的用途和目标读者
92 +
93 +**作者**: [可选]
94 +**创建日期**: YYYY-MM-DD
95 +**最后更新**: YYYY-MM-DD
96 +**状态**: [草稿/审阅中/已发布]
97 +
98 +---
99 +
100 +## 📑 目录
101 +
102 +- [背景](#背景)
103 +- [安装/配置](#安装配置)
104 +- [使用指南](#使用指南)
105 +- [API/配置](#api配置)
106 +- [示例](#示例)
107 +- [常见问题](#常见问题)
108 +- [相关资源](#相关资源)
109 +
110 +---
111 +
112 +## 背景
113 +
114 +说明文档的背景、目的和适用场景。
115 +
116 +---
117 +
118 +## 安装/配置
119 +
120 +### 前置条件
121 +
122 +列出所需的工具、环境等。
123 +
124 +### 步骤
125 +
126 +1. 第一步
127 +2. 第二步
128 +3. 第三步
129 +
130 +---
131 +
132 +## 使用指南
133 +
134 +### 基础用法
135 +
136 +```javascript
137 +// 代码示例
138 +代码块
139 +```
140 +````
141 +
142 +### 高级用法
143 +
144 +高级使用场景和技巧。
145 +
146 +---
147 +
148 +## API/配置
149 +
150 +### 配置项
151 +
152 +| 参数 | 类型 | 默认值 | 说明 |
153 +| ------ | ------ | --------- | -------- |
154 +| param1 | string | 'default' | 参数说明 |
155 +
156 +### 方法
157 +
158 +```typescript
159 +function example(param: string): void {
160 + // 实现
161 +}
162 +```
163 +
164 +---
165 +
166 +## 示例
167 +
168 +### 示例 1：场景描述
169 +
170 +```bash
171 +# 命令示例
172 +command
173 +```
174 +
175 +### 示例 2：场景描述
176 +
177 +```javascript
178 +// 代码示例
179 +code
180 +```
181 +
182 +---
183 +
184 +## 常见问题
185 +
186 +### Q: 问题标题？
187 +
188 +**A**: 答案说明。
189 +
190 +### Q: 另一个问题？
191 +
192 +**A**: 答案说明。
193 +
194 +---
195 +
196 +## 相关资源
197 +
198 +- [相关文档1](./link1.md)
199 +- [相关文档2](./link2.md)
200 +- [外部资源](https://example.com)
201 +
202 +---
203 +
204 +````
205 +
206 +---
207 +
208 +## Markdown 编写规范
209 +
210 +### 标题层级
211 +
212 +```markdown
213 +# H1 - 文档标题（每个文档只有一个）
214 +## H2 - 主要章节
215 +### H3 - 子章节
216 +#### H4 - 四级标题（避免更深）
217 +````
218 +
219 +**规则**:
220 +
221 +- H1 只用于文档标题
222 +- H2 用于主要章节
223 +- H3 用于子章节
224 +- 避免超过 H4
225 +
226 +### 代码块
227 +
228 +使用 ``` 语言标识 指定语言：
229 +
230 +````markdown
231 +\```javascript
232 +// JavaScript 代码
233 +\```
234 +
235 +\```bash
236 +
237 +# Bash 命令
238 +
239 +\```
240 +
241 +\```vue
242 +
243 +<!-- Vue 组件 -->
244 +<template>
245 + <div />
246 +</template>
247 +\```
248 +````
249 +
250 +支持的语法高亮：
251 +
252 +- `javascript` / `js`
253 +- `typescript` / `ts`
254 +- `vue`
255 +- `bash` / `sh`
256 +- `json`
257 +- `yaml` / `yml`
258 +- `markdown` / `md`
259 +
260 +### 列表
261 +
262 +**无序列表**:
263 +
264 +```markdown
265 +- 项目 1
266 +- 项目 2
267 + - 子项目 2.1
268 + - 子项目 2.2
269 +```
270 +
271 +**有序列表**:
272 +
273 +```markdown
274 +1. 第一步
275 +2. 第二步
276 +3. 第三步
277 +```
278 +
279 +### 表格
280 +
281 +```markdown
282 +| 列1 | 列2 | 列3 |
283 +| ----- | ----- | ----- |
284 +| 数据1 | 数据2 | 数据3 |
285 +```
286 +
287 +### 强调
288 +
289 +```markdown
290 +**粗体文本**
291 +_斜体文本_
292 +**_粗斜体_**
293 +`行内代码`
294 +```
295 +
296 +### 链接
297 +
298 +```markdown
299 +[链接文本](./path/to/file.md)
300 +[外部链接](https://example.com)
301 +[带标题的链接](https://example.com '鼠标悬停提示')
302 +```
303 +
304 +### 图片
305 +
306 +```markdown
307 +![图片描述](./path/to/image.png)
308 +![图片描述](./path/to/image.png '图片标题')
309 +```
310 +
311 +### 引用
312 +
313 +```markdown
314 +> 普通引用
315 +>
316 +> **引用中可以加粗**
317 +> 可以多行
318 +```
319 +
320 +### 分隔线
321 +
322 +```markdown
323 +---
324 +```
325 +
326 +### 任务列表
327 +
328 +```markdown
329 +- [x] 已完成任务
330 +- [ ] 待完成任务
331 +```
332 +
333 +### Emoji
334 +
335 +适当使用 emoji 增强可读性：
336 +
337 +| Emoji | 用途 |
338 +| ----- | --------- |
339 +| 📚 | 文档 |
340 +| 💻 | 代码/开发 |
341 +| 🧪 | 测试 |
342 +| 🏗️ | 架构 |
343 +| 🛠️ | 工具 |
344 +| ✅ | 完成/正确 |
345 +| ❌ | 错误/避免 |
346 +| ⚠️ | 警告 |
347 +| 💡 | 建议/提示 |
348 +| 📝 | 笔记/记录 |
349 +
350 +---
351 +
352 +## 文档更新流程
353 +
354 +### 1. 新增文档
355 +
356 +```bash
357 +# 1. 在对应分类下创建文档
358 +cd docs/architecture
359 +vim NEW_DOC.md
360 +
361 +# 2. 使用模板初始化
362 +cp ../TEMPLATES/STANDARD.md NEW_DOC.md
363 +
364 +# 3. 更新索引
365 +# 编辑 ../README.md，在对应分类下添加链接
366 +```
367 +
368 +### 2. 更新文档
369 +
370 +```bash
371 +# 1. 修改文档内容
372 +vim docs/xxx/FILE.md
373 +
374 +# 2. 更新"最后更新"日期
375 +# 在文档头部更新日期字段
376 +
377 +# 3. 如果有重大变更，更新 CHANGELOG.md
378 +```
379 +
380 +### 3. 移动/删除文档
381 +
382 +```bash
383 +# 移动文档
384 +git mv docs/old/FILE.md docs/new/FILE.md
385 +
386 +# 删除文档（需谨慎）
387 +git rm docs/xxx/FILE.md
388 +```
389 +
390 +### 4. 索引维护
391 +
392 +每次新增或移动文档后，**必须**更新 `docs/README.md`：
393 +
394 +1. 在对应分类下添加或更新链接
395 +2. 如果是任务文档，更新 `tasks/README.md`
396 +3. 更新"快速查找"部分（如果适用）
397 +
398 +---
399 +
400 +## 审查与发布
401 +
402 +### 自查清单
403 +
404 +发布文档前，确认：
405 +
406 +- [ ] 文档放在正确的分类目录
407 +- [ ] 文件名遵循命名规范
408 +- [ ] 使用标准文档结构模板
409 +- [ ] 代码块指定了语言标识
410 +- [ ] 所有链接有效（可点击测试）
411 +- [ ] 更新了相关索引（README.md）
412 +- [ ] 添加了创建和更新日期
413 +- [ ] 拼写和语法检查通过
414 +
415 +### PR 审查
416 +
417 +提交文档 PR 时：
418 +
419 +1. **标题格式**: `docs(category): 简短描述`
420 +
421 + ```bash
422 + docs(testing): 添加 Playwright E2E 测试指南
423 + docs(architecture): 更新组件索引文档
424 + ```
425 +
426 +2. **描述内容**:
427 + - 新增或修改的内容
428 + - 影响的文档
429 + - 相关的 Issue 或 PR
430 +
431 +3. **审查重点**:
432 + - 文档分类是否正确
433 + - 内容是否准确完整
434 + - 链接是否有效
435 + - 格式是否统一
436 +
437 +### 发布检查
438 +
439 +合并 PR 前确认：
440 +
441 +- [ ] 至少一人审查通过
442 +- [ ] CI 检查通过（如果有）
443 +- [ ] 文档索引已更新
444 +- [ ] 相关文档已同步更新
445 +
446 +---
447 +
448 +## 特殊文档规范
449 +
450 +### CHANGELOG.md
451 +
452 +遵循 [Keep a Changelog](https://keepachangelog.com/) 格式：
453 +
454 +```markdown
455 +# 更新日志
456 +
457 +## [Unreleased]
458 +
459 +### Added
460 +
461 +- 新功能 1
462 +- 新功能 2
463 +
464 +### Changed
465 +
466 +- 变更 1
467 +
468 +### Fixed
469 +
470 +- 修复 1
471 +
472 +## [1.2.0] - 2026-01-28
473 +
474 +### Added
475 +
476 +- 新功能
477 +```
478 +
479 +### README.md
480 +
481 +- 简洁明了，突出重点
482 +- 包含项目简介和快速开始
483 +- 提供清晰的文档导航
484 +
485 +### API 文档
486 +
487 +- 使用表格展示参数
488 +- 提供代码示例
489 +- 说明返回值和错误码
490 +
491 +---
492 +
493 +## 💡 最佳实践
494 +
495 +### 1. 保持简洁
496 +
497 +- ❌ 避免冗长描述
498 +- ✅ 用代码示例说话
499 +- ✅ 适当使用图表和截图
500 +
501 +### 2. 及时更新
502 +
503 +- 代码变更时同步更新文档
504 +- 标注"最后更新"日期
505 +- 过时文档及时归档
506 +
507 +### 3. 面向读者
508 +
509 +- 明确文档的目标读者
510 +- 提供不同深度的内容（入门/进阶）
511 +- 使用场景驱动的示例
512 +
513 +### 4. 可维护性
514 +
515 +- 避免重复内容
516 +- 使用引用和链接
517 +- 保持统一的格式
518 +
519 +### 5. 可搜索性
520 +
521 +- 使用关键词
522 +- 提供清晰的目录
523 +- 添加元数据标签
524 +
525 +---
526 +
527 +## 🔗 相关资源
528 +
529 +- [Markdown 指南](https://www.markdownguide.org/)
530 +- [文档驱动开发](https://www.writethedocs.org/)
531 +- [技术文档最佳实践](https://documentation.divio.com/)
532 +
533 +---
534 +
535 +**最后更新**: 2026-01-28
1 +# 📚 项目文档导航
2 +
3 +> 本文档提供项目所有文档的分类索引，帮助快速查找所需信息。
4 +
5 +## 📑 文档分类
6 +
7 +### 🏗️ 架构设计
8 +
9 +| 文档 | 说明 | 路径 |
10 +| ------------------------------------------ | ------------------------------ | ------------------------------ |
11 +| [架构文档](./architecture/ARCHITECTURE.md) | 应用架构、工程化配置、目录结构 | `architecture/ARCHITECTURE.md` |
12 +| [组件索引](./architecture/COMPONENTS.md) | 22个组件目录的分类索引 | `architecture/COMPONENTS.md` |
13 +
14 +### 💻 开发配置
15 +
16 +| 文档 | 说明 | 路径 |
17 +| --------------------------------------------------------- | ------------------------ | ---------------------------------- |
18 +| [ESLint + Prettier](./development/ESLINT_PRETTIER.md) | 代码规范与自动格式化配置 | `development/ESLINT_PRETTIER.md` |
19 +| [Husky + lint-staged](./development/HUSKY_LINT_STAGED.md) | Git Hooks 自动化检查配置 | `development/HUSKY_LINT_STAGED.md` |
20 +| [开发工作流](./development/WORKFLOW.md) | 团队开发流程与规范 | `development/WORKFLOW.md` |
21 +
22 +### 🧪 测试文档
23 +
24 +| 文档 | 说明 | 路径 |
25 +| ---------------------------------------------- | ------------------------ | ---------------------------- |
26 +| [Playwright 指南](./testing/PLAYWRIGHT.md) | E2E 测试框架完整指南 | `testing/PLAYWRIGHT.md` |
27 +| [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md) | 测试登录认证流程 | `testing/E2E_AUTH_GUIDE.md` |
28 +| [E2E 代理配置](./testing/E2E_PROXY_SETUP.md) | Vite 反向代理配置说明 | `testing/E2E_PROXY_SETUP.md` |
29 +| [E2E 测试服务器](./testing/E2E_TEST_SERVER.md) | 测试环境配置与服务器信息 | `testing/E2E_TEST_SERVER.md` |
30 +
31 +### 🛠️ 工具指南
32 +
33 +| 文档 | 说明 | 路径 |
34 +| ---------------------------------------- | ------------------------ | ----------------------- |
35 +| [Claude Skills](./tools/SKILLS_GUIDE.md) | Claude Code 技能完全指南 | `tools/SKILLS_GUIDE.md` |
36 +
37 +### 📝 变更记录
38 +
39 +| 文档 | 说明 | 路径 |
40 +| -------------------------- | -------------------------- | -------------- |
41 +| [更新日志](./CHANGELOG.md) | 功能更新历史（按时间倒序） | `CHANGELOG.md` |
42 +
43 +### 📋 任务管理
44 +
45 +| 目录 | 说明 | 路径 |
46 +| --------------------------- | -------------------- | ------------- |
47 +| [已完成任务](./tasks/done/) | 已完成的功能记录 | `tasks/done/` |
48 +| [开发计划](./tasks/plan/) | 进行中和计划中的功能 | `tasks/plan/` |
49 +| [待办事项](./tasks/TODO/) | 待办功能列表 | `tasks/TODO/` |
50 +
51 +---
52 +
53 +## 🚀 快速查找
54 +
55 +### 按场景查找
56 +
57 +**我要...**
58 +
59 +- 🆕 **新项目上手** → [架构文档](./architecture/ARCHITECTURE.md)
60 +- 🔧 **配置开发环境** → [ESLint + Prettier](./development/ESLINT_PRETTIER.md)
61 +- 🧪 **编写 E2E 测试** → [Playwright 指南](./testing/PLAYWRIGHT.md)
62 +- 🔐 **测试登录功能** → [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md)
63 +- 📝 **了解更新内容** → [更新日志](./CHANGELOG.md)
64 +- 🛠️ **使用 Claude Skills** → [Claude Skills 指南](./tools/SKILLS_GUIDE.md)
65 +
66 +### 按角色查找
67 +
68 +**前端开发者**
69 +
70 +1. [架构文档](./architecture/ARCHITECTURE.md) - 了解项目结构
71 +2. [组件索引](./architecture/COMPONENTS.md) - 查找可复用组件
72 +3. [ESLint + Prettier](./development/ESLINT_PRETTIER.md) - 配置代码规范
73 +4. [开发工作流](./development/WORKFLOW.md) - 遵循团队流程
74 +
75 +**测试工程师**
76 +
77 +1. [Playwright 指南](./testing/PLAYWRIGHT.md) - E2E 测试框架
78 +2. [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md) - 测试认证流程
79 +3. [E2E 代理配置](./testing/E2E_PROXY_SETUP.md) - 配置测试环境
80 +4. [E2E 测试服务器](./testing/E2E_TEST_SERVER.md) - 测试服务器信息
81 +
82 +**新成员**
83 +
84 +1. [架构文档](./architecture/ARCHITECTURE.md) - 了解整体架构
85 +2. [开发工作流](./development/WORKFLOW.md) - 学习开发流程
86 +3. [组件索引](./architecture/COMPONENTS.md) - 熟悉现有组件
87 +4. [更新日志](./CHANGELOG.md) - 了解最近更新
88 +
89 +---
90 +
91 +## 📖 文档编写规范
92 +
93 +### 新增文档时，请遵循以下规则：
94 +
95 +#### 1. 文件命名
96 +
97 +- ✅ 使用大写字母和下划线：`ARCHITECTURE.md`
98 +- ✅ 使用英文命名，文件名清晰描述内容
99 +- ❌ 避免中文文件名（`工作流.md` → `WORKFLOW.md`）
100 +- ❌ 避免空格和特殊字符
101 +
102 +#### 2. 文档分类
103 +
104 +根据文档内容，放入对应目录：
105 +
106 +```
107 +docs/
108 +├── architecture/ # 架构设计类文档
109 +├── development/ # 开发配置类文档
110 +├── testing/ # 测试相关文档
111 +├── tools/ # 工具使用指南
112 +└── tasks/ # 任务管理（done/plan/TODO）
113 +```
114 +
115 +#### 3. 更新索引
116 +
117 +新增文档后，**必须**更新本 `README.md`：
118 +
119 +1. 在对应分类下添加文档链接
120 +2. 更新"快速查找"部分（如果适用）
121 +3. 遵循现有格式和风格
122 +
123 +#### 4. 文档结构
124 +
125 +每个文档应包含：
126 +
127 +```markdown
128 +# 文档标题
129 +
130 +> 简短描述（1-2句话）
131 +
132 +## 目录
133 +
134 +- [背景](#背景)
135 +- [安装](#安装)
136 +- [使用](#使用)
137 +- [API](#api)
138 +- [常见问题](#常见问题)
139 +
140 +## 背景
141 +
142 +说明文档的背景和目标
143 +
144 +## 安装
145 +
146 +step-by-step 安装指南
147 +
148 +## 使用
149 +
150 +详细使用说明
151 +
152 +## 常见问题
153 +
154 +Q&A 格式
155 +```
156 +
157 +---
158 +
159 +## 🔍 搜索技巧
160 +
161 +### 在文档中搜索
162 +
163 +```bash
164 +# 在所有文档中搜索关键词
165 +cd docs
166 +grep -r "关键词" .
167 +
168 +# 只搜索 .md 文件
169 +grep -r "关键词" . --include="*.md"
170 +
171 +# 搜索特定目录
172 +grep -r "关键词" ./testing/
173 +```
174 +
175 +### VS Code 搜索
176 +
177 +1. `Ctrl/Cmd + Shift + F` - 全局搜索
178 +2. 在搜索框中输入关键词
179 +3. 限制搜索范围：`docs/**/*.md`
180 +
181 +---
182 +
183 +## 📊 文档统计
184 +
185 +| 分类 | 文档数量 | 最后更新 |
186 +| -------- | -------- | -------- |
187 +| 架构设计 | 2 | - |
188 +| 开发配置 | 3 | - |
189 +| 测试文档 | 4 | - |
190 +| 工具指南 | 1 | - |
191 +| 任务管理 | 3 | - |
192 +| **总计** | **13** | - |
193 +
194 +---
195 +
196 +## 🤝 贡献指南
197 +
198 +发现文档问题？欢迎改进：
199 +
200 +1. **修正错误**：直接修改文档并提交 PR
201 +2. **补充内容**：在对应分类下新增文档
202 +3. **优化索引**：改进本 `README.md` 的导航结构
203 +
204 +**注意事项**：
205 +
206 +- 保持客观、准确
207 +- 提供示例和代码
208 +- 更新日期和版本信息
209 +- 遵循现有文档风格
210 +
211 +---
212 +
213 +## 🔗 相关资源
214 +
215 +- [项目主 README](../README.md)
216 +- [CLAUDE.md](../CLAUDE.md) - 项目架构与开发指南
217 +- [代码规范](../.claude/rules/coding-style.md) - 全局编码规范
218 +- [Vue 最佳实践](../.claude/rules/vue-patterns.md) - Vue 3 开发指南
219 +
220 +---
221 +
222 +**最后更新**: 2026-01-28
223 +**维护者**: 开发团队
1 -# 🎯 Claude Code Skills 完全指南
2 -
3 -> 本文档收录了系统中所有可用的 Skills（技能），按功能类别整理，帮助您快速了解和使用这些强大的开发辅助工具。
4 -
5 ----
6 -
7 -## 📑 目录
8 -
9 -- [通用开发技能](#-通用开发技能)
10 -- [文档处理技能](#-文档处理技能)
11 -- [设计与品牌](#-设计与品牌)
12 -- [Claude Code 工作流](#-claude-code-工作流)
13 -- [代码审查与分析](#-代码审查与分析)
14 -- [架构与模式](#-架构与模式)
15 -- [记忆与学习](#-记忆与学习)
16 -- [Git 与工作流](#-git-与工作流)
17 -- [项目相关](#-项目相关)
18 -
19 ----
20 -
21 -## 🛠️ 通用开发技能
22 -
23 -| Skill | 名称 | 用途说明 |
24 -|:------|:-----|:---------|
25 -| `agent-browser` | 浏览器自动化 | 浏览器交互、Web 测试、表单填充、截图和数据提取 |
26 -| `algorithmic-art` | 算法艺术创作 | 使用 p5.js 创建基于种子随机性和交互式参数探索的算法艺术 |
27 -| `frontend-design` | 前端界面设计 | 创建高质量、生产级别的用户界面和交互式 Web 组件 |
28 -| `canvas-design` | Canvas 视觉设计 | 创建 .png 和 .pdf 格式的精美视觉艺术作品 |
29 -| `find-skills` | 技能发现器 | 帮助您发现和安装新的 agent skills |
30 -| `skill-creator` | 技能创建器 | 创建新的 skills 或更新现有 skills 的指南 |
31 -
32 ----
33 -
34 -## 📝 文档处理技能
35 -
36 -| Skill | 名称 | 用途说明 |
37 -|:------|:-----|:---------|
38 -| `docx` | Word 文档处理 | Word 文档的创建、编辑、分析，支持修订跟踪、注释和格式保留 |
39 -| `xlsx` | Excel 电子表格 | Excel 表格的创建、编辑、分析，支持公式、格式化和数据可视化 |
40 -| `pptx` | PowerPoint 演示文稿 | PowerPoint 的创建、编辑和分析，用于演示文稿制作 |
41 -| `pdf` | PDF 操作工具包 | PDF 文本和表格提取、创建新 PDF、合并/分割文档、表单处理 |
42 -| `doc-coauthoring` | 文档协同工作流 | 引导用户进行结构化的文档协同创作流程 |
43 -| `documentation-lookup` | 文档查询助手 | 查询库、框架、API 参考文档和代码示例 |
44 -
45 ----
46 -
47 -## 🎨 设计与品牌
48 -
49 -| Skill | 名称 | 用途说明 |
50 -|:------|:-----|:---------|
51 -| `brand-guidelines` | 品牌规范应用 | 应用 Anthropic 官方品牌颜色、排版到各种设计资产 |
52 -| `theme-factory` | 主题工厂 | 使用 10 种预设主题样式化幻灯片、文档、HTML 页面等 |
53 -| `web-artifacts-builder` | Web 构建工具套件 | 创建多组件 HTML artifacts，使用 React、Tailwind CSS 等现代技术 |
54 -| `slack-gif-creator` | Slack GIF 创作 | 创建针对 Slack 优化的动画 GIF，包含约束验证和动画概念 |
55 -
56 ----
57 -
58 -## 🚀 Claude Code 工作流
59 -
60 -| Skill | 名称 | 用途说明 |
61 -|:------|:-----|:---------|
62 -| `everything-claude-code:plan` | 实施计划 | 重述需求、评估风险、创建分步实施计划（等待用户确认） |
63 -| `everything-claude-code:tdd` | 测试驱动开发 | 强制执行测试优先编写工作流，确保 80%+ 测试覆盖率 |
64 -| `everything-claude-code:e2e` | 端到端测试 | 使用 Playwright 生成和运行 E2E 测试，管理测试旅程 |
65 -| `superpowers:brainstorming` | 头脑风暴 | 在任何创意工作（创建功能、组件、添加功能）之前使用 |
66 -| `superpowers:systematic-debugging` | 系统化调试 | 遇到 bug、测试失败或意外行为时的调试流程 |
67 -| `superpowers:verification-before-completion` | 完成前验证 | 在声称工作完成之前，运行验证命令和检查 |
68 -| `superpowers:executing-plans` | 执行计划 | 在单独的会话中执行书面实施计划，带审查检查点 |
69 -| `superpowers:writing-plans` | 编写计划 | 当有规范或需求时，在编写代码之前规划实施步骤 |
70 -
71 ----
72 -
73 -## 🔍 代码审查与分析
74 -
75 -| Skill | 名称 | 用途说明 |
76 -|:------|:-----|:---------|
77 -| `superpowers:requesting-code-review` | 请求代码审查 | 完成任务、实现主要功能或合并前验证工作质量 |
78 -| `superpowers:receiving-code-review` | 接收代码审查 | 在实现建议之前接收代码审查反馈 |
79 -| `everything-claude-code:security-review` | 安全审查 | 添加认证、处理用户输入、API 端点或敏感数据时的安全检测 |
80 -| `everything-claude-code:database-reviewer` | 数据库审查 | PostgreSQL 数据库查询优化、模式设计、安全和性能专家 |
81 -
82 ----
83 -
84 -## 📚 架构与模式
85 -
86 -| Skill | 名称 | 用途说明 |
87 -|:------|:-----|:---------|
88 -| `everything-claude-code:backend-patterns` | 后端架构模式 | Node.js、Express、Next.js API 路由的后端架构和 API 设计模式 |
89 -| `everything-claude-code:frontend-patterns` | 前端开发模式 | React、Next.js、状态管理、性能优化和 UI 最佳实践 |
90 -| `everything-claude-code:coding-standards` | 编码标准 | TypeScript、JavaScript、React 和 Node.js 的通用编码标准和最佳实践 |
91 -| `everything-claude-code:postgres-patterns` | PostgreSQL 模式 | 查询优化、模式设计、索引和安全性（基于 Supabase 最佳实践） |
92 -| `everything-claude-code:clickhouse-io` | ClickHouse 模式 | ClickHouse 数据库模式、查询优化、分析和数据工程最佳实践 |
93 -
94 ----
95 -
96 -## 🧠 记忆与学习
97 -
98 -| Skill | 名称 | 用途说明 |
99 -|:------|:-----|:---------|
100 -| `episodic-memory:search-conversations` | 搜索历史对话 | 跨会话语义或文本搜索，恢复之前的决策、解决方案和经验教训 |
101 -| `everything-claude-code:continuous-learning` | 持续学习 | 从 Claude Code 会话中提取可复用模式并保存为 skills |
102 -| `ship-learn-next` | 学习转化计划 | 将学习内容（如 YouTube 字幕、文章、教程）转化为可执行的实施计划 |
103 -
104 ----
105 -
106 -## 🛠️ Git 与工作流
107 -
108 -| Skill | 名称 | 用途说明 |
109 -|:------|:-----|:---------|
110 -| `superpowers:using-git-worktrees` | Git 工作树 | 开始需要与当前工作空间隔离的功能工作时创建隔离的 git 工作树 |
111 -| `superpowers:finishing-a-development-branch` | 完成开发分支 | 实现完成、所有测试通过，决定如何集成工作时的完成指南 |
112 -| `superpowers:dispatching-parallel-agents` | 并行代理调度 | 面对 2+ 个独立任务且无共享状态或顺序依赖时使用 |
113 -| `superpowers:subagent-driven-development` | 子代理驱动开发 | 使用独立任务在当前会话中执行实施计划 |
114 -
115 ----
116 -
117 -## 📊 项目相关
118 -
119 -| Skill | 名称 | 用途说明 |
120 -|:------|:-----|:---------|
121 -| `project-overview` | 项目概览 | 完整的项目架构和结构指南，探索代码库和理解项目组织 |
122 -| `glm-plan-usage:usage-query` | 使用量查询 | 查询 GLM Coding Plan 当前账户的使用信息 |
123 -| `glm-plan-bug:case-feedback` | 问题反馈 | 提交案例反馈以报告问题或建议 |
124 -
125 ----
126 -
127 -## 🎖️ 专业领域技能
128 -
129 -### 代码质量
130 -
131 -| Skill | 名称 | 用途说明 |
132 -|:------|:-----|:---------|
133 -| `everything-claude-code:code-reviewer` | 代码审查专家 | 主动审查代码质量、安全性和可维护性 |
134 -| `everything-claude-code:refactor-cleaner` | 重构清理 | 死代码清理和整合，运行分析工具安全移除未使用代码 |
135 -| `everything-claude-code:build-error-resolver` | 构建错误解决 | 构建和 TypeScript 错误解决专家 |
136 -| `everything-claude-code:tdd-guide` | TDD 指南 | 测试驱动开发专家，强制执行测试优先编写方法 |
137 -
138 -### 开发流程
139 -
140 -| Skill | 名称 | 用途说明 |
141 -|:------|:-----|:---------|
142 -| `everything-claude-code:planner` | 规划专家 | 复杂功能和重构的专家规划 |
143 -| `everything-claude-code:architect` | 软件架构师 | 系统设计、可扩展性和技术决策专家 |
144 -| `everything-claude-code:doc-updater` | 文档更新器 | 更新 codemaps 和文档的专家 |
145 -| `everything-claude-code:strategic-compact` | 策略性压缩 | 在逻辑阶段保留上下文的策略性压缩建议 |
146 -| `everything-claude-code:iterative-retrieval` | 迭代检索 | 逐步改进上下文检索的模式 |
147 -
148 -### 测试与评估
149 -
150 -| Skill | 名称 | 用途说明 |
151 -|:------|:-----|:---------|
152 -| `everything-claude-code:e2e-runner` | E2E 测试运行器 | 使用 Playwright 生成、维护和运行 E2E 测试 |
153 -| `everything-claude-code:eval-harness` | 评估框架 | Claude Code 会话的正式评估框架 |
154 -
155 ----
156 -
157 -## 💡 使用技巧
158 -
159 -### 调用方式
160 -
161 -1. **命令方式**：在对话中输入 `/skill-name`
162 - - 例如：`/plan`、`/review`、`/tdd`
163 -
164 -2. **自动触发**：Claude 会根据任务类型自动调用相关 skills
165 -
166 -3. **手动指定**：明确要求使用某个 skill
167 -
168 -### 优先级顺序
169 -
170 -当多个 skills 可能适用时，按以下顺序使用：
171 -
172 -1. **流程技能优先**（brainstorming、debugging）- 决定如何处理任务
173 -2. **实施技能其次**（frontend-design、mcp-builder）- 指导执行
174 -
175 -**示例**：
176 -- "让我们构建 X" → brainstorming → frontend-design
177 -- "修复这个 bug" → debugging → domain-specific skills
178 -
179 -### 技能类型
180 -
181 -- **刚性**（TDD、debugging）：严格遵循，不可偏离
182 -- **灵活**（patterns）：根据上下文调整原则
183 -
184 ----
185 -
186 -## 📖 快速参考
187 -
188 -### 开发新功能时的典型流程
189 -
190 -```
191 -1. brainstorming → 创意和方案探索
192 -2. plan → 制定实施计划
193 -3. tdd → 编写测试
194 -4. implementing → 编写代码
195 -5. code-review → 代码审查
196 -6. verification → 完成前验证
197 -```
198 -
199 -### 修复 Bug 时的典型流程
200 -
201 -```
202 -1. systematic-debugging → 问题诊断
203 -2. implementing → 修复代码
204 -3. testing → 验证修复
205 -4. verification → 确认完成
206 -```
207 -
208 -### 代码审查流程
209 -
210 -```
211 -1. requesting-code-review → 提交审查请求
212 -2. receiving-code-review → 接收反馈
213 -3. implementing → 应用修改
214 -```
215 -
216 ----
217 -
218 -## 🔗 相关文档
219 -
220 -- [CLAUDE.md](../CLAUDE.md) - 项目总体架构与开发指南
221 -- [VUE_CODE_STYLE_GUIDE.md](../VUE_CODE_STYLE_GUIDE.md) - Vue 代码风格规范
222 -- [CHANGELOG.md](../CHANGELOG.md) - 变更日志
223 -
224 ----
225 -
226 -## 📝 更新日志
227 -
228 -- **2025-01-27**: 初始版本，收录所有可用 Skills
229 -
230 ----
231 -
232 -*本文档由 Claude Code 自动生成和维护*
1 +# /src/components 组件目录索引
2 +
3 +## 目录划分
4 +
5 +| 目录 | 代表组件 | 说明 |
6 +| ------------ | ------------------------------------------------------------------------- | ------------------------------------------- |
7 +| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
8 +| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
9 +| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件（弹窗、列表、卡片、上传） |
10 +| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件（确认、头部、搜索、协议） |
11 +| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
12 +| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
13 +| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
14 +| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件（精选/活动/推荐等） |
15 +| infoEntry/ | formPage.vue | 信息录入相关组件 |
16 +| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
17 +| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
18 +| payment/ | WechatPayment.vue | 微信支付相关组件 |
19 +| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
20 +| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
21 +| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
22 +
23 +## 备注
24 +
25 +- 布局目录已归一：统一使用 [/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts
1 +# 📋 任务管理
2 +
3 +此目录包含项目任务管理的相关文档。
4 +
5 +## 📁 目录结构
6 +
7 +```
8 +tasks/
9 +├── done/ # 已完成的任务
10 +├── plan/ # 进行中和计划中的任务
11 +└── TODO/ # 待办事项列表
12 +```
13 +
14 +## 📂 各目录说明
15 +
16 +### ✅ done/ - 已完成任务
17 +
18 +**用途**: 存放已完成的功能和任务的详细记录
19 +
20 +**包含内容**:
21 +
22 +- 功能实现记录
23 +- 技术方案文档
24 +- 上线总结报告
25 +
26 +**示例**:
27 +
28 +- 欢迎页布局优化
29 +- 打卡草稿缓存功能
30 +- 视频播放器优化
31 +
32 +**如何添加**:
33 +完成任务后，将相关文档移动到 `done/` 目录，并更新此索引。
34 +
35 +---
36 +
37 +### 🔄 plan/ - 开发计划
38 +
39 +**用途**: 存放正在进行或计划中的功能开发文档
40 +
41 +**包含内容**:
42 +
43 +- 功能设计文档
44 +- 技术方案讨论
45 +- 开发进度跟踪
46 +- API 设计文档
47 +
48 +**示例**:
49 +
50 +- 新功能设计方案
51 +- 性能优化计划
52 +- 重构方案
53 +
54 +**如何添加**:
55 +
56 +1. 在 `plan/` 下创建文档
57 +2. 按功能或时间组织
58 +3. 完成后移动到 `done/`
59 +
60 +---
61 +
62 +### 📝 TODO/ - 待办事项
63 +
64 +**用途**: 待办功能、Bug 修复、改进建议的清单
65 +
66 +**包含内容**:
67 +
68 +- 功能需求列表
69 +- Bug 修复清单
70 +- 优化建议
71 +- 技术债务
72 +
73 +**如何使用**:
74 +
75 +1. 新增待办项时添加到对应分类
76 +2. 开始开发时移到 `plan/`
77 +3. 完成后移到 `done/`
78 +
79 +---
80 +
81 +## 🔄 任务生命周期
82 +
83 +```
84 +TODO → plan → done
85 + (待办) (计划) (完成)
86 +```
87 +
88 +### 详细流程
89 +
90 +1. **新建任务** → 添加到 `TODO/`
91 +2. **开始规划** → 移动到 `plan/`，创建设计文档
92 +3. **开发完成** → 移动到 `done/`，记录实现细节
93 +
94 +---
95 +
96 +## 📝 文档命名规范
97 +
98 +### 格式
99 +
100 +```
101 +[日期]_[类型]_[简短描述].md
102 +```
103 +
104 +### 示例
105 +
106 +- `20260128_feature_打卡草稿缓存.md`
107 +- `20260128_bugfix_视频播放器修复.md`
108 +- `20260128_optimize_首页加载优化.md`
109 +- `20260128_refactor_组件拆分.md`
110 +
111 +### 类型标识
112 +
113 +| 类型 | 说明 |
114 +| ---------- | -------- |
115 +| `feature` | 新功能 |
116 +| `bugfix` | Bug 修复 |
117 +| `optimize` | 性能优化 |
118 +| `refactor` | 代码重构 |
119 +| `docs` | 文档更新 |
120 +| `config` | 配置变更 |
121 +
122 +---
123 +
124 +## 🔍 快速查找
125 +
126 +### 查看所有已完成的任务
127 +
128 +```bash
129 +ls -1 done/
130 +```
131 +
132 +### 查看所有计划中的任务
133 +
134 +```bash
135 +ls -1 plan/
136 +```
137 +
138 +### 查看所有待办事项
139 +
140 +```bash
141 +ls -1 TODO/
142 +```
143 +
144 +### 搜索特定任务
145 +
146 +```bash
147 +# 搜索关键词
148 +find . -name "*.md" | xargs grep -l "关键词"
149 +```
150 +
151 +---
152 +
153 +## 📊 任务统计
154 +
155 +| 状态 | 数量 | 说明 |
156 +| --------- | ---- | --------------- |
157 +| ✅ 已完成 | - | 见 `done/` 目录 |
158 +| 🔄 进行中 | - | 见 `plan/` 目录 |
159 +| 📝 待办 | - | 见 `TODO/` 目录 |
160 +
161 +---
162 +
163 +## 💡 使用建议
164 +
165 +### 1. 定期清理
166 +
167 +- **每月**: 检查 `TODO/`，删除过时任务
168 +- **每周**: 更新 `plan/` 中的任务进度
169 +- **每季度**: 归档 `done/` 中的旧任务
170 +
171 +### 2. 保持更新
172 +
173 +- 完成任务后立即移动文档
174 +- 及时更新任务状态
175 +- 记录关键决策和教训
176 +
177 +### 3. 团队协作
178 +
179 +- 使用统一的文档格式
180 +- 明确任务负责人
181 +- 设置合理的截止日期
182 +
183 +---
184 +
185 +## 🔗 相关资源
186 +
187 +- [项目文档导航](../README.md)
188 +- [更新日志](../CHANGELOG.md)
189 +- [开发工作流](../development/WORKFLOW.md)
190 +
191 +---
192 +
193 +**最后更新**: 2026-01-28
1 新功能开发list(在.env加上配置开关控制下面设计到的功能点, 比如是否开启置顶功能,开启点评打卡, 开启打卡海报,开启点评列表): 1 新功能开发list(在.env加上配置开关控制下面设计到的功能点, 比如是否开启置顶功能,开启点评打卡, 开启打卡海报,开启点评列表):
2 - 入口页IndexCheckInPage涉及功能 2 +入口页IndexCheckInPage涉及功能
3 - - CheckinCard组件 <#footer-right> 3个点的缩略显示, 点击后从底部弹出vant的ActionSheet组件, 面板有置顶和点评两个选项. 3 +
4 +- CheckinCard组件 <#footer-right> 3个点的缩略显示, 点击后从底部弹出vant的ActionSheet组件, 面板有置顶和点评两个选项.
4 1. 置顶的功能, 使用图标back-top, 点击图标的时候弹出确认弹窗, 确认后调用接口置顶帖子. 5 1. 置顶的功能, 使用图标back-top, 点击图标的时候弹出确认弹窗, 确认后调用接口置顶帖子.
5 2. 点评打卡作业的功能, 使用图标comment, 点击图标的时候弹出确认弹窗, 确认后调用接口点评打卡作业. 评论弹框做成一个单独的组件以后扩展. 6 2. 点评打卡作业的功能, 使用图标comment, 点击图标的时候弹出确认弹窗, 确认后调用接口点评打卡作业. 评论弹框做成一个单独的组件以后扩展.
6 3. 海报功能, 使用图标share, 可以参考SharePoster组件的实现, 新增一个组件打卡海报, 这个组件最大的不同就是可能生成的图片是一张长图, 如果超过屏幕高度, 用户可以滑动查看. 现在内容和字段还不确定, 等确定了再实现可以先规划. 7 3. 海报功能, 使用图标share, 可以参考SharePoster组件的实现, 新增一个组件打卡海报, 这个组件最大的不同就是可能生成的图片是一张长图, 如果超过屏幕高度, 用户可以滑动查看. 现在内容和字段还不确定, 等确定了再实现可以先规划.
7 - - 显示点评列表功能, 在CheckinCard组件里面, 需要新增一个组件专门显示用户点评打卡的列表. 类似于朋友圈下面的评论列表, 放在CheckinCard组件的下面. 8 +- 显示点评列表功能, 在CheckinCard组件里面, 需要新增一个组件专门显示用户点评打卡的列表. 类似于朋友圈下面的评论列表, 放在CheckinCard组件的下面.
......
...@@ -47,6 +47,7 @@ pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4 ...@@ -47,6 +47,7 @@ pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4
47 ``` 47 ```
48 48
49 **文件信息:** 49 **文件信息:**
50 +
50 - 大小: 17.57MB (18420585 字节) 51 - 大小: 17.57MB (18420585 字节)
51 - Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH 52 - Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH
52 - MIME: video/mp4 53 - MIME: video/mp4
...@@ -65,6 +66,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 ...@@ -65,6 +66,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
65 ## 📋 开发进度 66 ## 📋 开发进度
66 67
67 ### ✅ 已完成 68 ### ✅ 已完成
69 +
68 - [x] 背景视频文件准备 (`welcome-bg.mp4`) 70 - [x] 背景视频文件准备 (`welcome-bg.mp4`)
69 - [x] 视频上传到七牛云 ✅ (17.57MB, Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH) 71 - [x] 视频上传到七牛云 ✅ (17.57MB, Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH)
70 - [x] 功能图标上传到七牛云 ✅ (33.53KB, Hash: FsqvctdBVJvXoQkAAEEhxuIRqX6h) 72 - [x] 功能图标上传到七牛云 ✅ (33.53KB, Hash: FsqvctdBVJvXoQkAAEEhxuIRqX6h)
...@@ -83,9 +85,11 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 ...@@ -83,9 +85,11 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
83 - [x] 访问逻辑优化 ✅ 85 - [x] 访问逻辑优化 ✅
84 86
85 ### ⏳ 待开发 87 ### ⏳ 待开发
88 +
86 - 无 89 - 无
87 90
88 ### ❌ 待确认 91 ### ❌ 待确认
92 +
89 - 无 93 - 无
90 94
91 --- 95 ---
...@@ -114,6 +118,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 ...@@ -114,6 +118,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
114 ### 调试欢迎页 118 ### 调试欢迎页
115 119
116 **重置欢迎页标志:** 120 **重置欢迎页标志:**
121 +
117 ```bash 122 ```bash
118 # URL 参数方式 123 # URL 参数方式
119 http://localhost:5173/?reset_welcome=true 124 http://localhost:5173/?reset_welcome=true
...@@ -124,6 +129,7 @@ location.reload() ...@@ -124,6 +129,7 @@ location.reload()
124 ``` 129 ```
125 130
126 **直接访问欢迎页:** 131 **直接访问欢迎页:**
132 +
127 ```javascript 133 ```javascript
128 window.showWelcome() 134 window.showWelcome()
129 ``` 135 ```
...@@ -133,29 +139,34 @@ window.showWelcome() ...@@ -133,29 +139,34 @@ window.showWelcome()
133 ## 🎯 核心特性 139 ## 🎯 核心特性
134 140
135 ### 视频背景 141 ### 视频背景
142 +
136 - ✅ 循环播放星空宇宙主题视频 143 - ✅ 循环播放星空宇宙主题视频
137 - ✅ 移动端和 PC 端自适应 144 - ✅ 移动端和 PC 端自适应
138 - ✅ 自动生成封面图 (七牛云视频处理) 145 - ✅ 自动生成封面图 (七牛云视频处理)
139 - ✅ 降级方案 (视频加载失败时使用静态图) 146 - ✅ 降级方案 (视频加载失败时使用静态图)
140 147
141 ### 首次访问检测 148 ### 首次访问检测
149 +
142 - ✅ localStorage 标志位 150 - ✅ localStorage 标志位
143 - ✅ 路由守卫自动拦截 151 - ✅ 路由守卫自动拦截
144 - ✅ 调试工具支持 152 - ✅ 调试工具支持
145 153
146 ### 功能入口 154 ### 功能入口
155 +
147 - ✅ 3个核心功能入口已确定 156 - ✅ 3个核心功能入口已确定
148 - ✅ 持续循环的上下浮动动效 157 - ✅ 持续循环的上下浮动动效
149 - ✅ 水平排列布局 158 - ✅ 水平排列布局
150 - ✅ 配置化入口列表 159 - ✅ 配置化入口列表
151 160
152 **功能入口详情:** 161 **功能入口详情:**
162 +
153 1. **课程中心** (`/courses`) - 探索精选课程 163 1. **课程中心** (`/courses`) - 探索精选课程
154 2. **活动中心** (`/activity`) - 精彩活动不容错过 164 2. **活动中心** (`/activity`) - 精彩活动不容错过
155 - ⚠️ **注意**: 当前为外链跳转，跳转到 `https://wxm.behalo.cc/pages/activity/activity` 165 - ⚠️ **注意**: 当前为外链跳转，跳转到 `https://wxm.behalo.cc/pages/activity/activity`
156 3. **个人中心** (`/profile`) - 管理您的账户 166 3. **个人中心** (`/profile`) - 管理您的账户
157 167
158 **布局设计:** 168 **布局设计:**
169 +
159 - 📐 **水平布局**: 3个图标水平排列成一行 170 - 📐 **水平布局**: 3个图标水平排列成一行
160 - 📍 **位置**: 标题在顶部，功能入口在底部 171 - 📍 **位置**: 标题在顶部，功能入口在底部
161 - ✨ **效果**: 星空宇宙主题视频背景，浮动动画效果 172 - ✨ **效果**: 星空宇宙主题视频背景，浮动动画效果
...@@ -163,6 +174,7 @@ window.showWelcome() ...@@ -163,6 +174,7 @@ window.showWelcome()
163 - 🏷️ **标题**: 复用召回页标题图片资源 ✅ 174 - 🏷️ **标题**: 复用召回页标题图片资源 ✅
164 175
165 **图标资源:** 176 **图标资源:**
177 +
166 - URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png` 178 - URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png`
167 - 大小: 33.53KB 179 - 大小: 33.53KB
168 - 上传状态: ✅ 已上传到七牛云 180 - 上传状态: ✅ 已上传到七牛云
...@@ -174,6 +186,7 @@ window.showWelcome() ...@@ -174,6 +186,7 @@ window.showWelcome()
174 ### Q: 视频上传失败? 186 ### Q: 视频上传失败?
175 187
176 **A:** 检查是否需要使用代理: 188 **A:** 检查是否需要使用代理:
189 +
177 ```bash 190 ```bash
178 USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh 191 USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh
179 ``` 192 ```
...@@ -181,6 +194,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh ...@@ -181,6 +194,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" ./upload-welcome-video.sh
181 ### Q: 封面图如何生成? 194 ### Q: 封面图如何生成?
182 195
183 **A:** 自动从视频中提取第一帧: 196 **A:** 自动从视频中提取第一帧:
197 +
184 ```javascript 198 ```javascript
185 const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001` 199 const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
186 ``` 200 ```
...@@ -188,6 +202,7 @@ const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001` ...@@ -188,6 +202,7 @@ const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
188 ### Q: 如何测试欢迎页? 202 ### Q: 如何测试欢迎页?
189 203
190 **A:** 重置标志后刷新页面: 204 **A:** 重置标志后刷新页面:
205 +
191 ```javascript 206 ```javascript
192 window.resetWelcomeFlag() 207 window.resetWelcomeFlag()
193 location.reload() 208 location.reload()
...@@ -195,4 +210,4 @@ location.reload() ...@@ -195,4 +210,4 @@ location.reload()
195 210
196 --- 211 ---
197 212
198 -*最后更新: 2026-01-28* 213 +_最后更新: 2026-01-28_
......
...@@ -5,6 +5,7 @@ ...@@ -5,6 +5,7 @@
5 为 mlaj 平台设计一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。 5 为 mlaj 平台设计一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。
6 6
7 **核心需求:** 7 **核心需求:**
8 +
8 - 视频背景循环播放（星空宇宙主题） 9 - 视频背景循环播放（星空宇宙主题）
9 - 悬浮的功能入口图标 + 文字介绍 10 - 悬浮的功能入口图标 + 文字介绍
10 - 持续循环的缩放位移动效 11 - 持续循环的缩放位移动效
...@@ -17,6 +18,7 @@ ...@@ -17,6 +18,7 @@
17 ### 问题 1: 欢迎页的主要目标？ 18 ### 问题 1: 欢迎页的主要目标？
18 19
19 **选项:** 20 **选项:**
21 +
20 - 品牌展示 - 营造高端/科技感的品牌印象 22 - 品牌展示 - 营造高端/科技感的品牌印象
21 - 功能引导 - 清晰展示核心功能入口 23 - 功能引导 - 清晰展示核心功能入口
22 - 新手引导 - 教育用户如何使用平台 24 - 新手引导 - 教育用户如何使用平台
...@@ -29,11 +31,13 @@ ...@@ -29,11 +31,13 @@
29 ### 问题 2: 视频背景的实现方式？ 31 ### 问题 2: 视频背景的实现方式？
30 32
31 **选项:** 33 **选项:**
34 +
32 - 原生 `<video>` 标签 35 - 原生 `<video>` 标签
33 - 简化版组件（参考 StarryBackground）✅ 36 - 简化版组件（参考 StarryBackground）✅
34 - 页面内直接实现 37 - 页面内直接实现
35 38
36 **决策:** 选择**简化版组件**，理由： 39 **决策:** 选择**简化版组件**，理由：
40 +
37 - 组件化便于复用和维护 41 - 组件化便于复用和维护
38 - 移除 Canvas 星星特效，保留视频播放逻辑 42 - 移除 Canvas 星星特效，保留视频播放逻辑
39 - 支持 Props 配置，灵活性高 43 - 支持 Props 配置，灵活性高
...@@ -43,16 +47,19 @@ ...@@ -43,16 +47,19 @@
43 ### 问题 3: 如何判断用户是否首次进入？ 47 ### 问题 3: 如何判断用户是否首次进入？
44 48
45 **选项:** 49 **选项:**
50 +
46 - localStorage 标志 ✅ 51 - localStorage 标志 ✅
47 - 后端接口判断 52 - 后端接口判断
48 - URL 参数控制 53 - URL 参数控制
49 54
50 **决策:** 选择 **localStorage 标志**，理由： 55 **决策:** 选择 **localStorage 标志**，理由：
56 +
51 - 简单高效，无需额外请求 57 - 简单高效，无需额外请求
52 - 符合前端存储特性 58 - 符合前端存储特性
53 - 开发调试方便（可手动清除） 59 - 开发调试方便（可手动清除）
54 60
55 **权衡:** 61 **权衡:**
62 +
56 - 缺点: 清除缓存后会再次显示 63 - 缺点: 清除缓存后会再次显示
57 - 解决方案: 文档说明这是预期行为，未来可升级为后端接口 64 - 解决方案: 文档说明这是预期行为，未来可升级为后端接口
58 65
...@@ -61,11 +68,13 @@ ...@@ -61,11 +68,13 @@
61 ### 问题 4: 图标和文字的动效风格？ 68 ### 问题 4: 图标和文字的动效风格？
62 69
63 **选项:** 70 **选项:**
71 +
64 - 轻量动效（3秒入场 + 悬停交互） 72 - 轻量动效（3秒入场 + 悬停交互）
65 - 持续循环（呼吸/缩放动画）✅ 73 - 持续循环（呼吸/缩放动画）✅
66 - 一次性入场 74 - 一次性入场
67 75
68 **决策:** 选择**持续循环**，理由： 76 **决策:** 选择**持续循环**，理由：
77 +
69 - 符合"星空宇宙"的神秘感主题 78 - 符合"星空宇宙"的神秘感主题
70 - 视觉冲击力更强，吸引用户注意力 79 - 视觉冲击力更强，吸引用户注意力
71 - 不同入口设置不同延迟，形成错落感 80 - 不同入口设置不同延迟，形成错落感
...@@ -77,21 +86,25 @@ ...@@ -77,21 +86,25 @@
77 ### 整体架构方案 86 ### 整体架构方案
78 87
79 **方案 A: 单页面组件** 88 **方案 A: 单页面组件**
89 +
80 ``` 90 ```
81 WelcomePage.vue 91 WelcomePage.vue
82 ├── 直接写 video 标签 92 ├── 直接写 video 标签
83 └── 内联功能入口 93 └── 内联功能入口
84 ``` 94 ```
95 +
85 - 优点: 简单直接 96 - 优点: 简单直接
86 - 缺点: 代码耦合，难以复用 97 - 缺点: 代码耦合，难以复用
87 98
88 **方案 B: 组件化设计 ✅** 99 **方案 B: 组件化设计 ✅**
100 +
89 ``` 101 ```
90 WelcomePage.vue 102 WelcomePage.vue
91 ├── VideoBackground.vue (通用组件) 103 ├── VideoBackground.vue (通用组件)
92 └── WelcomeContent.vue 104 └── WelcomeContent.vue
93 └── WelcomeEntryItem.vue 105 └── WelcomeEntryItem.vue
94 ``` 106 ```
107 +
95 - 优点: 组件复用、职责清晰、易维护 108 - 优点: 组件复用、职责清晰、易维护
96 - 缺点: 文件稍多 109 - 缺点: 文件稍多
97 110
...@@ -118,6 +131,7 @@ WelcomePage (视图容器) ...@@ -118,6 +131,7 @@ WelcomePage (视图容器)
118 ### 首次访问控制逻辑 131 ### 首次访问控制逻辑
119 132
120 **路由守卫方案:** 133 **路由守卫方案:**
134 +
121 ```javascript 135 ```javascript
122 // src/router/guards.js 136 // src/router/guards.js
123 const HAS_VISITED_WELCOME = 'has_visited_welcome' 137 const HAS_VISITED_WELCOME = 'has_visited_welcome'
...@@ -129,12 +143,11 @@ router.beforeEach((to, from, next) => { ...@@ -129,12 +143,11 @@ router.beforeEach((to, from, next) => {
129 } 143 }
130 144
131 // 首次访问检测 145 // 首次访问检测
132 - if (to.path !== '/welcome' && 146 + if (to.path !== '/welcome' && !localStorage.getItem(HAS_VISITED_WELCOME)) {
133 - !localStorage.getItem(HAS_VISITED_WELCOME)) {
134 localStorage.setItem(HAS_VISITED_WELCOME, 'true') 147 localStorage.setItem(HAS_VISITED_WELCOME, 'true')
135 return next({ 148 return next({
136 path: '/welcome', 149 path: '/welcome',
137 - query: { redirect: to.fullPath } 150 + query: { redirect: to.fullPath },
138 }) 151 })
139 } 152 }
140 153
...@@ -143,6 +156,7 @@ router.beforeEach((to, from, next) => { ...@@ -143,6 +156,7 @@ router.beforeEach((to, from, next) => {
143 ``` 156 ```
144 157
145 **调试功能:** 158 **调试功能:**
159 +
146 - URL 参数 `?reset_welcome=true` 重置标志位 160 - URL 参数 `?reset_welcome=true` 重置标志位
147 - 控制台 `window.resetWelcomeFlag()` 快捷方法 161 - 控制台 `window.resetWelcomeFlag()` 快捷方法
148 162
...@@ -155,12 +169,14 @@ router.beforeEach((to, from, next) => { ...@@ -155,12 +169,14 @@ router.beforeEach((to, from, next) => {
155 **位置:** `src/components/effects/VideoBackground.vue` 169 **位置:** `src/components/effects/VideoBackground.vue`
156 170
157 **核心特性:** 171 **核心特性:**
172 +
158 - 简化版设计，移除 Canvas 特效 173 - 简化版设计，移除 Canvas 特效
159 - 原生 `<video>` 标签实现 174 - 原生 `<video>` 标签实现
160 - 移动端和 PC 端自适应 175 - 移动端和 PC 端自适应
161 - 可配置视频源、播放速度、覆盖模式 176 - 可配置视频源、播放速度、覆盖模式
162 177
163 **Props 设计:** 178 **Props 设计:**
179 +
164 ```javascript 180 ```javascript
165 { 181 {
166 videoSrc: { type: String, required: true }, 182 videoSrc: { type: String, required: true },
...@@ -173,6 +189,7 @@ router.beforeEach((to, from, next) => { ...@@ -173,6 +189,7 @@ router.beforeEach((to, from, next) => {
173 ``` 189 ```
174 190
175 **关键实现点:** 191 **关键实现点:**
192 +
176 - 使用 `object-fit: cover` 确保全屏覆盖不变形 193 - 使用 `object-fit: cover` 确保全屏覆盖不变形
177 - 添加 `playsinline` 支持 iOS 内联播放 194 - 添加 `playsinline` 支持 iOS 内联播放
178 - 监听 `canplay` 事件移除 loading 状态 195 - 监听 `canplay` 事件移除 loading 状态
...@@ -187,6 +204,7 @@ router.beforeEach((to, from, next) => { ...@@ -187,6 +204,7 @@ router.beforeEach((to, from, next) => {
187 **核心布局:** 功能入口网格（2-3列） 204 **核心布局:** 功能入口网格（2-3列）
188 205
189 **入口项动效设计（持续循环）:** 206 **入口项动效设计（持续循环）:**
207 +
190 - CSS `@keyframes` 实现呼吸缩放效果 208 - CSS `@keyframes` 实现呼吸缩放效果
191 - 动画参数: `scale(1.0) → scale(1.08) → scale(1.0)` 209 - 动画参数: `scale(1.0) → scale(1.08) → scale(1.0)`
192 - 周期: 2-3秒 210 - 周期: 2-3秒
...@@ -194,9 +212,11 @@ router.beforeEach((to, from, next) => { ...@@ -194,9 +212,11 @@ router.beforeEach((to, from, next) => {
194 - Hover 时加速或高亮 212 - Hover 时加速或高亮
195 213
196 **CSS 动画示例:** 214 **CSS 动画示例:**
215 +
197 ```less 216 ```less
198 @keyframes breathe { 217 @keyframes breathe {
199 - 0%, 100% { 218 + 0%,
219 + 100% {
200 transform: scale(1); 220 transform: scale(1);
201 opacity: 0.9; 221 opacity: 0.9;
202 } 222 }
...@@ -224,11 +244,13 @@ router.beforeEach((to, from, next) => { ...@@ -224,11 +244,13 @@ router.beforeEach((to, from, next) => {
224 ### 现有方案分析 244 ### 现有方案分析
225 245
226 **从 deploy.sh 提取的关键逻辑:** 246 **从 deploy.sh 提取的关键逻辑:**
247 +
227 - 使用 `qshell qupload` 命令批量上传 248 - 使用 `qshell qupload` 命令批量上传
228 - 依赖配置文件 `~/.qshell/stdj_upload.conf` 249 - 依赖配置文件 `~/.qshell/stdj_upload.conf`
229 - 需要预先安装 qshell 工具 250 - 需要预先安装 qshell 工具
230 251
231 **发现的问题:** 252 **发现的问题:**
253 +
232 - 用户提到"需要挂代理才能访问" 254 - 用户提到"需要挂代理才能访问"
233 - 可能是七牛云 API 域名在某些网络环境下被限制 255 - 可能是七牛云 API 域名在某些网络环境下被限制
234 - 需要设置 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量 256 - 需要设置 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量
...@@ -238,11 +260,13 @@ router.beforeEach((to, from, next) => { ...@@ -238,11 +260,13 @@ router.beforeEach((to, from, next) => {
238 ### 通用化设计探索 260 ### 通用化设计探索
239 261
240 **原始方案问题:** 262 **原始方案问题:**
263 +
241 - 硬编码了欢迎页特定路径（`/docs/plan/26.1.28-欢迎页开发计划/`） 264 - 硬编码了欢迎页特定路径（`/docs/plan/26.1.28-欢迎页开发计划/`）
242 - 配置文件使用项目外的 `~/.qshell/stdj_upload.conf` 265 - 配置文件使用项目外的 `~/.qshell/stdj_upload.conf`
243 - 无法作为通用工具复用 266 - 无法作为通用工具复用
244 267
245 **改进方案:** 268 **改进方案:**
269 +
246 1. **项目内配置** 270 1. **项目内配置**
247 - 配置文件位置: `scripts/qiniu/configs/` 271 - 配置文件位置: `scripts/qiniu/configs/`
248 - 账户信息: `scripts/qiniu/account.json`（不入库） 272 - 账户信息: `scripts/qiniu/account.json`（不入库）
...@@ -263,11 +287,13 @@ router.beforeEach((to, from, next) => { ...@@ -263,11 +287,13 @@ router.beforeEach((to, from, next) => {
263 ### 使用场景设计 287 ### 使用场景设计
264 288
265 **场景 1: 上传欢迎页视频** 289 **场景 1: 上传欢迎页视频**
290 +
266 ```bash 291 ```bash
267 ./scripts/upload-to-qiniu.sh video/bg.mp4 mlaj/video/welcome-bg.mp4 292 ./scripts/upload-to-qiniu.sh video/bg.mp4 mlaj/video/welcome-bg.mp4
268 ``` 293 ```
269 294
270 **场景 2: 批量上传图片** 295 **场景 2: 批量上传图片**
296 +
271 ```bash 297 ```bash
272 # 复制模板并修改配置 298 # 复制模板并修改配置
273 cp scripts/qiniu/templates/image-upload.conf.template \ 299 cp scripts/qiniu/templates/image-upload.conf.template \
...@@ -278,6 +304,7 @@ cp scripts/qiniu/templates/image-upload.conf.template \ ...@@ -278,6 +304,7 @@ cp scripts/qiniu/templates/image-upload.conf.template \
278 ``` 304 ```
279 305
280 **场景 3: 使用代理上传** 306 **场景 3: 使用代理上传**
307 +
281 ```bash 308 ```bash
282 USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \ 309 USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
283 ./scripts/upload-to-qiniu.sh local.mp4 mlaj/video/remote.mp4 310 ./scripts/upload-to-qiniu.sh local.mp4 mlaj/video/remote.mp4
...@@ -288,6 +315,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \ ...@@ -288,6 +315,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
288 ### 视频封面图方案探索 315 ### 视频封面图方案探索
289 316
290 **原始方案问题:** 317 **原始方案问题:**
318 +
291 - 需要单独准备和上传封面图片 319 - 需要单独准备和上传封面图片
292 - 封面图可能与视频内容不匹配 320 - 封面图可能与视频内容不匹配
293 - 增加资源管理成本 321 - 增加资源管理成本
...@@ -295,6 +323,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \ ...@@ -295,6 +323,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
295 **改进方案: 使用七牛云视频处理参数** 323 **改进方案: 使用七牛云视频处理参数**
296 324
297 **方案选择:** 325 **方案选择:**
326 +
298 ```javascript 327 ```javascript
299 // 自动从视频中提取第一帧作为封面 328 // 自动从视频中提取第一帧作为封面
300 const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001` 329 const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
...@@ -305,10 +334,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -305,10 +334,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
305 ``` 334 ```
306 335
307 **七牛云视频帧处理参数:** 336 **七牛云视频帧处理参数:**
337 +
308 - `vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG 338 - `vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG
309 - 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation 339 - 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
310 340
311 **高级参数 (可选):** 341 **高级参数 (可选):**
342 +
312 ```javascript 343 ```javascript
313 // 指定截取时间点 344 // 指定截取时间点
314 ?vframe/jpg/offset/1 345 ?vframe/jpg/offset/1
...@@ -321,12 +352,14 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -321,12 +352,14 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
321 ``` 352 ```
322 353
323 **优势:** 354 **优势:**
355 +
324 - ✅ 只需上传一个视频文件 356 - ✅ 只需上传一个视频文件
325 - ✅ 封面图与视频内容一致 357 - ✅ 封面图与视频内容一致
326 - ✅ 减少资源管理成本 358 - ✅ 减少资源管理成本
327 - ✅ 支持动态调整参数 359 - ✅ 支持动态调整参数
328 360
329 **实现位置:** 361 **实现位置:**
362 +
330 - `VideoBackground.vue` 组件内部使用 computed 自动生成 363 - `VideoBackground.vue` 组件内部使用 computed 自动生成
331 - 环境变量只需配置 `VITE_WELCOME_VIDEO_URL` 364 - 环境变量只需配置 `VITE_WELCOME_VIDEO_URL`
332 - 移除 `VITE_WELCOME_VIDEO_POSTER` 配置项 365 - 移除 `VITE_WELCOME_VIDEO_POSTER` 配置项
...@@ -338,10 +371,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -338,10 +371,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
338 ### 技术风险 371 ### 技术风险
339 372
340 **1. 视频播放兼容性** 373 **1. 视频播放兼容性**
374 +
341 - iOS Safari 可能禁止自动播放 375 - iOS Safari 可能禁止自动播放
342 - 部分浏览器不支持 `playsinline` 376 - 部分浏览器不支持 `playsinline`
343 377
344 **应对:** 378 **应对:**
379 +
345 ```vue 380 ```vue
346 <video 381 <video
347 autoplay 382 autoplay
...@@ -353,15 +388,18 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -353,15 +388,18 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
353 x5-video-player-fullscreen="true" 388 x5-video-player-fullscreen="true"
354 > 389 >
355 ``` 390 ```
391 +
356 - 视频加载失败时使用静态背景图降级 392 - 视频加载失败时使用静态背景图降级
357 393
358 --- 394 ---
359 395
360 **2. 首次访问标志位问题** 396 **2. 首次访问标志位问题**
397 +
361 - 清除 localStorage 后会再次显示 398 - 清除 localStorage 后会再次显示
362 - 不同浏览器无法共享标志位 399 - 不同浏览器无法共享标志位
363 400
364 **应对:** 401 **应对:**
402 +
365 - 文档说明这是预期行为 403 - 文档说明这是预期行为
366 - 提供调试工具方便开发 404 - 提供调试工具方便开发
367 - 未来可升级为后端接口 405 - 未来可升级为后端接口
...@@ -369,10 +407,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -369,10 +407,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
369 --- 407 ---
370 408
371 **3. 视频加载性能** 409 **3. 视频加载性能**
410 +
372 - 文件过大导致加载缓慢 411 - 文件过大导致加载缓慢
373 - 弱网环境体验差 412 - 弱网环境体验差
374 413
375 **应对:** 414 **应对:**
415 +
376 - 限制文件大小 < 10MB 416 - 限制文件大小 < 10MB
377 - 使用七牛云视频处理参数自动生成封面图 (`?vframe/jpg/offset/0.001`) 417 - 使用七牛云视频处理参数自动生成封面图 (`?vframe/jpg/offset/0.001`)
378 - 封面图在视频加载前显示，提升用户体验 418 - 封面图在视频加载前显示，提升用户体验
...@@ -382,9 +422,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -382,9 +422,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
382 --- 422 ---
383 423
384 **4. 七牛云代理问题** 424 **4. 七牛云代理问题**
425 +
385 - 需要挂代理才能访问 426 - 需要挂代理才能访问
386 427
387 **应对:** 428 **应对:**
429 +
388 - 脚本支持 `USE_PROXY` 环境变量 430 - 脚本支持 `USE_PROXY` 环境变量
389 - 提供诊断脚本测试连通性 431 - 提供诊断脚本测试连通性
390 - 文档说明代理配置方法 432 - 文档说明代理配置方法
...@@ -394,9 +436,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -394,9 +436,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
394 ### 业务风险 436 ### 业务风险
395 437
396 **1. 功能入口待确认** 438 **1. 功能入口待确认**
439 +
397 - 设计稿未确定具体入口 440 - 设计稿未确定具体入口
398 441
399 **应对:** 442 **应对:**
443 +
400 - 先实现框架和核心逻辑 444 - 先实现框架和核心逻辑
401 - 入口配置化，后续易于调整 445 - 入口配置化，后续易于调整
402 - 使用 Mock 数据开发 446 - 使用 Mock 数据开发
...@@ -404,9 +448,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -404,9 +448,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
404 --- 448 ---
405 449
406 **2. 动效性能影响** 450 **2. 动效性能影响**
451 +
407 - 持续动画可能消耗 CPU/电量 452 - 持续动画可能消耗 CPU/电量
408 453
409 **应对:** 454 **应对:**
455 +
410 - 使用 CSS 动画而非 JS（性能更好） 456 - 使用 CSS 动画而非 JS（性能更好）
411 - 提供环境变量控制动画开关 457 - 提供环境变量控制动画开关
412 - 低端设备检测后降级为静态效果 458 - 低端设备检测后降级为静态效果
...@@ -436,7 +482,7 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -436,7 +482,7 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
436 ## 关键决策总结 482 ## 关键决策总结
437 483
438 | 决策点 | 选择 | 理由 | 484 | 决策点 | 选择 | 理由 |
439 -|--------|------|------| 485 +| ---------- | -------------- | ---------------------- |
440 | 页面目标 | 混合型 | 品牌展示 + 功能引导 | 486 | 页面目标 | 混合型 | 品牌展示 + 功能引导 |
441 | 视频实现 | 简化版组件 | 组件化，便于复用 | 487 | 视频实现 | 简化版组件 | 组件化，便于复用 |
442 | 首次检测 | localStorage | 简单高效 | 488 | 首次检测 | localStorage | 简单高效 |
...@@ -456,5 +502,5 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o ...@@ -456,5 +502,5 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
456 502
457 --- 503 ---
458 504
459 -*文档创建时间: 2026-01-28* 505 +_文档创建时间: 2026-01-28_
460 -*最后更新: 2026-01-28* 506 +_最后更新: 2026-01-28_
......
...@@ -5,6 +5,7 @@ ...@@ -5,6 +5,7 @@
5 为 mlaj 平台开发一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。 5 为 mlaj 平台开发一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。
6 6
7 **核心功能:** 7 **核心功能:**
8 +
8 - 视频背景循环播放（星空宇宙主题） 9 - 视频背景循环播放（星空宇宙主题）
9 - 悬浮的功能入口图标 + 文字介绍 10 - 悬浮的功能入口图标 + 文字介绍
10 - 持续循环的缩放位移动效 11 - 持续循环的缩放位移动效
...@@ -59,6 +60,7 @@ mlaj/ ...@@ -59,6 +60,7 @@ mlaj/
59 #### 步骤 1: 创建配置文件模板 60 #### 步骤 1: 创建配置文件模板
60 61
61 **创建 `scripts/qiniu/templates/video-upload.conf.template`:** 62 **创建 `scripts/qiniu/templates/video-upload.conf.template`:**
63 +
62 ```json 64 ```json
63 { 65 {
64 "src_dir": "./assets/video", 66 "src_dir": "./assets/video",
...@@ -77,6 +79,7 @@ mlaj/ ...@@ -77,6 +79,7 @@ mlaj/
77 ``` 79 ```
78 80
79 **创建 `scripts/qiniu/templates/image-upload.conf.template`:** 81 **创建 `scripts/qiniu/templates/image-upload.conf.template`:**
82 +
80 ```json 83 ```json
81 { 84 {
82 "src_dir": "./assets/images", 85 "src_dir": "./assets/images",
...@@ -109,6 +112,7 @@ scripts/qiniu/configs/ ...@@ -109,6 +112,7 @@ scripts/qiniu/configs/
109 **视频文件:** `docs/plan/26.1.28-欢迎页开发计划/video/welcome-bg.mp4` ✅ 已添加 112 **视频文件:** `docs/plan/26.1.28-欢迎页开发计划/video/welcome-bg.mp4` ✅ 已添加
110 113
111 **建议规格:** 114 **建议规格:**
115 +
112 - 分辨率: 1920x1080 (1080p) 116 - 分辨率: 1920x1080 (1080p)
113 - 编码格式: H.264 117 - 编码格式: H.264
114 - 时长: 10-20秒循环视频 118 - 时长: 10-20秒循环视频
...@@ -126,12 +130,14 @@ chmod +x scripts/upload-to-qiniu.sh ...@@ -126,12 +130,14 @@ chmod +x scripts/upload-to-qiniu.sh
126 ``` 130 ```
127 131
128 **上传成功后的 URL:** ✅ 已上传 132 **上传成功后的 URL:** ✅ 已上传
133 +
129 ``` 134 ```
130 视频: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 135 视频: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
131 封面: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001 136 封面: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001
132 ``` 137 ```
133 138
134 **文件信息:** 139 **文件信息:**
140 +
135 - 大小: 17.57MB (18420585 字节) 141 - 大小: 17.57MB (18420585 字节)
136 - Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH 142 - Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH
137 - 上传时间: 1.23s 143 - 上传时间: 1.23s
...@@ -139,6 +145,7 @@ chmod +x scripts/upload-to-qiniu.sh ...@@ -139,6 +145,7 @@ chmod +x scripts/upload-to-qiniu.sh
139 #### 步骤 5: 更新环境变量 145 #### 步骤 5: 更新环境变量
140 146
141 **`.env.development`:** 147 **`.env.development`:**
148 +
142 ```bash 149 ```bash
143 # 欢迎页功能开关 150 # 欢迎页功能开关
144 VITE_WELCOME_PAGE_ENABLED=true 151 VITE_WELCOME_PAGE_ENABLED=true
...@@ -149,12 +156,14 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 ...@@ -149,12 +156,14 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
149 ``` 156 ```
150 157
151 **`.env.production`:** 158 **`.env.production`:**
159 +
152 ```bash 160 ```bash
153 VITE_WELCOME_PAGE_ENABLED=true 161 VITE_WELCOME_PAGE_ENABLED=true
154 VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4 162 VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
155 ``` 163 ```
156 164
157 **说明:** 165 **说明:**
166 +
158 - 只需配置视频 URL，封面图会自动从视频中提取第一帧生成 167 - 只需配置视频 URL，封面图会自动从视频中提取第一帧生成
159 - 七牛云处理参数: `?vframe/jpg/offset/0.001` 表示从视频第 0.001 秒截取一帧作为 JPG 图片 168 - 七牛云处理参数: `?vframe/jpg/offset/0.001` 表示从视频第 0.001 秒截取一帧作为 JPG 图片
160 - 降级方案: 视频加载失败时自动使用该封面图作为静态背景 169 - 降级方案: 视频加载失败时自动使用该封面图作为静态背景
...@@ -359,6 +368,7 @@ main "$@" ...@@ -359,6 +368,7 @@ main "$@"
359 #### 步骤 2: 添加 npm scripts 368 #### 步骤 2: 添加 npm scripts
360 369
361 **`package.json`:** 370 **`package.json`:**
371 +
362 ```json 372 ```json
363 { 373 {
364 "scripts": { 374 "scripts": {
...@@ -435,33 +445,33 @@ const props = defineProps({ ...@@ -435,33 +445,33 @@ const props = defineProps({
435 /** 视频源 URL */ 445 /** 视频源 URL */
436 videoSrc: { 446 videoSrc: {
437 type: String, 447 type: String,
438 - required: true 448 + required: true,
439 }, 449 },
440 /** 封面图 URL (可选，不传则自动从视频生成) */ 450 /** 封面图 URL (可选，不传则自动从视频生成) */
441 poster: { 451 poster: {
442 type: String, 452 type: String,
443 - default: '' 453 + default: '',
444 }, 454 },
445 /** 是否自动播放 */ 455 /** 是否自动播放 */
446 autoplay: { 456 autoplay: {
447 type: Boolean, 457 type: Boolean,
448 - default: true 458 + default: true,
449 }, 459 },
450 /** 是否循环播放 */ 460 /** 是否循环播放 */
451 loop: { 461 loop: {
452 type: Boolean, 462 type: Boolean,
453 - default: true 463 + default: true,
454 }, 464 },
455 /** 是否静音 */ 465 /** 是否静音 */
456 muted: { 466 muted: {
457 type: Boolean, 467 type: Boolean,
458 - default: true 468 + default: true,
459 }, 469 },
460 /** 视频填充模式 */ 470 /** 视频填充模式 */
461 objectFit: { 471 objectFit: {
462 type: String, 472 type: String,
463 - default: 'cover' // cover, contain, fill 473 + default: 'cover', // cover, contain, fill
464 - } 474 + },
465 }) 475 })
466 476
467 const videoRef = ref(null) 477 const videoRef = ref(null)
...@@ -497,7 +507,7 @@ const onCanPlay = () => { ...@@ -497,7 +507,7 @@ const onCanPlay = () => {
497 } 507 }
498 508
499 // 视频加载错误 509 // 视频加载错误
500 -const onError = (e) => { 510 +const onError = e => {
501 console.error('[VideoBackground] 视频加载失败:', e) 511 console.error('[VideoBackground] 视频加载失败:', e)
502 isLoading.value = false 512 isLoading.value = false
503 showFallback.value = true 513 showFallback.value = true
...@@ -536,7 +546,7 @@ onUnmounted(() => { ...@@ -536,7 +546,7 @@ onUnmounted(() => {
536 546
537 defineExpose({ 547 defineExpose({
538 play, 548 play,
539 - pause 549 + pause,
540 }) 550 })
541 </script> 551 </script>
542 552
...@@ -584,12 +594,7 @@ defineExpose({ ...@@ -584,12 +594,7 @@ defineExpose({
584 594
585 ```vue 595 ```vue
586 <template> 596 <template>
587 - <VideoBackground 597 + <VideoBackground :video-src="videoUrl" autoplay loop muted />
588 - :video-src="videoUrl"
589 - autoplay
590 - loop
591 - muted
592 - />
593 </template> 598 </template>
594 599
595 <script setup> 600 <script setup>
...@@ -615,10 +620,7 @@ const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4' ...@@ -615,10 +620,7 @@ const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4'
615 <template> 620 <template>
616 <div class="welcome-page"> 621 <div class="welcome-page">
617 <!-- 视频背景 --> 622 <!-- 视频背景 -->
618 - <VideoBackground 623 + <VideoBackground v-if="videoUrl" :video-src="videoUrl" />
619 - v-if="videoUrl"
620 - :video-src="videoUrl"
621 - />
622 624
623 <!-- 内容区域 --> 625 <!-- 内容区域 -->
624 <WelcomeContent class="welcome-content" /> 626 <WelcomeContent class="welcome-content" />
...@@ -721,7 +723,7 @@ router.beforeEach((to, from, next) => { ...@@ -721,7 +723,7 @@ router.beforeEach((to, from, next) => {
721 markWelcomeVisited() 723 markWelcomeVisited()
722 return next({ 724 return next({
723 path: '/welcome', 725 path: '/welcome',
724 - query: { redirect: to.fullPath } 726 + query: { redirect: to.fullPath },
725 }) 727 })
726 } 728 }
727 729
...@@ -775,7 +777,7 @@ export const welcomeEntries = [ ...@@ -775,7 +777,7 @@ export const welcomeEntries = [
775 icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL 777 icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
776 route: '/courses', 778 route: '/courses',
777 color: '#4CAF50', 779 color: '#4CAF50',
778 - priority: 1 780 + priority: 1,
779 }, 781 },
780 { 782 {
781 id: 'activity', 783 id: 'activity',
...@@ -786,7 +788,7 @@ export const welcomeEntries = [ ...@@ -786,7 +788,7 @@ export const welcomeEntries = [
786 color: '#FF9800', 788 color: '#FF9800',
787 priority: 2, 789 priority: 2,
788 isExternal: true, // 标记为外链跳转 790 isExternal: true, // 标记为外链跳转
789 - externalUrl: 'https://wxm.behalo.cc/pages/activity/activity?token=&user_id=' 791 + externalUrl: 'https://wxm.behalo.cc/pages/activity/activity?token=&user_id=',
790 }, 792 },
791 { 793 {
792 id: 'profile', 794 id: 'profile',
...@@ -795,8 +797,8 @@ export const welcomeEntries = [ ...@@ -795,8 +797,8 @@ export const welcomeEntries = [
795 icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL 797 icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
796 route: '/profile', 798 route: '/profile',
797 color: '#2196F3', 799 color: '#2196F3',
798 - priority: 3 800 + priority: 3,
799 - } 801 + },
800 ] 802 ]
801 803
802 /** 804 /**
...@@ -826,12 +828,14 @@ export function getSortedEntries() { ...@@ -826,12 +828,14 @@ export function getSortedEntries() {
826 - 学习记录和设置 828 - 学习记录和设置
827 829
828 **布局设计:** 830 **布局设计:**
831 +
829 - 🌌 **环绕式布局**: 3个图标像天体行星一样环绕排列 832 - 🌌 **环绕式布局**: 3个图标像天体行星一样环绕排列
830 - 📍 **位置**: 页面中下位置 833 - 📍 **位置**: 页面中下位置
831 - 🎨 **视觉效果**: 星空宇宙主题，行星轨道感 834 - 🎨 **视觉效果**: 星空宇宙主题，行星轨道感
832 - 🖼️ **图标**: 统一使用七牛云图片图标 ✅ 835 - 🖼️ **图标**: 统一使用七牛云图片图标 ✅
833 836
834 **图标资源:** 837 **图标资源:**
838 +
835 - 文件名: `welcome_btn_1.png` 839 - 文件名: `welcome_btn_1.png`
836 - 七牛云URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png` ✅ 已上传 840 - 七牛云URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png` ✅ 已上传
837 - 文件大小: 33.53KB (34,333 字节) 841 - 文件大小: 33.53KB (34,333 字节)
...@@ -843,11 +847,7 @@ export function getSortedEntries() { ...@@ -843,11 +847,7 @@ export function getSortedEntries() {
843 847
844 ```vue 848 ```vue
845 <template> 849 <template>
846 - <div 850 + <div class="entry-item" :style="{ '--index': index }" @click="handleClick">
847 - class="entry-item"
848 - :style="{ '--index': index }"
849 - @click="handleClick"
850 - >
851 <!-- 图标 (图片) --> 851 <!-- 图标 (图片) -->
852 <div class="entry-icon"> 852 <div class="entry-icon">
853 <img :src="entry.icon" :alt="entry.title" /> 853 <img :src="entry.icon" :alt="entry.title" />
...@@ -871,12 +871,12 @@ import { useRouter } from 'vue-router' ...@@ -871,12 +871,12 @@ import { useRouter } from 'vue-router'
871 const props = defineProps({ 871 const props = defineProps({
872 entry: { 872 entry: {
873 type: Object, 873 type: Object,
874 - required: true 874 + required: true,
875 }, 875 },
876 index: { 876 index: {
877 type: Number, 877 type: Number,
878 - required: true 878 + required: true,
879 - } 879 + },
880 }) 880 })
881 881
882 const router = useRouter() 882 const router = useRouter()
...@@ -951,7 +951,8 @@ const handleClick = () => { ...@@ -951,7 +951,8 @@ const handleClick = () => {
951 } 951 }
952 952
953 @keyframes breathe { 953 @keyframes breathe {
954 - 0%, 100% { 954 + 0%,
955 + 100% {
955 opacity: 0.9; 956 opacity: 0.9;
956 } 957 }
957 50% { 958 50% {
...@@ -1124,6 +1125,7 @@ const sortedEntries = computed(() => getSortedEntries()) ...@@ -1124,6 +1125,7 @@ const sortedEntries = computed(() => getSortedEntries())
1124 #### 步骤 1: 更新项目文档 1125 #### 步骤 1: 更新项目文档
1125 1126
1126 **`CLAUDE.md` 添加说明:** 1127 **`CLAUDE.md` 添加说明:**
1128 +
1127 ```markdown 1129 ```markdown
1128 ### 欢迎页 1130 ### 欢迎页
1129 1131
...@@ -1141,7 +1143,7 @@ const sortedEntries = computed(() => getSortedEntries()) ...@@ -1141,7 +1143,7 @@ const sortedEntries = computed(() => getSortedEntries())
1141 1143
1142 **文件:** `docs/welcome-page-guide.md` 1144 **文件:** `docs/welcome-page-guide.md`
1143 1145
1144 -```markdown 1146 +````markdown
1145 # 欢迎页使用指南 1147 # 欢迎页使用指南
1146 1148
1147 ## 功能说明 1149 ## 功能说明
...@@ -1160,6 +1162,7 @@ VITE_WELCOME_PAGE_ENABLED=true ...@@ -1160,6 +1162,7 @@ VITE_WELCOME_PAGE_ENABLED=true
1160 VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4 1162 VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4
1161 VITE_WELCOME_VIDEO_POSTER=https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg 1163 VITE_WELCOME_VIDEO_POSTER=https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg
1162 ``` 1164 ```
1165 +````
1163 1166
1164 ### 功能入口配置 1167 ### 功能入口配置
1165 1168
...@@ -1174,8 +1177,8 @@ export const welcomeEntries = [ ...@@ -1174,8 +1177,8 @@ export const welcomeEntries = [
1174 icon: '📚', 1177 icon: '📚',
1175 route: '/courses', 1178 route: '/courses',
1176 color: '#4CAF50', 1179 color: '#4CAF50',
1177 - priority: 1 1180 + priority: 1,
1178 - } 1181 + },
1179 // ... 更多入口 1182 // ... 更多入口
1180 ] 1183 ]
1181 ``` 1184 ```
...@@ -1185,17 +1188,20 @@ export const welcomeEntries = [ ...@@ -1185,17 +1188,20 @@ export const welcomeEntries = [
1185 ### 重置欢迎页标志 1188 ### 重置欢迎页标志
1186 1189
1187 **方法 1: URL 参数** 1190 **方法 1: URL 参数**
1191 +
1188 ``` 1192 ```
1189 http://localhost:5173/?reset_welcome=true 1193 http://localhost:5173/?reset_welcome=true
1190 ``` 1194 ```
1191 1195
1192 **方法 2: 控制台** 1196 **方法 2: 控制台**
1197 +
1193 ```javascript 1198 ```javascript
1194 window.resetWelcomeFlag() 1199 window.resetWelcomeFlag()
1195 location.reload() 1200 location.reload()
1196 ``` 1201 ```
1197 1202
1198 ### 直接访问欢迎页 1203 ### 直接访问欢迎页
1204 +
1199 ```javascript 1205 ```javascript
1200 window.showWelcome() 1206 window.showWelcome()
1201 ``` 1207 ```
...@@ -1257,6 +1263,7 @@ pnpm dev_upload ...@@ -1257,6 +1263,7 @@ pnpm dev_upload
1257 ``` 1263 ```
1258 1264
1259 **关键属性说明:** 1265 **关键属性说明:**
1266 +
1260 - `muted`: 静音播放(移动端自动播放必需) 1267 - `muted`: 静音播放(移动端自动播放必需)
1261 - `playsinline`: iOS 内联播放 1268 - `playsinline`: iOS 内联播放
1262 - `webkit-playsinline`: iOS Safari 兼容 1269 - `webkit-playsinline`: iOS Safari 兼容
...@@ -1278,6 +1285,7 @@ will-change: transform, opacity; ...@@ -1278,6 +1285,7 @@ will-change: transform, opacity;
1278 ### 3. 七牛云视频处理 - 自动生成封面图 1285 ### 3. 七牛云视频处理 - 自动生成封面图
1279 1286
1280 **封面图自动生成:** 1287 **封面图自动生成:**
1288 +
1281 ```javascript 1289 ```javascript
1282 // VideoBackground 组件内部实现 1290 // VideoBackground 组件内部实现
1283 const posterUrl = computed(() => { 1291 const posterUrl = computed(() => {
...@@ -1290,11 +1298,13 @@ const posterUrl = computed(() => { ...@@ -1290,11 +1298,13 @@ const posterUrl = computed(() => {
1290 ``` 1298 ```
1291 1299
1292 **七牛云视频帧处理参数说明:** 1300 **七牛云视频帧处理参数说明:**
1301 +
1293 - `?vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG 图片 1302 - `?vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG 图片
1294 - 完整示例: `https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001` 1303 - 完整示例: `https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001`
1295 - 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation 1304 - 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
1296 1305
1297 **高级参数 (可选):** 1306 **高级参数 (可选):**
1307 +
1298 ```javascript 1308 ```javascript
1299 // 指定截取时间点 (第 1 秒) 1309 // 指定截取时间点 (第 1 秒)
1300 https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/1 1310 https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/1
...@@ -1310,6 +1320,7 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/ ...@@ -1310,6 +1320,7 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
1310 ``` 1320 ```
1311 1321
1312 **优势:** 1322 **优势:**
1323 +
1313 - ✅ 只需上传一个视频文件，无需单独准备封面图 1324 - ✅ 只需上传一个视频文件，无需单独准备封面图
1314 - ✅ 封面图与视频内容一致，不会出现不匹配 1325 - ✅ 封面图与视频内容一致，不会出现不匹配
1315 - ✅ 减少资源管理成本 1326 - ✅ 减少资源管理成本
...@@ -1329,11 +1340,13 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/ ...@@ -1329,11 +1340,13 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
1329 ``` 1340 ```
1330 1341
1331 **降级触发条件:** 1342 **降级触发条件:**
1343 +
1332 1. 视频加载失败 (网络错误、格式不支持) 1344 1. 视频加载失败 (网络错误、格式不支持)
1333 2. 视频自动播放被阻止 (iOS Safari 政策) 1345 2. 视频自动播放被阻止 (iOS Safari 政策)
1334 3. 视频解码失败 1346 3. 视频解码失败
1335 1347
1336 **降级方案:** 1348 **降级方案:**
1349 +
1337 - 使用自动生成的封面图作为静态背景 1350 - 使用自动生成的封面图作为静态背景
1338 - 保证用户始终能看到背景内容 1351 - 保证用户始终能看到背景内容
1339 1352
...@@ -1376,16 +1389,19 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/ ...@@ -1376,16 +1389,19 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
1376 ## 优先级总结 1389 ## 优先级总结
1377 1390
1378 ### 第 1 批 (核心功能) 🔴 1391 ### 第 1 批 (核心功能) 🔴
1392 +
1379 - ✅ 第 0 阶段: 准备工作 1393 - ✅ 第 0 阶段: 准备工作
1380 - ✅ 第 1 阶段: 通用上传工具 1394 - ✅ 第 1 阶段: 通用上传工具
1381 - ✅ 第 2 阶段: VideoBackground 组件 1395 - ✅ 第 2 阶段: VideoBackground 组件
1382 - ✅ 第 3 阶段: 路由与首次访问逻辑 1396 - ✅ 第 3 阶段: 路由与首次访问逻辑
1383 1397
1384 ### 第 2 批 (功能完善) 🟡 1398 ### 第 2 批 (功能完善) 🟡
1399 +
1385 - ⏳ 第 4 阶段: WelcomeContent 组件 1400 - ⏳ 第 4 阶段: WelcomeContent 组件
1386 - ⏳ 第 5 阶段: 测试与优化 1401 - ⏳ 第 5 阶段: 测试与优化
1387 1402
1388 ### 第 3 批 (收尾工作) 🟢 1403 ### 第 3 批 (收尾工作) 🟢
1404 +
1389 - ⏳ 第 6 阶段: 文档与部署 1405 - ⏳ 第 6 阶段: 文档与部署
1390 1406
1391 --- 1407 ---
...@@ -1402,5 +1418,5 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/ ...@@ -1402,5 +1418,5 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
1402 1418
1403 --- 1419 ---
1404 1420
1405 -*文档创建时间: 2026-01-28* 1421 +_文档创建时间: 2026-01-28_
1406 -*最后更新: 2026-01-28* 1422 +_最后更新: 2026-01-28_
......
This diff is collapsed. Click to expand it.