qinggang.deng/cps-develop-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update existing rule docs with AI output schema

Browse Source
This commit is contained in:
qg
2026-03-30 11:19:22 +08:00
parent 03a5087260
commit 4ddae35ffb
19 changed files with 103 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
02 - Design Standard/2.1 系统架构设计原则.md
View File

@@ -73,6 +73,10 @@
* **事件驱动与异步解耦：**
* **区分核心流与旁路流：** 主业务流程（如“用户下单”）应当是同步的；而非核心流程（如“下单后发送短信通知”、“增加积分”）应当通过**事件总线 (Event Bus)** 或 **消息队列 (MQ)** 异步解耦。
* *底线：* 旁路流的失败（如短信网关宕机）绝对不能导致主业务流程的回滚或失败。
* **防腐层设计 (ACL \- Anti-Corruption Layer)：**
* 在对接老旧的遗留系统或不可控的第三方外部 API（如支付网关、SaaS 接口）时，必须在系统边界建立防腐层（Adapter/Facade）。
* *实践：* 将外部混乱的数据模型在防腐层转换为系统内部干净的标准模型，防止外部概念“污染”我们的核心业务代码。外部接口升级时，只需修改防腐层即可。
* **防腐层设计 (ACL \- Anti-Corruption Layer)：**
* 在对接老旧的遗留系统或不可控的第三方外部 API（如支付网关、SaaS 接口）时，必须在系统边界建立防腐层（Adapter/Facade）。
* *实践：* 将外部混乱的数据模型在防腐层转换为系统内部干净的标准模型，防止外部概念“污染”我们的核心业务代码。外部接口升级时，只需修改防腐层即可。
## 🤖 [附加] AI 助手执行协议 (AI Output Schema)
**绝对红线**：默认采用模块化单体架构，除非明确要求否则禁止过度微服务拆分；强制遵循下层不可反向依赖上层的单向依赖流。

6
02 - Design Standard/2.2 API 接口设计规范.md
View File

@@ -152,4 +152,8 @@ API 是前后端、微服务之间沟通的**核心契约**。优秀的 API 设
* 40202: 账户余额不足。
* 50000: 服务器内部错误通配。
*规约：如果决定使用错误码，则禁止在代码中硬编码（如 return new Response(40102, "被冻结")），必须统一定义在 ErrorCodeEnum 枚举类中集中管理。*
*规约：如果决定使用错误码，则禁止在代码中硬编码（如 return new Response(40102, "被冻结")），必须统一定义在 ErrorCodeEnum 枚举类中集中管理。*
## 🤖 [附加] AI 助手执行协议 (AI Output Schema)
**绝对红线**：接口文档必须输出为 OpenAPI 3.0 YAML 格式；所有 HTTP 接口的响应体必须强制包裹在统一的 `{code, msg, data}` JSON 结构中。

10
02 - Design Standard/2.3 数据库与存储设计规范.md
View File

@@ -83,6 +83,10 @@ Redis 虽然快，但不当的使用会导致内存泄漏和严重的并发故
* **防范缓存雪崩 (Cache Avalanche)：** \* **问题：** 大量缓存在同一时刻集体过期，导致巨量请求瞬间全部打向数据库，击穿 DB。
* **对策：** 在设置 TTL 时，必须**加上一个随机的抖动时间**（例如，基础过期时间 2 小时 \+ 随机 0\~300 秒）。
* **防范缓存穿透 (Cache Penetration)：** \* **问题：** 黑客恶意查询一个数据库中绝对不存在的值（如 id=-1），导致缓存永远不命中，所有请求全打到 DB。
* **对策：** 即使数据库返回 Null，也要把这个 Null 值缓存进 Redis（设置一个较短的 TTL，如 5 分钟）；或者引入布隆过滤器 (Bloom Filter) 提前拦截。
* **防范缓存击穿 (Cache Breakdown)：** \* **问题：** 某一个“极其热点”的 Key 突然过期的一瞬间，上万个并发请求发现缓存未命中，同时去查询 DB 并尝试重写缓存，导致 DB 崩溃。
* **对策：** 使用分布式锁（如 Redisson）控制，只让一个线程去查询 DB 并重建缓存，其他线程等待；或针对极度热点的数据设置“逻辑过期”而非物理过期。
* **对策：** 即使数据库返回 Null，也要把这个 Null 值缓存进 Redis（设置一个较短的 TTL，如 5 分钟）；或者引入布隆过滤器 (Bloom Filter) 提前拦截。
* **防范缓存击穿 (Cache Breakdown)：** \* **问题：** 某一个“极其热点”的 Key 突然过期的一瞬间，上万个并发请求发现缓存未命中，同时去查询 DB 并尝试重写缓存，导致 DB 崩溃。
* **对策：** 使用分布式锁（如 Redisson）控制，只让一个线程去查询 DB 并重建缓存，其他线程等待；或针对极度热点的数据设置“逻辑过期”而非物理过期。
## 🤖 [附加] AI 助手执行协议 (AI Output Schema)
**绝对红线**：强制输出两部分内容：1. Mermaid 格式的 ER 图；2. 包含 [表名、字段名、类型、是否为空、默认值、索引说明] 的标准 Markdown 表格。