2026-11-02 09:27:48 +00:00
2 changed files with 128 additions and 9 deletions
@@ -11,12 +11,13 @@
 ## 文档索引

 | 文档         | 路径                                                                                                   | 版本                 | 作用                                                                   |
-| --- | --- | --- | --- |
+| ------------ | ------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------- |
 | **项目总纲** | [AGENTS.md](AGENTS.md)                                                                                 | V1.0                 | 硬约束、技术栈、仓库结构、命令契约、流程                               |
 | **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                 | 背景、目标、投入产出论证（不约束实现）                                 |
 | **工程规范** | [docs/工程规范/](docs/工程规范/README.md)                                                              | V1.0                 | Git、代码风格、格式化、API、数据库、测试、Review、日志、密钥、资产命名 |
+| **A0 报告**  | [灵犀_A0工程骨架与契约基线_实施报告_V0.1.md](docs/开发计划/灵犀_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/工程规范/`。
@@ -26,7 +27,7 @@
 ## 核心链路（五步）

 | 步骤 | 动作                                           | 产出                 |
-| --- | --- | --- |
+| ---- | ---------------------------------------------- | -------------------- |
 | 1    | 建行业 / 客户信息，选行业包并套客户资产包      | 归属根节点就绪       |
 | 2    | 要素卡 + 卖点库 → 脚本生成 / 校核 / 审核入库   | 已入库脚本（带编号） |
 | 3    | 图片批次（模板 × 商品图 × 规格）/ 视频逐镜生成 | 候选素材             |
@@ -38,7 +39,7 @@
 ## 功能模块（PRD V1.6）

 | 模块         | 定位                                                                     |
-| --- | --- |
+| ------------ | ------------------------------------------------------------------------ |
 | **脚本**     | 要素卡 / 卖点库 / 模板 / 生成 / 质量校核 / 审核入库 / 版本               |
 | **素材**     | 图片线（PSD 套版、抠图、规格矩阵）、视频线（逐镜生成、变体）、快筛与预览 |
 | **资产**     | 15 类资产的库、版本、引用、复审与复用度量                                |
@@ -60,20 +61,37 @@ infra/          compose、Nginx、监控、备份
 docs/           PRD / 技术架构 / 立项建议 / 工程规范
 ```

-当前仓库处于**规范与设计阶段**，尚未建代码；建仓必须遵循 [AGENTS.md §5](AGENTS.md) 的结构与依赖方向。
+当前已完成 **A0 工程骨架与契约基线**（monorepo、API/Worker/Web 骨架、Prisma 平台表、shared 契约包、UI 包、布局与登录壳、CI 与冒烟测试）；业务模块从 A1 起按开发计划推进。目录与依赖方向见 [AGENTS.md §5](AGENTS.md)。

 ---

-## 本地开发（建仓后适用）
+## 本地开发
+
+前置：Node.js `24.15.0`（`.nvmrc`）、pnpm `10.x`、Docker。

 ```bash
 cp .env.example .env.local
-pnpm compose:up          # PostgreSQL 18 / Redis 7.4 / MinIO
-pnpm db:migrate
-pnpm dev
+cp .env.local .env          # Prisma CLI 只读取 .env（两者均已 gitignore）
+pnpm compose:up             # PostgreSQL 18 / Redis 7.4 / S3 兼容存储
+pnpm db:migrate             # 首次建表；后续由 Prisma 迁移管理
+pnpm db:seed                # 幂等写入 system_configs 基线
+pnpm dev                    # 并行启动 api(3000) / web(5173) / worker
 ```

-命令与门禁见 [AGENTS.md §6](AGENTS.md) 与 [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md)。
+- **端口**：为避免与本机已有容器冲突，compose 宿主端口为 PostgreSQL `15432`、Redis `16379`、S3 `19000/19001`，容器内仍是 `5432/6379/9000/9001`；`.env.example` 已按宿主端口给出连接串。
+- **对象存储**：当前 Docker 环境拉取不到 `minio/minio` 镜像（registry denied、二进制 410），A0 的 compose 使用 `adobe/s3mock` 并提供 `assets / renders / temp / archive` 四个初始桶；CI 或生产接入真实 MinIO 时只需替换 `infra/docker-compose.dev.yaml` 的 `s3` 服务。
+- **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   # 本地门禁
+pnpm build && pnpm test:e2e                # 构建与端到端冒烟
+pnpm openapi:export && pnpm openapi:diff   # 契约快照与破坏性变更检查
+```
+
+命令与门禁见 [AGENTS.md §6](AGENTS.md) 与 [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md)。当前 UI 采用「顶部模块菜单 + 左侧功能菜单」布局，视觉方向为 **A · 云白蓝（传统企业后台 + 现代浅色质感）**。

 ---

@@ -0,0 +1,101 @@
+# 灵犀 · A0 工程骨架与契约基线 实施报告 V0.1
+
+> 对应开发计划：`docs/开发计划/灵犀_信息流素材生产平台_开发计划_V0.1.md` §6.1「A0 工程骨架与契约基线」  
+> 实施分支：`feat/a0-skeleton`（基于 `docs/dev-plan-v0.1`）  
+> 日期：2026-11-02
+
+## 1. 完成范围
+
+| WBS | 状态 | 落地内容 |
+| --- | --- | --- |
+| A0-INF-01 Monorepo / 工具链 | 完成 | pnpm workspace + Turborepo；TS strict、ESLint 9 flat + Prettier + commitlint + lint-staged + husky；`.nvmrc` / `engines` / `packageManager` / preinstall 仅允许 pnpm；目录与 AGENTS.md §5 一致 |
+| A0-INF-02 本地依赖与迁移种子 | 完成（种子范围受限，见 §4.4） | `infra/docker-compose.dev.yaml`（PG 18 / Redis 7.4 / S3 兼容服务）+ 健康检查；`.env.example`；Prisma 初始化与首版迁移；`system_configs` 幂等种子 |
+| A0-INF-03 CI 与质量门禁 | 完成 | `.gitea/workflows/ci.yml`：install → format → lint → typecheck → test → build → migrate → test:int → openapi:export/diff → e2e；产物归档；失败阻断 |
+| A0-BE-01 API 骨架 | 完成 | NestJS 11 + Fastify；Pino + `trace_id`；统一错误体 `{code,message,details,trace_id}`；`GET /health`；`/api/docs` 与 OpenAPI JSON；Zod 管道；CORS / Helmet |
+| A0-BE-02 Prisma 基线 | 完成 | `PrismaService` 封装；`outbox_events` / `idempotency_keys` / `system_configs`；ULID `char(26)`、软删/时间字段约定；首版迁移可重复执行 |
+| A0-SH-01 shared 包 | 完成 | 20 个错误码（40001–50003）、权限点常量与 `模块:动作` 规范、ULID、游标分页、时间/命名工具、通用 Zod schema；前后端共同引用 |
+| A0-FE-01 Web 骨架 | 完成 | Vite 6 + React 19 + Router 7 + TanStack Query 5 + Zustand 5；Semi `@douyinfe/semi-ui-19` 与 React19 适配入口；路径别名；fetch 请求层（token 注入、单飞 401 刷新、统一错误提示） |
+| A0-FE-02 UI 包基线 | 完成 | Semi 二次封装（表格/查询表单/弹窗/空态/错误态/加载骨架）；`icons.ts` 统一图标出口；locale；主题 token；ESLint 拦截越过出口的图标/UI 库与内联色值 |
+| A0-FE-03 布局与登录壳 | 完成 | 顶部模块菜单 + 左侧功能菜单 + 面包屑；用户菜单、任务角标占位；401/403/404/500 页；登录页；导航集中配置并按权限过滤 |
+| A0-QA-01 冒烟与报告 | 完成 | 健康检查冒烟、OpenAPI 冒烟、Playwright 登录/403/404/模块切换 4 条；覆盖率报告；CI 归档 |
+
+## 2. 关键实现位置
+
+- 契约与工具：`packages/shared/src/`（`errors/codes.ts`、`errors/api-error.ts`、`permissions.ts`、`ulid.ts`、`naming.ts`、`schemas/`）
+- UI 基线：`packages/ui/src/`（`icons.ts`、`components/`、`theme/tokens.css`、`locale.ts`）
+- API：`apps/api/src/`（`bootstrap.ts`、`common/filters`、`common/pipes`、`modules/platform/health/`、`openapi/document.ts`、`scripts/export-openapi.ts`）
+- 数据：`prisma/schema.prisma`、`prisma/migrations/20261102083445_init_platform_baseline/`、`prisma/seed.ts`、`prisma/SEED.md`
+- Web：`apps/web/src/`（`layout/`、`navigation/nav-config.ts`、`api/client.ts`、`pages/`、`stores/auth-store.ts`、`styles/`）
+- 基础设施：`infra/docker-compose.dev.yaml`、`infra/compose.dev.yaml`、`.env.example`
+- 契约快照：`openapi/lingxi.openapi.json`、`apps/web/src/api/generated/openapi.d.ts`
+
+## 3. 本地门禁实测
+
+| 命令 | 结果 |
+| --- | --- |
+| `pnpm format:check` | 通过 |
+| `pnpm lint` | 通过（0 error / 0 warning） |
+| `pnpm typecheck` | 通过（10/10 turbo tasks） |
+| `pnpm test` | 通过（shared 42、api 20、web 12） |
+| `pnpm build` | 通过（8/8 turbo tasks） |
+| `pnpm test:int` | 通过（真实 PostgreSQL + Redis，`/health` 200） |
+| `pnpm test:e2e` | 通过（4/4，Playwright/Chrome） |
+| `pnpm openapi:export` + `pnpm openapi:diff` | 通过；快照含 20 个错误码，OpenAPI `3.1.0` |
+| `pnpm compose:up` | 通过；`lingxi-pg` / `lingxi-redis` / `lingxi-s3` 均 healthy |
+| API 启动 | `/health` 200、`/api/docs` 200、`/api/openapi.json` 200 |
+| Worker 启动 | 连接 Redis 成功，收到 SIGTERM 后正常退出 |
+| 种子幂等 | 连续执行两次，`system_configs` 保持 7 条 |
+
+## 4. 与文档的差异与待确认
+
+### 4.1 宿主端口（环境适配）
+
+本机已有容器占用 5432 / 6379，A0 compose 宿主端口改为 **15432（PG）/ 16379（Redis）/ 19000–19001（S3）**，容器内端口不变。`.env.example` 已按宿主端口提供连接串；CI 使用 GitHub Actions services 的标准端口。
+
+### 4.2 对象存储镜像不可得（环境适配）
+
+当前 Docker 环境无法拉取 `minio/minio` 与 `minio/mc`（registry denied），`dl.min.io` 二进制返回 410。A0 使用 **`adobe/s3mock`** 并在启动时创建 `assets / renders / temp / archive` 四个桶，仅用于本地开发；CI / 生产接入真实 MinIO 时替换 compose 中 `s3` 服务即可，应用侧仍只依赖 S3 协议与环境变量。
+
+### 4.3 演示登录（A0 临时）
+
+A1 才实现真实鉴权。A0 登录页在 `VITE_PUBLIC_DEMO_SESSION` 非 `false` 时使用本地演示会话进入布局，便于验收布局与权限过滤；A1 接入真实登录后删除该分支。
+
+### 4.4 种子范围【待确认 Q-A0-01】
+
+开发计划 A0-INF-02 要求种子包含「超管、示例角色、核心字典、电商行业包占位」，但 `users / roles / dict_* / industry_packages` 等表分别在 A1 / A3 / A4 / B0 批次建立。A0 不提前建业务表，仅 seed `system_configs` 7 项，并在 `prisma/SEED.md` 登记待补种子清单。**请确认是否接受该拆分**；若要求 A0 内建表，则需调整开发计划批次顺序。
+
+### 4.5 错误码 HTTP 映射
+
+工程规范 04 未规定 50002 / 50003 的 HTTP 状态。A0 将 `50002 依赖不可用` 映射为 **503**（与 `/health` 依赖异常返回值一致），`50003 超时` 映射为 504；如需改为 502 / 504，请确认后调整 `packages/shared/src/errors/codes.ts` 与 `codes.spec.ts`。
+
+### 4.6 Prisma CLI 与环境文件
+
+Prisma CLI 只自动读取 `.env`，不读取 `.env.local`。本地需执行 `cp .env.local .env`（两者均在 `.gitignore`）；应用与种子脚本同时兼容 `.env.local` 与 `.env`。
+
+### 4.7 OpenAPI 破坏性检查实现
+
+npm 上 `oasdiff` 为占位包（0.0.1-security），A0 暂用自研 `scripts/openapi-diff.mjs` 做路径/操作/字段级破坏性检查；CI 可后续替换为 oasdiff 官方二进制，命令仍为 `pnpm openapi:diff`。
+
+### 4.8 前端视觉方向
+
+已按 oil-ui-pro 流程产出两轮方案：
+- v1（概念化：剪辑台 / 稿纸 / 调度台）被否决；
+- v2（传统且现代化：云白蓝 / 石墨 / 暖白青）经产品负责人选择 **A · 云白蓝**，已落地到 `packages/ui/src/theme/tokens.css`、`apps/web/src/styles/`、`apps/web/index.html`：
+  - 顶部模块菜单 + 左侧功能菜单 + 面包屑；
+  - 白色顶栏、`#F5F7FA` 工作区、白卡片、`#1677FF` 主色、6px 圆角；
+  - 工作台：4 指标卡 + 生产任务表 + 快速入口 + 最近素材；
+  - 登录页：左上品牌、居中白卡、浅灰背景。
+
+设计探索产物位于 `design/a0-ui-v2/`（含 6 屏、对比页与截图），按 `.gitignore` 约定不入库，仅本地留存评审。
+
+## 5. 已知风险与后续动作
+
+1. **A1 必须移除演示登录**并接入真实 JWT / 刷新令牌 / 权限守卫。
+2. 种子业务数据待 A1 / A3 / A4 / B0 表就绪后补齐（Q-A0-01）。
+3. MinIO 本地替代方案需在具备镜像的环境回归；生产 compose 与 CI 镜像另行处理。
+4. Web 主包约 599 kB（Semi 全量 CSS 689 kB），A0 接受；M1 前做路由级拆分与 Semi 按需样式。
+5. CI 首次运行需在 Gitea Actions 上验证 runner 是否支持 services 与 Playwright 浏览器安装。
+
+## 6. 下一步（A1）
+
+按开发计划进入 A1：identity / client 模块、真实登录与 RBAC、`ScopeContext`、客户与组织基础表、登录与权限三态测试。