infstellar
60ac45ca65
Archive eight completed changes and merge their final requirements into the main specifications. Resolve superseded sidecar, flat-library, runtime dependency, and PostgreSQL terminology conflicts. 归档八个已完成的变更，并将最终需求合并到主规格。解决已被替代的 sidecar、扁平图片库、运行时依赖和 PostgreSQL 术语冲突。
5.5 KiB
Purpose
为浏览器前端提供受控的扁平图片库管理能力，使用户能够浏览、预览和重命名当前数据范围内的图片，同时阻断任意路径访问和覆盖风险。
Requirements
Requirement: 系统必须提供受控的扁平图片列表
系统 MUST 只列出当前 scope 的可信图片根中存在有效 Meme 记录的图片，不得提供用户可见的目录层级。列表响应 MUST 返回稳定 meme_id、文件名、扩展名、大小、处理状态和受控媒体引用，不得返回服务器绝对路径或目录字段。列表 MUST 支持文件名筛选、分页和确定性排序。文件系统中没有对应 Meme 记录的孤立文件不得作为正常图片返回。
Scenario: 列出当前数据范围的图片
- WHEN 客户端请求图片列表并提供合法的筛选及分页参数
- THEN 系统返回当前 scope 内匹配的扁平图片列表
- AND 每张图片包含稳定 Meme 身份和受控媒体引用，不包含目录信息
Scenario: 提交已废弃的目录参数
- WHEN 客户端向图片列表提交
directory或其他目录选择参数 - THEN 系统返回参数错误
- AND 不执行目录浏览或兼容逻辑
Scenario: 目录中存在孤立文件
- WHEN 文件系统中存在未被当前 scope 的 Meme 记录引用的图片
- THEN 列表不返回该文件，并允许完整性检查流程报告或隔离它
Requirement: 系统必须安全地重命名图片
系统 MUST 在当前 scope 的可信图片根中执行重命名，保留原扩展名，拒绝覆盖已有文件，并在成功后更新数据库中的存储路径。重命名 MUST 保持原 meme_id 不变，并在成功后返回稳定 Meme 标识、新文件名和媒体引用。
Scenario: 重命名成功
- WHEN 客户端提交当前 scope 中存在的
meme_id和合法的新文件名 - THEN 原文件被重命名，扩展名和
meme_id保持不变，数据库存储路径同步更新
Scenario: 新文件名冲突
- WHEN 目标文件名已存在或当前 scope 已引用目标路径
- THEN 系统返回
409，且原文件和原 Meme 记录保持不变
Scenario: 新文件名非法
- WHEN 新文件名包含路径结构或使用内部保留名称
- THEN 系统返回
400，且原文件和原 Meme 记录保持不变
Scenario: 使用其他 scope 的 Meme 标识
- WHEN 客户端提交不属于当前 scope 的
meme_id - THEN 系统返回
404，不泄露目标资源信息且不修改文件
Requirement: 系统必须通过媒体接口提供图片
图片预览 MUST 通过受控媒体接口按当前 scope 和 meme_id 定位数据库记录，再读取受允许图片根目录保护的文件。接口 MUST 校验记录归属、存储路径和实际文件类型，不得仅凭客户端提供的文件路径读取媒体。
Scenario: 预览合法图片
- WHEN 客户端请求当前 scope 中存在且文件指纹有效的
meme_id - THEN 系统返回图片内容及正确的媒体类型
Scenario: 预览非法或不存在图片
- WHEN 客户端请求其他 scope、越界路径、文件缺失或不存在的 Meme 标识
- THEN 系统返回
403或404，不读取其他文件也不泄露资源归属
Requirement: 系统必须拒绝非扁平图片库存量
系统 MUST 在 schema migration 写入扁平约束前拒绝任何非扁平 Meme 业务 key，并 MUST 在应用启动就绪检查中拒绝非扁平 Meme 记录、图片根下嵌套的受支持图片以及与数据库记录不一致的嵌套业务文件。检查 MUST 是只读的，不得自动移动、导入、重命名或删除文件。受控的内部 staging 和 quarantine key MUST NOT 被当作业务图片拒绝。
Scenario: 扁平图片库通过就绪检查
- WHEN 数据库中的全部 Meme 使用扁平文件名，图片根不存在嵌套业务图片，且内部暂存区只包含受控操作文件
- THEN migration 和应用就绪检查允许服务继续启动
Scenario: migration 发现非扁平业务记录
- WHEN migration 在 Meme 记录或存储操作的业务字段中发现包含路径结构的业务 key
- THEN migration 在执行 schema DDL 前失败并报告一致性错误
- AND 不修改数据库记录或文件
Scenario: 启动发现嵌套业务图片
- WHEN 应用启动就绪检查发现非扁平 Meme 记录、图片根下的嵌套受支持图片或与数据库不一致的嵌套业务文件
- THEN 应用拒绝进入就绪状态并报告扁平图片库不一致
- AND 不自动修改任何记录或文件
Scenario: 内部恢复文件不阻止启动
- WHEN
.staging或.quarantine中存在符合存储操作协议的受控内部文件 - THEN migration 和应用就绪检查不把这些内部 key 视为非扁平业务图片
- AND 现有恢复流程仍可处理对应操作
Requirement: 系统必须安全地删除 Meme
系统 MUST 只删除当前 scope 中指定 meme_id 对应的数据库记录和图片文件。删除成功后，该 Meme MUST 不再出现在列表、媒体访问、语境和搜索结果中；任一步骤失败时 MUST 通过补偿或恢复流程避免半删除状态。
Scenario: 删除成功
- WHEN 客户端删除当前 scope 中存在的 Meme
- THEN 系统删除其业务记录和图片文件，并返回成功结果
Scenario: 删除过程失败
- WHEN 文件删除或数据库提交失败
- THEN 系统不报告成功，并恢复原资源或记录可继续恢复的删除操作