docs(specs): add AGENTS.md and engineering guidelines
项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立 总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈 基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、 格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。 影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。 回滚方式：git revert 本提交。
This commit is contained in:
Stev_Wang committed
1 parent
d062d79465
commit
00ae12435e
12 files changed
+1562
No files matched your search
@@ -0,0 +1,137 @@
|
||||
# 10 · 资产命名与 PSD 图层规范
|
||||
|
||||
| 项 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档版本 | V1.0（2026-11-02） |
|
||||
| 依据 | PRD §5.3（资产）、§5.2（素材线）、R-01 / R-19 / R-25 / R-29 / R-30；技术架构 §7.3 / §7.5 / §8.11 |
|
||||
| 适用范围 | 资产上传、模板制作、批次命名、成片导出、对象存储 |
|
||||
| 强制级别 | 强制（`PSD-*` 为图片线硬前提，不满足即不可入库） |
|
||||
|
||||
---
|
||||
|
||||
## 1 归属与层级
|
||||
|
||||
- `AST-01` 全部资产必须挂在「**行业 → 客户**」两级目录下；行业是客户的业务属性，**客户不可跨行业移动**（PRD R-20）。
|
||||
- `AST-02` 资产三级：**行业级（公共）→ 客户级（私有）→ 批次级（一次性）**；同名时客户级覆盖行业级。
|
||||
- `AST-03` 跨客户复用必须显式授权并留痕，**禁止**默认共享（PRD 5.3.2）。
|
||||
- `AST-04` 15 类资产固定为：行业包、脚本模板、视频方向、已入库脚本、图片模板、Logo、产品位置、警示语、人物池、场景池、光影/色调预设、BGM/音效、提示词模板、要素卡模板/卖点库、成片。新增类型须先改 PRD 与架构。
|
||||
- `AST-05` 资产状态：草稿 → 启用 → 停用；**被引用的资产只能停用不能删除**（R-02）；模板与提示词修改产生新版本并记录被引用的版本号（R-03）。
|
||||
|
||||
---
|
||||
|
||||
## 2 命名通用规则
|
||||
|
||||
| 项 | 规则 |
|
||||
| --- | --- |
|
||||
| 允许字符 | 中文、字母、数字、下划线 `_`、短横线 `-` |
|
||||
| 禁止字符 | 空格、`\ / : * ? " < > |`、`# % & { } $ ! ' @ + =`、控制字符 |
|
||||
| 长度 | ≤ 100 字符（含扩展名） |
|
||||
| 占位符 | `{行业}` `{客户}` `{视频方向}` `{日期}` `{序号}`（PRD R-01） |
|
||||
| 默认格式 | `{行业}-{客户}-{视频方向}-{序号}` |
|
||||
| 重名 | 自动追加序号（`-02`、`-03`），**禁止覆盖** |
|
||||
| 大小写 | 语义名大小写敏感；扩展名统一小写 |
|
||||
|
||||
- `AST-06` 占位符由服务端在**批次创建时快照**，之后修改命名规则不影响历史批次。
|
||||
- `AST-07` 文件名中的客户名使用**客户简称**（必填字段），不使用全称，避免超长与敏感信息。
|
||||
|
||||
---
|
||||
|
||||
## 3 各类编号与成片命名
|
||||
|
||||
| 对象 | 规则 | 示例 |
|
||||
| --- | --- | --- |
|
||||
| 脚本编号 | `{客户编码}-YYMMDD + 当日序号`，**过审入库时原子取号**；草稿不占号；一经分配不重用、不可改（R-21） | `LX001-261102-007` |
|
||||
| 素材批次号 | `{YYMMDD}{3 位当日序号}` | `261102003` |
|
||||
| 图片成片 | `{行业}-{客户}-{脚本方向}-{日期}-{序号}-{规格}` | `电商-某服饰-通勤穿搭-261102-01-9x16` |
|
||||
| 视频成片 | `{行业}-{客户}-{视频方向}-{序号}` | `电商-某服饰-达人到店-03` |
|
||||
| 导出目录 | `客户 / 交付日期 / 类型 / 批次` | `某服饰/2026-11-02/图片/261102003` |
|
||||
|
||||
- `AST-08` 规格后缀用 `宽x高` 或平台别名（`9x16`、`1x1`），由字典统一，**禁止**自由书写。
|
||||
- `AST-09` 成片命名与脚本编号必须可对账（交付清单同 key，PRD 5.5）。
|
||||
- `AST-10` 对象存储 key 与展示名分离：`storage_key = assets/{industry_id}/{customer_id}/{asset_id}/v{version}/{filename}`；展示名可改，key 不可改。
|
||||
|
||||
---
|
||||
|
||||
## 4 PSD 模板与图层约定（图片线核心）
|
||||
|
||||
### 4.1 图层前缀（唯一合法语义声明方式）
|
||||
|
||||
| 前缀 | 语义 | 数量要求 |
|
||||
| --- | --- | --- |
|
||||
| `image_replacement_` | 商品图替换位（主体） | ≥ 1 |
|
||||
| `clipping_mask_` | 剪贴容器 / 裁切区域 | 0..n |
|
||||
| `text_replacement_` | 文字替换位（可配置字号 / 对齐 / 颜色） | 0..n |
|
||||
|
||||
- `PSD-01` 命名结构：`<前缀><语义名>`，如 `image_replacement_main`、`text_replacement_price`；**前缀全小写且大小写敏感**。
|
||||
- `PSD-02` 同一模板内语义名唯一；重复命名视为非法。
|
||||
- `PSD-03` **无命名图层 / 解析失败 / 缺少 `image_replacement_` → 模板不得入库**，返回明确错误并提示设计师修正。
|
||||
- `PSD-04` 禁止用图层组名冒充命名图层；前缀必须落在**实际图层**上。
|
||||
- `PSD-05` 剪贴蒙版必须挂在 `clipping_mask_` 容器下，商品图替换后仍保持裁切关系。
|
||||
- `PSD-06` 新增图层前缀类型须先更新技术架构 §7.3 与本文，**禁止**在代码里私自识别新前缀。
|
||||
- `PSD-07` 模板入库时校验：图层语义完整性、画布尺寸与目标规格比例、字体是否在白名单、是否存在隐藏图层（隐藏图层默认忽略并记录）。
|
||||
- `PSD-08` 字体：镜像内置中文字体，启动自检；模板引用的字体不在白名单 → 拒绝入库（避免豆腐块，风险 R-T-18）。
|
||||
|
||||
### 4.2 抠图与合成
|
||||
|
||||
- `PSD-09` 抠图失败必须降级为原图并标 `low_quality`（原因码 `matting_fallback`），**默认不勾选**（R-30）。
|
||||
- `PSD-10` 合成结果必须过质量校验：安全区、Logo 完整性、主体不变形、警示语四项；未过则标 `low_quality` 并记录原因码。
|
||||
- `PSD-11` 视觉回归：`packages/render` 改动需跑像素级比对，阈值与基线图入库管理。
|
||||
|
||||
---
|
||||
|
||||
## 5 规格矩阵（字典化，禁止硬编码）
|
||||
|
||||
| 平台 | 比例 | 分辨率 |
|
||||
| --- | --- | --- |
|
||||
| 抖音 | 9:16 | 1080×1920 |
|
||||
| 小红书 | 3:4 | 1080×1440 |
|
||||
| 朋友圈 | 1:1 / 4:5 | 1080×1080 / 1080×1350 |
|
||||
| 横版 | 16:9 | 1920×1080 |
|
||||
| 电商主图 | 1:1 | 800×800 / 1200×1200 |
|
||||
|
||||
- `AST-11` 规格来自字典表，前后端与任务判定读同一来源（R-26）；新增规格改字典不发版。
|
||||
- `AST-12` 素材为主对象、规格为属性：**同源多规格不各建素材**，用 `material_specs` 承载（R-25）；素材与脚本多对多用关联表，**禁止 JSON 列存 ID**。
|
||||
|
||||
---
|
||||
|
||||
## 6 输出编码与存储
|
||||
|
||||
| 类型 | 参数 |
|
||||
| --- | --- |
|
||||
| 视频 | MP4 / H.264 / AAC / 1080×1920 / 30fps / `+faststart` |
|
||||
| 图片 | JPG（质量 92）或 PNG；导出质量 ≥ 90 |
|
||||
| 兜底 | 超限降质必须标 `low_quality`（原因码 `downscaled`），不得静默 |
|
||||
|
||||
| 桶 | 内容 | 保留 |
|
||||
| --- | --- | --- |
|
||||
| `assets` | 长期资产 | 永久（版本化） |
|
||||
| `renders` | 生成产物 | 按客户策略 |
|
||||
| `temp` | 任务中间文件 | 30 天 |
|
||||
| `archive` | 归档 | ≥ 12 个月 |
|
||||
| `uploads` | 原始上传 | 按资产生命周期 |
|
||||
| `exports` | 打包导出 | 3 天 |
|
||||
|
||||
- `AST-13` 下载一律短时效签名 URL（5–15 分钟），**禁止**公开读权限、禁止把签名 URL 存库。
|
||||
- `AST-14` 临时目录按任务隔离：`/tmp/task/{taskItemId}`，任务结束清理；失败任务保留 1 天便于排查后清理。
|
||||
|
||||
---
|
||||
|
||||
## 7 低质量原因码（统一枚举）
|
||||
|
||||
`matting_fallback`（抠图降级）· `missing_font`（缺字体）· `downscaled`（超限降质）· `logo_incomplete`（Logo 不完整）· `warning_missing`（警示语缺失）· `safe_area_violated`（安全区越界）· `subject_distorted`（主体变形）
|
||||
|
||||
- `AST-15` 原因码只增不改语义；前端与看板按码聚合，**禁止**在文案里写自由文本。
|
||||
- `AST-16` 低质量条目计入质量看板与指标（PRD 8.1），可被人工复核转为正常，但**必须留痕**。
|
||||
|
||||
---
|
||||
|
||||
## 8 检查清单（模板入库前）
|
||||
|
||||
- [ ] PSD 至少 1 个 `image_replacement_`，剪贴关系正确
|
||||
- [ ] 所有可替换位均有合法前缀，语义名唯一
|
||||
- [ ] 画布比例与目标规格匹配
|
||||
- [ ] 字体在白名单内，无隐藏图层未说明
|
||||
- [ ] 模板归属「行业 → 客户」正确，版本号已生成
|
||||
- [ ] 命名符合 §2，无非法字符，长度 ≤ 100
|
||||
- [ ] 低质量降级路径可触发，原因码已定义
|
||||
- [ ] 产物编码参数符合 §6，签名 URL 生效
|
||||
Reference in new issue
Block a user