airlabs-manage/项目总结文档.md

AirLabs Project 项目总结文档

内容组 · 项目制周期 / 成本 / 产出管理系统
更新日期：2025-02-11

---

1. 项目概述

1.1 定位

服务于以 AI 动画/视觉内容为核心产出的内容团队（约 30 人以内）的内部管理系统。

核心价值：以项目为核心，以内容提交为最小记录单位，自动汇总产出、进度、成本与损耗，支持项目完成后统一结算。

1.2 解决的核心问题

• 项目实际投入成本不可见
• 实际产出是否匹配项目目标
• 测试与损耗占比无法量化
• 项目超期难以追踪
• 项目结束后是否盈利

1.3 覆盖范围（V1）

• 内容组、内容类项目、动画/视觉内容生产
• PC 端 Web 应用（预留响应式，V2 适配移动端）
• 不包含：产品研发周期、精细工时、人事绩效、审批验收、移动端专属适配

---

2. 技术架构

层级	技术选型	说明
前端	Vue 3 + Element Plus + Vite	后台管理 UI
后端	Python FastAPI	高性能 API
数据库	SQLite	零配置，MVP 适用
图表	ECharts	仪表盘可视化
认证	JWT Token	登录鉴权与权限控制

2.1 部署

• CI/CD：Gitea Actions 自动构建
• 镜像：Docker 构建，推送到华为云 SWR
• 运行：K3s 集群，通过 Ingress 暴露服务
• 前端：静态构建后由后端统一托管（/ 路径返回 index.html）

2.2 目录结构

AirLabs Project/
├── backend/              # FastAPI 后端
│   ├── main.py           # 入口、静态文件托管、角色初始化
│   ├── models.py         # ORM 模型、枚举、权限定义
│   ├── calculations.py   # 成本分摊、损耗、效率、结算计算引擎
│   ├── config.py         # 配置
│   ├── database.py       # SQLAlchemy 引擎与会话
│   ├── auth.py           # 密码哈希、JWT
│   ├── schemas.py        # Pydantic 模型
│   └── routers/          # API 路由
│       ├── auth.py       # 登录、me
│       ├── users.py      # 用户 CRUD
│       ├── projects.py   # 项目 CRUD、完成、结算、效率
│       ├── submissions.py# 内容提交 CRUD、历史
│       ├── costs.py      # AI 工具、外包、人力调整、固定开支
│       ├── dashboard.py  # 仪表盘
│       └── roles.py      # 角色、权限
├── frontend/             # Vue 3 前端
│   └── src/
│       ├── views/        # 页面：Dashboard, Projects, ProjectDetail, Submissions,
│       │                 # Costs, Users, MemberDetail, Roles, Settlement, Login
│       ├── api/index.js  # 接口封装
│       ├── stores/auth.js# 用户状态
│       └── router/       # 路由与权限守卫
├── k8s/                  # K8s  manifests
├── .gitea/workflows/     # 部署流程
└── 人员清单.md           # 团队成员与薪资

---

3. 核心数据模型

3.1 项目（Project）

字段	说明
name	项目名称
project_type	客户正式/客户测试/内部原创/内部测试
status	制作中 / 已完成 / 废弃
leader_id	负责人
current_phase	前期/制作/后期
episode_duration_minutes	单集正片时长（分钟）
episode_count	集数
target_total_seconds	目标总秒数（计算属性 = 单集×集数×60）
estimated_completion_date	预估完成日期
actual_completion_date	实际完成日期
contract_amount	回款金额（客户正式项目）

3.2 用户（User）

• 姓名、用户名、所属阶段组（前期/制作/后期）
• 角色、月薪、社保、奖金
• 日成本 = (月薪+奖金+社保) ÷ 22 个工作日

3.3 内容提交（Submission）

• 提交人、所属项目、项目阶段、工作类型（制作/测试/方案）
• 内容制作类型（内容制作/设定策划/剪辑后期/其他）
• 产出时长（分钟/秒，换算为 total_seconds）
• 投入时长（小时，可选）
• 提交对象（组长/制片/内部/外部）
• 提交日期

---

4. 业务逻辑

4.1 成本结构

成本类型	计算方式
人力成本	按提交自动分摊：有秒数按秒数比例，无秒数按条数比例；支持 CostOverride 手动调整
AI 工具成本	指定项目 / 内容组整体（按产出秒数分摊）/ 手动分摊
外包成本	按项目直接归属
固定开支	办公室租金、水电费，按项目产出秒数比例分摊

4.2 损耗（Waste）与亏损（Loss）

概念区分：

• 损耗：生产效率指标（测试试错 + 超产废片），盈利项目也有
• 亏损：财务结果（总成本 > 回款），仅客户正式项目

损耗计算：

• 测试损耗：工作类型为「测试」的提交秒数
• 超产损耗：累计提交秒数 − 目标秒数（>0 部分）
• 废弃项目：全部产出直接记为损耗，损耗率 100%

损耗率 = 总损耗秒数 ÷ 目标秒数 × 100%

4.3 团队效率（人均基准对比法）

• 人均基准 = 目标秒数 ÷ 参与制作人数
• 超出比例 = (个人提交 − 人均基准) ÷ 人均基准 × 100%

4.4 进度计算

• 完成百分比 = 当前有秒数提交的累计秒数 ÷ 目标总秒数 × 100%
• 仅统计有产出秒数的提交（制作组 + 后期补拍）

---

5. 权限体系

角色	可见范围	典型权限
超级管理员	全量	全部
主管	所有项目	dashboard, project CRUD+complete, submission, cost, settlement, efficiency
组长	所负责项目	project view+create, submission, cost, efficiency
成员	本人提交、项目公开信息	project view, submission

权限标识：dashboard:view, project:view/create/edit/delete/complete, submission:view/create, cost:view/create/delete, user:view/manage, role:manage, settlement:view, efficiency:view

---

6. 前端页面与路由

路径	页面	权限
/login	登录	公开
/dashboard	仪表盘	dashboard:view
/projects	项目列表	project:view
/projects/:id	项目详情、提交、损耗、进度	project:view
/submissions	提交记录	submission:view
/costs	成本管理（AI/外包/固定开支/人力调整）	cost:view
/users	用户管理	user:manage
/users/:id/detail	成员详情	user:view
/roles	角色管理	role:manage
/settlement/:id	项目结算	settlement:view

项目详情页操作：编辑、确认完成（制作中→已完成）、标记废弃（制作中→废弃）、查看结算（已完成）

---

7. 废弃项目特性（近期新增）

• 状态：ProjectStatus.ABANDONED = "废弃"
• 含义：项目中途停止，不再继续制作
• 损耗：全部产出记为损耗，损耗率 100%
• 操作：
  • 项目详情页「标记废弃」按钮（仅制作中可见）
  • 编辑表单中状态下拉增加「废弃」选项
• 仪表盘：废弃项目纳入总损耗统计、成本构成统计、损耗排行

---

8. 人员与团队（来自 人员清单.md）

• 22 人：主管 3、组长 4、组员 15、Owner 2
• 职位涵盖：总导演、AI 导演、制片、动画制作、剪辑、编剧等
• 薪资与社保已录入，用于人力成本计算

---

9. PRD 与实现对照

PRD 要求	实现情况
项目管理（创建/编辑/状态/目标）	✅
内容提交表单	✅
项目详情（进度、提交、损耗）	✅
人力/AI/外包/固定开支成本	✅
仪表盘	✅
项目结算、盈亏	✅
废弃项目	✅（PRD 未写，实际补充）
登录与 4 级权限	✅
历史修改记录（版本追溯、修改原因）	⚠️ 部分（有 SubmissionHistory 表与 history 接口，前端展示待完善）
用户管理（新增/编辑/薪资）	✅

---

10. AI 能力模块（V2 新增）

10.1 技术架构

FastAPI 后端
  ├── services/ai_service.py        # 豆包模型调用（OpenAI 兼容协议）
  ├── services/report_service.py    # 报告数据汇总 + AI 摘要
  ├── services/feishu_service.py    # 飞书自建应用消息推送
  ├── services/scheduler_service.py # APScheduler 定时任务
  └── routers/reports.py            # 手动触发报告 API
          ↓                    ↓
    豆包 AI (ARK)         飞书开放平台
    生成报告摘要           私聊推送给管理员

10.2 功能清单

功能	说明
自动日报	每天 20:00，今日提交、项目进展、风险提醒
自动周报	每周五 20:00，项目进展、团队产出、成本概览
自动月报	每月1日 10:00，上月完整数据、成本明细、盈亏
项目风险预警	仪表盘展示，规则引擎检测超期/进度/损耗/停滞
手动触发	POST /api/reports/{daily,weekly,monthly}，调试用
报告预览	POST /api/reports/preview/{type}，不推送仅预览

10.3 新增依赖

包	用途
openai	豆包 AI 调用（兼容协议）
httpx	飞书 API 异步请求
apscheduler	定时任务调度
python-dotenv	.env 配置文件

10.4 配置项

通过 backend/.env 配置：

• ARK_API_KEY — 豆包 API Key
• ARK_MODEL — 模型名称
• FEISHU_APP_ID / FEISHU_APP_SECRET — 飞书应用凭证
• REPORT_RECEIVERS — 接收人手机号（逗号分隔）

---

11. PRD 与实现对照（更新）

PRD 要求	实现情况
项目管理（创建/编辑/状态/目标）	✅
内容提交表单	✅
项目详情（进度、提交、损耗）	✅
人力/AI/外包/固定开支成本	✅
仪表盘	✅
项目结算、盈亏	✅
废弃项目	✅（PRD 未写，实际补充）
登录与 4 级权限	✅
历史修改记录	⚠️ 部分
用户管理	✅
AI 自动报告 + 飞书推送	✅ V2 新增
项目风险预警	✅ V2 新增

---

12. 已知待办 / 待完善

• 历史修改记录：后端已有 SubmissionHistory，前端完整展示与 diff 对比可完善
• 数据导出：PRD 提到 V2 支持 Excel/PDF，当前未实现
• 移动端适配：V2 计划
• 数据库升级：若用户量增长，可迁移至 PostgreSQL
• AI 智能问答：V3 计划，前端聊天页面 + 自然语言查询
• 按权限分级推送：V3 计划，不同角色收到不同报告内容

---

13. 默认账号

• 首次启动自动创建：admin / admin123（超级管理员）

---

本文档用于项目交接、复盘与后续迭代参考。