# 📚 项目文档索引

> **酒店民宿短租预订平台** - 完整文档导航  
> **项目状态**：✅ 核心功能已完成（100%）  
> **最后更新**：2026-05-13

---

## 🎯 快速导航

### 新手入门
1. 📖 [项目需求文档](requirements/项目需求文档.md) - 了解项目功能和业务逻辑
2. 🗄️ [数据库设计](database/finance-database.md) - 查看数据库表结构
3. 📋 [任务清单](planning/TODO2.md) - 查看开发进度（已完成100%）
4. 📝 [开发总结](DEVELOPMENT_SUMMARY.md) - 查看项目完成情况

### 配置指南
- 💳 [微信支付配置](WECHAT_PAYMENT_SETUP.md) - 微信支付接入指南

### 核心系统设计
- 💰 [财务系统完整设计](finance-system.md) - 账户体系、资金流转、核心服务、安全保障（v2.0 重构版）
- 🎁 [邀请码系统](features/invite-system.md) - 邀请码生成、绑定和返现机制

---

## 📂 文档结构

```
docs/
├── README.md                          # 本文件 - 文档索引
├── finance-system.md                  # 财务系统完整设计文档（v2.0）
├── DEVELOPMENT_SUMMARY.md             # 开发总结（项目完成情况）
├── WECHAT_PAYMENT_SETUP.md            # 微信支付配置指南
├── requirements/
│   └── 项目需求文档.md                # 项目需求和功能说明
├── planning/
│   └── TODO2.md                       # 任务清单（已完成100%）
├── database/
│   └── finance-database.md            # 财务数据库设计（v2.0）
└── features/
    └── invite-system.md               # 邀请码系统设计文档
```

---

### 1. [财务系统完整设计](features/finance-system.md) - v3.0 合并版
**内容**：
- 四层账户体系设计（系统总账户、平台账户、商家账户、用户账户）
- 完整的资金流转流程（订单支付、结算、退款、提现）
- 结算周期和服务费计算
- 核心服务详解（AccountService、SettlementService、RefundService、WithdrawalService、ReportService）
- 数据库表结构和SQL定义
- API接口文档
- 前端页面实现（5个页面）
- 扩展方案（未来增加其他收入）
- 安全保障机制（事务、悲观锁、乐观锁、金额精度控制）
- 数据一致性保证
- 测试验证和部署说明
- 常见问题解答

**适合**：后端开发人员、架构师、财务人员、测试人员

---

### 2. [项目需求文档](requirements/项目需求文档.md)
**内容**：
- 项目概述和技术栈
- 系统架构设计
- 功能需求详细说明
  - 小程序端（C端用户 + B端商家）
  - 商家管理后台
  - 平台管理后台

**适合**：产品经理、开发人员、测试人员

---

### 3. [财务数据库设计](database/finance-database.md) - v2.0 更新
**内容**：
- 完整的数据库表结构（v2.0 重构版）
- 四层账户体系（system_accounts、platform_accounts、merchant_accounts、user_accounts）
- 资金流转逻辑和业务流程
- 数据一致性保证机制
- 索引说明和版本更新记录

**适合**：后端开发人员、数据库管理员

---

### 4. [任务清单 TODO2.md](planning/TODO2.md)
**内容**：
- 项目开发任务分解
- 各阶段完成情况（100%）
- 开发进度跟踪
- 更新日志

**适合**：项目经理、开发团队

---

### 5. [开发总结](DEVELOPMENT_SUMMARY.md)
**内容**：
- 项目整体完成情况
- 已实现的功能模块
- 技术架构说明
- 下一步计划

**适合**：所有团队成员

---

### 6. [微信支付配置](WECHAT_PAYMENT_SETUP.md)
**内容**：
- 微信支付商户配置
- API密钥设置
- 证书配置
- 退款功能配置

**适合**：后端开发人员、运维人员

---

### 7. [邀请码系统](features/invite-system.md)
**内容**：
- 邀请码生成规则（6位数字+大写字母）
- 邀请关系绑定流程
- 小程序码扫码邀请
- 邀请统计和返现机制
- 完整的技术实现和API接口

**适合**：产品经理、开发人员

---

## 🗄️ 数据库初始化

### 初始化脚本
位置：`database/migrations/001_init_schema.sql`

**包含内容**：
- 所有数据库表结构（v2.0 重构版）
- 系统总账户表（system_accounts）
- 平台账户表（platform_accounts）
- 商家账户表（merchant_accounts）
- 用户账户表（user_accounts）
- 各类交易流水表
- 索引和外键约束
- 初始化数据
- 触发器

### 执行方式
```bash
# 方式1：命令行执行（会清空所有数据）
mysql -u root -p < database/migrations/001_init_schema.sql

# 方式2：登录后执行
mysql -u root -p
source database/migrations/001_init_schema.sql;

# 方式3：初始化系统总账户和平台账户
USE your_database_name;
INSERT INTO system_accounts (account_name, balance, total_income, total_refund, total_withdrawn)
VALUES ('系统总账户', 0.00, 0.00, 0.00, 0.00);

INSERT INTO platform_accounts (account_name, balance, total_income, total_expense)
VALUES ('主账户', 0.00, 0.00, 0.00);
```

---

## 🚀 项目技术栈

| 模块 | 技术栈 |
|------|--------|
| 后端 | NestJS + TypeORM + MySQL + Redis + JWT |
| 小程序 | uni-app + Vue3 + Pinia + SCSS |
| 商家后台 | React 18 + TypeScript + Ant Design + Zustand |
| 平台后台 | React 18 + TypeScript + Ant Design + Zustand |
| 部署 | Docker + Kubernetes + Nginx |
| 包管理 | pnpm (monorepo) |

---

## 📊 项目完成情况

### 总体进度：94/94 (100%) ✅

- ✅ **阶段一**：退款财务处理完善（10/10）
- ✅ **阶段二**：小程序商家财务模块（17/17）
- ✅ **阶段三**：小程序用户钱包功能（10/10）
- ✅ **阶段四**：管理后台功能完善（23/23）
- ✅ **阶段五**：财务模块代码重构（15/15）
- ✅ **阶段六**：优惠券功能实现（11/11）
- ✅ **阶段七**：常住人和实名认证（8/8）

详细进度请查看 [TODO2.md](planning/TODO2.md)

---

## 🔗 相关链接

- [项目根目录](../)
- [CLAUDE.md](../CLAUDE.md) - AI开发指引
- [后端代码](../apps/server/)
- [小程序代码](../apps/miniapp/)
- [商家管理后台](../apps/merchant-admin/)
- [平台管理后台](../apps/platform-admin/)
- [数据库迁移脚本](../database/migrations/)

---

## 📝 文档维护

### 更新记录

| 日期 | 版本 | 说明 |
|------|------|------|
| 2024-01-XX | v5.0 | 财务系统账户体系重构（v2.0），新增系统总账户，重构平台账户 |
| 2026-05-13 | v4.2 | 新增结算系统设计文档，修复结算逻辑问题 |
| 2026-05-13 | v4.1 | 新增邀请码系统设计文档 |
| 2026-05-13 | v4.0 | 整合文档，删除重复内容，项目完成100% |
| 2026-05-12 | v3.0 | 完成阶段四、六、七开发 |
| 2026-05-12 | v2.0 | 完成财务系统设计和实现 |
| 2026-04-24 | v1.0 | 项目初始化 |

### 文档规范

1. **保持简洁**：避免重复内容，一个主题一个文档
2. **及时更新**：重要变更需同步更新文档
3. **清晰索引**：本README作为唯一入口
4. **版本控制**：重要变更需更新版本号

---

**维护团队**：开发团队  
**最后更新**：2026-05-13