Xiaoxia AI
308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
# 代码状态标注（2026-06-19）
|
||
|
||
> 本文档标注仓库中所有代码的当前状态，便于快速识别主线、兼容层、待迁移代码。
|
||
|
||
---
|
||
|
||
## 状态标签说明
|
||
|
||
- **✅ ACTIVE** - 当前主线代码，正在活跃使用
|
||
- **🔄 COMPAT** - 兼容层，为了向后兼容保留，但不是主线
|
||
- **⚠️ DEPRECATED** - 已废弃，计划删除
|
||
- **🚧 MIGRATE** - 待迁移到新主线
|
||
- **🧪 EXPERIMENTAL** - 实验性功能
|
||
|
||
---
|
||
|
||
## 一、领域层（Domain）
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
packages/domain/
|
||
├── entities.py ✅ 主领域模型（Asset, AssetLibrary, GenerationTask, GeneratedVideo）
|
||
├── classification.py ✅ 分类相关领域模型
|
||
├── project_management.py ✅ 项目管理领域模型
|
||
├── user.py ✅ 用户领域模型
|
||
├── permissions.py ✅ 权限领域模型
|
||
├── quota.py ✅ 配额领域模型
|
||
└── auth/ ✅ 认证领域服务
|
||
├── jwt_service.py
|
||
├── password_hasher.py
|
||
├── session_store.py
|
||
└── email_service.py
|
||
```
|
||
|
||
### 🔄 COMPAT - 兼容层
|
||
|
||
```
|
||
packages/domain/
|
||
├── asset.py 🔄 旧素材模型，仅用于兼容
|
||
├── asset_library.py 🔄 旧素材库模型，仅用于兼容
|
||
└── generated_video.py ✅ 实际已是主线，非兼容层
|
||
```
|
||
|
||
---
|
||
|
||
## 二、应用层（Application）
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
packages/application/
|
||
├── assets.py ✅ 素材用例
|
||
├── asset_libraries.py ✅ 素材库用例
|
||
├── classification_jobs.py ✅ 分类任务用例
|
||
├── ingest_jobs.py ✅ 摄入任务用例
|
||
├── generation_tasks.py ✅ 生成任务用例
|
||
├── generated_videos.py ✅ 生成结果用例
|
||
├── projects.py ✅ 项目用例
|
||
├── auth/ ✅ 认证用例
|
||
│ ├── login_use_case.py
|
||
│ ├── register_user_use_case.py
|
||
│ └── password_reset_use_case.py
|
||
└── workspace/ ✅ 工作空间用例
|
||
├── create_workspace_use_case.py
|
||
├── invite_member_use_case.py
|
||
└── subscription_use_case.py
|
||
```
|
||
|
||
---
|
||
|
||
## 三、仓储接口（Ports）
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
packages/ports/
|
||
├── classification_job_repository.py ✅ 分类任务仓储接口
|
||
├── ingest_job_repository.py ✅ 摄入任务仓储接口
|
||
├── generation_task_repository.py ✅ 生成任务仓储接口
|
||
├── generated_video_repository.py ✅ 生成结果仓储接口
|
||
├── project_repository.py ✅ 项目仓储接口
|
||
├── user_repository.py ✅ 用户仓储接口
|
||
├── workspace_repository.py ✅ 工作空间仓储接口
|
||
├── workspace_member_repository.py ✅ 工作空间成员仓储接口
|
||
└── workspace_invitation_repository.py ✅ 工作空间邀请仓储接口
|
||
```
|
||
|
||
### 🔄 COMPAT - 兼容层
|
||
|
||
```
|
||
packages/ports/
|
||
├── asset_repository.py 🔄 旧素材仓储接口，仅用于兼容
|
||
└── asset_library_repository.py 🔄 旧素材库仓储接口，仅用于兼容
|
||
```
|
||
|
||
---
|
||
|
||
## 四、适配器（Adapters）
|
||
|
||
### ✅ ACTIVE - 当前主线（SQLAlchemy）
|
||
|
||
```
|
||
packages/adapters/sqlalchemy_impl/
|
||
├── __init__.py
|
||
├── session.py ✅ 数据库会话管理
|
||
├── models.py ✅ SQLAlchemy 模型
|
||
├── asset_repository.py ✅ 素材仓储实现
|
||
├── asset_library_repository.py ✅ 素材库仓储实现
|
||
├── classification_job_repository.py ✅ 分类任务仓储实现
|
||
├── ingest_job_repository.py ✅ 摄入任务仓储实现
|
||
├── generation_task_repository.py ✅ 生成任务仓储实现
|
||
├── generated_video_repository.py ✅ 生成结果仓储实现
|
||
└── project_repository.py ✅ 项目仓储实现
|
||
```
|
||
|
||
### ✅ ACTIVE - 测试用（In-Memory）
|
||
|
||
```
|
||
packages/adapters/in_memory/
|
||
├── asset_repository.py ✅ 测试用内存实现
|
||
├── asset_library_repository.py ✅ 测试用内存实现
|
||
├── classification_job_repository.py ✅ 测试用内存实现
|
||
├── ingest_job_repository.py ✅ 测试用内存实现
|
||
├── user_repository.py ✅ 测试用内存实现
|
||
├── workspace_repository.py ✅ 测试用内存实现
|
||
├── workspace_member_repository.py ✅ 测试用内存实现
|
||
└── workspace_invitation_repository.py ✅ 测试用内存实现
|
||
```
|
||
|
||
### ✅ REMOVED - Postgres 旧实现
|
||
|
||
`packages/adapters/postgres/` 旧 psycopg adapter 已删除。
|
||
|
||
**说明**: SQLAlchemy 是当前唯一主线持久化 adapter，位于 `packages/adapters/sqlalchemy_impl/`。不要恢复旧 `packages/adapters/postgres/*`；架构守卫会阻止运行时代码重新引用 `packages.adapters.postgres` 或 `Postgres*` 路径。
|
||
|
||
---
|
||
|
||
## 五、API 层
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
apps/api/app/api/routes/
|
||
├── health.py ✅ 健康检查
|
||
├── auth.py ✅ 认证相关
|
||
├── workspaces.py ✅ 工作空间
|
||
├── projects.py ✅ 项目
|
||
├── upload.py ✅ 文件上传
|
||
├── assets.py ✅ 素材管理
|
||
├── asset_libraries.py ✅ 素材库管理
|
||
├── ingest_jobs.py ✅ 摄入任务
|
||
├── classification_jobs.py ✅ 分类任务
|
||
├── generation_tasks.py ✅ 生成任务
|
||
├── generated_videos.py ✅ 生成结果
|
||
└── project_management.py ✅ 项目管理高级功能
|
||
```
|
||
|
||
---
|
||
|
||
## 六、Worker 层
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
apps/worker/
|
||
├── celery_app.py ✅ Celery 应用
|
||
├── tasks.py ✅ 生成任务（主入口）
|
||
└── worker_app/
|
||
├── db.py ✅ 数据库会话
|
||
└── tasks/
|
||
├── health.py ✅ 健康检查任务
|
||
├── ingest.py ✅ 摄入任务
|
||
└── classification.py ✅ 分类任务
|
||
```
|
||
|
||
---
|
||
|
||
## 七、测试层
|
||
|
||
### ✅ ACTIVE - 当前主线测试
|
||
|
||
```
|
||
tests/integration/
|
||
├── test_asset_tags.py ✅ 素材标签测试
|
||
├── test_ingest_pipeline.py ✅ 摄入流程测试
|
||
├── test_upload_pipeline.py ✅ 上传流程测试
|
||
├── test_classification_pipeline.py ✅ 分类流程测试
|
||
├── test_generation_pipeline.py ✅ 生成流程测试
|
||
└── test_projects.py ✅ 项目测试
|
||
```
|
||
|
||
### ✅ ACTIVE - 单元测试
|
||
|
||
```
|
||
tests/unit/
|
||
├── test_jwt_service.py ✅ JWT 服务测试
|
||
├── test_password_hasher.py ✅ 密码哈希测试
|
||
├── test_session_store.py ✅ 会话存储测试
|
||
├── test_email_service.py ✅ 邮件服务测试
|
||
├── test_permissions.py ✅ 权限测试
|
||
├── test_quota.py ✅ 配额测试
|
||
├── test_login_use_case.py ✅ 登录用例测试
|
||
├── test_register_user_use_case.py ✅ 注册用例测试
|
||
├── test_password_reset_use_case.py ✅ 密码重置用例测试
|
||
├── test_create_workspace_use_case.py ✅ 创建工作空间用例测试
|
||
├── test_invite_member_use_case.py ✅ 邀请成员用例测试
|
||
├── test_accept_invitation_use_case.py ✅ 接受邀请用例测试
|
||
├── test_list_members_use_case.py ✅ 列出成员用例测试
|
||
├── test_remove_member_use_case.py ✅ 移除成员用例测试
|
||
├── test_update_member_role_use_case.py ✅ 更新成员角色用例测试
|
||
├── test_list_workspaces_use_case.py ✅ 列出工作空间用例测试
|
||
└── test_subscription_use_case.py ✅ 订阅用例测试
|
||
```
|
||
|
||
### 🚧 MIGRATE - 待更新测试
|
||
|
||
```
|
||
tests/unit/
|
||
└── test_api.py 🚧 需要按新主线重写
|
||
```
|
||
|
||
---
|
||
|
||
## 八、前端层
|
||
|
||
### ✅ ACTIVE - 当前主线
|
||
|
||
```
|
||
apps/web/src/
|
||
├── api/
|
||
│ ├── client.ts ✅ API 客户端
|
||
│ ├── auth.ts ✅ 认证 API
|
||
│ ├── workspace.ts ✅ 工作空间 API
|
||
│ ├── projects.ts ✅ 项目 API
|
||
│ ├── assets.ts ✅ 素材 API
|
||
│ ├── generation.ts ✅ 生成 API
|
||
│ └── subscription.ts ✅ 订阅 API
|
||
├── pages/
|
||
│ ├── auth/ ✅ 认证页面
|
||
│ ├── workspace/ ✅ 工作空间页面
|
||
│ │ ├── ProjectGeneration.tsx ✅ 生成页
|
||
│ │ └── ProjectResults.tsx ✅ 结果页
|
||
│ ├── profile/ ✅ 个人设置页面
|
||
│ ├── subscription/ ✅ 订阅页面
|
||
│ └── admin/ ✅ 管理页面
|
||
└── hooks/
|
||
├── useAuth.ts ✅ 认证 Hook
|
||
└── useWorkspace.ts ✅ 工作空间 Hook
|
||
```
|
||
|
||
---
|
||
|
||
## 九、快速定位指南
|
||
|
||
### 我想找...
|
||
|
||
**素材上传流程**:
|
||
```
|
||
apps/api/app/api/routes/upload.py (API)
|
||
↓
|
||
apps/api/app/core/storage.py (OSS / generated-files fallback)
|
||
↓
|
||
packages/domain/entities.py::Asset (领域模型)
|
||
↓
|
||
packages/adapters/sqlalchemy_impl/asset_repository.py (持久化)
|
||
```
|
||
|
||
**视频生成流程**:
|
||
```
|
||
apps/api/app/api/routes/generation_tasks.py (API)
|
||
↓
|
||
packages/application/generation_tasks.py (用例)
|
||
↓
|
||
apps/worker/tasks.py::generate_video (Worker)
|
||
↓
|
||
packages/adapters/sqlalchemy_impl/generation_task_repository.py (持久化)
|
||
```
|
||
|
||
**用户认证流程**:
|
||
```
|
||
apps/api/app/api/routes/auth.py (API)
|
||
↓
|
||
packages/application/auth/login_use_case.py (用例)
|
||
↓
|
||
packages/domain/auth/jwt_service.py (JWT)
|
||
↓
|
||
packages/domain/auth/session_store.py (会话)
|
||
```
|
||
|
||
---
|
||
|
||
## 十、清理计划
|
||
|
||
### 可以安全删除（待定）
|
||
- 暂无，所有兼容层目前仍保留
|
||
|
||
### 需要迁移到新主线
|
||
- 无待迁移代码
|
||
|
||
### 需要补充测试
|
||
- `test_api.py` 需要按新主线重写
|
||
|
||
---
|
||
|
||
**维护人**: 小虾 🦐
|
||
**最后更新**: 2026-06-19 10:10 GMT+8
|