# 代码状态标注（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
