68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
# Quality Guidelines
|
||
|
||
> Code quality standards for backend development.
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
<!--
|
||
Document your project's quality standards here.
|
||
|
||
Questions to answer:
|
||
- What patterns are forbidden?
|
||
- What linting rules do you enforce?
|
||
- What are your testing requirements?
|
||
- What code review standards apply?
|
||
-->
|
||
|
||
(To be filled by the team)
|
||
|
||
---
|
||
|
||
## Forbidden Patterns
|
||
|
||
<!-- Patterns that should never be used and why -->
|
||
|
||
(To be filled by the team)
|
||
|
||
---
|
||
|
||
## Required Patterns
|
||
|
||
<!-- Patterns that must always be used -->
|
||
|
||
### 部分 JSON 预览
|
||
|
||
- 从大会话文件的头部/尾部预览提取元数据时，必须识别 JSON 顶层结构；禁止用“第一个同名键”的正则结果代表顶层字段。
|
||
- 头部和尾部片段必须独立解析，禁止直接拼接后匹配，避免截断边界组合出文件中不存在的键值。
|
||
- 预览读取必须保持明确的字节上限；解析失败时按字段缺失安全降级，不能让单个损坏会话中断整个列表。
|
||
|
||
### 完整历史与有界快照
|
||
|
||
- 具体签名、存储格式、失败矩阵及回归断言见 [完整历史保存契约](./session-history.md)。
|
||
- 会话消息数、正文和工具内容的预览上限只能作用于快照缓存；成功保存的完整历史必须由 cc-web 自身持久化，不能依赖原生客户端日志继续存在。
|
||
- 完整档案先原子提交，随后更新有界快照；完整档案失败时不得用裁剪快照覆盖上次状态。档案提交成功而快照失败时，读取和会话列表仍须能找到已提交档案。
|
||
- 可信完整读取后的修改应保留清空、撤回和插入顺序；短预览及旧修订不能覆盖完整消息或丢掉后来追加的记录，正常并发保存不得静默漏记。
|
||
- 旧版截断历史只有在确认原始记录对应边界后才能补入完整档案；新建档案本身不能证明旧历史已完整。
|
||
- 大型运行态JSON须使用分段编码和直接构造对象的流式读取，禁止完整原文、全量写出缓冲及序列化克隆同时驻留；不能把单次读写有界解释为返回对象总内存有界。
|
||
- 任务状态版本保护在同一次归档提交内处理，失败不得提前推进可信基线或活跃任务状态；JSON读写需对照原生语义并覆盖跨段编码、短读短写及原子失败保护。
|
||
|
||
---
|
||
|
||
## Testing Requirements
|
||
|
||
<!-- What level of testing is expected -->
|
||
|
||
- 部分 JSON 解析改动必须使用超过完整解析阈值的真实文件夹具，证明测试确实进入预览分支。
|
||
- 回归至少覆盖：嵌套同名键早于顶层键、顶层键位于尾部、字符串伪键与转义、`null`、字段跨截断边界、头尾拼接伪命中。
|
||
- 完整历史回归须覆盖超过快照上限、长正文与工具结果、存储重开且原始日志不可用、短快照重复保存、正常并发修改、主动清空/删除、归档写入失败及快照缓存失败。
|
||
|
||
---
|
||
|
||
## Code Review Checklist
|
||
|
||
<!-- What reviewers should check -->
|
||
|
||
(To be filled by the team)
|