# AI 助手项目说明

本文件是 AI 助手改动本仓库前必读的约定。与代码/真实结果冲突时以代码为准；不确定先问，不要臆造。

## 开工前必读

- 开始任何任务前，必须依次阅读：
  1. 本文件 `AGENTS.md`（约定与铁律）
  2. `docs/长期规范/AI助手必读规范/系统架构.md`（运行边界、数据流、模块依赖、设计决策）
  3. `docs/长期规范/AI助手必读规范/IP操盘三大核心路线.md`（IP 操盘主线、验收标准和防跑偏规则）
  4. `docs/长期规范/AI助手必读规范/项目术语表.md`（遇到不懂的专有名词在此查证，不要臆测含义）
  5. `docs/长期规范/AI助手必读规范/项目状态.md`（当前进度；注意区分“代码已完成”与“线上已验收”）
- 读完后、动手前，必须用几句话向用户复述：项目定位、相关的运行边界与职责、本次任务要遵守的铁律和要避开的坑，以及打算如何改动；经用户确认后再开始写代码。
- 不确定的概念先查 `项目术语表.md` 或询问用户，禁止臆造。

## 项目定位

- 公司内部的抖音内容运营与创作工作台。产品重心已由“AI 视频生成”转向“IP 操盘、选题、脚本和辅助运营”；生成能力仍是内容执行层，不是唯一主线。
- IP 操盘目标是证据驱动的半自动闭环：真实账号数据 -> 定位诊断 -> 内容方向/选题 -> 分镜脚本 -> 日历/发布包 -> 数据复盘。中高风险动作由用户确认，不建设批量评论、Cookie 池、代理池或全自动发布。

## 技术栈与架构

- Angular 21 standalone + Signals；严格 TypeScript/模板检查。Express 仅承接本地代理、媒体处理和 FFmpeg/Whisper 等能力；长期业务数据经 fmode 云函数写入 Parse 项目命名空间 Class，文件本体进入七牛。
- 主产品界面主要由 `App` 的 `currentTab` 单壳切换驱动，不是常规 Angular Router 多页面应用；`app.routes.ts` 只保留少量旧入口/调试入口。
- `app.ts` 是历史主壳且体积很大。新业务逻辑优先放服务或独立 standalone 页面组件，不继续把流程堆进主壳。
- 登录用户的数据归属只能由服务端根据 Parse `sessionToken` 解析的用户决定；不得信任前端传入的 `userId`。
- 长期业务主数据写 Parse 项目命名空间 Class：`VideoWorkflowEntity`、`VideoWorkflowAudit`、`VideoWorkflowMigration` 或后续确认的 `VideoWorkflow*` 专用 Class；图片/视频/音频写七牛并登记 `VideoWorkflowFileAsset`。`localStorage` 仅允许轻量偏好和可重建缓存，短期试用/草稿使用 `sessionStorage` 或 IndexedDB。
- 数据库清理、迁移、测试数据重置或批量修改只能操作 `VideoWorkflowEntity`、`VideoWorkflowAudit`、`VideoWorkflowMigration`、`VideoWorkflowFileAsset` 四个项目 Class；`_User`、`APIG`、`APIGAuth`、`APIGOrder` 以及其他共享/平台 Class 绝对不能动。
- PSQL 不再作为本项目业务主存储；旧 PSQL 数据因尚未正式使用，本阶段不迁移、不删除。Parse Class 和字段结构不得擅自删除、重建或新增，新增字段必须先确认。

## 目录约定

- 新页面：`src/app/pages/<feature>/`；页面专属样式和模板与组件同目录。
- 可复用 UI：`src/app/components/`；跨页面业务逻辑、API、存储适配：`src/app/services/`；共享业务类型：`src/app/models/`。
- 新生成模式：放入 `src/app/pages/pipelines/<mode>/`，并同步登记 `pipeline-registry.ts`、`AppTab`/Tab 校验和主壳模板入口。
- Express 新接口：实现于 `server/routes/`，运行时配置集中在 `server/config/runtime-config.js`；避免继续膨胀 `server.js`。
- fmode 云函数源码：`cloud-functions/`；共用登录态逻辑放 `_session.js`。`cloud-functions/deployable/` 是构建产物，不手改、不提交。
- 工程校验/迁移脚本：`scripts/validation/`；Playwright 场景：`e2e/`；单元测试与被测文件同目录，使用 `*.spec.ts`。
- `docs/` 默认仅在本机保留并整体忽略，不作为提交或 CI 输入；AI 助手长期协作文档统一放在 `docs/长期规范/AI助手必读规范/`，仅作为本地开工读取与协作记录使用。`data/`、测试结果、本地部署脚本和个人资料不得作为 CI 或运行时输入。

## 工作流程铁律

- 修改前先读现有调用链和相邻测试；保留现有服务边界，不为单点需求另建一套账号、积分、存储或任务体系。
- 改前端/服务后至少运行相关 `*.spec.ts` 与 `npm run build`；改 IP 操盘主流程再运行 `npm run e2e:ip-operator`。
- 改云函数后运行 `npm run build:cloud-functions`、`npm run validate:cloud-functions`、`npm run smoke:cloud`；真实登录态、扣费或隔离测试需用户明确提供本地临时环境变量。
- 改计费链路额外运行 `npm run validate:jimeng-billing`；改存储边界额外运行 `npm run validate:storage-policy`。
- 提交前运行 `npm run review:guard` 和 `git status`。提交应原子化，说明改动范围与已运行的验证；仓库没有强制 Conventional Commits 格式。
- 每个任务结束前必须按类型回写文档：约定、目录、命令或已知坑变化更新 `AGENTS.md`；阶段进度更新 `docs/长期规范/AI助手必读规范/项目状态.md`；技术决策在 `docs/长期规范/AI助手必读规范/架构决策记录/` 新增 ADR；架构变化更新 `docs/长期规范/AI助手必读规范/系统架构.md`。没有需要更新时，必须显式说明“无需更新”。
- 运行边界、关键数据流、模块依赖方向、数据存储模型或关键设计决策发生变化时，必须在同一任务内同步 `docs/长期规范/AI助手必读规范/系统架构.md`；不能只更新项目状态或普通说明文档代替架构回写。
- 禁止提交 `.env`、session token、用户数据、媒体产物、测试结果、`deployable/` 或本地方案资料。禁止用真实生成/充值接口做无授权冒烟测试。
- 不直接修改或删除用户已有改动；不使用 `git reset --hard`、`git checkout --` 等破坏性命令。

## 常用命令

```bash
# 首次克隆仓库后启用版本化 pre-commit 提醒钩子；每个工作副本执行一次。
git config core.hooksPath .githooks

# 同时启动 Angular 前端和本地 Express 后端，进行日常联调。
npm run dev

# 一次性运行 Angular/Vitest 单元测试，适合提交前或修改服务后执行。
npm test -- --watch=false

# 执行生产构建，验证严格类型、模板和构建预算。
npm run build

# 修改 IP 操盘主流程或页面交互后运行对应 Playwright 回归。
npm run e2e:ip-operator

# 修改依赖 _session.js 的云函数后，重新生成 fmode 单文件部署包。
npm run build:cloud-functions

# 修改云函数源码、函数清单或部署约定后检查部署就绪状态。
npm run validate:cloud-functions

# 修改余额、预扣、确认、退款或即梦计费逻辑后执行。
npm run validate:jimeng-billing

# 修改浏览器存储、Parse 云端实体、评论/脚本等数据边界后执行。
npm run validate:storage-policy

# 只读预览 IP 操盘测试垃圾清理候选；需要先设置 SMOKE_SESSION_TOKEN，不会删除或 purge。
npm run inspect:ip-operator-cleanup

# 按 dry-run 报告软删除 IP 操盘测试垃圾候选；必须显式传入 --confirm SOFT_DELETE_IP_OPERATOR_CANDIDATES。
npm run cleanup:ip-operator:soft -- --input tmp/<dry-run-report>.json --confirm SOFT_DELETE_IP_OPERATOR_CANDIDATES

# 按清理报告解析/物理删除 IP 操盘测试垃圾；默认只解析 objectId，真正删除必须显式传入 --confirm PHYSICAL_DELETE_IP_OPERATOR_CANDIDATES。
npm run cleanup:ip-operator:physical -- --input tmp/<cleanup-report>.json

# 只读预览当前登录用户在四个 VideoWorkflow 白名单 Class 下的测试数据；必须先设置 SMOKE_SESSION_TOKEN，不会删除。
npm run inspect:videoworkflow-cleanup

# 物理删除当前登录用户在四个 VideoWorkflow 白名单 Class 下的测试数据；必须显式传入 --confirm DELETE_VIDEO_WORKFLOW_TEST_DATA。
npm run cleanup:videoworkflow:parse -- --confirm DELETE_VIDEO_WORKFLOW_TEST_DATA

# 云函数部署或函数 ID 变更后检查线上连通性与权限拦截。
npm run smoke:cloud

# 提交前检查疑似凭证和已知大文件治理阈值。
npm run review:guard
```

## 已知坑

- `App` 使用 `ViewEncapsulation.None` 让全局 `dh-*`、`pl-*`、`pipeline-*` 样式作用于子组件；改回默认封装会导致多个生成页面失样。
- fmode 运行环境不支持源码中的 `require('./_session')`。部署依赖它的函数前必须生成并复制 `cloud-functions/deployable/*.js`。
- `cloud-functions.ts` 是云函数 ID 的唯一前端登记点；部署说明中的状态可能滞后，以配置和真实 smoke 结果为准。
- fmode 网关偶发 `fetch failed` 或“必须提供 id”；只对只读/幂等请求做有限重试，充值、扣费、生成提交不得盲目重放。
- Playwright 固定使用 Edge、端口 `4300` 且串行运行；真实 LLM/E2E 会调用外部服务并可能产生费用。
- 前端生产包仍偏大，initial 预算当前为 warning `2.7MB`、error `3.0MB`；`app.ts`、IP 操盘组件和部分服务已很大，新增功能优先拆分，避免继续扩大单文件。
- 开发代理中的 `/api` 指向 TikHub，`/backend` 才指向本地 Express；生产环境没有本地 Express 抖音代理，抖音账号采集必须走 `CLOUD_FN.douyin` 云函数，否则 `https://app.fmode.cn/backend/api/douyin/call` 会返回 405。