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 1151 additions and 329 deletions
......@@ -59,12 +59,37 @@ src/
## 文档索引
- 近期功能更新记录：[/docs/CHANGELOG.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/CHANGELOG.md)
- 架构实现与工程配置：[/docs/ARCHITECTURE.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/ARCHITECTURE.md)
- /src/components 组件目录索引：[/docs/COMPONENTS.md](file:///Users/huyirui/program/itomix/git/mlaj/docs/COMPONENTS.md)
- 代码风格与最佳实践：[/VUE_CODE_STYLE_GUIDE.md](file:///Users/huyirui/program/itomix/git/mlaj/VUE_CODE_STYLE_GUIDE.md)
- 已知问题与改进建议：[/ISSUES_TO_FIX.md](file:///Users/huyirui/program/itomix/git/mlaj/ISSUES_TO_FIX.md)
- 协作说明（较长）：[/CLAUDE.md](file:///Users/huyirui/program/itomix/git/mlaj/CLAUDE.md)
📚 **完整文档导航**: [docs/README.md](./docs/README.md) - 所有文档的分类索引
### 快速链接
**架构设计**:
- [架构文档](./docs/architecture/ARCHITECTURE.md) - 应用架构与工程配置
- [组件索引](./docs/architecture/COMPONENTS.md) - /src/components 组件目录索引
**开发配置**:
- [ESLint + Prettier](./docs/development/ESLINT_PRETTIER.md) - 代码规范与格式化
- [Husky + lint-staged](./docs/development/HUSKY_LINT_STAGED.md) - Git Hooks 配置
- [开发工作流](./docs/development/WORKFLOW.md) - 团队开发流程
**测试文档**:
- [Playwright 指南](./docs/testing/PLAYWRIGHT.md) - E2E 测试框架
- [E2E 认证指南](./docs/testing/E2E_AUTH_GUIDE.md) - 测试登录认证
- [E2E 代理配置](./docs/testing/E2E_PROXY_SETUP.md) - 测试服务器代理
**工具指南**:
- [Claude Skills](./docs/tools/SKILLS_GUIDE.md) - Claude Code 技能完全指南
**其他**:
- [更新日志](./docs/CHANGELOG.md) - 功能更新记录
- [代码风格指南](./VUE_CODE_STYLE_GUIDE.md) - Vue 代码最佳实践
- [已知问题与改进建议](./ISSUES_TO_FIX.md) - 待优化项列表
- [项目协作说明](./CLAUDE.md) - Claude Code 开发指南（详细）
## 业务系统架构
......
# /src/components 组件目录索引
## 目录划分
| 目录 | 代表组件 | 说明 |
| --- | --- | --- |
| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件（弹窗、列表、卡片、上传） |
| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件（确认、头部、搜索、协议） |
| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件（精选/活动/推荐等） |
| infoEntry/ | formPage.vue | 信息录入相关组件 |
| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
| payment/ | WechatPayment.vue | 微信支付相关组件 |
| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
## 备注
- 布局目录已归一：统一使用 [/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts
# 📖 文档编写规范
本文档定义了项目中编写和维护文档的标准规范，确保文档质量、一致性和可维护性。
## 📑 目录
- [文档分类规则](#文档分类规则)
- [文件命名规范](#文件命名规范)
- [文档结构模板](#文档结构模板)
- [Markdown 编写规范](#markdown-编写规范)
- [文档更新流程](#文档更新流程)
- [审查与发布](#审查与发布)
---
## 文档分类规则
所有文档必须放在对应分类目录下：
```
docs/
├── architecture/ # 🏗️ 架构设计类
├── development/ # 💻 开发配置类
├── testing/ # 🧪 测试文档类
├── tools/ # 🛠️ 工具指南类
├── tasks/ # 📋 任务管理类
│ ├── done/ # 已完成任务
│ ├── plan/ # 计划中任务
│ └── TODO/ # 待办事项
├── CHANGELOG.md # 📝 变更记录（根目录）
└── README.md # 📚 文档导航索引（根目录）
```
### 如何选择分类
| 如果文档是关于... | 放在... |
| ------------------------------------ | ------------------------ |
| 系统架构、组件设计、目录结构 | `architecture/` |
| 开发工具配置、代码规范、Git Hooks | `development/` |
| 测试框架、测试指南、测试配置 | `testing/` |
| 外部工具使用指南（如 Claude Skills） | `tools/` |
| 任务、计划、待办事项 | `tasks/` |
| 版本更新历史 | `CHANGELOG.md`（根目录） |
---
## 文件命名规范
### 基本规则
1. **使用英文命名**
- ✅ `ARCHITECTURE.md`
- ❌ `架构文档.md`
2. **使用大写字母和下划线**
- ✅ `E2E_AUTH_GUIDE.md`
- ❌ `e2e-auth-guide.md`
3. **名称清晰描述内容**
- ✅ `ESLINT_PRETTIER.md`
- ❌ `CODE_STYLE.md`
4. **避免空格和特殊字符**
- ✅ `WORKFLOW.md`
- ❌ `工作流.md`
### 任务文档命名
格式：`[日期]_[类型]_[简短描述].md`
| 类型标识 | 说明 | 示例 |
| ---------- | -------- | ----------------------------------- |
| `feature` | 新功能 | `20260128_feature_打卡草稿缓存.md` |
| `bugfix` | Bug 修复 | `20260128_bugfix_视频播放器修复.md` |
| `optimize` | 性能优化 | `20260128_optimize_首页加载优化.md` |
| `refactor` | 代码重构 | `20260128_refactor_组件拆分.md` |
| `docs` | 文档更新 | `20260128_docs_API文档补充.md` |
| `config` | 配置变更 | `20260128_config_Vite配置优化.md` |
---
## 文档结构模板
### 标准模板
每个文档应遵循以下结构：
````markdown
# 文档标题
> 一句话描述文档的用途和目标读者
**作者**: [可选]
**创建日期**: YYYY-MM-DD
**最后更新**: YYYY-MM-DD
**状态**: [草稿/审阅中/已发布]
---
## 📑 目录
- [背景](#背景)
- [安装/配置](#安装配置)
- [使用指南](#使用指南)
- [API/配置](#api配置)
- [示例](#示例)
- [常见问题](#常见问题)
- [相关资源](#相关资源)
---
## 背景
说明文档的背景、目的和适用场景。
---
## 安装/配置
### 前置条件
列出所需的工具、环境等。
### 步骤
1. 第一步
2. 第二步
3. 第三步
---
## 使用指南
### 基础用法
```javascript
// 代码示例
代码块
```
````
### 高级用法
高级使用场景和技巧。
---
## API/配置
### 配置项
| 参数 | 类型 | 默认值 | 说明 |
| ------ | ------ | --------- | -------- |
| param1 | string | 'default' | 参数说明 |
### 方法
```typescript
function example(param: string): void {
// 实现
}
```
---
## 示例
### 示例 1：场景描述
```bash
# 命令示例
command
```
### 示例 2：场景描述
```javascript
// 代码示例
code
```
---
## 常见问题
### Q: 问题标题？
**A**: 答案说明。
### Q: 另一个问题？
**A**: 答案说明。
---
## 相关资源
- [相关文档1](./link1.md)
- [相关文档2](./link2.md)
- [外部资源](https://example.com)
---
````
---
## Markdown 编写规范
### 标题层级
```markdown
# H1 - 文档标题（每个文档只有一个）
## H2 - 主要章节
### H3 - 子章节
#### H4 - 四级标题（避免更深）
````
**规则**:
- H1 只用于文档标题
- H2 用于主要章节
- H3 用于子章节
- 避免超过 H4
### 代码块
使用 ``` 语言标识 指定语言：
````markdown
\```javascript
// JavaScript 代码
\```
\```bash
# Bash 命令
\```
\```vue
<!-- Vue 组件 -->
<template>
<div />
</template>
\```
````
支持的语法高亮：
- `javascript` / `js`
- `typescript` / `ts`
- `vue`
- `bash` / `sh`
- `json`
- `yaml` / `yml`
- `markdown` / `md`
### 列表
**无序列表**:
```markdown
- 项目 1
- 项目 2
- 子项目 2.1
- 子项目 2.2
```
**有序列表**:
```markdown
1. 第一步
2. 第二步
3. 第三步
```
### 表格
```markdown
| 列1 | 列2 | 列3 |
| ----- | ----- | ----- |
| 数据1 | 数据2 | 数据3 |
```
### 强调
```markdown
**粗体文本**
_斜体文本_
**_粗斜体_**
`行内代码`
```
### 链接
```markdown
[链接文本](./path/to/file.md)
[外部链接](https://example.com)
[带标题的链接](https://example.com '鼠标悬停提示')
```
### 图片
```markdown
![图片描述](./path/to/image.png)
![图片描述](./path/to/image.png '图片标题')
```
### 引用
```markdown
> 普通引用
>
> **引用中可以加粗**
> 可以多行
```
### 分隔线
```markdown
---
```
### 任务列表
```markdown
- [x] 已完成任务
- [ ] 待完成任务
```
### Emoji
适当使用 emoji 增强可读性：
| Emoji | 用途 |
| ----- | --------- |
| 📚 | 文档 |
| 💻 | 代码/开发 |
| 🧪 | 测试 |
| 🏗️ | 架构 |
| 🛠️ | 工具 |
| ✅ | 完成/正确 |
| ❌ | 错误/避免 |
| ⚠️ | 警告 |
| 💡 | 建议/提示 |
| 📝 | 笔记/记录 |
---
## 文档更新流程
### 1. 新增文档
```bash
# 1. 在对应分类下创建文档
cd docs/architecture
vim NEW_DOC.md
# 2. 使用模板初始化
cp ../TEMPLATES/STANDARD.md NEW_DOC.md
# 3. 更新索引
# 编辑 ../README.md，在对应分类下添加链接
```
### 2. 更新文档
```bash
# 1. 修改文档内容
vim docs/xxx/FILE.md
# 2. 更新"最后更新"日期
# 在文档头部更新日期字段
# 3. 如果有重大变更，更新 CHANGELOG.md
```
### 3. 移动/删除文档
```bash
# 移动文档
git mv docs/old/FILE.md docs/new/FILE.md
# 删除文档（需谨慎）
git rm docs/xxx/FILE.md
```
### 4. 索引维护
每次新增或移动文档后，**必须**更新 `docs/README.md`：
1. 在对应分类下添加或更新链接
2. 如果是任务文档，更新 `tasks/README.md`
3. 更新"快速查找"部分（如果适用）
---
## 审查与发布
### 自查清单
发布文档前，确认：
- [ ] 文档放在正确的分类目录
- [ ] 文件名遵循命名规范
- [ ] 使用标准文档结构模板
- [ ] 代码块指定了语言标识
- [ ] 所有链接有效（可点击测试）
- [ ] 更新了相关索引（README.md）
- [ ] 添加了创建和更新日期
- [ ] 拼写和语法检查通过
### PR 审查
提交文档 PR 时：
1. **标题格式**: `docs(category): 简短描述`
```bash
docs(testing): 添加 Playwright E2E 测试指南
docs(architecture): 更新组件索引文档
```
2. **描述内容**:
- 新增或修改的内容
- 影响的文档
- 相关的 Issue 或 PR
3. **审查重点**:
- 文档分类是否正确
- 内容是否准确完整
- 链接是否有效
- 格式是否统一
### 发布检查
合并 PR 前确认：
- [ ] 至少一人审查通过
- [ ] CI 检查通过（如果有）
- [ ] 文档索引已更新
- [ ] 相关文档已同步更新
---
## 特殊文档规范
### CHANGELOG.md
遵循 [Keep a Changelog](https://keepachangelog.com/) 格式：
```markdown
# 更新日志
## [Unreleased]
### Added
- 新功能 1
- 新功能 2
### Changed
- 变更 1
### Fixed
- 修复 1
## [1.2.0] - 2026-01-28
### Added
- 新功能
```
### README.md
- 简洁明了，突出重点
- 包含项目简介和快速开始
- 提供清晰的文档导航
### API 文档
- 使用表格展示参数
- 提供代码示例
- 说明返回值和错误码
---
## 💡 最佳实践
### 1. 保持简洁
- ❌ 避免冗长描述
- ✅ 用代码示例说话
- ✅ 适当使用图表和截图
### 2. 及时更新
- 代码变更时同步更新文档
- 标注"最后更新"日期
- 过时文档及时归档
### 3. 面向读者
- 明确文档的目标读者
- 提供不同深度的内容（入门/进阶）
- 使用场景驱动的示例
### 4. 可维护性
- 避免重复内容
- 使用引用和链接
- 保持统一的格式
### 5. 可搜索性
- 使用关键词
- 提供清晰的目录
- 添加元数据标签
---
## 🔗 相关资源
- [Markdown 指南](https://www.markdownguide.org/)
- [文档驱动开发](https://www.writethedocs.org/)
- [技术文档最佳实践](https://documentation.divio.com/)
---
**最后更新**: 2026-01-28
# 📚 项目文档导航
> 本文档提供项目所有文档的分类索引，帮助快速查找所需信息。
## 📑 文档分类
### 🏗️ 架构设计
| 文档 | 说明 | 路径 |
| ------------------------------------------ | ------------------------------ | ------------------------------ |
| [架构文档](./architecture/ARCHITECTURE.md) | 应用架构、工程化配置、目录结构 | `architecture/ARCHITECTURE.md` |
| [组件索引](./architecture/COMPONENTS.md) | 22个组件目录的分类索引 | `architecture/COMPONENTS.md` |
### 💻 开发配置
| 文档 | 说明 | 路径 |
| --------------------------------------------------------- | ------------------------ | ---------------------------------- |
| [ESLint + Prettier](./development/ESLINT_PRETTIER.md) | 代码规范与自动格式化配置 | `development/ESLINT_PRETTIER.md` |
| [Husky + lint-staged](./development/HUSKY_LINT_STAGED.md) | Git Hooks 自动化检查配置 | `development/HUSKY_LINT_STAGED.md` |
| [开发工作流](./development/WORKFLOW.md) | 团队开发流程与规范 | `development/WORKFLOW.md` |
### 🧪 测试文档
| 文档 | 说明 | 路径 |
| ---------------------------------------------- | ------------------------ | ---------------------------- |
| [Playwright 指南](./testing/PLAYWRIGHT.md) | E2E 测试框架完整指南 | `testing/PLAYWRIGHT.md` |
| [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md) | 测试登录认证流程 | `testing/E2E_AUTH_GUIDE.md` |
| [E2E 代理配置](./testing/E2E_PROXY_SETUP.md) | Vite 反向代理配置说明 | `testing/E2E_PROXY_SETUP.md` |
| [E2E 测试服务器](./testing/E2E_TEST_SERVER.md) | 测试环境配置与服务器信息 | `testing/E2E_TEST_SERVER.md` |
### 🛠️ 工具指南
| 文档 | 说明 | 路径 |
| ---------------------------------------- | ------------------------ | ----------------------- |
| [Claude Skills](./tools/SKILLS_GUIDE.md) | Claude Code 技能完全指南 | `tools/SKILLS_GUIDE.md` |
### 📝 变更记录
| 文档 | 说明 | 路径 |
| -------------------------- | -------------------------- | -------------- |
| [更新日志](./CHANGELOG.md) | 功能更新历史（按时间倒序） | `CHANGELOG.md` |
### 📋 任务管理
| 目录 | 说明 | 路径 |
| --------------------------- | -------------------- | ------------- |
| [已完成任务](./tasks/done/) | 已完成的功能记录 | `tasks/done/` |
| [开发计划](./tasks/plan/) | 进行中和计划中的功能 | `tasks/plan/` |
| [待办事项](./tasks/TODO/) | 待办功能列表 | `tasks/TODO/` |
---
## 🚀 快速查找
### 按场景查找
**我要...**
- 🆕 **新项目上手** → [架构文档](./architecture/ARCHITECTURE.md)
- 🔧 **配置开发环境** → [ESLint + Prettier](./development/ESLINT_PRETTIER.md)
- 🧪 **编写 E2E 测试** → [Playwright 指南](./testing/PLAYWRIGHT.md)
- 🔐 **测试登录功能** → [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md)
- 📝 **了解更新内容** → [更新日志](./CHANGELOG.md)
- 🛠️ **使用 Claude Skills** → [Claude Skills 指南](./tools/SKILLS_GUIDE.md)
### 按角色查找
**前端开发者**
1. [架构文档](./architecture/ARCHITECTURE.md) - 了解项目结构
2. [组件索引](./architecture/COMPONENTS.md) - 查找可复用组件
3. [ESLint + Prettier](./development/ESLINT_PRETTIER.md) - 配置代码规范
4. [开发工作流](./development/WORKFLOW.md) - 遵循团队流程
**测试工程师**
1. [Playwright 指南](./testing/PLAYWRIGHT.md) - E2E 测试框架
2. [E2E 认证指南](./testing/E2E_AUTH_GUIDE.md) - 测试认证流程
3. [E2E 代理配置](./testing/E2E_PROXY_SETUP.md) - 配置测试环境
4. [E2E 测试服务器](./testing/E2E_TEST_SERVER.md) - 测试服务器信息
**新成员**
1. [架构文档](./architecture/ARCHITECTURE.md) - 了解整体架构
2. [开发工作流](./development/WORKFLOW.md) - 学习开发流程
3. [组件索引](./architecture/COMPONENTS.md) - 熟悉现有组件
4. [更新日志](./CHANGELOG.md) - 了解最近更新
---
## 📖 文档编写规范
### 新增文档时，请遵循以下规则：
#### 1. 文件命名
- ✅ 使用大写字母和下划线：`ARCHITECTURE.md`
- ✅ 使用英文命名，文件名清晰描述内容
- ❌ 避免中文文件名（`工作流.md` → `WORKFLOW.md`）
- ❌ 避免空格和特殊字符
#### 2. 文档分类
根据文档内容，放入对应目录：
```
docs/
├── architecture/ # 架构设计类文档
├── development/ # 开发配置类文档
├── testing/ # 测试相关文档
├── tools/ # 工具使用指南
└── tasks/ # 任务管理（done/plan/TODO）
```
#### 3. 更新索引
新增文档后，**必须**更新本 `README.md`：
1. 在对应分类下添加文档链接
2. 更新"快速查找"部分（如果适用）
3. 遵循现有格式和风格
#### 4. 文档结构
每个文档应包含：
```markdown
# 文档标题
> 简短描述（1-2句话）
## 目录
- [背景](#背景)
- [安装](#安装)
- [使用](#使用)
- [API](#api)
- [常见问题](#常见问题)
## 背景
说明文档的背景和目标
## 安装
step-by-step 安装指南
## 使用
详细使用说明
## 常见问题
Q&A 格式
```
---
## 🔍 搜索技巧
### 在文档中搜索
```bash
# 在所有文档中搜索关键词
cd docs
grep -r "关键词" .
# 只搜索 .md 文件
grep -r "关键词" . --include="*.md"
# 搜索特定目录
grep -r "关键词" ./testing/
```
### VS Code 搜索
1. `Ctrl/Cmd + Shift + F` - 全局搜索
2. 在搜索框中输入关键词
3. 限制搜索范围：`docs/**/*.md`
---
## 📊 文档统计
| 分类 | 文档数量 | 最后更新 |
| -------- | -------- | -------- |
| 架构设计 | 2 | - |
| 开发配置 | 3 | - |
| 测试文档 | 4 | - |
| 工具指南 | 1 | - |
| 任务管理 | 3 | - |
| **总计** | **13** | - |
---
## 🤝 贡献指南
发现文档问题？欢迎改进：
1. **修正错误**：直接修改文档并提交 PR
2. **补充内容**：在对应分类下新增文档
3. **优化索引**：改进本 `README.md` 的导航结构
**注意事项**：
- 保持客观、准确
- 提供示例和代码
- 更新日期和版本信息
- 遵循现有文档风格
---
## 🔗 相关资源
- [项目主 README](../README.md)
- [CLAUDE.md](../CLAUDE.md) - 项目架构与开发指南
- [代码规范](../.claude/rules/coding-style.md) - 全局编码规范
- [Vue 最佳实践](../.claude/rules/vue-patterns.md) - Vue 3 开发指南
---
**最后更新**: 2026-01-28
**维护者**: 开发团队
# 🎯 Claude Code Skills 完全指南
> 本文档收录了系统中所有可用的 Skills（技能），按功能类别整理，帮助您快速了解和使用这些强大的开发辅助工具。
---
## 📑 目录
- [通用开发技能](#-通用开发技能)
- [文档处理技能](#-文档处理技能)
- [设计与品牌](#-设计与品牌)
- [Claude Code 工作流](#-claude-code-工作流)
- [代码审查与分析](#-代码审查与分析)
- [架构与模式](#-架构与模式)
- [记忆与学习](#-记忆与学习)
- [Git 与工作流](#-git-与工作流)
- [项目相关](#-项目相关)
---
## 🛠️ 通用开发技能
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `agent-browser` | 浏览器自动化 | 浏览器交互、Web 测试、表单填充、截图和数据提取 |
| `algorithmic-art` | 算法艺术创作 | 使用 p5.js 创建基于种子随机性和交互式参数探索的算法艺术 |
| `frontend-design` | 前端界面设计 | 创建高质量、生产级别的用户界面和交互式 Web 组件 |
| `canvas-design` | Canvas 视觉设计 | 创建 .png 和 .pdf 格式的精美视觉艺术作品 |
| `find-skills` | 技能发现器 | 帮助您发现和安装新的 agent skills |
| `skill-creator` | 技能创建器 | 创建新的 skills 或更新现有 skills 的指南 |
---
## 📝 文档处理技能
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `docx` | Word 文档处理 | Word 文档的创建、编辑、分析，支持修订跟踪、注释和格式保留 |
| `xlsx` | Excel 电子表格 | Excel 表格的创建、编辑、分析，支持公式、格式化和数据可视化 |
| `pptx` | PowerPoint 演示文稿 | PowerPoint 的创建、编辑和分析，用于演示文稿制作 |
| `pdf` | PDF 操作工具包 | PDF 文本和表格提取、创建新 PDF、合并/分割文档、表单处理 |
| `doc-coauthoring` | 文档协同工作流 | 引导用户进行结构化的文档协同创作流程 |
| `documentation-lookup` | 文档查询助手 | 查询库、框架、API 参考文档和代码示例 |
---
## 🎨 设计与品牌
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `brand-guidelines` | 品牌规范应用 | 应用 Anthropic 官方品牌颜色、排版到各种设计资产 |
| `theme-factory` | 主题工厂 | 使用 10 种预设主题样式化幻灯片、文档、HTML 页面等 |
| `web-artifacts-builder` | Web 构建工具套件 | 创建多组件 HTML artifacts，使用 React、Tailwind CSS 等现代技术 |
| `slack-gif-creator` | Slack GIF 创作 | 创建针对 Slack 优化的动画 GIF，包含约束验证和动画概念 |
---
## 🚀 Claude Code 工作流
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `everything-claude-code:plan` | 实施计划 | 重述需求、评估风险、创建分步实施计划（等待用户确认） |
| `everything-claude-code:tdd` | 测试驱动开发 | 强制执行测试优先编写工作流，确保 80%+ 测试覆盖率 |
| `everything-claude-code:e2e` | 端到端测试 | 使用 Playwright 生成和运行 E2E 测试，管理测试旅程 |
| `superpowers:brainstorming` | 头脑风暴 | 在任何创意工作（创建功能、组件、添加功能）之前使用 |
| `superpowers:systematic-debugging` | 系统化调试 | 遇到 bug、测试失败或意外行为时的调试流程 |
| `superpowers:verification-before-completion` | 完成前验证 | 在声称工作完成之前，运行验证命令和检查 |
| `superpowers:executing-plans` | 执行计划 | 在单独的会话中执行书面实施计划，带审查检查点 |
| `superpowers:writing-plans` | 编写计划 | 当有规范或需求时，在编写代码之前规划实施步骤 |
---
## 🔍 代码审查与分析
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `superpowers:requesting-code-review` | 请求代码审查 | 完成任务、实现主要功能或合并前验证工作质量 |
| `superpowers:receiving-code-review` | 接收代码审查 | 在实现建议之前接收代码审查反馈 |
| `everything-claude-code:security-review` | 安全审查 | 添加认证、处理用户输入、API 端点或敏感数据时的安全检测 |
| `everything-claude-code:database-reviewer` | 数据库审查 | PostgreSQL 数据库查询优化、模式设计、安全和性能专家 |
---
## 📚 架构与模式
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `everything-claude-code:backend-patterns` | 后端架构模式 | Node.js、Express、Next.js API 路由的后端架构和 API 设计模式 |
| `everything-claude-code:frontend-patterns` | 前端开发模式 | React、Next.js、状态管理、性能优化和 UI 最佳实践 |
| `everything-claude-code:coding-standards` | 编码标准 | TypeScript、JavaScript、React 和 Node.js 的通用编码标准和最佳实践 |
| `everything-claude-code:postgres-patterns` | PostgreSQL 模式 | 查询优化、模式设计、索引和安全性（基于 Supabase 最佳实践） |
| `everything-claude-code:clickhouse-io` | ClickHouse 模式 | ClickHouse 数据库模式、查询优化、分析和数据工程最佳实践 |
---
## 🧠 记忆与学习
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `episodic-memory:search-conversations` | 搜索历史对话 | 跨会话语义或文本搜索，恢复之前的决策、解决方案和经验教训 |
| `everything-claude-code:continuous-learning` | 持续学习 | 从 Claude Code 会话中提取可复用模式并保存为 skills |
| `ship-learn-next` | 学习转化计划 | 将学习内容（如 YouTube 字幕、文章、教程）转化为可执行的实施计划 |
---
## 🛠️ Git 与工作流
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `superpowers:using-git-worktrees` | Git 工作树 | 开始需要与当前工作空间隔离的功能工作时创建隔离的 git 工作树 |
| `superpowers:finishing-a-development-branch` | 完成开发分支 | 实现完成、所有测试通过，决定如何集成工作时的完成指南 |
| `superpowers:dispatching-parallel-agents` | 并行代理调度 | 面对 2+ 个独立任务且无共享状态或顺序依赖时使用 |
| `superpowers:subagent-driven-development` | 子代理驱动开发 | 使用独立任务在当前会话中执行实施计划 |
---
## 📊 项目相关
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `project-overview` | 项目概览 | 完整的项目架构和结构指南，探索代码库和理解项目组织 |
| `glm-plan-usage:usage-query` | 使用量查询 | 查询 GLM Coding Plan 当前账户的使用信息 |
| `glm-plan-bug:case-feedback` | 问题反馈 | 提交案例反馈以报告问题或建议 |
---
## 🎖️ 专业领域技能
### 代码质量
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `everything-claude-code:code-reviewer` | 代码审查专家 | 主动审查代码质量、安全性和可维护性 |
| `everything-claude-code:refactor-cleaner` | 重构清理 | 死代码清理和整合，运行分析工具安全移除未使用代码 |
| `everything-claude-code:build-error-resolver` | 构建错误解决 | 构建和 TypeScript 错误解决专家 |
| `everything-claude-code:tdd-guide` | TDD 指南 | 测试驱动开发专家，强制执行测试优先编写方法 |
### 开发流程
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `everything-claude-code:planner` | 规划专家 | 复杂功能和重构的专家规划 |
| `everything-claude-code:architect` | 软件架构师 | 系统设计、可扩展性和技术决策专家 |
| `everything-claude-code:doc-updater` | 文档更新器 | 更新 codemaps 和文档的专家 |
| `everything-claude-code:strategic-compact` | 策略性压缩 | 在逻辑阶段保留上下文的策略性压缩建议 |
| `everything-claude-code:iterative-retrieval` | 迭代检索 | 逐步改进上下文检索的模式 |
### 测试与评估
| Skill | 名称 | 用途说明 |
|:------|:-----|:---------|
| `everything-claude-code:e2e-runner` | E2E 测试运行器 | 使用 Playwright 生成、维护和运行 E2E 测试 |
| `everything-claude-code:eval-harness` | 评估框架 | Claude Code 会话的正式评估框架 |
---
## 💡 使用技巧
### 调用方式
1. **命令方式**：在对话中输入 `/skill-name`
- 例如：`/plan`、`/review`、`/tdd`
2. **自动触发**：Claude 会根据任务类型自动调用相关 skills
3. **手动指定**：明确要求使用某个 skill
### 优先级顺序
当多个 skills 可能适用时，按以下顺序使用：
1. **流程技能优先**（brainstorming、debugging）- 决定如何处理任务
2. **实施技能其次**（frontend-design、mcp-builder）- 指导执行
**示例**：
- "让我们构建 X" → brainstorming → frontend-design
- "修复这个 bug" → debugging → domain-specific skills
### 技能类型
- **刚性**（TDD、debugging）：严格遵循，不可偏离
- **灵活**（patterns）：根据上下文调整原则
---
## 📖 快速参考
### 开发新功能时的典型流程
```
1. brainstorming → 创意和方案探索
2. plan → 制定实施计划
3. tdd → 编写测试
4. implementing → 编写代码
5. code-review → 代码审查
6. verification → 完成前验证
```
### 修复 Bug 时的典型流程
```
1. systematic-debugging → 问题诊断
2. implementing → 修复代码
3. testing → 验证修复
4. verification → 确认完成
```
### 代码审查流程
```
1. requesting-code-review → 提交审查请求
2. receiving-code-review → 接收反馈
3. implementing → 应用修改
```
---
## 🔗 相关文档
- [CLAUDE.md](../CLAUDE.md) - 项目总体架构与开发指南
- [VUE_CODE_STYLE_GUIDE.md](../VUE_CODE_STYLE_GUIDE.md) - Vue 代码风格规范
- [CHANGELOG.md](../CHANGELOG.md) - 变更日志
---
## 📝 更新日志
- **2025-01-27**: 初始版本，收录所有可用 Skills
---
*本文档由 Claude Code 自动生成和维护*
# /src/components 组件目录索引
## 目录划分
| 目录 | 代表组件 | 说明 |
| ------------ | ------------------------------------------------------------------------- | ------------------------------------------- |
| activity/ | ActivityCard.vue、ActivityApplyHistoryPopup.vue | 活动卡片、报名/历史相关弹窗 |
| calendar/ | CollapsibleCalendar.vue、TaskCalendar.vue | 日历与任务日历组件 |
| checkin/ | CheckInDialog.vue、CheckInList.vue、CheckinCard.vue、UploadVideoPopup.vue | 打卡/作业相关组件（弹窗、列表、卡片、上传） |
| common/ | ConfirmDialog.vue、GradientHeader.vue、SearchBar.vue、UserAgreement.vue | 通用基础组件（确认、头部、搜索、协议） |
| count/ | AddTargetDialog.vue、CheckinTargetList.vue、postCountModel.vue | 计数型打卡相关组件 |
| courses/ | CourseCard.vue、CourseList.vue、LiveStreamCard.vue、ReviewPopup.vue | 课程展示与列表、直播卡片、评价弹窗等 |
| effects/ | FrostedGlass.vue、StarryBackground.vue | 视觉效果组件 |
| homePage/ | FeaturedCoursesSection.vue、LatestActivitiesSection.vue | 首页区块组件（精选/活动/推荐等） |
| infoEntry/ | formPage.vue | 信息录入相关组件 |
| layout/ | AppLayout.vue、BottomNav.vue | 页面布局与底部导航 |
| media/ | AudioPlayer.vue、VideoPlayer.vue、PdfPreview.vue、OfficeViewer.vue | 音视频播放器与文档预览 |
| payment/ | WechatPayment.vue | 微信支付相关组件 |
| poster/ | RecallPoster.vue、SharePoster.vue | 海报生成与分享相关组件 |
| studyDetail/ | StudyCatalogPopup.vue、StudyCommentsSection.vue、StudyMaterialsPopup.vue | 学习详情页的弹窗与评论区 |
| teacher/ | TaskFilter.vue、TaskCascaderFilter.vue | 教师端筛选与任务相关组件 |
## 备注
- 布局目录已归一：统一使用 [/src/components/layout](file:///Users/huyirui/program/itomix/git/mlaj/src/components/layout)，已移除 /src/layouts
# 📋 任务管理
此目录包含项目任务管理的相关文档。
## 📁 目录结构
```
tasks/
├── done/ # 已完成的任务
├── plan/ # 进行中和计划中的任务
└── TODO/ # 待办事项列表
```
## 📂 各目录说明
### ✅ done/ - 已完成任务
**用途**: 存放已完成的功能和任务的详细记录
**包含内容**:
- 功能实现记录
- 技术方案文档
- 上线总结报告
**示例**:
- 欢迎页布局优化
- 打卡草稿缓存功能
- 视频播放器优化
**如何添加**:
完成任务后，将相关文档移动到 `done/` 目录，并更新此索引。
---
### 🔄 plan/ - 开发计划
**用途**: 存放正在进行或计划中的功能开发文档
**包含内容**:
- 功能设计文档
- 技术方案讨论
- 开发进度跟踪
- API 设计文档
**示例**:
- 新功能设计方案
- 性能优化计划
- 重构方案
**如何添加**:
1. 在 `plan/` 下创建文档
2. 按功能或时间组织
3. 完成后移动到 `done/`
---
### 📝 TODO/ - 待办事项
**用途**: 待办功能、Bug 修复、改进建议的清单
**包含内容**:
- 功能需求列表
- Bug 修复清单
- 优化建议
- 技术债务
**如何使用**:
1. 新增待办项时添加到对应分类
2. 开始开发时移到 `plan/`
3. 完成后移到 `done/`
---
## 🔄 任务生命周期
```
TODO → plan → done
(待办) (计划) (完成)
```
### 详细流程
1. **新建任务** → 添加到 `TODO/`
2. **开始规划** → 移动到 `plan/`，创建设计文档
3. **开发完成** → 移动到 `done/`，记录实现细节
---
## 📝 文档命名规范
### 格式
```
[日期]_[类型]_[简短描述].md
```
### 示例
- `20260128_feature_打卡草稿缓存.md`
- `20260128_bugfix_视频播放器修复.md`
- `20260128_optimize_首页加载优化.md`
- `20260128_refactor_组件拆分.md`
### 类型标识
| 类型 | 说明 |
| ---------- | -------- |
| `feature` | 新功能 |
| `bugfix` | Bug 修复 |
| `optimize` | 性能优化 |
| `refactor` | 代码重构 |
| `docs` | 文档更新 |
| `config` | 配置变更 |
---
## 🔍 快速查找
### 查看所有已完成的任务
```bash
ls -1 done/
```
### 查看所有计划中的任务
```bash
ls -1 plan/
```
### 查看所有待办事项
```bash
ls -1 TODO/
```
### 搜索特定任务
```bash
# 搜索关键词
find . -name "*.md" | xargs grep -l "关键词"
```
---
## 📊 任务统计
| 状态 | 数量 | 说明 |
| --------- | ---- | --------------- |
| ✅ 已完成 | - | 见 `done/` 目录 |
| 🔄 进行中 | - | 见 `plan/` 目录 |
| 📝 待办 | - | 见 `TODO/` 目录 |
---
## 💡 使用建议
### 1. 定期清理
- **每月**: 检查 `TODO/`，删除过时任务
- **每周**: 更新 `plan/` 中的任务进度
- **每季度**: 归档 `done/` 中的旧任务
### 2. 保持更新
- 完成任务后立即移动文档
- 及时更新任务状态
- 记录关键决策和教训
### 3. 团队协作
- 使用统一的文档格式
- 明确任务负责人
- 设置合理的截止日期
---
## 🔗 相关资源
- [项目文档导航](../README.md)
- [更新日志](../CHANGELOG.md)
- [开发工作流](../development/WORKFLOW.md)
---
**最后更新**: 2026-01-28
新功能开发list(在.env加上配置开关控制下面设计到的功能点, 比如是否开启置顶功能,开启点评打卡, 开启打卡海报,开启点评列表):
入口页IndexCheckInPage涉及功能
- CheckinCard组件 <#footer-right> 3个点的缩略显示, 点击后从底部弹出vant的ActionSheet组件, 面板有置顶和点评两个选项.
1. 置顶的功能, 使用图标back-top, 点击图标的时候弹出确认弹窗, 确认后调用接口置顶帖子.
2. 点评打卡作业的功能, 使用图标comment, 点击图标的时候弹出确认弹窗, 确认后调用接口点评打卡作业. 评论弹框做成一个单独的组件以后扩展.
3. 海报功能, 使用图标share, 可以参考SharePoster组件的实现, 新增一个组件打卡海报, 这个组件最大的不同就是可能生成的图片是一张长图, 如果超过屏幕高度, 用户可以滑动查看. 现在内容和字段还不确定, 等确定了再实现可以先规划.
- 显示点评列表功能, 在CheckinCard组件里面, 需要新增一个组件专门显示用户点评打卡的列表. 类似于朋友圈下面的评论列表, 放在CheckinCard组件的下面.
入口页IndexCheckInPage涉及功能
- CheckinCard组件 <#footer-right> 3个点的缩略显示, 点击后从底部弹出vant的ActionSheet组件, 面板有置顶和点评两个选项.
1. 置顶的功能, 使用图标back-top, 点击图标的时候弹出确认弹窗, 确认后调用接口置顶帖子.
2. 点评打卡作业的功能, 使用图标comment, 点击图标的时候弹出确认弹窗, 确认后调用接口点评打卡作业. 评论弹框做成一个单独的组件以后扩展.
3. 海报功能, 使用图标share, 可以参考SharePoster组件的实现, 新增一个组件打卡海报, 这个组件最大的不同就是可能生成的图片是一张长图, 如果超过屏幕高度, 用户可以滑动查看. 现在内容和字段还不确定, 等确定了再实现可以先规划.
- 显示点评列表功能, 在CheckinCard组件里面, 需要新增一个组件专门显示用户点评打卡的列表. 类似于朋友圈下面的评论列表, 放在CheckinCard组件的下面.
......
......@@ -47,6 +47,7 @@ pnpm run upload:qiniu video/welcome-bg.mp4 mlaj/video/welcome-bg.mp4
```
**文件信息:**
- 大小: 17.57MB (18420585 字节)
- Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH
- MIME: video/mp4
......@@ -65,6 +66,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
## 📋 开发进度
### ✅ 已完成
- [x] 背景视频文件准备 (`welcome-bg.mp4`)
- [x] 视频上传到七牛云 ✅ (17.57MB, Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH)
- [x] 功能图标上传到七牛云 ✅ (33.53KB, Hash: FsqvctdBVJvXoQkAAEEhxuIRqX6h)
......@@ -83,9 +85,11 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
- [x] 访问逻辑优化 ✅
### ⏳ 待开发
- 无
### ❌ 待确认
- 无
---
......@@ -114,6 +118,7 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
### 调试欢迎页
**重置欢迎页标志:**
```bash
# URL 参数方式
http://localhost:5173/?reset_welcome=true
......@@ -124,6 +129,7 @@ location.reload()
```
**直接访问欢迎页:**
```javascript
window.showWelcome()
```
......@@ -133,29 +139,34 @@ window.showWelcome()
## 🎯 核心特性
### 视频背景
- ✅ 循环播放星空宇宙主题视频
- ✅ 移动端和 PC 端自适应
- ✅ 自动生成封面图 (七牛云视频处理)
- ✅ 降级方案 (视频加载失败时使用静态图)
### 首次访问检测
- ✅ localStorage 标志位
- ✅ 路由守卫自动拦截
- ✅ 调试工具支持
### 功能入口
- ✅ 3个核心功能入口已确定
- ✅ 持续循环的上下浮动动效
- ✅ 水平排列布局
- ✅ 配置化入口列表
**功能入口详情:**
1. **课程中心** (`/courses`) - 探索精选课程
2. **活动中心** (`/activity`) - 精彩活动不容错过
- ⚠️ **注意**: 当前为外链跳转，跳转到 `https://wxm.behalo.cc/pages/activity/activity`
3. **个人中心** (`/profile`) - 管理您的账户
**布局设计:**
- 📐 **水平布局**: 3个图标水平排列成一行
- 📍 **位置**: 标题在顶部，功能入口在底部
- ✨ **效果**: 星空宇宙主题视频背景，浮动动画效果
......@@ -163,6 +174,7 @@ window.showWelcome()
- 🏷️ **标题**: 复用召回页标题图片资源 ✅
**图标资源:**
- URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png`
- 大小: 33.53KB
- 上传状态: ✅ 已上传到七牛云
......@@ -174,6 +186,7 @@ window.showWelcome()
### Q: 视频上传失败?
**A:** 检查是否需要使用代理:
```bash
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
### Q: 封面图如何生成?
**A:** 自动从视频中提取第一帧:
```javascript
const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
```
......@@ -188,6 +202,7 @@ const posterUrl = `${videoUrl}?vframe/jpg/offset/0.001`
### Q: 如何测试欢迎页?
**A:** 重置标志后刷新页面:
```javascript
window.resetWelcomeFlag()
location.reload()
......@@ -195,4 +210,4 @@ location.reload()
---
*最后更新: 2026-01-28*
_最后更新: 2026-01-28_
......
......@@ -5,6 +5,7 @@
为 mlaj 平台设计一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。
**核心需求:**
- 视频背景循环播放（星空宇宙主题）
- 悬浮的功能入口图标 + 文字介绍
- 持续循环的缩放位移动效
......@@ -17,6 +18,7 @@
### 问题 1: 欢迎页的主要目标？
**选项:**
- 品牌展示 - 营造高端/科技感的品牌印象
- 功能引导 - 清晰展示核心功能入口
- 新手引导 - 教育用户如何使用平台
......@@ -29,11 +31,13 @@
### 问题 2: 视频背景的实现方式？
**选项:**
- 原生 `<video>` 标签
- 简化版组件（参考 StarryBackground）✅
- 页面内直接实现
**决策:** 选择**简化版组件**，理由：
- 组件化便于复用和维护
- 移除 Canvas 星星特效，保留视频播放逻辑
- 支持 Props 配置，灵活性高
......@@ -43,16 +47,19 @@
### 问题 3: 如何判断用户是否首次进入？
**选项:**
- localStorage 标志 ✅
- 后端接口判断
- URL 参数控制
**决策:** 选择 **localStorage 标志**，理由：
- 简单高效，无需额外请求
- 符合前端存储特性
- 开发调试方便（可手动清除）
**权衡:**
- 缺点: 清除缓存后会再次显示
- 解决方案: 文档说明这是预期行为，未来可升级为后端接口
......@@ -61,11 +68,13 @@
### 问题 4: 图标和文字的动效风格？
**选项:**
- 轻量动效（3秒入场 + 悬停交互）
- 持续循环（呼吸/缩放动画）✅
- 一次性入场
**决策:** 选择**持续循环**，理由：
- 符合"星空宇宙"的神秘感主题
- 视觉冲击力更强，吸引用户注意力
- 不同入口设置不同延迟，形成错落感
......@@ -77,21 +86,25 @@
### 整体架构方案
**方案 A: 单页面组件**
```
WelcomePage.vue
├── 直接写 video 标签
└── 内联功能入口
```
- 优点: 简单直接
- 缺点: 代码耦合，难以复用
**方案 B: 组件化设计 ✅**
```
WelcomePage.vue
├── VideoBackground.vue (通用组件)
└── WelcomeContent.vue
└── WelcomeEntryItem.vue
```
- 优点: 组件复用、职责清晰、易维护
- 缺点: 文件稍多
......@@ -118,6 +131,7 @@ WelcomePage (视图容器)
### 首次访问控制逻辑
**路由守卫方案:**
```javascript
// src/router/guards.js
const HAS_VISITED_WELCOME = 'has_visited_welcome'
......@@ -129,12 +143,11 @@ router.beforeEach((to, from, next) => {
}
// 首次访问检测
if (to.path !== '/welcome' &&
!localStorage.getItem(HAS_VISITED_WELCOME)) {
if (to.path !== '/welcome' && !localStorage.getItem(HAS_VISITED_WELCOME)) {
localStorage.setItem(HAS_VISITED_WELCOME, 'true')
return next({
path: '/welcome',
query: { redirect: to.fullPath }
query: { redirect: to.fullPath },
})
}
......@@ -143,6 +156,7 @@ router.beforeEach((to, from, next) => {
```
**调试功能:**
- URL 参数 `?reset_welcome=true` 重置标志位
- 控制台 `window.resetWelcomeFlag()` 快捷方法
......@@ -155,12 +169,14 @@ router.beforeEach((to, from, next) => {
**位置:** `src/components/effects/VideoBackground.vue`
**核心特性:**
- 简化版设计，移除 Canvas 特效
- 原生 `<video>` 标签实现
- 移动端和 PC 端自适应
- 可配置视频源、播放速度、覆盖模式
**Props 设计:**
```javascript
{
videoSrc: { type: String, required: true },
......@@ -173,6 +189,7 @@ router.beforeEach((to, from, next) => {
```
**关键实现点:**
- 使用 `object-fit: cover` 确保全屏覆盖不变形
- 添加 `playsinline` 支持 iOS 内联播放
- 监听 `canplay` 事件移除 loading 状态
......@@ -187,6 +204,7 @@ router.beforeEach((to, from, next) => {
**核心布局:** 功能入口网格（2-3列）
**入口项动效设计（持续循环）:**
- CSS `@keyframes` 实现呼吸缩放效果
- 动画参数: `scale(1.0) → scale(1.08) → scale(1.0)`
- 周期: 2-3秒
......@@ -194,9 +212,11 @@ router.beforeEach((to, from, next) => {
- Hover 时加速或高亮
**CSS 动画示例:**
```less
@keyframes breathe {
0%, 100% {
0%,
100% {
transform: scale(1);
opacity: 0.9;
}
......@@ -224,11 +244,13 @@ router.beforeEach((to, from, next) => {
### 现有方案分析
**从 deploy.sh 提取的关键逻辑:**
- 使用 `qshell qupload` 命令批量上传
- 依赖配置文件 `~/.qshell/stdj_upload.conf`
- 需要预先安装 qshell 工具
**发现的问题:**
- 用户提到"需要挂代理才能访问"
- 可能是七牛云 API 域名在某些网络环境下被限制
- 需要设置 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量
......@@ -238,11 +260,13 @@ router.beforeEach((to, from, next) => {
### 通用化设计探索
**原始方案问题:**
- 硬编码了欢迎页特定路径（`/docs/plan/26.1.28-欢迎页开发计划/`）
- 配置文件使用项目外的 `~/.qshell/stdj_upload.conf`
- 无法作为通用工具复用
**改进方案:**
1. **项目内配置**
- 配置文件位置: `scripts/qiniu/configs/`
- 账户信息: `scripts/qiniu/account.json`（不入库）
......@@ -263,11 +287,13 @@ router.beforeEach((to, from, next) => {
### 使用场景设计
**场景 1: 上传欢迎页视频**
```bash
./scripts/upload-to-qiniu.sh video/bg.mp4 mlaj/video/welcome-bg.mp4
```
**场景 2: 批量上传图片**
```bash
# 复制模板并修改配置
cp scripts/qiniu/templates/image-upload.conf.template \
......@@ -278,6 +304,7 @@ cp scripts/qiniu/templates/image-upload.conf.template \
```
**场景 3: 使用代理上传**
```bash
USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
./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" \
### 视频封面图方案探索
**原始方案问题:**
- 需要单独准备和上传封面图片
- 封面图可能与视频内容不匹配
- 增加资源管理成本
......@@ -295,6 +323,7 @@ USE_PROXY=true PROXY_HOST="127.0.0.1:7890" \
**改进方案: 使用七牛云视频处理参数**
**方案选择:**
```javascript
// 自动从视频中提取第一帧作为封面
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
```
**七牛云视频帧处理参数:**
- `vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG
- 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
**高级参数 (可选):**
```javascript
// 指定截取时间点
?vframe/jpg/offset/1
......@@ -321,12 +352,14 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
```
**优势:**
- ✅ 只需上传一个视频文件
- ✅ 封面图与视频内容一致
- ✅ 减少资源管理成本
- ✅ 支持动态调整参数
**实现位置:**
- `VideoBackground.vue` 组件内部使用 computed 自动生成
- 环境变量只需配置 `VITE_WELCOME_VIDEO_URL`
- 移除 `VITE_WELCOME_VIDEO_POSTER` 配置项
......@@ -338,10 +371,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
### 技术风险
**1. 视频播放兼容性**
- iOS Safari 可能禁止自动播放
- 部分浏览器不支持 `playsinline`
**应对:**
```vue
<video
autoplay
......@@ -353,15 +388,18 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
x5-video-player-fullscreen="true"
>
```
- 视频加载失败时使用静态背景图降级
---
**2. 首次访问标志位问题**
- 清除 localStorage 后会再次显示
- 不同浏览器无法共享标志位
**应对:**
- 文档说明这是预期行为
- 提供调试工具方便开发
- 未来可升级为后端接口
......@@ -369,10 +407,12 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
---
**3. 视频加载性能**
- 文件过大导致加载缓慢
- 弱网环境体验差
**应对:**
- 限制文件大小 < 10MB
- 使用七牛云视频处理参数自动生成封面图 (`?vframe/jpg/offset/0.001`)
- 封面图在视频加载前显示，提升用户体验
......@@ -382,9 +422,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
---
**4. 七牛云代理问题**
- 需要挂代理才能访问
**应对:**
- 脚本支持 `USE_PROXY` 环境变量
- 提供诊断脚本测试连通性
- 文档说明代理配置方法
......@@ -394,9 +436,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
### 业务风险
**1. 功能入口待确认**
- 设计稿未确定具体入口
**应对:**
- 先实现框架和核心逻辑
- 入口配置化，后续易于调整
- 使用 Mock 数据开发
......@@ -404,9 +448,11 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
---
**2. 动效性能影响**
- 持续动画可能消耗 CPU/电量
**应对:**
- 使用 CSS 动画而非 JS（性能更好）
- 提供环境变量控制动画开关
- 低端设备检测后降级为静态效果
......@@ -435,14 +481,14 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
## 关键决策总结
| 决策点 | 选择 | 理由 |
|--------|------|------|
| 页面目标 | 混合型 | 品牌展示 + 功能引导 |
| 视频实现 | 简化版组件 | 组件化，便于复用 |
| 首次检测 | localStorage | 简单高效 |
| 动效风格 | 持续循环 | 符合主题，视觉冲击力强 |
| 架构设计 | 组件化 | 职责清晰，易维护 |
| 上传工具 | 通用化 | 支持多种场景复用 |
| 决策点 | 选择 | 理由 |
| ---------- | -------------- | ---------------------- |
| 页面目标 | 混合型 | 品牌展示 + 功能引导 |
| 视频实现 | 简化版组件 | 组件化，便于复用 |
| 首次检测 | localStorage | 简单高效 |
| 动效风格 | 持续循环 | 符合主题，视觉冲击力强 |
| 架构设计 | 组件化 | 职责清晰，易维护 |
| 上传工具 | 通用化 | 支持多种场景复用 |
| 封面图方案 | 七牛云自动生成 | 减少资源管理，内容一致 |
---
......@@ -456,5 +502,5 @@ const posterUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/o
---
*文档创建时间: 2026-01-28*
*最后更新: 2026-01-28*
_文档创建时间: 2026-01-28_
_最后更新: 2026-01-28_
......
......@@ -5,6 +5,7 @@
为 mlaj 平台开发一个欢迎页，作为用户首次进入时的引导页面，展示核心功能入口。
**核心功能:**
- 视频背景循环播放（星空宇宙主题）
- 悬浮的功能入口图标 + 文字介绍
- 持续循环的缩放位移动效
......@@ -59,6 +60,7 @@ mlaj/
#### 步骤 1: 创建配置文件模板
**创建 `scripts/qiniu/templates/video-upload.conf.template`:**
```json
{
"src_dir": "./assets/video",
......@@ -77,6 +79,7 @@ mlaj/
```
**创建 `scripts/qiniu/templates/image-upload.conf.template`:**
```json
{
"src_dir": "./assets/images",
......@@ -109,6 +112,7 @@ scripts/qiniu/configs/
**视频文件:** `docs/plan/26.1.28-欢迎页开发计划/video/welcome-bg.mp4` ✅ 已添加
**建议规格:**
- 分辨率: 1920x1080 (1080p)
- 编码格式: H.264
- 时长: 10-20秒循环视频
......@@ -126,12 +130,14 @@ chmod +x scripts/upload-to-qiniu.sh
```
**上传成功后的 URL:** ✅ 已上传
```
视频: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
封面: https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001
```
**文件信息:**
- 大小: 17.57MB (18420585 字节)
- Hash: lpipKorSMZBEVa-eCevwvcqkB8ZH
- 上传时间: 1.23s
......@@ -139,6 +145,7 @@ chmod +x scripts/upload-to-qiniu.sh
#### 步骤 5: 更新环境变量
**`.env.development`:**
```bash
# 欢迎页功能开关
VITE_WELCOME_PAGE_ENABLED=true
......@@ -149,12 +156,14 @@ VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
```
**`.env.production`:**
```bash
VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4
```
**说明:**
- 只需配置视频 URL，封面图会自动从视频中提取第一帧生成
- 七牛云处理参数: `?vframe/jpg/offset/0.001` 表示从视频第 0.001 秒截取一帧作为 JPG 图片
- 降级方案: 视频加载失败时自动使用该封面图作为静态背景
......@@ -359,6 +368,7 @@ main "$@"
#### 步骤 2: 添加 npm scripts
**`package.json`:**
```json
{
"scripts": {
......@@ -435,33 +445,33 @@ const props = defineProps({
/** 视频源 URL */
videoSrc: {
type: String,
required: true
required: true,
},
/** 封面图 URL (可选，不传则自动从视频生成) */
poster: {
type: String,
default: ''
default: '',
},
/** 是否自动播放 */
autoplay: {
type: Boolean,
default: true
default: true,
},
/** 是否循环播放 */
loop: {
type: Boolean,
default: true
default: true,
},
/** 是否静音 */
muted: {
type: Boolean,
default: true
default: true,
},
/** 视频填充模式 */
objectFit: {
type: String,
default: 'cover' // cover, contain, fill
}
default: 'cover', // cover, contain, fill
},
})
const videoRef = ref(null)
......@@ -497,7 +507,7 @@ const onCanPlay = () => {
}
// 视频加载错误
const onError = (e) => {
const onError = e => {
console.error('[VideoBackground] 视频加载失败:', e)
isLoading.value = false
showFallback.value = true
......@@ -536,7 +546,7 @@ onUnmounted(() => {
defineExpose({
play,
pause
pause,
})
</script>
......@@ -584,12 +594,7 @@ defineExpose({
```vue
<template>
<VideoBackground
:video-src="videoUrl"
autoplay
loop
muted
/>
<VideoBackground :video-src="videoUrl" autoplay loop muted />
</template>
<script setup>
......@@ -615,10 +620,7 @@ const videoUrl = 'https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4'
<template>
<div class="welcome-page">
<!-- 视频背景 -->
<VideoBackground
v-if="videoUrl"
:video-src="videoUrl"
/>
<VideoBackground v-if="videoUrl" :video-src="videoUrl" />
<!-- 内容区域 -->
<WelcomeContent class="welcome-content" />
......@@ -721,7 +723,7 @@ router.beforeEach((to, from, next) => {
markWelcomeVisited()
return next({
path: '/welcome',
query: { redirect: to.fullPath }
query: { redirect: to.fullPath },
})
}
......@@ -772,31 +774,31 @@ export const welcomeEntries = [
id: 'courses',
title: '课程中心',
subtitle: '探索精选课程',
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
route: '/courses',
color: '#4CAF50',
priority: 1
priority: 1,
},
{
id: 'activity',
title: '活动中心',
subtitle: '精彩活动不容错过',
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
route: '/activity',
color: '#FF9800',
priority: 2,
isExternal: true, // 标记为外链跳转
externalUrl: 'https://wxm.behalo.cc/pages/activity/activity?token=&user_id='
isExternal: true, // 标记为外链跳转
externalUrl: 'https://wxm.behalo.cc/pages/activity/activity?token=&user_id=',
},
{
id: 'profile',
title: '个人中心',
subtitle: '管理您的账户',
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
icon: 'https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png', // 七牛云URL
route: '/profile',
color: '#2196F3',
priority: 3
}
priority: 3,
},
]
/**
......@@ -826,12 +828,14 @@ export function getSortedEntries() {
- 学习记录和设置
**布局设计:**
- 🌌 **环绕式布局**: 3个图标像天体行星一样环绕排列
- 📍 **位置**: 页面中下位置
- 🎨 **视觉效果**: 星空宇宙主题，行星轨道感
- 🖼️ **图标**: 统一使用七牛云图片图标 ✅
**图标资源:**
- 文件名: `welcome_btn_1.png`
- 七牛云URL: `https://cdn.ipadbiz.cn/mlaj/images/welcome_btn_1.png` ✅ 已上传
- 文件大小: 33.53KB (34,333 字节)
......@@ -843,11 +847,7 @@ export function getSortedEntries() {
```vue
<template>
<div
class="entry-item"
:style="{ '--index': index }"
@click="handleClick"
>
<div class="entry-item" :style="{ '--index': index }" @click="handleClick">
<!-- 图标 (图片) -->
<div class="entry-icon">
<img :src="entry.icon" :alt="entry.title" />
......@@ -871,12 +871,12 @@ import { useRouter } from 'vue-router'
const props = defineProps({
entry: {
type: Object,
required: true
required: true,
},
index: {
type: Number,
required: true
}
required: true,
},
})
const router = useRouter()
......@@ -903,7 +903,7 @@ const handleClick = () => {
<style scoped lang="less">
.entry-item {
position: absolute; // 绝对定位，形成环绕效果
position: absolute; // 绝对定位，形成环绕效果
display: flex;
flex-direction: column;
align-items: center;
......@@ -951,7 +951,8 @@ const handleClick = () => {
}
@keyframes breathe {
0%, 100% {
0%,
100% {
opacity: 0.9;
}
50% {
......@@ -1035,9 +1036,9 @@ const sortedEntries = computed(() => getSortedEntries())
display: flex;
flex-direction: column;
align-items: center;
justify-content: flex-end; // 内容靠下，位于中下位置
justify-content: flex-end; // 内容靠下，位于中下位置
padding: 2rem;
padding-bottom: 6rem; // 距离底部有足够空间
padding-bottom: 6rem; // 距离底部有足够空间
}
.entries-grid {
......@@ -1124,6 +1125,7 @@ const sortedEntries = computed(() => getSortedEntries())
#### 步骤 1: 更新项目文档
**`CLAUDE.md` 添加说明:**
```markdown
### 欢迎页
......@@ -1141,7 +1143,7 @@ const sortedEntries = computed(() => getSortedEntries())
**文件:** `docs/welcome-page-guide.md`
```markdown
````markdown
# 欢迎页使用指南
## 功能说明
......@@ -1160,6 +1162,7 @@ VITE_WELCOME_PAGE_ENABLED=true
VITE_WELCOME_VIDEO_URL=https://cdn.ipadbiz.cn/mlaj/video/welcome-background.mp4
VITE_WELCOME_VIDEO_POSTER=https://cdn.ipadbiz.cn/mlaj/images/welcome-poster.jpg
```
````
### 功能入口配置
......@@ -1174,8 +1177,8 @@ export const welcomeEntries = [
icon: '📚',
route: '/courses',
color: '#4CAF50',
priority: 1
}
priority: 1,
},
// ... 更多入口
]
```
......@@ -1185,17 +1188,20 @@ export const welcomeEntries = [
### 重置欢迎页标志
**方法 1: URL 参数**
```
http://localhost:5173/?reset_welcome=true
```
**方法 2: 控制台**
```javascript
window.resetWelcomeFlag()
location.reload()
```
### 直接访问欢迎页
```javascript
window.showWelcome()
```
......@@ -1257,6 +1263,7 @@ pnpm dev_upload
```
**关键属性说明:**
- `muted`: 静音播放(移动端自动播放必需)
- `playsinline`: iOS 内联播放
- `webkit-playsinline`: iOS Safari 兼容
......@@ -1278,6 +1285,7 @@ will-change: transform, opacity;
### 3. 七牛云视频处理 - 自动生成封面图
**封面图自动生成:**
```javascript
// VideoBackground 组件内部实现
const posterUrl = computed(() => {
......@@ -1290,11 +1298,13 @@ const posterUrl = computed(() => {
```
**七牛云视频帧处理参数说明:**
- `?vframe/jpg/offset/0.001` - 从视频第 0.001 秒截取一帧作为 JPG 图片
- 完整示例: `https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001`
- 官方文档: https://developer.qiniu.com/dora/1316/video-frame-operation
**高级参数 (可选):**
```javascript
// 指定截取时间点 (第 1 秒)
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/
```
**优势:**
- ✅ 只需上传一个视频文件，无需单独准备封面图
- ✅ 封面图与视频内容一致，不会出现不匹配
- ✅ 减少资源管理成本
......@@ -1329,11 +1340,13 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
```
**降级触发条件:**
1. 视频加载失败 (网络错误、格式不支持)
2. 视频自动播放被阻止 (iOS Safari 政策)
3. 视频解码失败
**降级方案:**
- 使用自动生成的封面图作为静态背景
- 保证用户始终能看到背景内容
......@@ -1376,16 +1389,19 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
## 优先级总结
### 第 1 批 (核心功能) 🔴
- ✅ 第 0 阶段: 准备工作
- ✅ 第 1 阶段: 通用上传工具
- ✅ 第 2 阶段: VideoBackground 组件
- ✅ 第 3 阶段: 路由与首次访问逻辑
### 第 2 批 (功能完善) 🟡
- ⏳ 第 4 阶段: WelcomeContent 组件
- ⏳ 第 5 阶段: 测试与优化
### 第 3 批 (收尾工作) 🟢
- ⏳ 第 6 阶段: 文档与部署
---
......@@ -1402,5 +1418,5 @@ https://cdn.ipadbiz.cn/mlaj/video/welcome-bg.mp4?vframe/jpg/offset/0.001/w/1920/
---
*文档创建时间: 2026-01-28*
*最后更新: 2026-01-28*
_文档创建时间: 2026-01-28_
_最后更新: 2026-01-28_
......
This diff is collapsed. Click to expand it.