# Jointo 项目文档

本目录包含 Jointo 视频制作平台的所有技术文档，按模块和文档类型组织。

## 📁 目录结构

### `/architecture` - 架构文档
跨模块的系统架构设计和重大技术决策文档。

- **ADRs (Architecture Decision Records)**: 架构决策记录
  - UUID v7 迁移决策
  - PostgreSQL 17 UUID v7 实现
  - 分镜资源架构设计
  - 镜头尺寸和运动标准化
  - 变体到标签系统重构

- **技术栈文档**: `tech-stack.md` - 项目整体技术选型
- **迁移总结**: 系统重构和迁移的总结文档

### `/client` - 前端文档
React + Vite + TypeScript 前端应用的所有文档。

- **RFCs (Request for Comments)**: 技术提案和功能设计
  - 表单系统设计 (001-008, 101-128)
  - 项目资源链接功能
  - 智能搜索功能
  - 文件夹选择器
  - 主题色彩系统
  - 分镜变体 UI

- **Changelogs**: 版本变更记录
  - 面包屑导航实现
  - 项目 API 集成
  - 文件夹分类功能
  - 时长单位转换

- **Guides**: 使用指南和最佳实践
  - 表单使用示例
  - 组件演示代码

### `/server` - 后端文档
FastAPI + Python 后端服务的所有文档。

- **RFCs**: 技术提案和功能设计
  - AI 积分定价系统 (001)
  - 附件资源架构 (002-003)
  - Docker + asyncpg 配置 (004)
  - 项目表设计 (005)
  - 脚本存储重设计 (006)
  - SQLModel ORM (008)
  - 文件夹功能 (012)
  - 手机登录 (013)
  - 认证系统重构 (014)
  - 积分系统设计 (015)
  - 枚举类型重构 (130-133)

- **Changelogs**: 版本变更记录
  - 默认图片系统
  - 项目回收站系统
  - 分镜枚举重构
  - AI 服务实现
  - 文件夹枚举优化

- **Guides**: 部署和故障排查指南
  - 局域网访问配置
  - 数据库故障排查
  - 用户服务测试

### `/guides` - 开发指南
通用开发指南和最佳实践。

- **AI 开发辅助**:
  - [AI 提示词指南](./guides/ai-prompts-guide.md) - 完整的 AI 提示词使用指南
  - [AI 提示词快速参考](./guides/ai-prompts-quick-reference.md) - 常用提示词速查表
  - [AI 开发提示词](./guides/ai-development-prompts.md) - AI 辅助开发提示词集合

- **开发规范**:
  - 测试规范
  - 代码规范
  - 文档规范

### `/admin` - 管理后台文档
管理后台相关的技术文档（待补充）。

- **RFCs**: 技术提案
- **Changelogs**: 变更记录
- **Guides**: 使用指南
- **ADRs**: 架构决策

### `/requirements` - 需求文档
产品需求、设计规范和开发计划。

- **产品需求文档 (PRD)**:
  - `prd-daoyanzu-requirements.md` - 导演组核心需求
  - `prd-daoyanzu-mock-data.md` - Mock 数据规范

- **设计规范**:
  - `api-design-specification.md` - API 设计规范
  - `database-design.md` - 数据库设计
  - `component-design.md` - 组件设计规范
  - `ui-design-specification.md` - UI 设计规范

- **开发计划**:
  - `development-plan.md` - 开发路线图
  - `feature-expansion.md` - 功能扩展计划
  - `PROGRESS_UPDATE_2025-01-18.md` - 进度更新

- **子目录**:
  - `/backend` - 后端架构和服务设计
  - `/frontend` - 前端架构和技术栈

### `/.archive` - 归档文档
已完成、过时或被替代的历史文档。

按模块组织：
- `/admin` - 管理后台归档
- `/client` - 前端归档
- `/server` - 后端归档
- `/requirements` - 需求归档

## 📝 文档类型说明

### RFC (Request for Comments)
技术提案文档，用于新功能开发和重大重构。

**编号规则**:
- `001-099`: 新功能和架构设计
- `101-199`: Bug 修复和优化

**命名格式**: `<编号>-<简短描述>.md`

### ADR (Architecture Decision Record)
架构决策记录，记录重要的技术选型和架构决策。

**内容包括**:
- 决策背景和问题
- 考虑的方案
- 最终决策和理由
- 影响和后果

### Changelog
版本变更日志，记录功能更新和 Bug 修复。

**命名格式**: `<日期>-<主题>.md`  
**日期格式**: `YYYY-MM-DD`

### Guide
使用指南和最佳实践文档。

**内容包括**:
- 部署指南
- API 使用文档
- 故障排查
- 开发规范

## 🔍 如何查找文档

1. **按模块查找**: 根据前端/后端/架构分类进入对应目录
2. **按类型查找**: 根据 RFC/ADR/Changelog/Guide 分类查找
3. **按时间查找**: Changelog 按日期命名，可按时间顺序查看
4. **按编号查找**: RFC 按编号组织，相关文档编号连续

## 📌 文档编写规范

1. **文档必须包含**:
   - 清晰的标题和目标
   - 背景说明
   - 详细的技术方案
   - 影响范围

2. **文档命名**:
   - 使用小写字母和连字符
   - 包含编号（RFC/ADR）或日期（Changelog）
   - 简短描述性标题

3. **文档归档**:
   - 完成的功能文档移至 `.archive`
   - 保持原有目录结构
   - 添加归档说明

## 🚀 快速导航

### 核心文档
- **技术栈**: [architecture/tech-stack.md](./architecture/tech-stack.md)
- **数据库设计**: [requirements/database-design.md](./requirements/database-design.md)
- **API 规范**: [requirements/api-design-specification.md](./requirements/api-design-specification.md)
- **开发计划**: [requirements/development-plan.md](./requirements/development-plan.md)

### AI 开发辅助 🤖
- **AI 提示词指南**: [guides/ai-prompts-guide.md](./guides/ai-prompts-guide.md) - 完整的提示词使用指南
- **快速参考**: [guides/ai-prompts-quick-reference.md](./guides/ai-prompts-quick-reference.md) - 常用提示词速查表

### 测试相关
- **测试规范**: [../server/tests/README.md](../server/tests/README.md) - 测试目录和规范
- **后端架构**: [server/guides/backend-architecture.md](./server/guides/backend-architecture.md) - 后端分层架构

---

**文档维护**: 所有开发人员  
**最后更新**: 2026-02-04

## 💡 使用 AI 辅助开发

Jointo 项目配置了 `jointo-tech-stack` skill，可以自动应用项目规范。

**快速开始**：
1. 查看 [AI 提示词快速参考](./guides/ai-prompts-quick-reference.md) 了解常用提示词
2. 参考 [AI 提示词指南](./guides/ai-prompts-guide.md) 学习最佳实践
3. 直接使用提示词，AI 会自动遵循项目规范

**示例**：
```
为 Project API 创建集成测试，参考 test_folder_api.py
```

AI 会自动：
- 加载 jointo-tech-stack 规范
- 分析现有测试模式
- 生成符合规范的测试代码