Dev Protocol

Step 0.1: 任务完成后

1. 更新 CHANGELOG.md（按协议格式记录变更）
2. 将任务从 DOING 移至 DONE（填写完成日期和版本号）
3. 检查是否有因本任务完成而解锁的新可开发任务
4. 向用户报告完成情况

一、开发任务启动流程

每次确认开发任务后，AI 必须按以下顺序执行：

Step 1: 读取项目上下文

1. 读取 CHANGELOG.md → 了解最近开发历史和当前进度
2. 读取 TASKBOARD.md → 了解当前任务状态和整体进度
3. 读取 07-UI设计规范.md → 了解目标页面的设计规格
4. 读取 ui-reference/ 目录中的参考截图 → 了解视觉目标
5. 读取项目根目录的 package.json / composer.json → 了解依赖和项目配置
6. 读取已有的代码文件 → 了解当前代码风格和结构

Step 2: 任务分析

在动手写代码之前，先明确：

- 任务目标：要实现什么功能/修复什么问题
- UI 参考：对照 07-UI设计规范.md 和 ui-reference/ 截图
- 影响范围：涉及哪些文件/模块
- 依赖关系：是否需要新增依赖，TASKBOARD 中标注的前置任务是否完成
- 风险评估：是否影响已有功能

Step 3: 制定开发计划

向用户输出开发计划，包含：

- 任务概述（一句话说明）
- 涉及文件列表
- 开发步骤（1, 2, 3...）
- 预计影响

Step 4: 执行开发

按计划逐步执行，每完成一个步骤确认无误后再进行下一步。

Step 5: 收尾

开发完成后必须执行收尾流程（见下方"开发收尾规范"）。

二、前端代码规范 (uni-app)

2.1 项目结构

src/
├── api/                  # API 接口定义
│   ├── modules/          # 按模块划分
│   │   ├── user.js
│   │   ├── drama.js
│   │   └── ...
│   └── index.js          # 统一导出 + 请求实例
├── assets/               # 静态资源（图片、字体、全局样式）
│   ├── images/
│   ├── fonts/
│   └── styles/
│       ├── variables.scss    # SCSS 变量
│       ├── mixins.scss       # SCSS 混入
│       └── global.scss       # 全局样式
├── components/           # 公共组件
│   ├── common/           # 通用基础组件
│   └── business/         # 业务通用组件
├── composables/          # 组合式函数（hooks）
├── layouts/              # 布局组件
├── pages/                # 页面（uni-app 页面目录）
│   ├── index/            # 首页（刷刷）
│   │   └── index.vue
│   ├── find/             # 找片
│   │   └── index.vue
│   ├── welfare/          # 福利
│   │   └── index.vue
│   ├── mine/             # 我的
│   │   └── index.vue
│   ├── drama/            # 剧集相关
│   │   ├── detail.vue    # 剧集详情
│   │   └── play.vue      # 播放页
│   └── ...
├── stores/               # Pinia 状态管理
│   ├── index.js
│   └── modules/
├── utils/                # 工具函数
├── App.vue
├── main.js
├── manifest.json         # uni-app 配置
├── pages.json            # 页面路由配置
└── uni.scss              # uni-app 内置 SCSS 变量

2.2 跨端开发注意事项

2.3 条件编译示例

// #ifdef H5
import axios from 'axios'
// #endif

// #ifdef MP-WEIXIN
// 小程序端使用 uni.request
// #endif

// #ifdef APP-PLUS
// APP 端专属逻辑
// #endif

2.4 命名规范

2.5 Vue 组件规范

<!-- 组件模板顺序 -->
<template>
  <!-- 1. 根元素，单一根节点 -->
  <!-- 2. 按逻辑分区，用注释分隔 -->
</template>

<script setup>
// 1. 导入顺序：
//    ① Vue 内置
//    ② 第三方库
//    ③ 项目内部（@/ 开头）
//    ④ 相对路径

// 2. Props 定义
const props = defineProps({
  dramaId: {
    type: Number,
    required: true,
  },
  title: {
    type: String,
    default: '',
  },
})

// 3. Emits 定义
const emit = defineEmits(['update', 'close'])

// 4. 响应式状态
const loading = ref(false)
const dataList = ref([])

// 5. 计算属性
const filteredList = computed(() => {
  return dataList.value.filter(item => item.active)
})

// 6. 方法
function handleClick() {
  // ...
}

// 7. 生命周期
onMounted(() => {
  // ...
})

// 8. 暴露给父组件
defineExpose({
  refresh: handleClick,
})
</script>

<style lang="scss" scoped>
/* 使用 BEM 命名 */
.drama-card {
  &__title {
    font-size: 16px;
  }

  &--active {
    color: #1890ff;
  }
}
</style>

2.6 API 接口规范

// src/api/modules/drama.js
import { request } from '@/api/index'

/** 获取剧集列表 */
export function getDramaList(params) {
  return request({
    url: '/api/v1/dramas',
    method: 'GET',
    data: params,
  })
}

/** 获取剧集详情 */
export function getDramaDetail(id) {
  return request({
    url: `/api/v1/dramas/${id}`,
    method: 'GET',
  })
}

2.7 请求封装规范

// src/api/index.js
// #ifdef H5
import axios from 'axios'
// #endif

const BASE_URL = import.meta.env.VITE_API_BASE_URL

// #ifdef H5
const service = axios.create({
  baseURL: BASE_URL,
  timeout: 15000,
})
// #endif

// #ifndef H5
// 小程序/APP 使用 uni.request 封装
const service = {
  request(options) {
    return new Promise((resolve, reject) => {
      uni.request({
        url: BASE_URL + options.url,
        method: options.method || 'GET',
        data: options.data || {},
        header: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${uni.getStorageSync('token')}`,
        },
        success: (res) => {
          if (res.statusCode === 200) {
            resolve(res.data)
          } else {
            reject(res.data)
          }
        },
        fail: reject,
      })
    })
  }
}
// #endif

export function request(options) {
  return service.request ? service.request(options) : service(options)
}

2.8 状态管理规范 (Pinia)

// src/stores/modules/drama.js
import { defineStore } from 'pinia'
import { getDramaList } from '@/api/modules/drama'

export const useDramaStore = defineStore('drama', {
  state: () => ({
    dramaList: [],
    currentDrama: null,
    loading: false,
  }),

  getters: {
    activeDramas: (state) => state.dramaList.filter(d => d.status === 1),
  },

  actions: {
    async fetchDramaList(params) {
      this.loading = true
      try {
        const { data } = await getDramaList(params)
        this.dramaList = data.list
      } finally {
        this.loading = false
      }
    },
  },
})

2.9 样式规范

// 1. 优先使用 SCSS 变量
$color-primary: #1890ff;
$color-success: #52c41a;
$color-warning: #faad14;
$color-danger: #ff4d4f;
$color-text: #333333;
$color-text-secondary: #666666;
$color-border: #e8e8e8;
$font-size-base: 14px;
$border-radius-base: 4px;

// 2. 间距使用 4px 基数
// margin/padding: 4, 8, 12, 16, 20, 24, 32

// 3. z-index 层级管理
$z-dropdown: 100;
$z-sticky: 200;
$z-fixed: 300;
$z-modal-backdrop: 400;
$z-modal: 500;
$z-popover: 600;
$z-tooltip: 700;
$z-toast: 800;

三、Python 后端代码规范 (FastAPI)

3.1 项目结构

app/
├── main.py               # FastAPI 应用入口
├── config.py             # 配置文件（数据库、Redis、JWT 等）
├── api/                  # API 路由（按模块划分）
│   ├── __init__.py
│   ├── deps.py           # 公共依赖（鉴权、分页等）
│   └── v1/
│       ├── __init__.py
│       ├── user.py       # 用户相关路由
│       ├── drama.py      # 剧集相关路由
│       ├── coin.py       # 金币相关路由
│       └── member.py     # 会员相关路由
├── models/               # SQLAlchemy 数据模型
│   ├── __init__.py
│   ├── user.py
│   ├── drama.py
│   ├── coin.py
│   └── member.py
├── schemas/              # Pydantic 请求/响应模型
│   ├── __init__.py
│   ├── user.py
│   ├── drama.py
│   ├── common.py         # 通用响应模型
│   └── ...
├── services/             # 业务逻辑层
│   ├── __init__.py
│   ├── user_service.py
│   ├── drama_service.py
│   ├── coin_service.py
│   └── ...
├── core/                 # 核心模块
│   ├── __init__.py
│   ├── security.py       # JWT、密码加密
│   ├── database.py       # 数据库连接
│   ├── redis.py          # Redis 连接
│   ├── exceptions.py     # 自定义异常
│   └── middleware.py      # 中间件
├── utils/                # 工具函数
│   ├── __init__.py
│   └── helpers.py
└── requirements.txt      # 依赖清单

3.2 命名规范

3.3 路由规范

# app/api/v1/drama.py
from fastapi import APIRouter, Depends, Query
from app.schemas.drama import DramaListResponse, DramaDetailResponse
from app.schemas.common import SuccessResponse, PagedResponse
from app.services import drama_service
from app.api.deps import get_current_user

router = APIRouter(prefix="/dramas", tags=["剧集"])


@router.get("", response_model=SuccessResponse[PagedResponse[DramaListResponse]])
async def get_drama_list(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=50),
    category: str = Query(None),
    keyword: str = Query(None),
):
    """获取剧集列表"""
    result = await drama_service.get_list(
        page=page,
        page_size=page_size,
        category=category,
        keyword=keyword,
    )
    return SuccessResponse(data=result)


@router.get("/{drama_id}", response_model=SuccessResponse[DramaDetailResponse])
async def get_drama_detail(drama_id: int):
    """获取剧集详情"""
    drama = await drama_service.get_detail(drama_id)
    return SuccessResponse(data=drama)

3.4 服务层规范

# app/services/drama_service.py
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select, func
from app.models.drama import Drama
from app.core.exceptions import BusinessException


class DramaService:
    def __init__(self, db: AsyncSession):
        self.db = db

    async def get_list(
        self,
        page: int = 1,
        page_size: int = 20,
        category: str = None,
        keyword: str = None,
    ) -> dict:
        """获取剧集列表"""
        query = select(Drama).where(Drama.status == 1)

        if category:
            query = query.where(Drama.category == category)
        if keyword:
            query = query.where(Drama.title.contains(keyword))

        # 总数
        count_query = select(func.count()).select_from(query.subquery())
        total = (await self.db.execute(count_query)).scalar()

        # 分页
        query = query.order_by(Drama.created_at.desc())
        query = query.offset((page - 1) * page_size).limit(page_size)
        result = (await self.db.execute(query)).scalars().all()

        return {
            "list": result,
            "total": total,
            "page": page,
            "page_size": page_size,
            "total_pages": (total + page_size - 1) // page_size,
        }

    async def get_detail(self, drama_id: int) -> Drama:
        """获取剧集详情"""
        drama = await self.db.get(Drama, drama_id)
        if not drama:
            raise BusinessException("剧集不存在")
        return drama

3.5 Pydantic 模型规范

# app/schemas/common.py
from pydantic import BaseModel
from typing import Generic, TypeVar, Optional, List

T = TypeVar("T")


class SuccessResponse(BaseModel, Generic[T]):
    """统一成功响应"""
    code: int = 0
    message: str = "success"
    data: Optional[T] = None


class PagedResponse(BaseModel, Generic[T]):
    """分页响应"""
    list: List[T]
    total: int
    page: int
    page_size: int
    total_pages: int


class ErrorResponse(BaseModel):
    """统一错误响应"""
    code: int
    message: str
    data: Optional[None] = None

3.6 数据模型规范

# app/models/drama.py
from sqlalchemy import Column, Integer, String, Text, BigInteger, SmallInteger, DateTime
from sqlalchemy.sql import func
from app.core.database import Base


class Drama(Base):
    __tablename__ = "dramas"

    id = Column(BigInteger, primary_key=True, autoincrement=True)
    title = Column(String(100), nullable=False, comment="剧名")
    cover = Column(String(255), comment="封面URL")
    description = Column(Text, comment="简介")
    category = Column(String(50), comment="分类")
    tags = Column(String(500), comment="标签JSON")
    total_episodes = Column(Integer, default=0, comment="总集数")
    status = Column(SmallInteger, default=1, comment="状态 0下架 1上架")
    is_exclusive = Column(SmallInteger, default=0, comment="是否独家")
    is_new = Column(SmallInteger, default=0, comment="是否新剧")
    unlock_coins = Column(Integer, default=0, comment="解锁金币数")
    view_count = Column(BigInteger, default=0, comment="播放量")
    collect_count = Column(BigInteger, default=0, comment="收藏量")
    created_at = Column(DateTime, server_default=func.now())
    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())

3.7 API 响应格式

// 成功响应
{
    "code": 0,
    "message": "success",
    "data": {
        "list": [...],
        "total": 100
    }
}

// 错误响应
{
    "code": 40001,
    "message": "参数错误：缺少 drama_id",
    "data": null
}

// 分页响应
{
    "code": 0,
    "message": "success",
    "data": {
        "list": [...],
        "total": 100,
        "page": 1,
        "page_size": 20,
        "total_pages": 5
    }
}

3.8 错误码规范

3.9 自定义异常

# app/core/exceptions.py
from fastapi import HTTPException, status


class BusinessException(HTTPException):
    """业务逻辑异常"""
    def __init__(self, message: str, code: int = 41001):
        super().__init__(
            status_code=status.HTTP_OK,
            detail={"code": code, "message": message, "data": None},
        )

四、Git 提交规范

4.1 Commit Message 格式

<type>(<scope>): <subject>

<body>

4.2 Type 类型

4.3 Scope 范围

4.4 示例

feat(drama): 新增剧集收藏功能
fix(coin): 修复金币扣除后余额未更新的问题
refactor(user): 重构用户信息页面组件