文档记录原则
适用范围: 仅 WorldTourCasino 主项目
本文件定义如何将工作内容记录到 docs 文档中心。
核心原则
docs 子目录是一个独立的 Git 仓库，使用 VitePress 构建，托管在 GitHub Pages。
除了快速参考的构建命令和项目架构概览外，所有详细的项目文档都应该集中在 docs 子项目中。
文档分类原则
1. 技术迭代记录
- docs 子项目的技术迭代 → 技术文档
- 主项目的技术迭代 → docs 下的相应分类目录
2. 故障排查和解决方案
目标目录：故障排查
3. 工具和自动化
目标目录：工程-工具
4. 个人工作总结
目标目录：成员（根据 git 用户信息自动匹配）
5. 需求相关
目标目录：需求记录
文档更新原则
重要：优先更新现有文档
总结工作时，必须先查找并更新相关的现有文档，而不是只创建新文档。
避免信息过时
防止多个文档中出现重复或矛盾的信息。
更新流程
- 先搜索相关的现有文档（使用 Grep 或 Glob 工具）
- 更新找到的相关文档内容
- 只有在确实没有相关文档时才创建新文档
示例
更新 VS Code 配置时：
- 应同时更新 vscode/README 等相关配置文档
- 不要只创建新的总结文档
里程碑文档同步规则
主动更新
当任务达到阶段性成果或里程碑时，应主动更新相关项目文档。
不确定时询问
如果不确定是否需要更新文档，应询问用户："这个改动是否需要同步到项目文档？"
里程碑示例
- 解决了长期存在的技术问题
- 完成了新功能或重要优化
- 发现并修复了关键 bug
- 完成了架构调整或重构
更新内容
应包括：
- 问题的根本原因
- 解决方案和实施细节
- 验证结果和影响范围
- 相关配置或代码变更
文档工作流程
1. 查阅文档
优先在 docs 中查找项目相关文档
2. 更新文档
根据上述原则写入相应目录
3. 本地预览
bash
cd docs
npm run dev # 启动本地预览服务器（端口 5173）4. 发布文档
bash
cd docs
npm run sync # 同步文档到 GitHub Pages文档访问地址
- 线上: https://zhaoheng666.github.io/WTC-Docs/
- 本地: 运行
npm run dev后访问端口 5173
重要提醒
- 文档服务器固定使用端口 5173，启动时会自动终止占用进程
- docs 是独立的 Git 仓库，有自己的提交历史
- 文档使用 VitePress，支持 Markdown 和 Vue 组件
- 已配置中文搜索和自动图片优化
最后更新: 2025-10-13 维护者: WorldTourCasino Team