video-shuoshan/docs/changelog.md

需求变更日志 (Changelog)

按日期倒序记录每次需求变更。每条记录在开发完成、测试验收通过后归档。

---

2026-03-16 — v0.8.4: 管理员操作审计日志

状态: ✅ 已完成 | 验收: ✅ 通过（本地测试）

变更内容

1. AdminAuditLog 模型 — 新增审计日志 Model，记录操作人、操作类型（12 种）、目标、变更前后值（JSONField）、IP 地址、时间
2. log_admin_action() 辅助函数 — 统一的审计日志写入接口，自动获取操作人和客户端 IP
3. 12 处 view 埋点 — 所有管理员 mutation 操作均记录审计日志：
   • 创建类：团队创建、团队管理员创建、用户创建、成员创建
   • 修改类：团队更新、团队充值、设置秒数池、用户额度更新、系统设置更新、成员额度更新
   • 状态类：用户状态切换、成员状态切换
4. 日志查询 API — GET /api/v1/admin/logs，支持按操作类型、操作人、日期范围筛选 + 分页
5. 前端日志页面 — /admin/logs 操作日志页，含筛选栏（操作类型下拉、操作人搜索、日期范围）、变更详情展示（旧值 → 新值）、分页
6. 侧栏导航 — AdminLayout 新增"操作日志"菜单项

变更文件

文件	改动
backend/apps/accounts/models.py	新增 AdminAuditLog 模型 + log_admin_action 函数
backend/apps/accounts/migrations/0005_adminauditlog.py	新增迁移
backend/apps/generation/views.py	12 处埋点 + admin_audit_logs_view 新端点
backend/apps/generation/urls.py	新增 admin/logs 路由
web/src/types/index.ts	新增 AuditLog 接口
web/src/lib/api.ts	新增 getAuditLogs 方法
web/src/pages/AuditLogsPage.tsx	新建日志页面
web/src/pages/AuditLogsPage.module.css	新建日志页面样式
web/src/pages/AdminLayout.tsx	侧栏新增"操作日志"
web/src/App.tsx	新增 /admin/logs 路由

新增 API

Method	Endpoint	Description
GET	/api/v1/admin/logs	审计日志查询（支持 action/operator/start_date/end_date 筛选）

触发原因

• 充值、修改秒数等操作直接对应金钱，填错无法追溯
• 需要记录谁在什么时候做了什么操作、改了什么值

---

2026-03-16 — v0.8.3: 团队详情弹窗重构 + 修改秒数功能

状态: ✅ 已完成 | 验收: 待测试

变更内容

1. 团队详情：抽屉→弹窗 — 右侧抽屉改为居中弹窗（Modal），遵循 VideoDetailModal 设计规范：毛玻璃背景 backdrop-filter: blur(24px)、border-radius: 16px、入场动画、精致的关闭按钮
2. 弹窗尺寸优化 — 宽度 1080px、最小高度 70vh，桌面端大气不小气
3. 字号提升 — 统计卡片标签 #8b8ea8 12px、数值 #f1f0ff 18px、成员表 14px（对齐 VideoDetailModal 规范）
4. 修改秒数池功能 — 团队详情"总秒数池"卡片旁新增编辑按钮，支持直接设置 total_seconds_pool 值（后端校验不能低于已消耗秒数、不能为负）
5. member_count 修复 — 后端团队详情 API 漏返回 member_count 字段，已补上

变更文件

文件	改动
web/src/pages/TeamsPage.tsx	抽屉→弹窗结构、修改秒数池 UI + handler
web/src/pages/TeamsPage.module.css	全部 Team Detail Modal 样式重写（VideoDetailModal 规范）
web/src/lib/api.ts	新增 setTeamPool API 方法
backend/apps/generation/views.py	新增 admin_team_set_pool_view、团队详情补返 member_count
backend/apps/generation/urls.py	新增 admin/teams/<id>/set-pool 路由

新增 API

Method	Endpoint	Description
PUT	/api/v1/admin/teams/<id>/set-pool	直接设置团队总秒数池

触发原因

• 团队详情使用右侧抽屉形式，信息拥挤、不符合暗色主题规范
• 充值秒数填错后无法修改，而这些秒数直接对应金钱
• 成员数卡片值为空（后端遗漏字段）

---

2026-03-16 — v0.8.2: 管理后台 UI 修复（4 项）+ 失败原因展示

状态: ✅ 已完成 | 验收: 待测试

变更内容

1. DatePicker 日历透明修复 — .dropdown 背景从半透明 var(--color-bg-card) 改为不透明 #16161e + backdrop-filter
2. 自定义 Select 组件 — 替换原生 <select> 白色下拉面板，暗色主题 + 动画 + click-outside 关闭（RecordsPage 1 处、UsersPage 2 处）
3. 公告横幅美化 — 渐变背景 + 左侧强调色竖条 + CSS 跑马灯滚动（hover 暂停）+ 淡出遮罩
4. Toast 全局化 — <Toast /> 从 VideoGenerationPage 移至 App.tsx 根级，管理后台页面（如设置页保存）可正常显示提示
5. 失败原因 tooltip — 消费记录表中失败状态悬浮显示 error_message；CSV 导出增加"失败原因"列；后端 admin_records API 返回 error_message 字段

变更文件

文件	改动
web/src/components/DatePicker.module.css	.dropdown 背景改为不透明
web/src/components/Select.tsx	新建自定义暗色 Select 组件
web/src/components/Select.module.css	新建 Select 样式
web/src/pages/RecordsPage.tsx	替换原生 select + 失败原因 tooltip + CSV 导出
web/src/pages/RecordsPage.module.css	新增 errorTooltip 样式
web/src/pages/UsersPage.tsx	替换 2 处原生 select
web/src/components/AnnouncementBanner.tsx	跑马灯结构
web/src/components/AnnouncementBanner.module.css	渐变背景 + 滚动动画
web/src/App.tsx	全局 <Toast />
web/src/components/VideoGenerationPage.tsx	移除局部 <Toast />
web/src/types/index.ts	AdminRecord 增加 error_message
backend/apps/generation/views.py	admin_records 返回 error_message

触发原因

• DatePicker / Select 下拉面板与暗色主题不协调
• 公告横幅样式简陋
• 管理后台保存设置无反馈
• 失败记录无法查看具体原因

---

2026-03-15 — v0.8.1: Seedance API 友好错误提示 + Mock 数据清理

状态: ✅ 已完成 | 验收: ✅ 通过（本地端到端测试）

变更内容

1. Seedance API 友好错误提示 — seedance_client.py 新增 SeedanceAPIError 异常类 + ERROR_MESSAGES 错误码映射表，API 报错时返回中文友好提示（如"参考图片中检测到真实人脸"）而非原始英文错误
2. views.py 错误传递优化 — video_generate_view 异常处理识别 SeedanceAPIError，将 user_message 存入 error_message 字段，前端直接展示具体原因
3. 移除前端 Mock 数据 — generation.ts 删除 DEV 环境下的 7 个硬编码 mock 任务，消除页面加载时的 404 轮询错误

变更文件

文件	改动
backend/utils/seedance_client.py	新增 SeedanceAPIError 异常类 + ERROR_MESSAGES 映射 + create_task 错误解析
backend/apps/generation/views.py	异常处理区分 SeedanceAPIError，存储友好错误信息
web/src/store/generation.ts	删除 DEV mock 数据（7 个假任务），消除 404 轮询

触发原因

• 本地测试上传含真人面部的图片，Seedance 返回 400 但前端只显示"生成失败，请重试"，用户无法理解失败原因
• DEV 环境 mock 数据的假 taskId 触发持续 404 轮询错误

备注

• 已覆盖错误码：隐私人脸、敏感图片/视频、参数无效、频率超限、余额不足
• 未匹配的错误码会直接展示 API 原始 message

---

2026-03-15 — v0.8.0: Seedance API 全流程修复 + TOS 视频持久化

状态: ✅ 已完成 | 验收: ✅ 通过（本地端到端测试）

变更内容

1. 音频引用支持 — 后端 content_items 构建新增 audio 类型分支，Seedance API 可接收音频参考素材
2. 视频 TOS 持久化 — Seedance 返回的临时 URL（24h 有效）自动下载并上传到 TOS，生成永久 CDN 链接；失败时降级使用临时 URL
3. 移除硬编码密钥 — ARK_API_KEY 默认值从测试 key 改为空字符串，避免生产环境误用
4. 渐进式轮询 — 前端轮询从固定 3 分钟改为渐进式：前 2 分钟每 10s → 2-5 分钟每 30s → 5 分钟后每 60s
5. TOS 新桶配置 — 切换到独立桶 airdrama-media（cn-beijing），TOS 配置默认值更新
6. K8s Secret 注入 — TOS_ACCESS_KEY / TOS_SECRET_KEY 通过 K8s Secret 注入，CI/CD 自动创建
7. CI/CD 密钥同步 — deploy.yaml 新增 TOS 密钥到 kubectl secret 创建命令

变更文件

文件	改动
backend/apps/generation/views.py	新增 audio content_item 分支 + 完成时 TOS 持久化逻辑
backend/utils/tos_client.py	新增 upload_from_url() — 从 URL 下载并上传到 TOS
backend/config/settings.py	TOS 桶/区域/端点改为 airdrama-media (cn-beijing)；ARK_API_KEY 默认值清空
web/src/store/generation.ts	setInterval → setTimeout 渐进式轮询
k8s/backend-deployment.yaml	新增 6 个 TOS 环境变量（AK/SK from Secret）
.gitea/workflows/deploy.yaml	kubectl secret 新增 TOS_ACCESS_KEY / TOS_SECRET_KEY

触发原因

• Seedance API 文档审查发现：音频引用未传递、视频 URL 24h 过期、密钥硬编码
• 需要独立 TOS 桶存放生成视频（原桶为同事的阿里云 OSS）

备注

• 本地测试通过：文生视频 "一只猫在阳光下伸懒腰" → 87,300 tokens → 永久 TOS URL
• Seedance 2.0 定价：不含视频输入 46 元/百万 tokens，含视频输入 28 元/百万 tokens
• 资源包 5,000,000 tokens，约可生成 57 个 4 秒 720p 视频

---

2026-03-13 — 异常上报体系优化 + 轮询策略调整

状态: ✅ 已完成 | 验收: ✅ 通过

变更内容

1. LogCenterMiddleware — 新增 Django 中间件，捕获 DRF 之外的异常（导入错误、中间件异常、URL 解析失败），上报日志中台
2. custom_exception_handler 优化 — 未处理异常返回 JSON {'error': '...'} 而非 HTML 500
3. 轮询间隔调整 — 前端视频生成任务轮询从 5 秒改为 3 分钟（Seedance 生成耗时 2-5 分钟）
4. CLAUDE.md 更新 — 增量开发指南从 "Autonomous Skill" 修正为 "agent-auto"

变更文件

文件	改动
backend/utils/log_center.py	新增 LogCenterMiddleware + 优化 custom_exception_handler
backend/config/settings.py	MIDDLEWARE 列表首位加入中间件
web/src/store/generation.ts	轮询间隔 5000ms → 180000ms
CLAUDE.md	增量开发指南更新

触发原因

• 线上 /api/v1/video/tasks 返回 500，日志中台未收到错误上报
• 视频生成轮询过于频繁，增加后端负载

---

2026-03-13 — Phase 4: TOS 存储 + Seedance API 集成

状态: ✅ 已完成 | 验收: ✅ 通过

变更内容

1. TOS 文件上传 — 火山引擎 TOS（S3 兼容）上传，POST /api/v1/media/upload
2. Seedance API 对接 — 火山方舟 Seedance 视频生成 API，异步 create_task + query_task
3. 数据库持久化 — GenerationRecord 新增 ark_task_id、result_url、error_message、reference_urls
4. 前端重写 — generation store 完全重写：TOS 上传 → API 调用 → 轮询 → 展示结果
5. 页面刷新持久化 — loadTasks() 从数据库加载历史任务

新增/变更 API

端点	方法	说明
/api/v1/media/upload	POST	上传文件到 TOS
/api/v1/video/generate	POST	创建 Seedance 任务（改写）
/api/v1/video/tasks	GET	用户任务列表（新增）
/api/v1/video/tasks/<uuid>	GET	单任务状态轮询（新增）

变更文件

文件	改动
backend/utils/tos_client.py	新增：TOS 上传客户端
backend/utils/seedance_client.py	新增：Seedance API 客户端
backend/config/settings.py	TOS + ARK 配置
backend/apps/generation/models.py	4 个新字段
backend/apps/generation/views.py	3 个新端点 + 重写 generate
backend/apps/generation/urls.py	3 条新路由
backend/apps/generation/serializers.py	references 字段
backend/requirements.txt	tos>=2.7, requests>=2.31
web/src/store/generation.ts	完全重写
web/src/types/index.ts	BackendTask 接口
web/src/lib/api.ts	mediaApi + videoApi
web/src/components/VideoGenerationPage.tsx	loadTasks on mount
web/src/components/GenerationCard.tsx	视频播放器 + 错误态

---

2026-03-13 — 测试隔离 + Mock 数据清理

状态: ✅ 已完成 | 验收: ✅ 通过

变更内容

1. 测试 DB 隔离 — TESTING=true 环境变量切换到 test_db.sqlite3，Playwright 自动启动测试后端
2. 移除 Mock 数据兜底 — DashboardPage 图表仅显示真实数据，无 mock fallback

触发原因

• E2E 测试会污染开发数据库
• Dashboard 应展示真实数据而非虚假 Mock

---

2026-03-12 — Phase 3: 秒数计量 + 管理后台重做 + 个人中心

状态: ✅ 已完成 | 验收: ✅ 通过（agent-auto 自动测试）

变更内容

1. 计量单位变更 — 所有「调用次数」改为「生成秒数」(daily_seconds_limit / monthly_seconds_limit)
2. 管理后台重做 — Sidebar 多页面布局，4 个子路由：
   • /admin/dashboard — 仪表盘 + ECharts 折线图 + 排行柱状图
   • /admin/users — 用户管理（分页、搜索、配额编辑、启用/禁用）
   • /admin/records — 消费记录（时间筛选、导出 CSV）
   • /admin/settings — 系统设置 + 公告管理
3. 用户个人中心 (/profile) — ECharts 环形进度条 + Sparkline + 消费记录
4. 8 个新 API 端点 — admin: stats/users/users/:id/quota/status/records + profile: overview/records

设计规范

• 深色主题（Linear/Vercel 风格）
• ECharts + echarts-for-react
• Arco Design 组件库优先

---

2026-03-12 — Phase 2: 后端 + 用户认证 + 管理面板

状态: ✅ 已完成 | 验收: ✅ 通过（agent-auto 自动测试）

变更内容

1. Django 后端 — Django 4.2 + DRF + MySQL 云数据库
2. JWT 认证 — SimpleJWT + 前端 Token 自动刷新
3. 用户系统 — 登录 /login + 注册 /register
4. 管理后台 — 基础仪表盘 + 用户配额管理
5. 9 个新 API 端点 — 认证 4 个 + 管理 3 个 + 已有接口认证 2 个

---

2025 — Phase 1: 核心视频生成 UI

状态: ✅ 已完成 | 验收: ✅ 通过（92 单元测试 + 14 E2E 测试）

变更内容

1. 视频生成页 — 全能参考/首尾帧双模式
2. InputBar — contentEditable 富文本 + @ mention
3. 深色主题 UI — #0a0a0f 背景 + Arco Design
4. 状态管理 — Zustand store

---

模板（新增变更请复制此模板）

## YYYY-MM-DD — 变更标题

**状态**: 🔲 开发中 / ✅ 已完成 | **验收**: 🔲 待验收 / ✅ 通过 / ❌ 未通过

### 变更内容
1. ...

### 变更文件
| 文件 | 改动 |
|------|------|
| `path/to/file` | 描述 |

### 触发原因
- ...

### 备注
- ...