feat: bootstrap commercial AI drama platform

2026-08-24 10:24:34 +08:00
commit ffb27d845b
100 changed files with 35314 additions and 0 deletions
@@ -0,0 +1,316 @@
+# API 与本地执行器参考
+
+## 认证
+
+除健康检查和登录接口外，业务接口要求：
+
+```http
+Authorization: Bearer <session-token>
+```
+
+服务端会按以下顺序解析访问边界：
+
+```text
+user → organization → workspace → project → permission
+```
+
+请求头中的 `x-user-id`、`x-organization-id`、`x-workspace-id` 和 `x-project-id` 只有在显式设置 `AI_DRAMA_ALLOW_DEV_CONTEXT=1` 时才可用于本地接口调试。正式部署不要启用该 bypass。
+
+## 业务 API 分组
+
+| 分组 | 主要接口 | 典型权限 |
+| --- | --- | --- |
+| 认证与会话 | `/api/auth/login`、`/api/auth/session`、`/api/auth/logout`、`/api/auth/password`、`/api/auth/sessions/*` | 登录用户 |
+| MFA 与企业身份 | `/api/auth/login/mfa`、`/api/auth/mfa/*`、`/api/auth/sso/*`、`/api/system/identity/*` | MFA 管理或 `system:settings:*` |
+| 租户上下文 | `/api/context`、`/api/organizations/*`、`/api/workspaces/*`、`/api/projects/*` | 按组织 / 工作区 / 项目角色 |
+| 用户通知中心 | `/api/notifications`、`/api/notifications/:id`、`/api/notifications/read-all`、`/api/notification-preferences` | 登录用户 / 当前组织 |
+| 内容生产 | `/api/production/catalog`、`/api/production/graph`、`/api/production/script/*`、`/api/production/bible`、`/api/production/shots/*` | `script:edit`、`asset:edit`、`job:create` |
+| 资产与声音 | `/api/assets/*`、`/api/assets/:assetId/versions/upload`、`/api/assets/:assetId/verify`、`/api/assets/:assetId/versions/:versionId/restore` | `asset:edit`、`voice:edit` |
+| 生成任务 | `/api/jobs`、`/api/jobs/:jobId/*`、`/api/adapters/dry-run` | `job:create` 或 `queue:manage` |
+| 审片与交付 | `/api/production/reviews/*`、`/api/production/qa/run`、`/api/production/deliveries/*`、`/api/exports/write` | `qa:review`、`delivery:approve` |
+| 组织运营 | `/api/usage`、`/api/billing`、`/api/organizations/:id/commercial`、`/api/organizations/:id/usage`、`/api/organizations/:id/usage/export`、`/api/organizations/:id/billing`、`/api/organizations/:id/quotas/:quotaId`、`/api/audit`、`/api/audit/export` | `usage:view`、`billing:manage`、`quota:manage`、`audit:view` |
+| 模型中台 | `/api/platform/models`、`/api/platform/models/register`、`/api/platform/models/:id/probe` | `model:manage` |
+| 全局用户治理 | `/api/system/users`、`/api/system/users/:userId`、`/api/system/users/:userId/revoke-sessions` | 仅系统管理员 |
+| 系统设置 | `/api/system/config`、`/api/system/health`、`/api/system/readiness`、`/api/system/backups`、`/api/system/feature-flags`、`/api/system/notifications`、`/api/system/api-clients` | 系统管理员 / 对应系统权限 |
+
+未登录返回 `401`；已登录但没有作用域或权限返回 `403`。接口不会因为前端菜单隐藏就跳过后端检查。
+
+### 审计与合规中心
+
+```http
+GET /api/audit?page=1&pageSize=25&query=&action=&targetType=&targetId=&result=&actorUserId=&from=YYYY-MM-DD&to=YYYY-MM-DD
+GET /api/audit/:auditId
+GET /api/audit/export?pageSize=500&format=json
+GET /api/audit/export?pageSize=500&format=csv
+```
+
+审计列表由服务端分页并返回 `auditLog`、`pagination`、`facets` 和 `scope`。`org_owner` / `org_admin` 默认只能看当前组织；其他拥有审计读取权限的角色只能看当前工作区 / 项目及组织级事件；系统管理员获得全局视图。查询参数只负责缩小范围，不能扩大当前作用域；跨组织、跨工作区或跨项目筛选会返回 `403`。详情接口同时返回同一对象的关联审计和可关联的账号安全事件。导出支持 JSON 和 UTF-8 CSV，并复用相同的服务端权限与筛选条件。
+
+### 用户通知中心与组织级偏好
+
+通知中心是用户在当前组织、当前工作区内的收件箱，不等同于管理员配置的邮件或 Webhook 投递渠道。通知事件由服务端按组织成员、工作区/项目成员和事件类型计算收件人，前端不能扩大收件范围。
+
+```http
+GET   /api/notifications?limit=60&unreadOnly=1
+PATCH /api/notifications/:notificationId       # { "read": true | false }
+POST  /api/notifications/read-all
+GET   /api/notification-preferences
+PATCH /api/notification-preferences/:category  # { "enabled": true | false }
+```
+
+`limit` 会被服务端限制在 1-200；`unreadOnly=1` 只改变列表，不改变返回的 `unreadCount`。单条已读/未读和“全部已读”都只作用于当前用户、当前组织以及当前工作区可见的通知，跨用户、跨组织或不属于当前作用域的通知返回 `404`。
+
+通知偏好按“用户 + 组织 + 类别”保存，切换组织后使用独立配置。当前类别包括：生成任务、审片、交付、协作任务、组织访问、用量配额和系统通知。服务端在创建用户通知前真正检查偏好，关闭某类后不会只在前端隐藏，而是不会写入该用户的收件箱；重新开启只影响后续事件，不会自动补发历史消息。
+
+### 项目协作任务
+
+协作任务是可分派、可追踪的项目记录，不等同于由生成任务或审片状态推导出来的 `/api/work-items` 待办。任务只能落在当前组织 / 工作区 / 项目作用域内，并保存标题、说明、类型、优先级、负责人、截止时间、关联页面、状态、完成时间和审计记录。
+
+```http
+GET   /api/tasks?status=all&assignedTo=me&limit=100
+POST  /api/tasks
+PATCH /api/tasks/:taskId
+```
+
+`task:manage` 可以创建、分派和编辑任务；`task:complete` 的成员只能更新自己负责任务的状态，不能修改标题、负责人、优先级或截止时间；`task:view` 只能读取当前项目任务。任务分派会按用户通知偏好创建站内消息，任务状态变更和跨组织访问也会写入权限边界和审计流。项目归档后任务写操作返回 `409 project_archived`。
+
+系统管理员配置的 `/api/system/notifications` 仍负责组织级本地日志/Webhook 渠道和投递审计；Webhook 默认只允许投递到本地私有 HTTP 地址，云端或付费节点不会被平台自动启用。
+
+### 项目生命周期与只读归档
+
+项目是可审计的生产边界，不是只有名称和状态的目录项。创建项目时会持久化 `template_id`，并立即初始化系列、第一季、试播集和一个 starter shot；新项目默认处于 `draft`。
+
+```http
+PATCH /api/projects/:projectId
+POST  /api/projects/:projectId/lifecycle
+```
+
+生命周期动作包括：`pause`、`resume`、`activate`、`submit-review`、`archive`、`restore`。归档前服务端会检查 `queued`、`running` 和 `blocked` 生成任务；存在未完成任务时返回 `409 project_has_active_jobs`。归档会保存 `archived_at`、`archived_by` 和 `archived_from_status`，恢复时回到归档前状态。
+
+归档项目仍可读取生产图谱、任务历史、审计和交付资料，但剧本、资产、声音、生成、QA、交付审批等写操作由后端统一返回 `409 project_archived`。前端项目工厂只负责呈现可用操作，不能替代服务端权限边界。
+
+### 系统生产就绪度与数据库快照
+
+系统管理员可读取部署边界和当前运行时状态：
+
+```text
+GET  /api/system/readiness
+GET  /api/system/backups
+POST /api/system/backups
+```
+
+`/api/system/readiness` 会明确区分当前激活运行时与目标 provider：业务数据库当前返回 `node:sqlite`，PostgreSQL、Redis、S3-compatible 对象存储只有在对应 `PLATFORM_*` 环境变量存在时标记为“已配置”，不会把 compose 注入误报成已经完成业务迁移。`POST /api/system/backups` 使用 SQLite `VACUUM INTO` 创建 `data/backups/` 下的快照，并写入 `system.database.backup_created` 审计事件；接口不提供在线恢复，恢复必须经过停机审查和人工确认。
+
+### 商业运营、席位与配额
+
+组织管理员或组织所有者可以读取当前组织的套餐、席位预留、工作区配额和本月用量：
+
+```text
+GET   /api/organizations/:organizationId/commercial
+GET   /api/organizations/:organizationId/commercial/export
+PATCH /api/organizations/:organizationId/billing
+PATCH /api/organizations/:organizationId/quotas/:quotaId
+PATCH /api/organizations/:organizationId/cost-centers/:costCenterId
+```
+
+`billing` 更新接受 `planName`、`billingCycle`（monthly / quarterly / annual）、`currency`、`baseFee`、`seatUnitPrice`、`storageUnitPrice`、`clipUnitPrice`、`seatLimit`、`storageGb`、`monthlyClipQuota`、`quotaWarningPercent`、`localRunnerOnly` 和 `cloudConnectorsRequireApproval`。服务端会阻止席位低于活跃成员加待处理邀请、片段额度低于本月已用量、存储额度低于已记录用量的修改，并记录 `billing.account.updated` 审计事件和可查询的 `billing_account_events` 变更记录。
+
+工作区配额不能超过组织套餐上限，也不能低于已用量；违反时分别返回 `409 quota_above_plan` 或 `409 quota_below_usage`。普通成员即使知道接口路径，也会收到 `403 permission_denied`，前端菜单隐藏不构成权限边界。
+
+商业运营响应额外包含 `quotaWarnings`、`costCenters`、按工作区拆分的 `costCenterDetail`、`billingHistory` 和 `usageTrend`。`usageTrend` 是最近 31 天按自然日聚合的数组，每项为 `{ day, units, estimatedCost, events }`；没有事件的日期不会伪造为零值。成本中心预算由 `billing:manage` 控制，导出接口返回可归档的完整 JSON，不会把云端或付费连接器伪装成本地成本。
+
+事件级用量中心用于账务核对、配额追踪和成本归属：
+
+```text
+GET /api/organizations/:organizationId/usage?page=1&pageSize=25&from=YYYY-MM-DD&to=YYYY-MM-DD&workspaceId=&projectId=&userId=&kind=&unitName=&costCenter=&query=
+GET /api/organizations/:organizationId/usage/export?format=json&from=YYYY-MM-DD&to=YYYY-MM-DD&workspaceId=&projectId=&userId=&kind=&unitName=&costCenter=&query=
+GET /api/organizations/:organizationId/usage/export?format=csv&from=YYYY-MM-DD&to=YYYY-MM-DD&workspaceId=&projectId=&userId=&kind=&unitName=&costCenter=&query=
+```
+
+明细接口返回 `items`、`summary`、`pagination` 和 `facets`。每条事件包含时间、工作区、项目、操作者、事件类型、计量单位、估算成本、成本中心和元数据；筛选、分页和导出都在服务端执行。组织管理员可查看本组织范围，普通成员即使直接调用路径也会收到 `403`；成本中心和配额预警在管理台可以回跳到同一组明细筛选条件。
+
+组织账单台账用于把套餐、席位、存储、片段和事件级本地计量固化为可审计的账期快照：
+
+```text
+GET  /api/organizations/:organizationId/invoices?status=&query=&page=1&pageSize=25
+GET  /api/organizations/:organizationId/invoices/:invoiceId
+POST /api/organizations/:organizationId/invoices/generate
+POST /api/organizations/:organizationId/invoices/:invoiceId/status
+GET  /api/organizations/:organizationId/invoices/export?format=json|csv&status=&query=
+```
+
+只有拥有 `billing:manage` 的组织管理员或组织所有者可以生成账单、修改账单状态和编辑计价参数；拥有 `usage:view` 的角色可以读取账单台账。普通成员直接调用接口也会收到 `403 permission_denied`，跨组织读取会收到 `403 organization_forbidden`。
+
+`generate` 默认按组织套餐周期生成当前账期草稿，也接受成对的 `periodStart` / `periodEnd`、`taxRate` 和 `dueDays`。同一组织同一账期通过数据库唯一约束保证幂等，重复生成返回原账单而不会覆盖原快照。账单状态机为 `draft -> issued -> paid`，`issued` 可以转为 `overdue` 或 `void`，`overdue` 可以补记为 `paid`；已支付和已作废账单不可逆修改。每次生成和状态变更都会写入账单事件及组织审计日志，详情接口会返回 `lines` 明细。
+
+套餐接口的计价字段包括 `baseFee`、`seatUnitPrice`、`storageUnitPrice` 和 `clipUnitPrice`，默认值为 0；本地环境不会凭空产生收费。生成账单时会保存套餐、席位、工作区存储、片段用量、成本中心和税率快照，JSON/CSV 导出可用于后续财务系统适配。
+
+### 组织邀请生命周期
+
+组织管理员或拥有 `organization:members:invite` 的角色可以管理成员邀请：
+
+```text
+GET  /api/organizations/:organizationId
+GET  /api/organizations/:organizationId/members
+POST /api/organizations/:organizationId/invitations
+POST /api/organizations/:organizationId/invitations/:invitationId/resend
+POST /api/organizations/:organizationId/invitations/:invitationId/revoke
+GET  /api/invitations/preview?token=:token
+POST /api/auth/register
+```
+
+创建或重发邀请时，服务端只在当前响应返回一次性 `inviteToken` 和 `acceptUrl`；数据库保存的是令牌哈希和短提示，不保存明文令牌。邀请默认 7 天过期，过期邀请不会继续占用席位。重发会替换令牌哈希，使旧注册链接立即返回 `404 invitation_not_found`；撤销会清空令牌哈希、返回 `revoked`，并释放待入组席位。未登录预览仍可读取邀请范围，但注册时会再次校验令牌、邮箱和有效期。
+
+普通成员调用组织邀请接口返回 `403 permission_denied`；重复邀请同一邮箱返回 `409 invitation_already_pending`，已是组织成员的邮箱返回 `409 invitation_recipient_already_member`。
+
+### MFA
+
+- `POST /api/auth/login` 在账号启用 TOTP 后返回 `mfaRequired` 和短时 `challengeToken`，不创建正式会话。
+- `POST /api/auth/login/mfa` 使用 `challengeToken + code` 完成二次验证并创建 Bearer session；挑战 5 分钟过期，连续错误 5 次锁定。
+- `GET /api/auth/mfa`、`POST /api/auth/mfa/setup`、`POST /api/auth/mfa/enable`、`POST /api/auth/mfa/setup/cancel`、`POST /api/auth/mfa/disable` 只接受真实浏览器 session。
+- MFA 密钥使用 AES-GCM 加密；生产部署应设置独立的 `AI_DRAMA_MFA_ENCRYPTION_KEY`，不要依赖默认开发密钥。
+
+### 企业身份中心
+
+系统管理员可通过以下接口管理身份控制面：
+
+```text
+GET   /api/system/identity
+PATCH /api/system/identity/policy
+POST  /api/system/identity/providers
+PATCH /api/system/identity/providers/:providerId
+POST  /api/system/identity/providers/:providerId/probe
+POST  /api/system/identity/directory-syncs
+PATCH /api/system/identity/directory-syncs/:directoryId
+POST  /api/system/identity/directory-syncs/:directoryId/rotate-token
+GET   /api/auth/sso/providers
+GET   /api/auth/sso/start?providerId=:id&returnTo=/
+GET   /api/auth/sso/callback
+POST  /api/auth/sso/redeem
+```
+
+OIDC 已实现 Authorization Code + PKCE、state/nonce 一次性状态、ID Token 签名校验（JWKS）、claims 映射、按 Provider 绑定组织/工作区、自动创建成员和正式 Bearer session。回调不会把 session token 放进 URL，而是跳转到前端兑换 60 秒一次性票据；票据重放返回 `401`。如果用户启用了 MFA，票据兑换会返回现有 MFA challenge/enrollment challenge，再复用 `/api/auth/login/mfa` 或 `/api/auth/mfa/enroll/*`。
+
+提供商配置只保存 `clientSecretRef` 或 `idpCertRef` 环境变量引用，不保存 Client Secret 或 SAML 证书正文。OIDC 已实现 discovery 探测、Authorization Code + PKCE、state/nonce、JWKS 签名校验和一次性 SSO ticket。SAML 已实现 HTTP-Redirect AuthnRequest、持久化 RelayState、HTTP-POST ACS、签名/Audience/时间窗口/`InResponseTo` 校验、组织/工作区入组、MFA 和一次性 SSO ticket；ACS 不接受前端提交的用户身份。
+
+### 全局用户治理
+
+系统管理员可以跨组织查询用户、查看组织/工作区/项目归属、MFA 状态、最近登录和活跃会话：
+
+```text
+GET   /api/system/users?query=&status=&limit=100
+POST  /api/system/users
+GET   /api/system/users/:userId
+PATCH /api/system/users/:userId              # status: active | suspended
+POST  /api/system/users/:userId/reset-password
+POST  /api/system/users/:userId/reset-mfa
+POST  /api/system/users/:userId/memberships
+POST  /api/system/users/:userId/revoke-sessions
+```
+
+系统管理员可以手动创建账号并一次性取得初始密码、重置密码或 MFA、授予/移除系统管理员身份，并将用户加入指定组织、工作区和项目。加入关系会经过组织席位、层级归属和角色 scope 校验。停用或安全重置会立即撤销该用户的全部 Bearer session；不能停用当前系统管理员，也不能停用最后一个系统管理员或组织唯一所有者。所有状态变化、密码/MFA 重置、归属变化和强制会话撤销都会写入审计日志。组织管理员仍只能访问本组织成员接口，不能读取全局目录。
+
+生产部署至少应设置：`AI_DRAMA_SESSION_SECRET`、`AI_DRAMA_MFA_ENCRYPTION_KEY`、`AI_DRAMA_OIDC_STORAGE_KEY`、`AI_DRAMA_FRONTEND_ORIGIN` 和每个 Provider 引用的 Client Secret 环境变量。默认回调地址为 `http://127.0.0.1:8787/api/auth/sso/callback`，多实例部署请使用固定的 `AI_DRAMA_OIDC_REDIRECT_URI`。
+
+SCIM 目录由管理员创建后得到一次性 Bearer 令牌；令牌只保存 SHA-256 哈希。启用目录后，使用该令牌调用：
+
+```text
+GET    /scim/v2.0/:directoryId/Users
+POST   /scim/v2.0/:directoryId/Users
+PATCH  /scim/v2.0/:directoryId/Users/:userId
+DELETE /scim/v2.0/:directoryId/Users/:userId
+```
+
+SCIM 用户只会进入该目录绑定的组织，停用操作会同时停用组织成员资格，不能跨组织写入。
+
+资产文件版本会登记 `fileName`、`mimeType`、`fileSize` 和 `contentSha256`。`POST /api/assets/:assetId/versions/upload` 写入新的真实文件版本，`POST /api/assets/:assetId/verify` 重新读取文件并比较哈希/大小，验证结果写入审计日志；`GET /api/assets/:assetId/content` 返回 ETag，便于下游缓存和交付校验。
+
+## Worker API
+
+本地 API 启动时会自动启动本地 Worker；不需要额外启动第二个 Worker 进程。Worker 会：
+
+- 使用数据库租约 `leased_by` / `leased_at` 领取任务，避免多个 Runner 重复执行。
+- 受 `AI_DRAMA_WORKER_CONCURRENCY` 限制，默认并发为 `2`，最大为 `8`。
+- 按 `AI_DRAMA_WORKER_POLL_MS` 轮询，默认 `1200ms`。
+- 只领取 `status=queued`、依赖已完成、连接器 `status=ready` 且 `cost_mode=local` 的任务。
+- 连接器异常时保留 attempt、错误信息、审计事件和通知事件；未达到 `max_attempts` 会按指数退避自动重新排队，超过上限才保持 `failed`。
+- 发现 `leased_at` 超时的 running 任务时会回收租约，按最大尝试次数重新排队或标记失败，避免 Worker 进程退出后任务永久卡住。
+- 心跳、队列最老任务等待时长和告警级别会写入 Worker 状态，管理员可以批量重试或取消任务。
+
+```text
+GET  /api/admin/queue
+POST /api/admin/queue/batch       # action: retry | cancel | priority
+GET  /api/system/worker
+POST /api/system/worker/dispatch
+```
+
+`GET /api/system/worker` 返回 `workerId`、`healthStatus`、心跳年龄、过期阈值、并发数、轮询间隔、队列深度、队列告警、当前执行数、最近领取 / 完成 / 失败 / 回收 / 重试时间和最后错误。`POST /api/system/worker/dispatch` 用于管理员立即触发一次领取，适合排障和演示。
+
+可选环境变量：
+
+```text
+AI_DRAMA_WORKER_ENABLED=1
+AI_DRAMA_WORKER_ID=local-worker-<host>
+AI_DRAMA_WORKER_POLL_MS=1200
+AI_DRAMA_WORKER_CONCURRENCY=2
+AI_DRAMA_WORKER_LEASE_MS=300000
+AI_DRAMA_WORKER_STALE_MS=30000
+```
+
+如果设置 `AI_DRAMA_WORKER_ENABLED=0`，任务不会自动执行，后台仍会显示 Worker 已暂停。
+
+## 模型协议适配器
+
+模型连接器在模型中台注册，密钥只保存为环境变量名，不保存密钥本身：
+
+```json
+{
+  "label": "本地单画面图片服务",
+  "endpoint": "http://127.0.0.1:7860/api/generate/image",
+  "kind": "http-json",
+  "capability": ["text-to-image", "single-frame"],
+  "costMode": "local",
+  "authEnv": "LOCAL_IMAGE_TOKEN",
+  "protocol": {
+    "healthRoute": "health",
+    "routes": { "image": "generate" },
+    "models": { "image": "qwen-image-local" }
+  }
+}
+```
+
+支持三种协议：
+
+- `http-json`：向 `endpoint` POST 完整生产合同和 `execution` 元数据。
+- `openai-compatible`：按 `image`、`video`、`tts`、`asr`、`chat` 选择路由和模型；图片请求固定发送 `n: 1`。
+- `comfyui`：向 `prompt` 路由提交工作流，作为可选桥接，不是默认生产链路。
+
+图片任务会检查响应中的 `data`、`images` 或 `outputs` 数组，必须恰好返回一项；返回多张、拼图、分屏或 contact sheet 的结果会进入失败状态，不会进入后续视频链路。
+
+外部或混合成本连接器默认需要管理员显式审批；本地 Worker 不会自动领取 `mixed` / `cloud` 任务。
+
+## 启动与验证
+
+```bash
+cd /Users/xz/Documents/daima/ai短剧/ai-drama-platform
+npm run api
+npm run dev
+```
+
+验证顺序建议：
+
+```bash
+npm run build
+npm run smoke:identity
+npm run smoke:system-users
+npm run smoke:commercial-ops
+npm run smoke:oidc
+npm run smoke:tenant
+npm run smoke:creator-suite
+npm run smoke:ops
+npm run smoke:production-catalog
+npm run smoke:worker
+npm run smoke:all
+```
+
+多个 smoke 会写入同一个 SQLite 文件，应顺序执行。
@@ -0,0 +1,63 @@
+# 本地化 AI 短剧/漫剧平台架构
+
+## 产品模块
+
+### 三类产品面
+
+- **创作空间**：我的工作台、项目工厂、剧本拆解、Series Bible、资产与选角、Continuity Ledger、导演工作台、生成任务、审片和交付。
+- **管理员后台**：管理概览、组织与工作区、用户与权限、模型与 Runner、队列与任务、用量与成本、审计与合规。
+- **系统设置**：系统健康、部署模式、存储、队列并发、单画面策略、真实末帧策略、固定声线、QA 门、通知、API 客户端和功能开关。
+
+三类产品面共享同一套上下文选择器，但权限边界不同。组织管理员治理租户内资源；系统管理员治理本地部署实例和平台级策略。
+
+- 前端生产台：生产总控、剧本拆解、资产选角、导演工作台、生成队列、审片中心、交付运营。
+- 数据核心：series bible、character locks、location locks、prop locks、shot list、voice lines、continuity ledger、generation jobs、QA results。
+- 生成适配器：默认对接用户自有模型平台；支持自定义 HTTP JSON、OpenAI-compatible 本地网关和 NewAPI 音频中转；ComfyUI 为可选适配器。
+- 质检门：一图一画面、连续性、IndexTTS-2.5 固定配音、paraformer-zh-long 声音/字幕/ASR 对齐、片段衔接。
+- 交付目录：prompt pack、配音台词表、剪辑合成清单、QA 结果和最终视频工程目录。
+
+## 系统治理数据
+
+- `system_settings`：部署和生成策略的持久化键值，支持类型化编辑和审计。
+- `feature_flags`：系统范围功能开关，默认关闭外部云连接器和非必要适配器。
+- `notification_channels`：本地事件日志和可选 Webhook。
+- `api_clients`：本地 Runner/企业集成客户端及 scope。
+- `service_health`：本地 API、SQLite 和各类 Runner 的健康、延迟、队列深度。
+- `system_admins`：独立于组织角色的系统管理员身份。
+
+## 本地执行层
+
+API 进程启动时自动初始化 `server/worker.mjs`，Worker 通过数据库租约领取可执行任务，并把执行状态、attempt、错误、用量和审计事件写回 SQLite。领取条件由服务端强制执行：任务必须是 `queued`，前置依赖必须完成，连接器必须 `ready` 且 `cost_mode=local`。因此管理员可以在队列页看到真实的在线状态、并发、队列深度、最近心跳和失败原因，而不会把云端任务伪装成本地自动执行。
+
+Worker 运营层还维护租约超时回收、最大尝试次数、指数退避、队列最老等待时长和心跳失效判断。管理员可通过 `/api/admin/queue/batch` 批量重试/取消，并通过 `/api/system/worker` 读取告警状态；这部分状态不是前端计算，而是由本地 Worker 和数据库共同写回。
+
+商业运营数据按组织保存账单周期、配额预警阈值、账单变更历史和成本中心。系统管理员用户治理与组织管理员成员治理分开：系统管理员可以创建全局账号、重置密码/MFA、调整组织/工作区/项目归属；所有动作都经过后端 session、scope 和 role 校验并写入审计。
+
+模型执行请求统一经过 `server/execution.mjs` 的协议层：自定义 HTTP JSON 发送生产合同，OpenAI-compatible 按操作映射标准路由，ComfyUI 只负责 optional workflow bridge。认证信息通过 `authEnv` 指向进程环境变量，数据库和导出包不保存密钥。
+
+## 推荐流水线
+
+1. 写 series bible 和 episode card。
+2. 锁定角色、服装、声音、场景、道具、天气和固定机位。
+3. 生成每个镜头的一张完整单画面关键帧，输出数量必须等于 1。
+4. 后续镜头优先用上一段视频的实际末帧作为首帧；大跨度场景先插入过渡镜头。
+5. 台词先走 NewAPI/IndexTTS-2.5 固定 TTS 声线，使用 `prompt_speech` 参考音频锁定角色；无法口型同步时使用侧脸、背影、低头、远景、反应镜头、环境插入镜头。
+6. 音频生成后走 NewAPI/paraformer-zh-long 的 `verbose_json` 识别，用 ASR 文本校验台词准确性，用词级时间戳生成字幕时间轴。
+7. 视频片段通过 QA 后进入剪辑合成。
+
+生成任务在进入 Worker 前还会经过单画面、连续性、成本策略和外部连接审批门；图片响应中 `data`、`images`、`outputs` 任一数组都必须恰好有一项。
+
+## 旧资产复用
+
+- `/Users/xz/Documents/daima/ai短剧/codex_qu_2026-08-15/work/rebuild_no_narration_v1.py`：单画面正负约束、Qwen Image、QwenEdit、H3 首尾帧桥接、输出数量检查。
+- `/Users/xz/Documents/daima/ai短剧/generate_thunderstorm_drama_locked_midshot_v3_cn_dialogue.py`：雷暴样片的角色锁、场景锁、对白、实际末帧串联。
+- `/Users/xz/Documents/daima/ai短剧/outputs/voice_lock_strategy/voice_lock_plan.md`：固定 TTS 声音加规避嘴形的声音策略。
+- `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/docs/NEWAPI_AUDIO_WORKFLOW.md`：NewAPI 中转 `IndexTTS-2.5` 和 `paraformer-zh-long` 的音频请求格式。
+
+## 禁止默认行为
+
+- 不默认使用付费或云端节点。
+- 不在配置、导出文件或日志里保存 NewAPI 密钥；需要认证时只读取环境变量。
+- 不把 MiniMax H3 每次随机采样的原生声音当角色最终声线。
+- 不把 storyboard、contact sheet、collage、九宫格、边界表作为生成输入。
+- 不让同一张生成图出现多个地点、多个时间点、多个机位或多个连续动作。
@@ -0,0 +1,45 @@
+# 商业 AI 短剧/漫剧平台对标蓝图
+
+## 对标结论
+
+商业平台的核心不是单点生成，而是把内容生产拆成稳定流水线：
+
+```text
+项目工厂 → 剧本导入/拆解 → 角色与资产选角 → 分镜/导演台 → 生成队列 → 审片质检 → 合成交付 → 运营复用
+```
+
+本地版要保留用户的硬约束：本地/自有模型平台优先、ComfyUI optional、单画面生成、固定声线、连续性 ledger。
+
+## 当前已落入 MVP 的平台能力
+
+- 生产总控：商用准备度、批次、流水线、任务队列、QA 证据、交付物。
+- 剧本拆解：长文本导入、章节拆分、角色/场景/道具抽取、风格预设。
+- 资产选角：角色定妆、三视图占位、衣橱、声线锁、复用范围、场景库、道具库。
+- 导演工作台：镜头表、首尾帧、声音锁、QA、实际末帧衔接、批量动作。
+- 生成队列：本地适配器请求包、local-only 成本策略、dry-run contract。
+- 执行运营：本地 Worker 自动领取、租约防重、并发上限、心跳、依赖阻塞、失败 attempt 和管理员手动 dispatch。
+- 模型中台：自定义 HTTP JSON、OpenAI-compatible 和 ComfyUI optional 协议路由；密钥只引用环境变量。
+- 审片中心：一图一画面、连续性、声音字幕、片段衔接。
+- 交付运营：分镜 JSON、prompt pack、配音台词表、剪辑清单、视频工程目录。
+- 企业身份：真实 Bearer session、TOTP MFA、系统级身份策略、OIDC Authorization Code + PKCE/JWKS 登录运行时、Provider 绑定组织/工作区/默认角色、SSO 自动入组、组织绑定的 SCIM Users 同步接口和令牌轮换。
+- 通知中心：按用户、组织、工作区隔离的站内收件箱、未读计数、单条/全部已读、组织级通知偏好和服务端收件人过滤。
+- 协作任务中心：项目内任务创建、负责人分派、优先级、截止时间、状态流转、本人任务更新、站内通知和审计记录；与派生待办中心联动。
+- 版本台账：资产版本不可覆盖，支持恢复历史版本并将恢复动作写入审计流；镜头和交付批次的完整回滚仍需继续接入。
+- 项目生命周期：项目创建即初始化系列 / 第一季 / 试播集 / starter shot；支持草稿、制作中、暂停、审片中、归档和恢复，归档前阻断未完成任务，归档后的生产写操作由后端统一锁定。
+- 可审计运维：系统就绪度、SQLite 快照、队列租约、Worker 心跳、通知投递记录、API Client 撤销和跨组织审计查询。
+
+## 下一阶段的商用增强
+
+- 登录风险策略、设备信任、SSO 会话撤销联动和更细的 IdP claims/组到角色映射。
+- PostgreSQL / 对象存储 / Redis 的生产部署 profile，以及多实例 Worker 的分布式锁和水平扩展。
+- 对象存储迁移：将当前本地文件资产、首尾帧、视频片段、音频、字幕和审片证据迁移到可配置的 S3-compatible provider，并补齐生命周期与保留策略。
+- 版本系统增强：角色锁 v1/v2、场景锁、镜头改稿、批次回滚，以及将资产恢复扩展到镜头/交付批次。
+- 证据化 QA：图像检测、ASR 字幕对齐、声纹相似度、首尾帧差异、镜头连续性分数。
+- 合成器：本地 ffmpeg 工程生成、字幕、固定音轨、环境声、最终 master。
+- 商业运营增强：真实计费系统、成本分摊结算、客户交付审批和发布渠道连接器。
+
+当前 MVP 的接口清单、Worker 生命周期和协议 JSON 示例见 `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/docs/API_REFERENCE.md`。
+
+## 本地版商业定位
+
+这个项目不做云平台壳子，而做“私有部署的 AI 漫剧生产中台”：把用户已有模型、脚本、ComfyUI 工作流、TTS、口型模型和剪辑工具统一纳管。默认不调用付费云端节点，所有外部适配器必须显式启用。
@@ -0,0 +1,51 @@
+# 2026 商业 AI 视频/短剧平台功能研究
+
+调研目标：不是做一个生成页面，而是抽象商业平台必须具备的生产能力，并落成本地/私有部署 AI 短剧平台。
+
+## 公开产品信号
+
+- Runway Dev：强调 Workflows、自定义 pipeline、私有 API endpoint、开发者集成、企业支持。
+  - https://dev.runwayml.com/
+  - https://help.runwayml.com/hc/en-us/articles/50085269258643-Publishing-a-Workflow-as-an-Endpoint
+  - https://runway.com/news/company-news/introducing-runway-dev
+- Kling AI：一体化 AI 视频/图片创作，图生视频、motion control、lip sync、avatar、元素和声音控制。
+  - https://kling.ai/
+  - https://kling.ai/explore/klingai_lipsync
+  - https://kling.ai/blog/kling-video-3-omni-native-lip-sync-audio-guide
+- Vidu：Reference to Video、多参考图、角色/物体/场景一致性、保存 references 复用。
+  - https://www.vidu.com/
+  - https://www.vidu.com/ai-reference-to-video
+  - https://www.vidu.com/tools/consistent-character-ai
+- Pika：AI 视频创作、effects、trend workflow、自动化、图片到视频、面向社交传播的快速生成。
+  - https://pika.art/
+
+## 商业平台必须覆盖的功能域
+
+1. 工作区与团队：tenant、seat、成员、角色、权限、审计日志。
+2. 项目工厂：创建项目、模板、剧集、季、工程目录、版本。
+3. 剧本拆解：长文本导入、章节/场次/镜头拆分、角色/道具/场景抽取。
+4. 资产一致性：角色定妆、三视图、衣橱、道具、场景、声线、参考图保存和复用。
+5. 导演工作台：镜头表、首尾帧、镜头依赖、动作/机位、批量操作。
+6. 模型中台：模型注册、能力标签、endpoint、runner health、队列深度、路由策略。
+7. 生成编排：批量任务、优先级、依赖、重试、取消、失败边界、成本策略。
+8. 审片质检：单画面、角色一致性、声音字幕、ASR、镜头衔接、人工审核。
+9. 成本额度：套餐、配额、用量、成本中心、预算预警、外部云审批。
+10. 合规版权：原创/IP、真人脸权、声音授权、参考素材来源、禁止默认云端付费节点。
+11. 合成交付：剪辑清单、字幕、音轨、封面、最终视频、发布渠道、模板复用。
+12. 开发者/企业接口：私有 API、workflow endpoint、自定义 runner、权限鉴权。
+
+## 本项目已落地的本地版能力
+
+- `src/platform/platformData.js`：平台级 tenant、plan、members、permissions、model registry、runner health、projects、asset storage、review lanes、cost centers、compliance policies、audit log。
+- `server/local-api.mjs`：平台摘要、模型、成本、合规、审计、模型注册、任务队列、导出写盘接口。
+- `src/App.jsx`：生产总控、项目工厂、剧本拆解、资产选角、导演工作台、生成队列、模型中台、审片中心、成本合规、交付运营、平台管理。
+
+## 下一步工程化优先级
+
+1. 把静态平台数据迁移到 SQLite/Postgres。
+2. 前端所有页面改为 API 读写，保留本地 fallback。
+3. 接入真实 job runner：任务状态、依赖、重试、取消、失败日志。
+4. 对接自有模型平台 HTTP runner；ComfyUI 继续 optional。
+5. 补本地鉴权和角色权限。
+6. 引入文件资产索引：图片、视频、音频、字幕、QA 截图。
+7. 把 QA 从规则检查升级为证据检查：图像检测、ASR、声纹、首尾帧差异。
@@ -0,0 +1,106 @@
+# 商业化多组织、多工作区设计
+
+## 目标
+
+`ai-drama-platform` 的商业形态不是“一个剧集的生产页面”，而是一个可以私有部署、承载多个内容公司的 AI 短剧/漫剧生产中台。所有生产数据都必须从组织和工作区上下文开始，任务、资产、审片和交付都不能脱离租户边界。
+
+本地 MVP 使用 Node 24 内置 `node:sqlite`，已经接入邮箱 + 密码登录、scrypt 密码哈希和 Bearer session。仅在显式设置 `AI_DRAMA_ALLOW_DEV_CONTEXT=1` 的本地调试场景下，才允许请求头模拟上下文；默认运行模式是 session-only。后续替换为 SSO/OIDC 时，只需要替换身份解析层，不改变业务表和 scope 查询。
+
+## 产品层级
+
+```text
+用户 User
+  └── 组织 Organization（公司 / 内容厂牌 / 客户租户）
+        ├── 组织成员 Organization Member
+        ├── 套餐、账单、配额、策略
+        └── 工作区 Workspace（制作部 / 项目组 / 客户空间）
+              ├── 工作区成员 Workspace Member
+              ├── 项目 Project（系列 / 模板 / 客户项目）
+              │     ├── 季 / 集 / 剧本 / 资产锁 / 分镜
+              │     ├── 生成任务 / 尝试记录 / 审片 / 合规
+              │     └── 交付版本 / 发布渠道
+              └── 模型连接器、Runner、资产存储策略
+```
+
+组织解决客户和计费隔离，工作区解决团队协作隔离，项目解决内容访问和交付隔离。一个用户可以加入多个组织，在同一组织中进入多个工作区；项目默认继承工作区成员，但敏感项目可以额外配置 project member。
+
+## 角色模型
+
+| 作用域 | 角色 | 典型能力 |
+| --- | --- | --- |
+| 组织 | `org_owner` | 组织设置、成员、账单、模型策略、全项目可见 |
+| 组织 | `org_admin` | 成员、工作区、模型和审计管理 |
+| 工作区 | `producer` | 建项目、排队、批次、成本、交付审批 |
+| 工作区 | `writer` | 剧本、分集、对白、镜头草稿 |
+| 工作区 | `art_director` | 角色/场景/道具锁、参考图、prompt、连续性 |
+| 工作区 | `voice_editor` | 声线锁、TTS、字幕、ASR 对齐 |
+| 工作区 | `reviewer` | QA、审片意见、通过/驳回 |
+| 项目 | `project_editor` | 指定项目内容编辑 |
+| 项目 | `project_viewer` | 只读查看、下载被授权的交付物 |
+
+权限不是写死在前端。API 根据 `organization_members`、`workspace_members`、`project_members` 合并角色权限，并在每个项目、任务、模型、交付接口执行检查。前端显示权限矩阵只是帮助用户理解，不能作为安全边界。
+
+## 数据表
+
+### 身份和租户
+
+- `users`：用户身份、显示名、邮箱、状态。
+- `organizations`：租户、slug、部署模式、所有者。
+- `organization_members`：用户加入组织的角色、邀请状态。
+- `workspaces`：组织下的生产空间。
+- `workspace_members`：工作区角色。
+- `projects`：工作区下的系列、模板或客户项目。
+- `project_members`：项目级额外授权。
+- `invitations`：待接受邀请，不把邀请误当作已加入成员。
+
+### 生产和中台
+
+- `series`、`seasons`、`episodes`：剧集结构。
+- `assets`、`asset_versions`：角色、场景、道具、参考图、首尾帧、音频和视频资产版本。
+- `shots`：分镜、首帧/末帧、镜头状态和 continuity lock 引用。
+- `generation_jobs`、`job_attempts`：任务、重试、取消、执行器和输出。
+- `reviews`、`review_comments`：审片 lane、QA gate、意见和决策。
+- `model_connectors`：自有模型平台、HTTP JSON、OpenAI-compatible、ComfyUI optional adapter。
+- `deliveries`：剪辑清单、字幕、封面、master 和发布渠道。
+
+### 商业治理
+
+- `billing_accounts`：套餐、席位、存储、片段额度和云连接策略。
+- `quota_allocations`、`usage_events`：配额和按任务的用量计量。
+- `compliance_records`：原创/IP、肖像权、声音权、参考素材来源、单画面检查。
+- `audit_logs`：谁在什么组织/工作区/项目中做了什么操作，以及结果和元数据。
+
+## 请求上下文
+
+本地调试 bypass 使用以下请求头，缺省时使用种子账号和种子工作区；真实浏览器请求必须携带登录后的 Bearer session：
+
+```text
+x-user-id: u-owner
+x-organization-id: org-studio-lab
+x-workspace-id: ws-local-aidrama
+x-project-id: thunder-mouth
+```
+
+真实部署必须由登录会话或网关注入用户身份，禁止让客户端直接提交任意组织 ID 后绕过 membership 检查。API 的最小检查顺序是：
+
+1. 用户存在且状态为 active。
+2. 用户是组织成员，且组织状态可用。
+3. 工作区属于当前组织，用户拥有工作区 membership。
+4. 项目属于当前工作区，用户拥有项目 membership 或工作区角色允许继承访问。
+5. 当前角色拥有该动作所需权限。
+6. 记录 audit log，涉及生成、下载、模型调用和导出时记录 usage event。
+
+## AI 短剧生产的业务硬门
+
+这些约束属于组织策略或项目策略，不能只放在 prompt 文本里：
+
+- `single_frame_only`：每个图片生成任务只能输出一张连续完整画面，拒绝 split-screen、漫画多格、storyboard、collage、contact sheet。
+- `continuity_lock_required`：角色、服装、道具、场景、天气、镜头角度、声线必须有 lock 和 ledger。
+- `actual_last_frame_chain`：后续视频优先引用上一段真实末帧，不能只引用描述性文本。
+- `voice_lock_required`：对白使用固定声线；MiniMax H3 随机原生声音不作为最终角色声线。
+- `mouth_safe_shot_policy`：口型不稳定时优先侧脸、背影、低头、远景、反应镜头或环境插入镜头。
+- `local_runner_only`：默认只允许本地/自有模型；云端节点必须显式审批并留下审计记录。
+
+## MVP 与后续
+
+当前可运行 MVP 先交付真实的租户、成员、权限、项目 scope、邀请、审计、用量和模型注册接口，生产资产表和任务表已经预留。下一阶段可以把认证、Redis/BullMQ 队列、对象存储、ffmpeg 合成和真实 Runner 接入，不需要重做组织模型。
@@ -0,0 +1,72 @@
+# NewAPI 音频工作流
+
+本项目的中文声音链路使用用户自有 NewAPI 中转到 Xinference，不在仓库内保存密钥。
+
+## 环境变量
+
+```bash
+export NEWAPI_API_KEY="..."
+```
+
+`GET https://newapi.ysblack.com/v1/models` 未带认证时返回 `401 Invalid token` 是预期行为。所有真实请求必须带 `Authorization: Bearer $NEWAPI_API_KEY`。
+
+## TTS 配音
+
+- 模型：`IndexTTS-2.5`
+- 端点：`POST https://newapi.ysblack.com/v1/audio/speech`
+- 请求：`multipart/form-data`
+- 用途：中文角色配音、固定声线、情绪参考
+
+`IndexTTS-2.5` 的角色声线不是预设 voice 列表，而是由 `prompt_speech` 参考音频锁定。每个角色必须有授权参考音频，并在逐句生成时重复使用同一角色参考音频。
+
+当前工程没有用户确认的正式角色参考音频。此前用临时/机器化参考音频生成的 IndexTTS 样音已经作废。禁止使用以下音频作为 `prompt_speech`：
+
+- macOS `say` 生成的本地离线 TTS
+- MiniMax H3 原生音轨
+- 旧 probe / 临时测试 wav
+- 听感机器化、带混响、带背景声、无授权或未经用户试听确认的声音
+
+正式流程必须先获得干净自然的人声参考，或用 `Qwen3-TTS VoiceDesign`、`CosyVoice` 等自然声线先做候选试听。候选试听一次只生成单句，用户确认后才能把该声音登记为角色锁并进入批量生成。
+
+```bash
+curl -sS -o line_001.wav \
+  -X POST "https://newapi.ysblack.com/v1/audio/speech" \
+  -H "Authorization: Bearer $NEWAPI_API_KEY" \
+  -H "Accept: application/json, audio/*" \
+  -F "model=IndexTTS-2.5" \
+  -F "input=先别出去，树下和金属牌旁都危险。" \
+  -F "voice=default" \
+  -F "response_format=wav" \
+  -F "speed=1.0" \
+  -F "kwargs={\"language\":\"ZH\"}" \
+  -F "prompt_speech=@voices/chen_yu/approved_ref_01.wav;type=audio/wav;filename=prompt.wav"
+```
+
+## ASR 校验
+
+- 模型：`paraformer-zh-long`
+- 端点：`POST https://newapi.ysblack.com/v1/audio/transcriptions`
+- 请求：`multipart/form-data`
+- 用途：中文识别、台词准确性校验、字幕和时间轴对齐
+
+```bash
+curl -sS \
+  -X POST "https://newapi.ysblack.com/v1/audio/transcriptions" \
+  -H "Authorization: Bearer $NEWAPI_API_KEY" \
+  -F "model=paraformer-zh-long" \
+  -F "file=@voices/chen_yu/line_001.wav;type=audio/wav" \
+  -F "language=zh" \
+  -F "response_format=verbose_json"
+```
+
+`verbose_json` 返回识别文本、词级时间戳和音频时长。生产字幕时以原始台词表为准，ASR 文本用于发现漏字错字，ASR 时间戳用于对齐字幕。
+
+## 生产顺序
+
+1. 收集或生成候选角色声线，一次只做单句试听。
+2. 用户试听确认后，把正式参考音频登记为 `approved_ref_01.wav`。
+3. 用 `IndexTTS-2.5` 按角色正式参考音频生成逐句 wav。
+4. 标准化音频采样率、响度和命名，并写入缓存。
+5. 用 `paraformer-zh-long` 对逐句 wav 或整集混音做 `verbose_json` 识别。
+6. 比对原始台词和 ASR 文本，异常句重生成或人工复核。
+7. 用原始台词文本加 ASR 时间戳生成字幕，再进入剪辑合成。
@@ -0,0 +1,59 @@
+# Commercial Multi-Tenant Platform Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将单工作区演示台升级为具有真实组织、工作区、用户、角色、项目 scope、邀请、审计和用量边界的本地商业化 AI 短剧生产平台 MVP。
+
+**Architecture:** 使用 Node 24 内置 SQLite 持久化身份、租户、成员、项目、任务和治理数据；HTTP API 通过请求上下文解析 membership 和权限，再为 React 前端提供可切换的 organization/workspace/project context。既有剧本、资产、导演台和 QA 继续复用，但所有平台管理数据优先来自 SQLite，静态数据只作为无 API 时的回退。
+
+**Tech Stack:** React 19 + Vite 7 + lucide-react；Node 24 `node:sqlite`；原生 Node HTTP；现有 Playwright 依赖用于渲染验证。
+
+---
+
+### Task 1: 建立租户数据库和种子数据
+
+**Files:**
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/server/schema.sql`
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/server/db.mjs`
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/data/platform.sqlite` (运行时生成)
+
+- [ ] 创建外键、索引、时间戳齐全的租户、成员、项目、任务、模型、配额、合规、审计表。
+- [ ] 用两个组织、三个工作区、多个角色和两个项目建立可切换种子数据。
+- [ ] 用 `DatabaseSync` 的 `prepare().run/all/get()` 封装参数化查询和事务。
+- [ ] 运行 `node -e 'import("./server/db.mjs")'`，确认数据库和种子数据可读。
+
+### Task 2: 增加 scope-aware API
+
+**Files:**
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/server/tenant.mjs`
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/server/local-api.mjs`
+
+- [ ] 解析 `x-user-id`、`x-organization-id`、`x-workspace-id`、`x-project-id`。
+- [ ] 在所有组织、工作区、项目、任务、模型、审片和导出接口执行 membership 和权限检查。
+- [ ] 新增 context、组织、工作区、项目、邀请、用量、账单、权限和审计接口。
+- [ ] 让新增任务、模型、项目和邀请写入 SQLite，并同步写 audit log / usage event。
+
+### Task 3: 前端接入真实组织上下文
+
+**Files:**
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/lib/api.js`
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/App.jsx`
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/styles.css`
+
+- [ ] 启动时请求 `/api/context`，失败时显示明确的本地回退状态。
+- [ ] 顶栏增加组织、工作区、项目和当前用户上下文切换。
+- [ ] 平台管理页展示成员、待邀请、工作区、项目访问、权限矩阵、配额和审计。
+- [ ] 邀请成员、创建工作区、创建项目和注册模型走真实 API，成功后刷新上下文。
+
+### Task 4: 验证商业 MVP
+
+**Files:**
+- Verify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/package.json`
+- Verify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/server/local-api.mjs`
+- Verify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/App.jsx`
+
+- [ ] 运行 `npm run build`。
+- [ ] 用 curl 验证默认组织、切换组织、邀请、创建工作区和越权请求。
+- [ ] 在 `http://127.0.0.1:5173/` 验证桌面端和移动端，完成组织切换、平台管理和生成任务路径。
+- [ ] 确认控制台无错误、页面不横向溢出，API 和 Vite 服务保持运行。
+
@@ -0,0 +1,40 @@
+# Commercial Creator Suite Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在已经具备认证、租户和生产流水线的本地平台上，补齐商业创作套件的资产、声音、批量生产和项目助手入口。
+
+**Architecture:** 新增独立的 React 创作模块文件，复用现有项目 API、SQLite 任务队列和 RBAC，不复制竞品品牌或页面。所有批量动作拆成带项目/镜头范围的独立 job；声音试听保持单句约束；资产状态以项目 continuity lock 为主数据。
+
+**Tech Stack:** React 19 + Vite + lucide-react + 现有 Node HTTP API / SQLite。
+
+---
+
+### Task 1: 创作套件信息架构
+
+**Files:**
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/App.jsx`
+- Create: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/components/CreatorSuitePages.jsx`
+
+- [ ] 增加资产库、声音与字幕、批量生产、项目助手四个受现有项目权限保护的入口。
+- [ ] 用项目角色、场景、道具、voice lines、generation jobs 和 ledger 生成可操作视图。
+
+### Task 2: 生产动作接线
+
+**Files:**
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/App.jsx`
+- Modify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/styles.css`
+
+- [ ] 批量生产按镜头逐条写入现有 `/api/jobs`，保留 local-only 和 adapter 选择。
+- [ ] 单句试听只允许当前选中台词写入一个 job，禁止批量生成声音。
+- [ ] 增加桌面/移动端布局、筛选、选择态、成功和错误反馈。
+
+### Task 3: 回归验证
+
+**Files:**
+- Verify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/components/CreatorSuitePages.jsx`
+- Verify: `/Users/xz/Documents/daima/ai短剧/ai-drama-platform/src/App.jsx`
+
+- [ ] 运行 `npm run build`、`npm run smoke:tenant`、`npm run write:exports`。
+- [ ] 登录系统管理员、组织管理员、普通编剧，确认菜单和后台权限不越权。
+- [ ] 用浏览器检查 1280px 和 390px 视口，确认无横向溢出和控制台错误。