0 Fork 0

Files

T

ci / 质量门禁 (push) Canceled after 0s

Details

背景：
- 开发机上前端/后端/worker 需要分别启动，端口被旧进程占用时排查成本高；
  PostgreSQL / Redis 已按约定提前以 Docker 启动，脚本不再负责。

改动：
- 新增 ./dev.sh：后台启动 api(3000)/web(5173)/worker，启动前自动检测并结束
  端口占用进程（--no-kill 可改为直接失败），等待健康检查后返回。
- 提供 start/stop/restart/status/logs/clean 子命令；stop 按进程组结束并兜底
  释放端口；支持 --api-only/--web-only/--no-worker/--follow。
- 自动加载仓库根 .env.local/.env 并导出给子进程（worker 读取 REDIS_URL 需要）。
- .dev/ 纳入 gitignore；README 本地开发章节补充脚本用法。

影响面：
- 仅新增开发工具与文档，不影响构建、运行时与 CI；`pnpm dev` 保持原行为。

回滚方式：
- 回滚本提交即可，无数据与配置变更。

验证证据：
- bash -n 通过；
- ./dev.sh start / status / stop / restart / clean / --follow 实测；
- 占用 3000/5173 的假服务被自动结束并成功启动；
- --no-kill、--api-only、--no-worker 行为符合预期。

2026-11-03 07:31:50 +08:00

8.4 KiB

Raw Blame History

灵犀 · 信息流广告素材一站式生产平台

面向信息流广告投放的素材生产平台：行业包 → 要素卡 → 脚本 → 素材 → 快筛 → 导出即归档。

图片线：确定性批量流水线（PSD 模板套版 + 自动抠图 + 多规格合成），不做 AI 生图。
视频线：AI 逐镜图生视频（关键帧 → 单镜 → 拼接 → 校验）。
内核不分行业：电商、金融等差异收敛为可配置行业包，新行业只换配置、不发版。

文档索引

文档	路径	版本	作用
项目总纲	AGENTS.md	V1.0	硬约束、技术栈、仓库结构、命令契约、流程
PRD	灵犀-信息流广告素材一站式生产平台PRD.md	V1.6（最新）	需求、业务规则（R-01~R-30）、验收标准
技术架构	灵犀_信息流素材生产平台_技术架构_V0.1.md	V0.4（内部版本）	技术选型、分层模块、数据模型、接口、ADR
开发计划	灵犀_信息流素材生产平台_开发计划_V0.1.md	V0.1（初稿）	全项目 M0–M4：里程碑、批次、WBS、七管理模块专项、门禁、风险、验收
立项建议	灵犀_信息流素材生产平台_立项建议书_V0.1.md	V0.1	背景、目标、投入产出论证（不约束实现）
工程规范	docs/工程规范/	V1.0	Git、代码风格、格式化、API、数据库、测试、Review、日志、密钥、资产命名
A0 报告	灵犀_A0工程骨架与契约基线_实施报告_V0.1.md	V0.1	A0 完成范围、门禁实测、环境适配与待确认事项
历史 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 工程骨架与契约基线（monorepo、API/Worker/Web 骨架、Prisma 平台表、shared 契约包、UI 包、布局与登录壳、CI 与冒烟测试）；业务模块从 A1 起按开发计划推进。目录与依赖方向见 AGENTS.md §5。

本地开发

前置：Node.js 24.15.0（.nvmrc）、pnpm 10.x、Docker。

cp .env.example .env.local
cp .env.local .env          # Prisma CLI 只读取 .env（两者均已 gitignore）
pnpm check:dev              # 检查本机 PostgreSQL / Redis 是否可用
pnpm db:migrate             # 首次建表；后续由 Prisma 迁移管理
pnpm db:seed                # 幂等写入 system_configs 基线
pnpm dev                    # 并行启动 api(3000) / web(5173) / worker

也可以使用一键脚本（后台启动、自动检测并释放端口、带健康检查）：

./dev.sh                    # 启动 api + web + worker
./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 接入真实登录后删除。

常用校验：

pnpm lint && pnpm typecheck && pnpm test   # 本地门禁
pnpm build && pnpm test:e2e                # 构建与端到端冒烟
pnpm openapi:export && pnpm openapi:diff   # 契约快照与破坏性变更检查
pnpm ci:local                              # 本地跑完整 CI 门禁

Gitea 暂未部署 Actions runner，推送后远程 CI 会停留在 queued；当前以 pnpm ci:local 为准，runner 就绪后 .gitea/workflows/ci.yml 会自动接管。

命令与门禁见 AGENTS.md §6 与 06-测试与CI规范。当前 UI 采用「顶部模块菜单 + 左侧功能菜单」布局，视觉方向为 A · 云白蓝（传统企业后台 + 现代浅色质感）。

约定速查

包管理只用 pnpm，Node 锁定 24.15.0；UI 只用 Semi Design，图标只用 Remix Icon。
客户数据隔离、审计 append-only、导出全留痕、阈值单一来源、低质量不可静默——均为硬约束。
完整红线见 AGENTS.md §3。

8.4 KiB Raw Blame History Unescape Escape