---
title: AI 提示词与执行约束（WWJCloud）
description: 统一的 AI 协作提示词、上下文提供清单与强制约束，确保回答可执行、改动可控、与架构规划一致。
---

# AI 提示词与执行约束（WWJCloud）

## 目标
- 回答必须“可执行、可核验、最小改动、可回滚”。
- 严格遵守本项目的领域边界、数据一致性与微服务演进路线。

## 提供上下文（调用 AI 前的必备信息）
- 任务目的与期望产出（代码/文档/脚本/命令）。
- 影响范围（目录/模块/表/接口）。
- 相关文件片段（尽量给出路径与行号）。
- 现状与约束（运行环境、端口、依赖版本、是否允许新依赖）。
- 回滚策略（如仅限编辑文档、不许改表结构、不改公开 API）。

## 强制约束（回答/改动必须遵守）
- 架构与边界
  - 禁跨域直查数据库；跨域仅通过“域 SDK 接口/领域事件”。
  - 保持统一 Swagger（/docs、/docs-json），文档站按前缀（/api、/adminapi）分组。
  - 事件/任务：事件走 Kafka（或 Outbox→Kafka），任务走 Redis（或 Outbox→Worker），允许现阶段沿用 DB jobs 作为 Outbox。
- 数据与迁移
  - 不重命名/拆分现有表；优先加索引与新增伴随表（如 Outbox）。
  - 新增字段/索引需说明兼容性与回滚方式。
- 安全与网关
  - 网关二选一（Traefik/Kong）作为北向入口；东西向留给服务网格（Envoy/Istio）。
  - 默认开启 JWT 校验、限流、超时/重试、熔断（如可用）。
- 可观测
  - 保留 traceId、site_id；核心链路加指标与追踪埋点。
- 代码与风格
  - 避免破坏性重构；提交“最小可行改动”。
  - 保留原缩进与格式；新增代码遵循项目风格与命名规范。

## 代码与文档编辑规范
- 代码
  - 仅在必要文件做“最小范围编辑”；注释解释“为什么改”。
  - 新接口/事件需提供类型、示例载荷与兼容策略。
  - 新依赖需标注用途、体量与替代方案，默认不引入重量依赖。
- 文档
  - 路径引用保持现有规则：`/wwjcloud/...`；侧边栏改动需同步 `zh.mts`。
  - 新文档放置目录：`admin/docs/src/wwjcloud/project/`。

## 决策检查清单（回答前自检）
- 该改动是否违反“禁跨域直查库”？
- 是否影响公开 API/事件契约？若是，是否给出兼容与迁移指引？
- 是否可回滚（仅新增文件/配置、或可逆编辑）？
- 是否与 Roadmap/Plan 一致（M0–M3 阶段）？
- 是否提供了验证步骤（命令/接口/可观测指标）？

## 通用提示词模板
- 功能开发
  - “请在不破坏现有 API 的前提下，为 {domain} 域新增 {feature}，产出：
    1) 变更文件列表与最小改动；2) 新增接口/事件定义（含类型与示例）；
    3) 单元/集成验证步骤；4) 回滚方法。上下文：{files...} 约束：禁跨域直查库、保留 /docs-json。”
- 事件接入
  - “为 {domain} 接入事件 `{eventType}`：发布点、订阅方、载荷 schema（含 tenantId/idempotencyKey/traceId）、Outbox 入队、Kafka 主题、重试/幂等策略、验证步骤。”
- 性能优化
  - “分析 {table/query} 的慢查询，提出仅加索引与读模型的优化方案；避免改表/改名；给出索引 DDL 与回滚方案，并提供前后对比验证步骤。”
- 网关与熔断
  - “在 {Traefik|Kong} 中为 {route} 启用 JWT、限流、超时/重试、熔断；给出最小配置片段、灰度方案与回滚；不改变后端服务代码。”
- 文档生成
  - “基于 `/docs-json` 拉取，更新 `openapi/api/{frontend|adminapi}`；仅路径与侧边栏更新，不改内容。”

## 示例回答应包含
- 变更点清单（文件/行号范围、改动理由）。
- 验证步骤（命令、接口调用、预期输出）。
- 回滚步骤（如何还原文件/配置、撤销索引/发布）。
- 影响评估（性能、安全、兼容性）。

---
以上规范用于约束 AI 在 WWJCloud 项目内的协作行为，确保结果“可用、可控、可演进”。 