docs/v1.0

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 提示词指南 - 完整的 AI 提示词使用指南
  • AI 提示词快速参考 - 常用提示词速查表
  • AI 开发提示词 - 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
• 数据库设计: requirements/database-design.md
• API 规范: requirements/api-design-specification.md
• 开发计划: requirements/development-plan.md

AI 开发辅助 🤖

• AI 提示词指南: guides/ai-prompts-guide.md - 完整的提示词使用指南
• 快速参考: guides/ai-prompts-quick-reference.md - 常用提示词速查表

测试相关

• 测试规范: ../server/tests/README.md - 测试目录和规范
• 后端架构: server/guides/backend-architecture.md - 后端分层架构

---

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

💡 使用 AI 辅助开发

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

快速开始：

1. 查看 AI 提示词快速参考 了解常用提示词
2. 参考 AI 提示词指南 学习最佳实践
3. 直接使用提示词，AI 会自动遵循项目规范

示例：

为 Project API 创建集成测试，参考 test_folder_api.py

AI 会自动：

• 加载 jointo-tech-stack 规范
• 分析现有测试模式
• 生成符合规范的测试代码