Stev_Wang
45467558ab
ci / 质量门禁 (push) Successful in 5m25s
背景：A6 全部 WBS 与门禁完成，按文档规范同批更新实现记录与计划状态。 改动： - 新增 docs/开发计划/灵犀_A6任务中心与队列骨架_实施报告_V0.1.md：范围与完成度、交付物、门禁结果、关键口径（202 / 幂等 / 取消重试 / SSE / 状态机 / 队列物理名 / Outbox 退避 / 前端预估 / 角标）、与计划差异、已知遗留与下一步。 - 开发计划：状态行与 A6 批次置为已完成、§6.7 增加执行状态与完成情况、§7.6 增加状态行、M0 清单勾选任务中心。 - README：索引新增 A6 报告，当前进度推进到 A7。 影响面：仅文档与索引；无代码行为变化。 回滚：撤销提交恢复文档。 验证：pnpm format:check 通过；报告中的门禁数据来自本批实际执行结果。
136 lines
11 KiB
Markdown
136 lines
11 KiB
Markdown
# 灵犀 · 信息流广告素材一站式生产平台
|
||
|
||
面向信息流广告投放的素材生产平台：**行业包 → 要素卡 → 脚本 → 素材 → 快筛 → 导出即归档**。
|
||
|
||
- **图片线**：确定性批量流水线（PSD 模板套版 + 自动抠图 + 多规格合成），不做 AI 生图。
|
||
- **视频线**：AI 逐镜图生视频（关键帧 → 单镜 → 拼接 → 校验）。
|
||
- **内核不分行业**：电商、金融等差异收敛为可配置**行业包**，新行业只换配置、不发版。
|
||
|
||
---
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 路径 | 版本 | 作用 |
|
||
| ------------ | ------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------- |
|
||
| **项目总纲** | [AGENTS.md](AGENTS.md) | V1.2 | 硬约束、技术栈、仓库结构、命令契约、流程 |
|
||
| **PRD** | [灵犀-信息流广告素材一站式生产平台PRD.md](docs/PRD/灵犀-信息流广告素材一站式生产平台PRD.md) | **V1.6（最新）** | 需求、业务规则（R-01~R-30）、验收标准 |
|
||
| **技术架构** | [灵犀_信息流素材生产平台_技术架构_V0.1.md](docs/技术架构/灵犀_信息流素材生产平台_技术架构_V0.1.md) | **V0.4（内部版本）** | 技术选型、分层模块、数据模型、接口、ADR |
|
||
| **开发计划** | [灵犀_信息流素材生产平台_开发计划_V0.1.md](docs/开发计划/灵犀_信息流素材生产平台_开发计划_V0.1.md) | **V0.1（初稿）** | 全项目 M0–M4：里程碑、批次、WBS、七管理模块专项、门禁、风险、验收 |
|
||
| 立项建议 | [灵犀_信息流素材生产平台_立项建议书_V0.1.md](docs/立项建议/灵犀_信息流素材生产平台_立项建议书_V0.1.md) | V0.1 | 背景、目标、投入产出论证（不约束实现） |
|
||
| **工程规范** | [docs/工程规范/](docs/工程规范/README.md) | V1.0 | Git、代码风格、格式化、API、数据库、测试、Review、日志、密钥、资产命名 |
|
||
| **A0 报告** | [灵犀_A0工程骨架与契约基线_实施报告_V0.1.md](docs/开发计划/灵犀_A0工程骨架与契约基线_实施报告_V0.1.md) | V0.1 | A0 完成范围、门禁实测、环境适配与待确认事项 |
|
||
| **A1 报告** | [灵犀_A1身份认证与用户管理_实施报告_V0.1.md](docs/开发计划/灵犀_A1身份认证与用户管理_实施报告_V0.1.md) | V0.1 | A1 完成范围、契约/实现/测试、遗留与下一步 |
|
||
| **A2 报告** | [灵犀_A2角色权限与数据范围_实施报告_V0.1.md](docs/开发计划/灵犀_A2角色权限与数据范围_实施报告_V0.1.md) | V0.1 | A2 完成范围、H1 决策、前后端/测试、遗留与下一步 |
|
||
| **A3 报告** | [灵犀_A3客户与行业目录_实施报告_V0.1.md](docs/开发计划/灵犀_A3客户与行业目录_实施报告_V0.1.md) | V0.1 | A3 完成范围、两级行业决策、混搭 UI、测试与遗留 |
|
||
| **A4 报告** | [灵犀_A4数据字典与系统配置_实施报告_V0.1.md](docs/开发计划/灵犀_A4数据字典与系统配置_实施报告_V0.1.md) | V0.1 | A4 完成范围、三层合并/配置版本、方案 A UI、测试与遗留 |
|
||
| **A5 报告** | [灵犀_A5审计与日志_实施报告_V0.1.md](docs/开发计划/灵犀_A5审计与日志_实施报告_V0.1.md) | V0.1 | A5 完成范围、append-only / 检索导出 / 运行日志、A+A+C UI、测试与遗留 |
|
||
| **A6 报告** | [灵犀_A6任务中心与队列骨架_实施报告_V0.1.md](docs/开发计划/灵犀_A6任务中心与队列骨架_实施报告_V0.1.md) | V0.1 | A6 完成范围、任务协议 / 九队列 / SSE / Outbox、方案 A UI、e2e 与遗留 |
|
||
| **ADR** | [docs/adr/](docs/adr/README.md) | — | 架构决策记录（ADR-001 权限；ADR-002 两级行业目录） |
|
||
| 历史 PRD | `docs/PRD/灵犀_信息流素材生产平台_PRD_V0.1~V0.3.md` | 归档 | 仅作沿革参考，**不具约束力** |
|
||
|
||
> 阅读顺序：`AGENTS.md` → PRD §1/§6 → 技术架构 §0.2/§3 → 按任务查 `docs/工程规范/`。
|
||
|
||
---
|
||
|
||
## 核心链路（五步）
|
||
|
||
| 步骤 | 动作 | 产出 |
|
||
| ---- | ---------------------------------------------- | -------------------- |
|
||
| 1 | 建行业 / 客户信息，选行业包并套客户资产包 | 归属根节点就绪 |
|
||
| 2 | 要素卡 + 卖点库 → 脚本生成 / 校核 / 审核入库 | 已入库脚本（带编号） |
|
||
| 3 | 图片批次（模板 × 商品图 × 规格）/ 视频逐镜生成 | 候选素材 |
|
||
| 4 | 按组并排快筛，勾选保留项 | 待导出素材 |
|
||
| 5 | 导出（固定目录 + 命名规则）+ 自动归档 | 可投素材 + 交付清单 |
|
||
|
||
---
|
||
|
||
## 功能模块（PRD V1.6）
|
||
|
||
| 模块 | 定位 |
|
||
| ------------ | ------------------------------------------------------------------------ |
|
||
| **脚本** | 要素卡 / 卖点库 / 模板 / 生成 / 质量校核 / 审核入库 / 版本 |
|
||
| **素材** | 图片线（PSD 套版、抠图、规格矩阵）、视频线（逐镜生成、变体）、快筛与预览 |
|
||
| **资产** | 15 类资产的库、版本、引用、复审与复用度量 |
|
||
| **平台管理** | 组织账号、客户、角色管理、AI 配置、数据字典、审计、行业包与表单设计器 |
|
||
|
||
> 早期文档中的「四大模块（脚本生成 / 素材生产 / 编辑 / 管理）」已于 PRD V1.6 重构为「脚本 / 素材 / 资产 / 平台管理」三主线 + 一底座。
|
||
|
||
---
|
||
|
||
## 目录结构（目标态）
|
||
|
||
```
|
||
apps/api NestJS HTTP + SSE + AI 回调
|
||
apps/worker 异步任务（图片 / 视频 / 导出 / 入库）
|
||
apps/web React SPA
|
||
packages/ shared · form-engine · render · ai-sdk · ui
|
||
prisma/ 数据模型与迁移
|
||
infra/ compose、Nginx、监控、备份
|
||
docs/ PRD / 技术架构 / 开发计划 / 立项建议 / 工程规范
|
||
```
|
||
|
||
当前已完成 **A0 工程骨架与契约基线**、A1 身份认证、A2 角色权限、A3 客户与行业目录、A4 数据字典与系统配置、A5 审计与日志、A6 任务中心与队列骨架；下一步 A7 AI 配置与调用底座。目录与依赖方向见 [AGENTS.md §5](AGENTS.md)。
|
||
|
||
---
|
||
|
||
## 本地开发
|
||
|
||
前置：Node.js `24.15.0`（`.nvmrc`）、pnpm `10.x`、Docker。
|
||
|
||
```bash
|
||
cp .env.example .env.local
|
||
cp .env.local .env # Prisma CLI 只读取 .env（两者均已 gitignore）
|
||
pnpm check:dev # 检查本机 PostgreSQL / Redis 是否可用
|
||
pnpm db:init # 首次/迁移后：应用已有迁移 + 幂等种子（不重置数据、不改已有密码）
|
||
pnpm dev # 并行启动 api(3000) / web(5173) / worker
|
||
```
|
||
|
||
> **日常启动不需要执行任何数据库命令**。`pnpm dev` / `./dev.sh` 都不会迁移、播种或重置数据库，已有账号密码保持不变。
|
||
> **只有需要清空本地库时才用 `pnpm db:reset`**：它会清空全部表并重新 seed，admin 等种子账号会回到初始密码 `lingxi2026` 且 `must_change_password=true`。为避免误清本地改过的密码/数据，该命令默认被拦截，必须显式执行：
|
||
>
|
||
> ```bash
|
||
> ALLOW_DB_RESET=1 pnpm db:reset # 确认清库才执行
|
||
> ```
|
||
>
|
||
> 日常迁移 / 补种子请用 `pnpm db:init`（幂等，不改已有密码）。
|
||
> 生产环境部署只用 `prisma migrate deploy`（`db:init` 的第一步），**不执行 seed / reset**；用户密码不会因重启或发布被重置。
|
||
|
||
也可以使用一键脚本（自动检测并释放端口、带健康检查，启动后默认跟随日志）：
|
||
|
||
```bash
|
||
./dev.sh # 启动 api + web + worker，并前台跟随日志（Ctrl+C 停止全部）
|
||
./dev.sh start -d # 后台启动
|
||
./dev.sh status # 端口 / PID / 健康状态
|
||
./dev.sh logs [api|web|worker] # 跟踪日志（默认全部）
|
||
./dev.sh stop # 停止并释放 3000 / 5173
|
||
./dev.sh --help # 全部参数
|
||
```
|
||
|
||
> `dev.sh` 只负责开发服务，不启动 PostgreSQL / Redis 或任何 Docker 容器；这两者按约定在开发前已就绪。
|
||
|
||
- **本地数据库**：直接复用本机已有 Docker 服务 `docker-postgres-1`（PostgreSQL 18，`127.0.0.1:5432`），库名 `lingxi`，用户 `postgres`，密码 `postgres`；Redis 复用 `docker-redis-1`（`127.0.0.1:6379`）。请先确认这两个容器已启动，本仓库不会另起 PG/Redis。
|
||
- **对象存储**：使用公网 RustFS（`https://oss.xinsenidea.com`，桶 `lingxi-dev`）；A0 的 `assets / renders / temp` 三类产物暂共用该桶，待 A1 按前缀拆分。真实 access key / secret 只写入本地 `.env.local`（已 gitignore），仓库内只保留占位。
|
||
- **API 文档**：启动 api 后访问 `http://127.0.0.1:3000/api/docs`，OpenAPI JSON 在 `openapi/lingxi.openapi.json`。
|
||
- **演示登录**：A0 尚未接鉴权（A1 实现），`VITE_PUBLIC_DEMO_SESSION=true` 时登录页使用本地演示会话进入工作台；A1 接入真实登录后删除。
|
||
|
||
常用校验：
|
||
|
||
```bash
|
||
pnpm lint && pnpm typecheck && pnpm test # 本地门禁
|
||
VITE_PUBLIC_DEMO_SESSION=true pnpm test:e2e # 构建 + 端到端冒烟（demo 会话）
|
||
pnpm openapi:export && pnpm openapi:diff # 契约快照与破坏性变更检查
|
||
pnpm ci:local # 本地跑完整 CI 门禁（已内置 e2e 所需 env）
|
||
```
|
||
|
||
> **推送前本地门禁仍为强制项**：跑 `pnpm ci:local`（或至少 `format:check + lint + typecheck + test`）。远端自建 Gitea 已部署 Actions runner（`gitea-runner-01`），push `main` 自动执行 `.gitea/workflows/ci.yml`；需要快速确认 runner 可用时手动触发 `.gitea/workflows/ci-smoke.yml`（约 1 分钟）。远端 CI 失败必须立即修复，**不得以「远端 CI 会跑」替代本地门禁**。
|
||
|
||
命令与门禁见 [AGENTS.md §6](AGENTS.md) 与 [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md)。当前 UI 采用「顶部模块菜单 + 左侧功能菜单」布局，视觉方向为 **A · 云白蓝（传统企业后台 + 现代浅色质感）**。
|
||
|
||
---
|
||
|
||
## 约定速查
|
||
|
||
- 包管理只用 **pnpm**，Node 锁定 **24.15.0**；UI 只用 **Semi Design**，图标只用 **Remix Icon**。
|
||
- 客户数据隔离、审计 append-only、导出全留痕、阈值单一来源、低质量不可静默——均为硬约束。
|
||
- 完整红线见 [AGENTS.md §3](AGENTS.md)。
|