Wiki 系统：最佳实践

核心观点：项目 Wiki 是团队的"第二大脑"，也是 AI 理解项目的桥梁

什么是项目 Wiki？

项目 Wiki 是集中管理项目所有重要信息的文档系统。

与普通文档的区别

文档类型	目的	维护方式	受众
README	快速了解项目	随意、不定期	新手
API 文档	查询接口说明	自动生成	开发者
项目 Wiki	全面了解项目	持续更新	开发者 + AI

为什么 Wiki 特别适合 AI？

结构化：AI 容易理解和搜索
全面性：覆盖项目的各个方面
可导航：AI 可以按需查阅
易维护：Markdown 格式，更新方便

Wiki 应该包含什么内容？

核心章节（必备）

1. 项目概述

markdown

# 项目概述

## 项目简介
- 做什么的
- 解决什么问题
- 目标用户是谁

## 项目目标
- 核心功能
- 业务指标
- 技术指标

2. 技术栈

markdown

# 技术栈

## 前端
- 框架：React 18
- 语言：TypeScript
- 状态管理：Zustand
- 样式：Tailwind CSS

## 后端
- 框架：Nest.js
- 数据库：PostgreSQL
- ORM：Prisma
- 缓存：Redis

## 开发工具
- 包管理：pnpm
- 代码规范：ESLint + Prettier
- 测试：Jest + Testing Library

3. 项目结构

markdown

# 项目结构

## 前端结构

src/ ├── components/ # 通用组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── utils/ # 工具函数 ├── api/ # API 调用 └── types/ # TypeScript 类型


## 后端结构

src/ ├── modules/ # 业务模块 ├── common/ # 通用模块 ├── config/ # 配置 └── database/ # 数据库相关

4. 开发规范

markdown

# 开发规范

## 代码风格
- 命名：camelCase（变量/函数）、PascalCase（组件/类）
- 注释：JSDoc 格式
- 文件名：kebab-case

## Git 提交规范
feat: 新功能
fix: 修复 Bug
docs: 文档更新
refactor: 重构

## 代码审查清单
- [ ] 代码符合规范
- [ ] 有必要的测试
- [ ] 更新了相关文档

5. 业务规则

markdown

# 业务规则

## 用户注册
- 手机号必须唯一
- 密码至少 8 位
- 需要短信验证码

## 订单状态流转
pending → paid → preparing → delivering → completed
                            ↓
                         cancelled

## 优惠券使用
- 每个订单只能用一张
- 不能叠加使用
- 新人券仅限首单

进阶章节（推荐）

6. 数据模型

markdown

# 数据模型

## 核心实体
- User（用户）
- Order（订单）
- Product（商品）
- Coupon（优惠券）

## ER 图
```mermaid
erDiagram
    User ||--o{ Order : places
    Order ||--|{ Product : contains
    User ||--o{ Coupon : owns

字段说明

User 表

id: UUID
phone: VARCHAR(20), UNIQUE
password_hash: VARCHAR(255)
created_at: TIMESTAMP


#### 7. API 文档
```markdown
# API 文档

## 认证
所有 API 需要在 Header 中携带：

Authorization: Bearer


## 用户相关

### POST /api/users/register
注册新用户

**请求体**：
```json
{
  "phone": "13800138000",
  "password": "password123",
  "code": "123456"
}

响应：

json

{
  "code": 0,
  "data": {
    "user_id": "uuid",
    "token": "jwt_token"
  }
}


#### 8. 常见问题
```markdown
# 常见问题

## 开发问题

### Q: 本地启动报错 "Cannot find module"
A: 先运行 `pnpm install`

### Q: 数据库连接失败
A: 检查 `.env` 中的 `DATABASE_URL`

## 业务问题

### Q: 为什么订单创建后不能立即取消？
A: 商家接单后（状态变为 `preparing`）就不能取消了，这是业务规则。

9. 决策记录

markdown

# 决策记录

## 为什么选择 PostgreSQL 而不是 MySQL？

**时间**：2024-03-15

**背景**：
- 需要支持 JSON 字段查询
- 需要更好的并发性能

**选项对比**：
| 数据库 | 优势 | 劣势 |
|-------|-----|------|
| MySQL | 生态成熟 | JSON 支持较弱 |
| PostgreSQL | JSON 支持、并发性能好 | 运维经验少 |

**决策**：选择 PostgreSQL

**结果**：运行 3 个月，效果良好

如何选择 Wiki 工具？

对比常见工具

工具	优势	劣势	适合场景
VitePress	简单、快速、Markdown 原生	功能相对简单	开发者项目
GitBook	功能丰富、美观	付费、自定义受限	商业文档
Notion	灵活、协作方便	搜索弱、版本管理弱	小团队
Confluence	企业级、功能强大	复杂、昂贵	大企业
Docusaurus	Facebook 出品、可定制	配置复杂	开源项目

用 VitePress 搭建 Wiki（快速开始）

步骤 1：初始化

bash

# 在项目根目录
pnpm add -D vitepress

# 创建文档目录
mkdir -p docs/.vitepress

步骤 2：配置

typescript

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '项目 Wiki',
  description: '项目文档中心',
  base: '/wiki/',

  themeConfig: {
    sidebar: [
      {
        text: '概述',
        items: [
          { text: '项目简介', link: '/overview/intro' },
          { text: '技术栈', link: '/overview/tech-stack' },
        ]
      },
      {
        text: '开发',
        items: [
          { text: '开发规范', link: '/dev/guidelines' },
          { text: '项目结构', link: '/dev/structure' },
        ]
      }
    ]
  }
})

步骤 3：写文档

markdown

<!-- docs/overview/intro.md -->
# 项目简介

这是一个外卖订餐系统...

步骤 4：运行和部署

bash

# 本地预览
pnpm docs:dev

# 构建
pnpm docs:build

# 部署到 Vercel/Netlify

让 AI 使用 Wiki

方式 1：直接引用

你：帮我写一个用户登录功能

参考项目 Wiki：
- 技术栈：docs/overview/tech-stack.md
- 开发规范：docs/dev/guidelines.md
- API 规范：docs/dev/api.md

方式 2：总结后告诉 AI

你：帮我写一个用户登录功能

项目信息：
- 框架：Nest.js + TypeORM
- 数据库：PostgreSQL
- 认证方式：JWT
- 密码加密：bcrypt
- 代码风格：参考 src/modules/user

详细规范见项目 Wiki（已上传到上下文）

方式 3：让 AI 自己读（最推荐）

前提：AI 工具支持读取本地文件（如 Claude Code）

你：帮我写一个用户登录功能

AI：（自动读取项目 Wiki）
我看了你的 Wiki：
- 技术栈：Nest.js + TypeORM
- 认证用 JWT
- 代码风格参考 user 模块

我给你写一个符合规范的实现...

Wiki 维护最佳实践

1. 及时更新

原则：代码变了，文档也要变。

实践：

提交代码时，同步更新文档
代码审查时检查文档是否需要更新
每个迭代结束检查一遍文档

2. 保持简洁

原则：文档是给人看的，不是写小说。

实践：

只写必要的内容
用表格、列表代替长篇大论
多用代码示例

3. 持续改进

原则：文档是活的，不是写完就不动。

实践：

记录团队经常问的问题
定期清理过时内容
根据使用反馈优化结构

4. 让 AI 帮忙

AI 可以帮你：

检查文档完整性
生成 API 文档
补充缺失的示例
优化文档结构

下一步

现在你已经知道如何搭建项目 Wiki。

接下来，我们通过**"拉了么"项目**的真实案例，看看 Wiki 在实际项目中是如何发挥作用的。

← 返回模块目录 | 继续学习："拉了么"项目案例 →

Wiki 系统：最佳实践 ​

什么是项目 Wiki？ ​

与普通文档的区别 ​

为什么 Wiki 特别适合 AI？ ​

Wiki 应该包含什么内容？ ​

核心章节（必备） ​

1. 项目概述 ​

2. 技术栈 ​

3. 项目结构 ​

4. 开发规范 ​

5. 业务规则 ​

进阶章节（推荐） ​

6. 数据模型 ​

字段说明 ​

User 表 ​

9. 决策记录 ​

如何选择 Wiki 工具？ ​

对比常见工具 ​

推荐：VitePress ​

用 VitePress 搭建 Wiki（快速开始） ​

步骤 1：初始化 ​

步骤 2：配置 ​

步骤 3：写文档 ​

步骤 4：运行和部署 ​

让 AI 使用 Wiki ​

方式 1：直接引用 ​

方式 2：总结后告诉 AI ​

方式 3：让 AI 自己读（最推荐） ​

Wiki 维护最佳实践 ​

1. 及时更新 ​

2. 保持简洁 ​

3. 持续改进 ​

4. 让 AI 帮忙 ​

下一步 ​

Wiki 系统：最佳实践

什么是项目 Wiki？

与普通文档的区别

为什么 Wiki 特别适合 AI？

Wiki 应该包含什么内容？

核心章节（必备）

1. 项目概述

2. 技术栈

3. 项目结构

4. 开发规范

5. 业务规则

进阶章节（推荐）

6. 数据模型

字段说明

User 表

9. 决策记录

如何选择 Wiki 工具？

对比常见工具

推荐：VitePress

用 VitePress 搭建 Wiki（快速开始）

步骤 1：初始化

步骤 2：配置

步骤 3：写文档

步骤 4：运行和部署

让 AI 使用 Wiki

方式 1：直接引用

方式 2：总结后告诉 AI

方式 3：让 AI 自己读（最推荐）

Wiki 维护最佳实践

1. 及时更新

2. 保持简洁

3. 持续改进

4. 让 AI 帮忙

下一步