docs(release): freeze v0.1.16 production surface
This commit is contained in:
Xiaoxia AI
+200
-25
@@ -1,41 +1,216 @@
|
||||
# 当前发布面清单
|
||||
|
||||
最后更新：2026-06-22
|
||||
最后更新：2026-06-23
|
||||
生产基线：`v0.1.16`
|
||||
公网 Web：`https://saas.xiaoxiajianji.com/`
|
||||
公网 API：`https://saas-api.xiaoxiajianji.com/`
|
||||
|
||||
## 已开放并已验证
|
||||
---
|
||||
|
||||
- 认证：注册、登录、获取当前用户
|
||||
- 工作空间：创建、列表、详情
|
||||
- 项目：创建、列表、进入素材/生成/结果页
|
||||
- 素材：素材库创建、上传、入库、列表
|
||||
- 分类：单个分类、批量分类任务提交与状态轮询
|
||||
- 生成：创建生成任务、轮询任务、查看结果
|
||||
- 成片：公网下载 URL、直接打开生成文件
|
||||
## 1. 当前定位
|
||||
|
||||
## 明确暂未开放
|
||||
当前 SaaS 版是视频处理/自动生成 MVP，已打通：
|
||||
|
||||
- 订阅升级、支付、配额变更
|
||||
- 账单、发票、账单下载
|
||||
- Admin 后台：用户管理、数据分析、系统监控、日志查看
|
||||
- Profile 高级设置：资料编辑、通知偏好、账号安全、会话管理
|
||||
- 全局项目列表、全局成员管理
|
||||
登录 → 工作空间 → 项目 → 素材库 → 上传素材 → 生成真实 MP4 → 下载成片。
|
||||
|
||||
## 发布门禁
|
||||
当前版本不是完整智能自动剪辑平台。旧版桌面软件中的素材诊断、标题库、成片历史、模板编排、ASR/TTS/BGM/转场等能力，已进入后续升级路线，但不属于当前已开放能力。
|
||||
|
||||
---
|
||||
|
||||
## 2. 已开放并已验证
|
||||
|
||||
### 2.1 账号与认证
|
||||
|
||||
- 用户注册。
|
||||
- 用户登录。
|
||||
- 获取当前用户 `/auth/me`。
|
||||
- 401 时清理前端过期登录态。
|
||||
- 刷新/直接进入受保护页面时校验本地 token。
|
||||
|
||||
生产验证：
|
||||
|
||||
- `public_auth_flow=ok`
|
||||
|
||||
### 2.2 工作空间
|
||||
|
||||
- 创建工作空间。
|
||||
- 查询工作空间列表。
|
||||
- 进入工作空间详情。
|
||||
- 工作空间成员基础权限校验。
|
||||
|
||||
生产验证：
|
||||
|
||||
- 公网 auth smoke 中 `/workspaces` 返回 200。
|
||||
|
||||
### 2.3 项目
|
||||
|
||||
- 创建项目。
|
||||
- 查询项目。
|
||||
- 通过项目详情恢复 workspace 上下文。
|
||||
- 进入项目素材页、生成页、结果页。
|
||||
|
||||
生产验证：
|
||||
|
||||
- 项目详情 smoke 已通过。
|
||||
- 直接 URL/刷新后的项目上下文恢复已修复并发布。
|
||||
|
||||
### 2.4 素材与素材库
|
||||
|
||||
- 创建项目级素材库。
|
||||
- 上传单个素材。
|
||||
- 批量上传素材。
|
||||
- 上传后创建 ingest job。
|
||||
- 查询 ingest job 状态。
|
||||
- 素材上传会校验 workspace/project/library 归属关系。
|
||||
|
||||
生产验证：
|
||||
|
||||
- `public_upload_flow=ok`
|
||||
- `public_batch_upload_flow=ok`
|
||||
|
||||
### 2.5 视频生成
|
||||
|
||||
- 创建生成任务。
|
||||
- Worker 异步执行生成。
|
||||
- 轮询生成任务状态。
|
||||
- 生成真实 MP4。
|
||||
- 生成失败提示已初步人话化。
|
||||
- Worker 生产默认并发限制为 1，降低小机器 FFmpeg 并发风险。
|
||||
|
||||
生产验证：
|
||||
|
||||
- `public_generation_flow=ok`
|
||||
|
||||
### 2.6 成片下载
|
||||
|
||||
- 查询生成结果。
|
||||
- 获取下载 URL。
|
||||
- 公网下载 MP4。
|
||||
|
||||
生产验证：
|
||||
|
||||
- 下载响应 `Content-Type: video/mp4`。
|
||||
|
||||
### 2.7 权限边界
|
||||
|
||||
当前已验证：
|
||||
|
||||
- 匿名访问 `/auth/me` 返回 401。
|
||||
- 匿名访问工作空间返回 401。
|
||||
- 匿名访问项目详情返回 401。
|
||||
- 非成员访问他人项目返回 403。
|
||||
- 非成员访问他人素材库返回 404。
|
||||
- 非成员上传到他人项目/素材库返回 403。
|
||||
|
||||
生产验证：
|
||||
|
||||
- `public_boundary_flow=ok`
|
||||
|
||||
### 2.8 生产发布与监控
|
||||
|
||||
- 生产发布使用 tag 触发。
|
||||
- runtime-builder 构建 API/Worker 镜像和 Web 产物。
|
||||
- 生产机只接收 artifact、`docker load`、迁移数据库、重启容器和健康检查。
|
||||
- 生产 API `/health` 返回真实发布版本。
|
||||
- 生产 Worker 默认 `WORKER_CONCURRENCY=1`。
|
||||
- 生产资源巡检 cron 已启用，每 5 分钟写入 `/var/lib/xiaoxia-ci/duty_report.json`。
|
||||
|
||||
生产验证：
|
||||
|
||||
- `https://saas-api.xiaoxiajianji.com/health` 返回 `version: v0.1.16`。
|
||||
- 最新巡检报告显示 API/Web/容器/版本正常，但内存偏低为 warning。
|
||||
|
||||
---
|
||||
|
||||
## 3. 明确暂未开放
|
||||
|
||||
这些功能未完成后端闭环，必须禁用或显示“暂未开放”，不得假成功。
|
||||
|
||||
- 订阅升级、支付、配额变更。
|
||||
- 账单、发票、账单下载。
|
||||
- Admin 后台：用户管理、数据分析、系统监控、日志查看。
|
||||
- Profile 高级设置：资料编辑、通知偏好、账号安全、会话管理。
|
||||
- 全局项目列表。
|
||||
- 全局成员管理。
|
||||
- 完整标题库。
|
||||
- 素材智能视图：推荐、慎用、高风险、未使用、最近使用。
|
||||
- 素材缺口诊断。
|
||||
- 成片历史管理、封面预览、批量下载、复核状态。
|
||||
- 统一任务中心和任务重试。
|
||||
- 模板编排和剪辑计划预览。
|
||||
- ASR 字幕、TTS 配音、BGM 混音、转场包装。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发布门禁
|
||||
|
||||
- 生产 Web 使用预构建 artifact，不在生产机执行前端构建。
|
||||
- 生产部署默认跳过 API/worker 镜像构建；只有专用构建机可显式设置 `ALLOW_PRODUCTION_BUILDS=true`。
|
||||
- 生产 Web `/api` 必须代理到 `xiaoxia-api-production:8000`，不得使用共享网络别名 `api`。
|
||||
- 生产部署默认跳过 API/Worker 镜像构建。
|
||||
- API/Worker 只能由 runtime-builder 构建运行时镜像。
|
||||
- 生产 Web `/api` 必须代理到 `xiaoxia-api-production:8000`。
|
||||
- API/Worker 发布后必须 force recreate Web，避免 Nginx 静态 upstream 缓存旧 API 容器 IP。
|
||||
- 未实现后端的功能不得接入 UI 调用；按钮必须禁用或页面必须显示“暂未开放”。
|
||||
- 公网发布后必须运行 `python scripts/smoke_public_auth_flow.py`。
|
||||
- 公网发布后必须至少运行：
|
||||
- `python scripts\smoke_public_auth_flow.py`
|
||||
- `python scripts\smoke_public_upload_flow.py`
|
||||
- 公开生成 smoke。
|
||||
- `/health` 版本必须等于当前生产 tag。
|
||||
- 资源巡检报告如有 `alerts`，不得忽略。
|
||||
|
||||
## 已有防回归测试
|
||||
---
|
||||
|
||||
## 5. 已有防回归测试
|
||||
|
||||
- `apps/web/src/api/auth.test.ts`：认证用户字段归一化，防止 `user_id/email_verified` 与 `id/is_email_verified` 漂移。
|
||||
- `tests/unit/test_release_scripts.py`：生产 artifact 部署、生产 Nginx 代理、禁用 subscription API 接入、Admin coming-soon 路由等门禁。
|
||||
- `tests/unit/test_release_scripts.py`：生产 artifact 部署、生产 Nginx 代理、Web recreate、runtime builder、版本注入、Worker 并发限制等门禁。
|
||||
- `tests/unit/test_production_resource_monitoring.py`：生产资源巡检脚本和 heartbeat 报告契约。
|
||||
- `tests/integration/test_projects.py`：项目详情和 workspace 上下文恢复。
|
||||
- `scripts/smoke_public_auth_flow.py`：公网注册、登录、`/auth/me`、`/workspaces` smoke。
|
||||
- `scripts/smoke_public_upload_flow.py`：公网工作空间、项目、素材库、上传和 ingest smoke。
|
||||
|
||||
## 后续工程化
|
||||
---
|
||||
|
||||
- API/worker 镜像发布应进一步升级为镜像仓库/预构建镜像模式。
|
||||
- 需要增加浏览器级 E2E，覆盖登录后创建工作空间、创建项目、上传素材、生成结果。
|
||||
- 需要 OpenAPI/前端 API 合约检查，避免路由和字段再次漂移。
|
||||
## 6. 当前已知风险
|
||||
|
||||
### 6.1 生产机规格偏小
|
||||
|
||||
现状：
|
||||
|
||||
- CPU：2 核。
|
||||
- 内存：约 1.7GiB。
|
||||
- swap：已补 2GiB。
|
||||
- 根分区：约 40GiB，最近巡检约 79%。
|
||||
|
||||
影响：
|
||||
|
||||
- 资源抖动可能导致 TLS/SSH/业务入口超时。
|
||||
- swap 和 Worker 并发限制是缓解，不是长期扩容替代。
|
||||
|
||||
建议：
|
||||
|
||||
- 生产机升级到至少 4GiB，推荐 8GiB。
|
||||
|
||||
### 6.2 Gitea 仍与生产业务同机
|
||||
|
||||
现状：
|
||||
|
||||
- 构建任务已拆到 runtime-builder。
|
||||
- Gitea 服务本体仍在生产业务机。
|
||||
|
||||
影响：
|
||||
|
||||
- Git/Gitea 与生产业务共享 CPU、内存、磁盘和网络入口。
|
||||
- 单机故障会同时影响代码仓库、发布入口和生产业务。
|
||||
|
||||
建议：
|
||||
|
||||
- 后续迁移 Gitea 到独立服务器，或升级当前生产机后再拆分。
|
||||
|
||||
---
|
||||
|
||||
## 7. 下一步
|
||||
|
||||
1. 执行真实浏览器 UAT：登录 → 工作空间 → 项目 → 批量上传 → 生成 → 下载。
|
||||
2. 继续扫权限边界：成片下载、生成任务、素材列表、任务日志。
|
||||
3. 处理生产资源长期风险：升级生产机或迁移 Gitea。
|
||||
4. 进入开发包 2：素材智能视图与素材缺口诊断。
|
||||
|
||||
@@ -0,0 +1,166 @@
|
||||
# 小虾 SaaS 生产 UAT 验收清单
|
||||
|
||||
> 基线版本：`v0.1.16`
|
||||
> 适用环境：`https://saas.xiaoxiajianji.com/`
|
||||
> 创建时间：2026-06-23
|
||||
|
||||
---
|
||||
|
||||
## 1. 使用规则
|
||||
|
||||
- 每次生产发布后，至少按本清单跑一遍主链路。
|
||||
- 如果任一步失败，不允许说“生产完成”。
|
||||
- 所有失败都要记录：页面、按钮、截图、浏览器错误、API 响应、用户账号、项目名、任务 ID。
|
||||
- 未开放功能必须显示“暂未开放”或禁用，不允许假成功。
|
||||
|
||||
---
|
||||
|
||||
## 2. 主链路 UAT
|
||||
|
||||
### 2.1 登录
|
||||
|
||||
- [ ] 打开 `https://saas.xiaoxiajianji.com/login`。
|
||||
- [ ] 输入账号密码。
|
||||
- [ ] 登录成功后进入工作空间页面。
|
||||
- [ ] 刷新页面后仍保持正确登录状态。
|
||||
- [ ] 如果登录态过期，能回到登录页，不出现“卡在工作空间加载失败”。
|
||||
|
||||
验收：用户可以稳定登录和刷新。
|
||||
|
||||
### 2.2 工作空间
|
||||
|
||||
- [ ] 打开工作空间列表。
|
||||
- [ ] 能看到已有工作空间。
|
||||
- [ ] 能创建新工作空间。
|
||||
- [ ] 能进入工作空间详情。
|
||||
- [ ] 直接刷新工作空间页面不丢状态。
|
||||
|
||||
验收：工作空间加载不报错。
|
||||
|
||||
### 2.3 项目
|
||||
|
||||
- [ ] 在工作空间内创建项目。
|
||||
- [ ] 能进入项目详情。
|
||||
- [ ] 能进入项目素材页。
|
||||
- [ ] 能进入项目生成页。
|
||||
- [ ] 能进入项目结果页。
|
||||
- [ ] 复制项目页 URL 后重新打开，workspace/project 上下文能恢复。
|
||||
|
||||
验收：项目页面刷新和直接 URL 都能正常使用。
|
||||
|
||||
### 2.4 素材上传
|
||||
|
||||
- [ ] 创建或选择素材库。
|
||||
- [ ] 上传 1 个素材。
|
||||
- [ ] 页面显示上传成功。
|
||||
- [ ] 上传多个素材。
|
||||
- [ ] 每个文件有独立成功/失败提示。
|
||||
- [ ] 上传时页面不被全局锁死。
|
||||
- [ ] 刷新后已上传素材仍可见。
|
||||
|
||||
验收：单文件和批量上传都可用。
|
||||
|
||||
### 2.5 视频生成
|
||||
|
||||
- [ ] 进入生成页。
|
||||
- [ ] 选择素材库。
|
||||
- [ ] 发起生成任务。
|
||||
- [ ] 能看到任务状态变化。
|
||||
- [ ] 生成成功后能进入结果。
|
||||
- [ ] 如果失败，错误提示必须说人话。
|
||||
|
||||
验收：生成任务可完成，失败时用户知道怎么办。
|
||||
|
||||
### 2.6 成片下载
|
||||
|
||||
- [ ] 打开结果页。
|
||||
- [ ] 能看到生成结果。
|
||||
- [ ] 点击下载。
|
||||
- [ ] 下载得到 MP4 文件。
|
||||
- [ ] 视频可以正常播放。
|
||||
|
||||
验收：用户能拿到可播放成片。
|
||||
|
||||
---
|
||||
|
||||
## 3. 暂未开放功能检查
|
||||
|
||||
以下入口如出现，必须禁用或显示“暂未开放”：
|
||||
|
||||
- [ ] Admin 后台。
|
||||
- [ ] 账单管理。
|
||||
- [ ] 订阅升级。
|
||||
- [ ] 配额变更。
|
||||
- [ ] 会话管理。
|
||||
- [ ] 全局成员管理。
|
||||
- [ ] 未完成的智能剪辑功能。
|
||||
|
||||
验收：没有假入口，没有假成功。
|
||||
|
||||
---
|
||||
|
||||
## 4. 权限边界 UAT
|
||||
|
||||
### 4.1 匿名用户
|
||||
|
||||
- [ ] 未登录访问工作空间，应跳转登录或返回 401。
|
||||
- [ ] 未登录访问项目，应跳转登录或返回 401。
|
||||
- [ ] 未登录访问上传接口，应返回 401。
|
||||
|
||||
### 4.2 非成员用户
|
||||
|
||||
- [ ] 用户 B 不能访问用户 A 的项目。
|
||||
- [ ] 用户 B 不能访问用户 A 的素材库。
|
||||
- [ ] 用户 B 不能上传到用户 A 的项目。
|
||||
- [ ] 用户 B 不能下载用户 A 的成片。
|
||||
|
||||
验收：跨账号不能越权。
|
||||
|
||||
---
|
||||
|
||||
## 5. 生产监控验收
|
||||
|
||||
- [ ] `https://saas-api.xiaoxiajianji.com/health` 返回 200。
|
||||
- [ ] `/health` 中 `version` 等于当前生产 tag。
|
||||
- [ ] `/var/lib/xiaoxia-ci/duty_report.json` 存在。
|
||||
- [ ] 巡检报告 `alerts` 如非空，已记录并处理。
|
||||
- [ ] API/Web/关键容器状态正常。
|
||||
|
||||
验收：生产版本和资源状态可观测。
|
||||
|
||||
---
|
||||
|
||||
## 6. 记录模板
|
||||
|
||||
```text
|
||||
UAT 日期：
|
||||
生产版本：
|
||||
测试账号：
|
||||
工作空间：
|
||||
项目：
|
||||
素材数量：
|
||||
生成任务 ID：
|
||||
结果：通过 / 不通过
|
||||
问题截图：
|
||||
问题描述：
|
||||
API 响应：
|
||||
处理结论：
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前 v0.1.16 验证结果
|
||||
|
||||
自动 smoke 已通过：
|
||||
|
||||
- [x] `public_auth_flow=ok`
|
||||
- [x] `public_upload_flow=ok`
|
||||
- [x] `public_generation_flow=ok`
|
||||
- [x] API health 返回 `version: v0.1.16`
|
||||
- [x] 生产资源巡检 cron 已启用
|
||||
|
||||
待真实浏览器确认：
|
||||
|
||||
- [ ] 老大真实账号完整 UAT。
|
||||
- [ ] 成片在浏览器/播放器中人工播放确认。
|
||||
- [ ] 未开放入口人工检查。
|
||||
@@ -0,0 +1,58 @@
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def test_current_release_surface_freezes_v016_capabilities():
|
||||
docs = Path("docs/CURRENT-RELEASE-SURFACE.md").read_text(encoding="utf-8")
|
||||
|
||||
assert "生产基线：`v0.1.16`" in docs
|
||||
assert "public_auth_flow=ok" in docs
|
||||
assert "public_upload_flow=ok" in docs
|
||||
assert "public_generation_flow=ok" in docs
|
||||
assert "version: v0.1.16" in docs
|
||||
assert "/var/lib/xiaoxia-ci/duty_report.json" in docs
|
||||
assert "Gitea 仍与生产业务同机" in docs
|
||||
|
||||
|
||||
def test_current_release_surface_keeps_unimplemented_features_closed():
|
||||
docs = Path("docs/CURRENT-RELEASE-SURFACE.md").read_text(encoding="utf-8")
|
||||
|
||||
for feature in [
|
||||
"订阅升级",
|
||||
"Admin 后台",
|
||||
"完整标题库",
|
||||
"素材缺口诊断",
|
||||
"统一任务中心",
|
||||
"ASR 字幕",
|
||||
"TTS 配音",
|
||||
]:
|
||||
assert feature in docs
|
||||
assert "不得假成功" in docs
|
||||
|
||||
|
||||
def test_production_uat_checklist_covers_main_user_flow():
|
||||
docs = Path("docs/PRODUCTION-UAT-CHECKLIST.md").read_text(encoding="utf-8")
|
||||
|
||||
for step in [
|
||||
"登录",
|
||||
"工作空间",
|
||||
"项目",
|
||||
"素材上传",
|
||||
"视频生成",
|
||||
"成片下载",
|
||||
"权限边界",
|
||||
"生产监控验收",
|
||||
]:
|
||||
assert step in docs
|
||||
for flow_step in ["登录", "工作空间", "项目", "批量上传", "生成", "下载"]:
|
||||
assert flow_step in docs
|
||||
assert "version` 等于当前生产 tag" in docs
|
||||
|
||||
|
||||
def test_production_uat_checklist_records_v016_smoke_results():
|
||||
docs = Path("docs/PRODUCTION-UAT-CHECKLIST.md").read_text(encoding="utf-8")
|
||||
|
||||
assert "当前 v0.1.16 验证结果" in docs
|
||||
assert "public_auth_flow=ok" in docs
|
||||
assert "public_upload_flow=ok" in docs
|
||||
assert "public_generation_flow=ok" in docs
|
||||
assert "老大真实账号完整 UAT" in docs
|
||||
Reference in New Issue
Block a user