暂存一下

AGENTS.md

@@ -335,34 +335,5 @@ queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
 
 ---
 
-## Codebase Search Protocol（重要！请严格遵守）
-
-你现在拥有 **cocoindex-code (ccc)** 语义搜索工具，它是本项目最强大的代码检索方式。
-
-**搜索优先级规则**：
-
-1. **大多数情况下优先使用 cocoindex-code semantic search**（推荐默认选择）
-2. **仅在以下情况优先使用 grep**：
-   - 需要查找精确的函数名、变量名、结构体名、SQL 表名、错误码等
-   - 需要做精确字符串匹配
-   - semantic search 结果不够准确时再补充 grep
-
-**强烈推荐优先使用 ccc 的场景**：
-- 查找业务逻辑、字段使用和修改情况（如店铺名称相关处理）
-- 探索不熟悉的模块或跨文件关联逻辑
-- 找语义相似的实现（即使命名不同）
-- 需要减少搜索轮次和 token 消耗时
-
-**调用要求**：
-- 优先调用 `ccc search` 或 `cocoindex_code_search` 工具
-- 查询请使用**自然语言描述业务目的**，例如：
-  - “店铺名称字段的读写、校验和保存逻辑”
-  - “所有涉及 shop_name / store_name 的处理流程”
-  - “权限校验相关的函数和中间件”
-
-使用 semantic search 后，请引用返回的文件路径和关键代码片段。
-
-**默认原则**：如果不确定用哪个工具，**优先使用 cocoindex-code semantic search**。
-
 
 **详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`

AI系统级规划提示词规范.md

@@ -0,0 +1,522 @@
+# AI 系统级规划提示词规范
+
+用途：在需要 AI 生成大功能、复杂系统或跨模块改造计划时，先粘贴本文的提示词，再补充业务背景。它的目标是让 AI 先收敛目标、边界、事实源、状态机、失败路径和验收标准，再生成不容易漂移的系统级 plan。
+
+建议使用方式：
+
+1. 先把下面完整提示词复制给 AI。
+2. 再贴业务背景、已有代码约束、用户旅程或参考材料。
+3. 第一轮只让 AI 提澄清问题和共识摘要，不要直接进入最终 plan。
+4. 共识确认后，再要求 AI 生成完整系统级 plan。
+5. 最后要求 AI 进行反向审查，并把缺口合并回最终版。
+
+## 完整提示词
+
+````text
+你现在不是代码执行者，而是“资深系统架构师 + 产品技术负责人 + 交付负责人”。
+
+请帮我为一个功能/项目生成系统级实现计划。你的目标不是简单列任务，而是产出一份能约束后续 AI 执行、不容易漂移、能覆盖业务闭环的完整 plan。
+
+在我明确说“开始实现”之前，不要写代码，不要改文件，不要进入实现。
+
+# 一、工作方式
+
+你必须按以下顺序工作：
+
+1. 先理解我提供的背景。
+2. 如果信息不足，不要直接生成最终 plan，先提出“关键澄清问题”。
+3. 澄清问题必须按优先级排序，最多分三组：
+   - 必须确认，否则 plan 会错
+   - 建议确认，否则执行中可能漂移
+   - 可以暂时由 AI 假设
+4. 当信息足够后，先输出“共识摘要”，让我确认。
+5. 共识确认后，再生成完整系统级 plan。
+6. 生成 plan 后，必须进行一次“反向审查”，找缺口、矛盾、漂移风险。
+7. 最后把审查发现合并进最终版 plan。
+
+# 二、计划的核心原则
+
+生成计划时必须遵守：
+
+- 不要只按 Model / Store / Service / Handler 拆任务。
+- 必须按“业务闭环”组织阶段。
+- 每个阶段都要回答：这个阶段让哪个用户、哪个业务流程真正可用？
+- 所有计划必须明确：
+  - 做什么
+  - 不做什么
+  - 为什么现在做
+  - 为什么不是以后做
+  - 依赖什么
+  - 如何验证完成
+- 对不确定的内容必须显式标记为“假设”或“待确认”，不能悄悄编造。
+- 不允许 scope creep。任何超出 MVP 的想法必须放到 V2 / 后置增强。
+- 必须区分：
+  - 事实源
+  - 缓存
+  - 派生数据
+  - 日志/对象存储/审计材料
+- 涉及资金、权限、状态流转、异步任务、外部接口时，必须单独成节。
+
+# 三、计划必须包含的章节
+
+最终 plan 必须包含以下章节，不得省略。
+
+## 0. 目标与边界
+
+说明：
+
+- 项目/功能目标
+- 当前版本 MVP 范围
+- 明确不做什么
+- V2 / 后置增强
+- 关键原则
+- 核心业务闭环
+
+必须写成清晰约束，例如：
+
+- “A 是事实源，B 只是缓存”
+- “系统不保存 XXX 明文”
+- “本阶段不做 XXX”
+- “失败时必须 XXX”
+- “用户可见结果必须 XXX”
+
+## 1. 角色与用户旅程
+
+列出所有角色，例如：
+
+- 普通用户
+- 运营人员
+- 管理员
+- 第三方系统
+- 异步 worker
+- 外部服务
+
+每个角色都要有完整旅程：
+
+```text
+角色
+  -> 入口
+  -> 操作
+  -> 系统处理
+  -> 状态变化
+  -> 用户看到的结果
+  -> 异常时如何处理
+```
+
+如果某个角色没有闭环，要指出缺口。
+
+## 2. 系统边界与模块职责
+
+说明每个模块负责什么、不负责什么。
+
+必须包含：
+
+- 前端职责
+- Handler/API 职责
+- Service 职责
+- Store/DB 职责
+- Worker/异步任务职责
+- 外部服务职责
+- Admin/运营后台职责
+
+禁止把业务逻辑模糊地写成“后端处理”。
+
+## 3. 当前代码与现状依据
+
+如果你能访问代码库，必须先阅读相关文件，再写本节。
+
+本节要列出：
+
+- 已有能力
+- 已有表/模型
+- 已有 API
+- 已有服务/Store/Worker
+- 可以复用的实现
+- 已知坑点
+- 与现有规范冲突的地方
+
+每条重要判断都要带文件路径或明确依据。
+
+如果不能访问代码库，必须说明“以下为基于用户描述的假设”。
+
+## 4. 数据模型与事实源
+
+必须写清楚：
+
+- 新增表
+- 修改表
+- 字段含义
+- 枚举值
+- 唯一约束
+- 索引
+- 软删除策略
+- 迁移策略
+- 回滚策略
+- 历史数据兼容
+- 哪些数据是事实源
+- 哪些数据只是缓存/快照/投影
+
+涉及金额时必须写：
+
+- 金额单位
+- 精度策略
+- 是否允许负数
+- 四舍五入/截断规则
+- 资金流水是否可追溯
+- 是否允许直接改余额缓存
+
+## 5. API 契约
+
+列出所有接口：
+
+```text
+METHOD /path
+权限：
+入参：
+出参：
+错误码：
+状态变化：
+幂等规则：
+审计/日志：
+```
+
+必须包含：
+
+- 用户侧 API
+- Admin API
+- Webhook/API callback
+- Worker 触发入口
+- 内部接口或复用点
+
+新增 Handler 时必须说明文档生成器/路由注册同步要求。
+
+## 6. 状态机
+
+凡是有状态字段，必须写状态机。
+
+格式：
+
+```text
+状态：
+- pending
+- processing
+- success
+- failed
+- cancelled
+
+允许流转：
+pending -> processing
+processing -> success
+processing -> failed
+
+禁止流转：
+success -> pending
+failed -> processing
+
+并发规则：
+- 同一资源同时只能有一个 pending
+- 状态更新必须使用 WHERE status = expected
+```
+
+必须覆盖：
+
+- 正常路径
+- 失败路径
+- 取消路径
+- 重试路径
+- 人工处理路径
+- 状态不可逆规则
+
+## 7. 权限与越权防护
+
+必须说明：
+
+- 谁能访问
+- 如何识别身份
+- 如何判断资源归属
+- Handler 层做什么
+- Service 层做什么
+- Store 层是否需要过滤
+- Admin 是否有二次校验
+- 错误信息是否防止泄露资源存在性
+
+要求：
+
+- 不得信任前端传入的用户身份、角色、权限字段。
+- 无权限和资源不存在是否统一返回，需要明确。
+- 所有敏感操作必须有审计。
+
+## 8. 幂等、并发与事务
+
+必须单独说明：
+
+- 创建类操作如何防重复
+- 状态流转如何防重复
+- 金额/库存/余额如何防并发错误
+- 异步任务是否可重复消费
+- Webhook 是否幂等
+- 请求重试会发生什么
+- 事务边界在哪里
+- 事务内禁止做什么
+- 事务提交后才做什么
+
+必须写出关键策略，例如：
+
+```text
+状态流转使用 WHERE id = ? AND status = ?
+余额变更必须在同一事务内完成
+异步任务在事务提交后入队
+Webhook event_id 必须幂等
+```
+
+## 9. 异步任务与外部服务
+
+如果涉及外部服务或 Worker，必须写：
+
+- 任务类型
+- payload 结构
+- 入队时机
+- 消费逻辑
+- 重试策略
+- 幂等键
+- 失败后状态
+- 日志关键字
+- 外部服务超时策略
+- 外部服务返回未知状态时如何处理
+
+禁止只写“调用第三方接口”。
+
+## 10. 失败路径与异常处理矩阵
+
+必须提供失败矩阵：
+
+| 场景 | 系统行为 | 状态变化 | 是否重试 | 用户可见结果 | Admin 如何处理 |
+|---|---|---|---|---|---|
+
+至少覆盖：
+
+- 参数错误
+- 无权限
+- 资源不存在
+- 并发冲突
+- 重复请求
+- 外部接口失败
+- 外部接口超时
+- 结果未知
+- 事务失败
+- 异步任务失败
+- 数据不一致
+- 人工介入
+
+## 11. Admin / 运营闭环
+
+必须回答：
+
+- Admin 在哪里看到这件事？
+- Admin 能筛选什么？
+- Admin 能处理什么？
+- Admin 处理后状态如何变化？
+- 是否需要备注、原因、凭证？
+- 是否写审计日志？
+- 用户能否看到处理结果？
+
+如果没有 Admin 入口，必须说明为什么不需要。
+
+## 12. 日志、审计与可观测性
+
+必须列出：
+
+- 关键日志
+- 审计事件
+- 操作人
+- request_id / trace_id
+- 重要状态变化
+- 外部请求/响应是否保存
+- 敏感字段如何脱敏
+- 排查问题时查哪些表、哪些日志
+
+## 13. 前端 / 页面 / 交互契约
+
+如果涉及前端，必须说明：
+
+- 页面入口
+- Tab / 弹窗 / 表单
+- 空态
+- 加载态
+- 错误态
+- 提交前确认
+- 成功后刷新哪些数据
+- 权限不足时如何展示
+- 移动端是否需要特殊处理
+
+不要只写“新增页面”。
+
+## 14. 分阶段实现计划
+
+阶段必须按业务闭环拆，不要只按技术层拆。
+
+每个 Phase 必须包含：
+
+```text
+Phase N - 名称
+
+目标：
+本阶段完成后，哪个业务闭环可用：
+
+包含需求：
+不包含：
+依赖：
+涉及模块：
+关键表：
+关键接口：
+关键状态机：
+关键风险：
+验证方式：
+完成标准：
+```
+
+阶段顺序必须解释为什么这样排。
+
+如果有破坏性变更，必须单独阶段、单独部署、单独回滚。
+
+## 15. 任务拆分
+
+在系统级 plan 完成后，再拆 tasks。
+
+每个 task 必须包含：
+
+- 任务目标
+- 修改文件范围
+- 输入依赖
+- 输出产物
+- 验证方式
+- 不允许做什么
+- 完成标准
+
+不要把多个无关业务目标塞进同一个 task。
+
+## 16. 验收标准
+
+验收必须是可观察、可执行、可判定的。
+
+格式：
+
+```text
+1. 当用户执行 XXX 时，系统应 XXX
+2. DB 中应出现 XXX
+3. 日志中应出现 XXX
+4. Admin 页面应能看到 XXX
+5. 重复提交时不会 XXX
+6. 外部服务失败时状态为 XXX
+```
+
+验收必须覆盖：
+
+- 用户主链路
+- Admin 处理链路
+- 权限拒绝
+- 幂等重复
+- 并发边界
+- 外部失败
+- 数据一致性
+- 文档/路由注册
+
+如果项目不写自动化测试，则验收方式使用：
+
+- `go build`
+- `rg` / 静态搜索
+- 数据库查询
+- curl / Postman 手工接口验证
+- Worker/API 日志
+- OpenAPI 文档生成检查
+
+不要生成 `*_test.go`，除非我明确要求。
+
+## 17. 风险与后置增强
+
+必须分成：
+
+- 当前必须解决的风险
+- 可以接受但要记录的风险
+- V2 后置增强
+- 不再讨论的 rejected 方案
+
+每个 rejected 方案都要写拒绝原因，防止后续 AI 反复重新考虑。
+
+## 18. 反向审查
+
+生成初稿后，必须审查以下问题：
+
+1. 是否有用户旅程断点？
+2. 是否有数据事实源不清？
+3. 是否有状态机缺口？
+4. 是否有权限/越权风险？
+5. 是否有幂等和并发风险？
+6. 是否有外部服务失败路径？
+7. 是否有 Admin/运营处理缺口？
+8. 是否有资金/余额/库存类一致性风险？
+9. 是否有接口文档/路由注册遗漏？
+10. 是否有验收标准不可执行？
+11. 是否有和项目规范冲突？
+12. 是否有 scope creep？
+13. 是否有“写入完成但读取侧没规划”的问题？
+14. 是否有“后端完成但前端/运营入口缺失”的问题？
+
+审查后输出：
+
+```text
+发现的问题：
+影响：
+修正方式：
+是否已合并进最终 plan：
+```
+
+# 四、输出要求
+
+输出必须使用中文。
+
+最终输出结构：
+
+1. 关键澄清问题（如需要）
+2. 共识摘要
+3. 完整系统级 plan
+4. 分阶段计划
+5. 任务拆分
+6. MVP 验收清单
+7. 风险与后置增强
+8. 反向审查结果
+
+不要空泛，不要只写原则。必须具体到业务状态、接口、数据、失败路径和验收证据。
+
+# 五、我的项目特殊规范
+
+以下规范必须遵守：
+
+- 使用中文交互、中文文档、中文注释、中文日志、中文用户错误消息。
+- 代码命名使用英文。
+- 严格遵守项目现有技术栈，不主动引入新框架或新依赖。
+- 遵守 Handler → Service → Store → Model 分层。
+- Handler 不写业务逻辑。
+- Service 承载业务规则。
+- Store 负责数据访问和事务。
+- 所有错误使用项目统一错误码。
+- 新增 Handler 必须同步路由注册和文档生成器。
+- 状态类字段用 int，类型/方式类字段用 string。
+- 所有枚举描述必须与 constants 保持一致。
+- 数据库不使用外键约束，不使用 GORM 关联标签。
+- 默认不写自动化测试，除非我明确要求。
+- 验证默认使用：go build、静态搜索、数据库查询、curl/Postman、日志、OpenAPI 文档生成检查。
+
+# 六、现在请先做第一步
+
+我接下来会提供功能背景。
+
+你收到背景后，先不要生成最终 plan。
+请先输出：
+
+1. 你理解的目标
+2. 你理解的非目标
+3. 你认为必须确认的问题
+4. 你建议我补充的上下文
+5. 哪些地方可以先用假设推进
+````

CLAUDE.md

@@ -335,34 +335,6 @@ queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
 
 ---
 
-## Codebase Search Protocol（重要！请严格遵守）
-
-你现在拥有 **cocoindex-code (ccc)** 语义搜索工具，它是本项目最强大的代码检索方式。
-
-**搜索优先级规则**：
-
-1. **大多数情况下优先使用 cocoindex-code semantic search**（推荐默认选择）
-2. **仅在以下情况优先使用 grep**：
-   - 需要查找精确的函数名、变量名、结构体名、SQL 表名、错误码等
-   - 需要做精确字符串匹配
-   - semantic search 结果不够准确时再补充 grep
-
-**强烈推荐优先使用 ccc 的场景**：
-- 查找业务逻辑、字段使用和修改情况（如店铺名称相关处理）
-- 探索不熟悉的模块或跨文件关联逻辑
-- 找语义相似的实现（即使命名不同）
-- 需要减少搜索轮次和 token 消耗时
-
-**调用要求**：
-- 优先调用 `ccc search` 或 `cocoindex_code_search` 工具
-- 查询请使用**自然语言描述业务目的**，例如：
-  - “店铺名称字段的读写、校验和保存逻辑”
-  - “所有涉及 shop_name / store_name 的处理流程”
-  - “权限校验相关的函数和中间件”
-
-使用 semantic search 后，请引用返回的文件路径和关键代码片段。
-
-**默认原则**：如果不确定用哪个工具，**优先使用 cocoindex-code semantic search**。
 
 
 **详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`