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

# 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. 哪些地方可以先用假设推进
````