1
2
3

规范即代码 → 规范直接生成实现，而非仅作为指导文档
权力倒置 → 代码服务于规范，而非规范服务于代码
测试优先 → 强制 TDD，不可协商地要求先写测试

1
2

Constitution → Specify → Plan → Tasks → Implement
   (宪章)      (规范)    (计划)  (任务)   (实施)

1
2
3

Specs as Source of Truth → specs/ 目录始终反映系统当前真实状态
Changes as Proposals → 所有修改先以提案形式存在，经确认后实施
Lock Intent → AI 编码前通过明确规范锁定意图

1
2
3
4
5
6

同时处理：
├── 找产品确认商品细节
├── 找运营确认玩法逻辑
├── 找跨团队研发对齐接口
├── 找跨项目研发对齐交互
└── 内部技术方案评审

1
2
3
4
5
6

前置任务链：
├── 玩法引擎：依赖数据、激励动作要在引擎仓库里实现
├── 外部依赖：关联的代码改动在其他服务里
├── 配置中心：要去阿波罗（Apollo）配配置
├── 雅典娜：商品场景得先配好（早期没数据还得 Mock）
└── 数据库：涉及表变更，得去测试环境操作

1
2
3
4
5
6
7
8
9

speckit 假设的流程：
Constitution → Specify → Plan → Tasks → Implement
     ↓            ↓        ↓       ↓         ↓
  一次性定义   一次性写清   线性规划   任务分解   按序实施

企业现实：
多方博弈 → 动态调整 → 并行推进 → 持续扯皮 → 边做边改
    ↓          ↓          ↓          ↓          ↓
 需求会变   方案会改   依赖会卡   资源会抢   意外会来

1
2
3
4
5
6
7
8
9

speckit 流程：
Constitution 定义原则 → Specify 定义需求 → Plan 设计方案 → ...

但真实需求必须"考古"：
├── 这个商品创建以前有什么坑？
├── 现有玩法能力有哪些？
├── 导航小结页的 Banner 怎么弹？
├── Apollo 配置有什么特殊处理？
└── 雅典娜 20 种商品类型的配置方式各不同

1
2
3
4
5
6
7
8
9

speckit/openspec 的思路：
规范化流程 → 约束 AI 行为 → 期望产出质量
    ↓
问题：流程本身不适配企业现实，约束越多越僵化

AI 工程化的思路：
上下文完整性 → AI 决策质量 → 自动沉淀经验 → 下次更好
    ↓
解法：不是约束 AI，而是给 AI 完整信息 + 让知识复利

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

speckit 模式（第 3 次做）：
1. Constitution → 写项目原则（已有，跳过）
2. Specify → 写需求规范（45 分钟，人逐步想起遗漏告诉 AI）
3. Plan → 写技术方案（人提醒：Apollo 有坑、钱包要区分）
4. Tasks → 生成任务（人补充：雅典娜配置注意事项）
5. Implement → 执行（遇到问题再排查）
耗时：45 分钟 + 排查时间，知识留在人脑

AI 工程化模式（第 3 次做）：
1. /req-dev "商品发放需求"
2. Agent 识别意图 → 自动加载 context/experience/商品发放历史问题.md
3. Agent 提醒："历史上有钱包选择、Apollo 配置、雅典娜商品类型三个坑点"
4. 人确认："对，继续"
5. Skill 执行 → 自动校验 → 生成代码 → 沉淀新发现
耗时：10 分钟，知识沉淀到 context/

1
2
3
4
5

执行 → 有问题 → 验证 → 排查 → 继续执行
                    ↓
            排查信息往往没被记录
                    ↓
        时间一久或换人，下次重新排查

1
2
3
4
5
6
7

Speckit 模式：
第 1 次商品发放需求：45 分钟（人逐步想起遗漏）
第 2 次商品发放需求：45 分钟（人 AGAIN 逐步想起遗漏）
第 n 次商品发放需求：45 分钟（还是要想，还是那么久）

边际成本恒定，无复利效应。
知识在哪里？在人脑里，每次都要重新想起来。

1
2

传统开发：累积技术债务 → 每个功能增加复杂性 → 代码库越来越难维护
复合工程：每个功能产出文档模式 → 创建可复用组件 → 建立减少决策疲劳的约定 → 知识在团队中复合增长

1
2
3
4
5

Plan ──────→ Work ──────→ Review ──────→ Compound
详细规划     执行工作     质量检查       知识沉淀
   ↑                                       │
   └───────────────────────────────────────┘
            知识复合：下次规划更精准

1
2
3
4
5
6

第一次解决 "N+1 query in brief generation" → Research (30 min)
文档化 → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
下次类似问题 → Quick lookup (2 min)
知识复合 → Team gets smarter

Each unit of engineering work should make subsequent units of work easier—not harder.

1
2
3

触发：发现 Agent 在某类问题上反复出错
沉淀：将教训写入 AGENTS.md / CLAUDE.md / 系统提示词
效果：该类错误不再发生，无需人工提醒

1
2
3

触发：Code Review 时反复指出同类问题
沉淀：创建 Lint 规则 / Pre-commit Hook / CI 检查
效果：问题在提交前自动拦截，减少人工负担

1
2
3

触发：某个多步骤操作被团队重复执行
沉淀：封装为 Skill / Command / Agent
效果：一键触发标准化流程，新人也能执行专家级操作

1
2
3

触发：花了较长时间解决某个棘手问题
沉淀：结构化记录到 context/experience/ 目录
效果：下次遇到类似问题，Agent 自动加载相关经验

1
2
3
4
5
6
7
8

方式 1：写文档
问题：没人看。写完就过时。维护成本高。

方式 2：靠人传授
问题：老人离职知识断层。新人上手慢。传授效率低。

方式 3：代码注释
问题：注释会过时。只能解释"是什么"，难以解释"为什么这么做"和"以前踩过什么坑"。

1
2
3
4
5
6
7
8
9

不是：写一份"商品发放注意事项"文档，期望大家会看
而是：在 context/experience/商品发放历史问题.md 里记录，
      Agent 在执行商品发放需求时自动加载，主动提醒

不是：靠老人口头传授"Apollo 配置有个坑"
而是：把坑编码到 skill 里，执行时自动校验

不是：在代码里写注释"这里要注意 XX"
而是：让 AI 在生成代码前就已经知道要注意 XX

1
2
3
4
5
6
7

用户输入 → Command（入口）→ Agent（决策层）→ Skill（执行层）
                              ↓
                         意图识别、流程路由
                              ↓
                         调用具体 Skill 执行
                              ↓
                         experience-index（经验检索）

1
2
3
4
5
6
7
8
9
10

路径 1：经验沉淀（/optimize-flow）
用户发现规律 → experience-depositor Agent → 识别规则类型 → 写入规则文件
                                                              ↓
                                              context-rules.md（上下文映射）
                                              risk-rules.md（风险识别）
                                              service-rules.md（服务补全）
                                              pattern-rules.md（代码模式）

路径 2：经验检索（experience-index Skill）
需求分析/方案设计/代码编写前 → 自动检索匹配规则 → 加载相关 Context、提示风险、建议服务

1
2
3
4
5
6
7

第 1 次做支付需求：45 分钟（边做边踩坑）
    ↓ 沉淀规则：/optimize-flow "支付需求要加载 payment-service.md 并提示资金安全"

第 2 次做支付需求：15 分钟（experience-index 自动加载背景、提示风险）
    ↓ 沉淀更多规则：错误处理模式、服务依赖关系

第 N 次做支付需求：5 分钟（系统已积累完整的支付领域知识）

1
2

传统文档：写完没人看，看了也找不到对的时机
AI 工程化：experience-index 在正确的时刻自动检索，主动推送给 Agent

1
2
3
4

上下文腐蚀的恶性循环：
加载更多信息 → 窗口膨胀 → 信息检索精度下降 → 行为异常
                ↓
        人发现问题 → 加更多上下文纠正 → 窗口更膨胀 → 更差

1
2
3
4
5
6
7
8
9

Transformer 架构的约束：
├── 每个 token 都要关注所有其他 token，产生 n² 个成对关系
├── 训练数据中短序列比长序列更常见，模型对长上下文依赖的经验较少
└── 位置编码插值虽允许处理更长序列，但会降低 token 位置理解的精度

结果：
├── 每引入一个新 token 都会消耗注意力预算
├── 低质量的 token 会"稀释"高质量信息
└── 关键信息可能被噪声淹没

1
2
3
4
5

工具设计不当的后果：
├── 工具描述冗长 → 消耗上下文预算
├── 工具边界模糊 → AI 决策困难，产生更多试错对话
├── 工具返回冗余信息 → 上下文快速膨胀
└── 最终：窗口爆满，任务失败

1
2
3
4
5
6
7
8

context/
├── business/
│   └── 活动业务边界.md        ← 概要层（意图识别时加载）
├── tech/
│   └── Apollo配置规范.md      ← 技术层（方案设计时加载）
└── experience/
    ├── 商品发放历史问题.md    ← 经验层（实施前加载）
    └── 雅典娜配置注意事项.md  ← 详细层（配置时加载）

1
2
3
4
5
6
7

传统方式（预加载）：
启动 → 加载所有相关文档（20000 tokens）→ 开始工作 → 窗口已满一半

即时策略：
启动 → 加载索引文件（500 tokens）→ 识别当前阶段 → 按需加载（3000 tokens）
                                                    ↓
                                          窗口保持精简，信息高度相关

1
2
3
4
5
6
7
8
9
10

压缩（Compaction）：
├── 将接近上下文窗口限制的对话内容总结
├── 保留：架构决策、未解决的 bug、实现细节
├── 丢弃：冗余的工具输出或消息
└── 用摘要重新初始化新的上下文窗口

结构化笔记（Structured Note-taking）：
├── 智能体定期将笔记写入上下文窗口外的持久化存储
├── 稍后根据需要拉回上下文窗口
└── 实现跨压缩步骤的连贯性

1
2
3
4
5
6
7
8
9
10
11

好的工具设计：
├── 自包含：不依赖"记住"之前的对话
├── 返回精简：只返回 token 高效的必要信息
├── 边界清晰：用途明确，减少决策成本
└── 发挥模型优势：利用模型擅长的能力

坏的工具设计：
├── 返回完整数据库查询结果（可能数千行）
├── 工具描述长达数百 token
├── 多个工具功能重叠，边界模糊
└── 强迫模型做它不擅长的事情

1
2
3

AI 的决策质量 ∝ 可用信息的完整性 × 信息的信噪比
                        ↑                    ↑
                   不是越多越好          高信号、低噪声才有效

1
2
3
4
5

用户输入 → Command → Agent（决策层）→ Skill（执行层）
                         ↓
                    意图识别、流程路由
                         ↓
                    调用具体 Skill 执行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

your-project/
├── AGENTS.md              # 项目记忆入口（每次会话自动加载）
├── .codebuddy/            # AI 自动化配置
│   ├── agents/            # Agent 定义（决策层）
│   ├── commands/          # 命令入口
│   └── skills/            # Skill 定义（执行层）
├── context/               # 项目知识库（长期记忆）
│   ├── business/          # 业务领域知识
│   ├── tech/              # 技术背景
│   │   └── services/      # 服务分析文档
│   └── experience/        # 历史经验
├── requirements/          # 需求管理
│   ├── INDEX.md           # 需求索引
│   ├── in-progress/       # 进行中需求
│   └── completed/         # 已完成需求
└── workspace/             # 代码工作区（Git 忽略）

1
2
3
4
5
6
7
8

不是：做完需求后专门花时间"写总结"
而是：在流程关键节点自动触发沉淀

具体触发点：
├── 需求完成时 → requirement-completer skill 自动提取可复用经验
├── 遇到问题解决后 → 用户说"记住这个坑" → experience-depositor agent 记录
├── 代码提交时 → code-commit skill 检查是否有值得记录的模式
└── 流程优化时 → /optimize-flow 命令专门用于沉淀和优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# context/experience/商品发放-钱包选择问题.md

## 问题描述
商品发放时选错钱包类型，导致用户领取失败

## 触发条件
- 需求涉及商品发放
- 商品类型为虚拟商品

## 解决方案
虚拟商品必须发到虚拟钱包，实物商品发到实物钱包
具体判断逻辑见 Apollo 配置：xxx.wallet.type

## 校验方式
检查 goods_type 与 wallet_type 的匹配关系

## 关联文档
- context/tech/Apollo配置规范.md
- context/tech/services/商品服务技术总结.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Agent 的上下文加载逻辑：

1. 意图识别阶段
   phase-router 识别意图，路由到对应 Agent
        ↓
2. 经验检索阶段
   Agent 调用 experience-index Skill，传入场景描述
   Skill 检索四类规则文件：
   ├── context-rules.md  → 匹配需加载的背景文档
   ├── risk-rules.md     → 匹配风险提示
   ├── service-rules.md  → 匹配服务依赖建议
   └── pattern-rules.md  → 匹配代码规范
        ↓
3. 返回结构化结果
   {
     "context": { "files": ["商品发放历史问题.md"] },
     "risk": { "alerts": [{"level": "high", "message": "注意钱包类型"}] },
     "service": { "suggestions": ["商品服务", "钱包服务"] },
     "pattern": { "files": ["error-handling.md"] }
   }
        ↓
4. Agent 主动提醒
   "注意：历史上商品发放有钱包选择问题，请确认..."

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

阶段 1：纯文档（被动）
context/experience/xxx.md
→ AI 读取后提醒，但需要人确认

阶段 2：校验 Skill（半自动）
skill/product-distribution-validator
→ 自动校验配置，发现问题直接报错

阶段 3：完整 Command（全自动）
cmd/implement-product-distribution
→ 一个命令：加载背景 + 校验 + 生成 + 提醒 + 沉淀新经验

演进判断标准：
- 同类需求做了 5 次以上 → 考虑封装 Skill
- Skill 被调用 10 次以上 → 考虑封装 Command
- 不要过早抽象，让实践驱动演进

1
2
3
4
5
6
7
8
9

speckit 的知识流向：
人脑 → Spec 文档 → 代码
      ↑__________|
      下次还要从人脑开始

AI 工程化的知识流向：
人脑 → context/ → Skill → Command
         ↑_________|________|
         知识留在工具链里，下次直接复用

1
2
3

每次执行：Constitution → Specify → Plan → Tasks → Implement
                                                    ↓
                                              每次从头开始

1
2
3
4
5
6

F(CurrentSpec, DeltaSpec) → NewSpec

缺失的维度：
F(CurrentSpec, DeltaSpec, Context, Lessons) → NewSpec + Knowledge
                           ↑          ↑
                     实施上下文    经验教训

1
2
3
4
5

传统工具：帮你"做事"
复合工程：帮你"越做越快"

传统工具：每次都是新的开始
AI 工程化：每次都站在上次的肩膀上

1
2

Spec 越详细 → 越接近代码本身 → 维护两份"代码"
Spec 越简略 → 越难指导 AI → 失去规范的意义

1
2
3
4
5
6
7
8
9
10
11
12

AI 工程化的上下文组织：
├── 服务概要：这个服务做什么、边界在哪
├── 业务概要：核心业务流程、关键概念
├── 模块概要：模块职责、依赖关系
├── 接口概要：对外接口、调用方式
└── 代码指针：具体细节在 xxx/xxx.go 的 xxx 函数

不维护：
├── ❌ 详细的数据结构定义（代码里有）
├── ❌ 完整的接口参数说明（代码里有）
├── ❌ 具体的实现逻辑描述（代码里有）
└── ❌ 任何可以从代码直接获取的信息

1
2
3
4
5
6
7

.codebuddy/skills/
├── req-create/            # 需求创建
│   ├── SKILL.md          # 技能定义
│   └── templates/        # 模板资源
├── design-create/         # 方案创建
├── workspace-setup/       # 环境搭建
└── code-commit/           # 代码提交

1
2
3
4
5
6

.codebuddy/agents/
├── phase-router.md        # 阶段路由，意图识别
├── requirement-manager.md # 需求全生命周期管理
├── design-manager.md      # 方案全生命周期管理
├── implementation-executor.md # 开发实施执行
└── experience-depositor.md    # 经验沉淀（独立上下文）

1
2
3
4
5
6
7
8

执行复杂需求时：
├── 加载业务背景（5000 tokens）
├── 加载技术上下文（8000 tokens）
├── 加载历史经验（3000 tokens）
├── 当前对话记录（持续增长）
└── ...
        ↓
窗口频繁爆满 → 强制截断 → 丢失关键上下文 → AI 行为异常

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

传统模式（单一 Agent）：
用户输入 → 一个大 Agent 处理所有事情 → 上下文持续膨胀 → 窗口爆满 → 任务失败

Subagent 模式：
用户输入 → 主 Agent（决策层）
              ↓
    意图识别 + 任务拆分
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
Subagent1  Subagent2  Subagent3
(独立窗口)  (独立窗口)  (独立窗口)
    └─────────┼─────────┘
              ↓
    结果汇总 → 主 Agent 继续

1
2
3
4
5
6
7
8
9

核心文件：
├── requirements/INDEX.md      # 需求状态索引
├── requirements/in-progress/  # 进行中的需求详情
└── context/session/           # 会话级临时上下文

工作流程：
1. Subagent 启动时：读取状态文件，快速理解当前状态
2. Subagent 执行中：专注自己的任务
3. Subagent 结束时：更新状态文件，提交"干净的交接"

1
2
3
4
5
6
7

speckit：依赖"一个 Agent 记住所有事情"
         Constitution → Specify → Plan → Tasks → Implement
         上下文持续累积，到 Implement 阶段时窗口已经很满

Subagent：依赖"结构化的状态传递"
         每个阶段独立的 Subagent，独立的上下文窗口
         状态通过文件传递，而非上下文累积

1
2
3
4
5
6
7
8
9
10
11
12
13

基础集成：
├── TAPD MCP（需求管理）
│   ├── 自动获取需求详情
│   ├── 关联相关需求
│   └── 更新需求状态
├── 工蜂 MCP（代码管理）
│   ├── 自动创建分支
│   ├── 提交代码变更
│   └── 创建合并请求
└── iWiki MCP（知识管理）
    ├── 检索历史技术方案
    ├── 获取业务背景文档
    └── 关联团队知识库

1
2
3
4
5

# 安装 AgentProjectKit 插件
/plugin install agent-project-kit@tmap-codebuddy-plugin

# 验证安装
/plugin list

1
2

# 初始化 AI 工程项目
/agent-project-kit:init-project

1
2
3
4

# 加载相关服务，生成技术总结
/agent-project-kit:load-service 
/agent-project-kit:load-service 
/agent-project-kit:load-service

1
2
3
4
5
6
7
8
9
10
11
12
13

用户执行 /agent-project-kit:load-service 
                ↓
1. 克隆服务代码到 workspace/loadservice/ 目录
                ↓
2. 分析服务架构、业务逻辑、API 接口：
   - 业务定位、核心职责、技术栈
   - 依赖关系、对外接口、数据模型
   - 关键模块、配置要点、常见坑点
                ↓
3. 生成技术文档到 context/tech/services/ 目录
                ↓
结果：AI 获得该服务的完整上下文，后续任何涉及该服务的需求
      都会自动加载这份上下文

1
2
3
4
5

# 创建新需求
/req-dev 实现用户认证功能

# 或者指定已有需求继续工作
/req-dev REQ-001

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

需求：实现 12 月活动的商品发放

执行过程中发现问题：
- Apollo 配置有特殊格式要求
- 雅典娜 20 种商品类型，配置方式各不同
- 钱包选择要区分虚拟/实物
- 敏感 接口有合规要求

知识沉淀：
人："@agent，记住这些坑"
    ↓
自动生成/更新 context/:
├── context/tech/Apollo配置规范.md
├── context/experience/雅典娜配置注意事项.md
├── context/experience/商品发放历史问题.md
└── context/business/跨团队协作.md

耗时：45 分钟（首次建立）

1
2
3
4
5
6
7
8
9
10
11
12

需求：实现春节活动的商品发放（类似场景）

AI 自动加载 context/，自动提醒历史坑点
人 review："嗯，都考虑到了" ✓

新发现：春节活动需要限制地域
    ↓
"@agent，记住地域限制"
    ↓
context/ 自动更新

耗时：15 分钟（大量复用，少量新增）

1
2
3
4
5
6
7
8
9
10
11
12

当 context/ 足够完善，封装为能力层：

skill/product-distribution-helper:
- 自动加载所有商品发放相关 context/
- 自动校验 Apollo 配置格式
- 自动检查雅典娜商品类型
- 自动提醒钱包选择、地域限制
- 自动生成监控配置

使用：/implement-product-distribution → 一键完成

耗时：3 分钟（高度自动化）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

speckit/openspec：
1. 学习工具用法（1-2 小时）
2. 了解服务架构（需老人讲解，2-4 小时）
3. 熟悉流程规范（1 小时）
4. 开始工作：依赖记忆和老人传授，首次质量不稳定
总计：4-7 小时准备 + 不稳定的首次质量

AI 工程化：
1. 脚手架初始化（15 分钟）
2. 工具包安装（5 分钟）
3. 立即开始工作：
   - context/ 提供服务上下文
   - MCP 自动集成 TAPD/工蜂/Apollo
   - cmd/skill 引导完成任务
   - 首次就能高质量完成
总计：20 分钟准备 + 稳定的首次质量

1
2
3
4
5
6
7
8
9
10
11
12
13
14

5 人团队，各做 2 次商品发放：

speckit：5 人 × 2 次 × 45 分钟 = 450 分钟

AI 工程化：
第 1 人第 1 次：45 分钟 → context/ 建立
第 1 人第 2 次：15 分钟
第 2 人第 1 次：15 分钟（复用第 1 人 context/）
第 2 人第 2 次：10 分钟
...
第 5 人第 2 次：5 分钟

总计：126 分钟
节省：450 - 126 = 324 分钟（72%）

1
2
3
4
5

Opus 4.1 需要的东西，Sonnet 4.5 已经内化了
    ↓
系统提示可以删 2000 个 tokens
    ↓
工具每周都在变简单

1

人 → 发指令 → AI 执行 → 人检查 → 人发下一个指令

1

人 → 设定目标 → 主 Agent 拆解 → 多个 Subagent 协作 → 主 Agent 汇总 → 人验收

1

人 → 设定目标 → Agent 团队自主协作数小时/数天 → 人验收最终结果

1
2
3
4
5
6
7
8
9

通用 Agent 路线：
├── 优势：简单，不需要协调
├── 劣势：上下文负担重，需要"知道所有事情"
└── 适合：简单任务、短时间任务

专门化 Agent 路线：
├── 优势：每个 Agent 更专精，上下文更精简
├── 劣势：需要协调机制，状态传递成本
└── 适合：复杂任务、长时间任务、团队协作场景

1
2
3
4
5
6
7
8
9
10
11
12
13

人类团队：
├── 产品经理：理解需求、拆解任务
├── 技术 Leader：设计方案、分配工作
├── 开发工程师：实现功能
├── 测试工程师：验证质量
└── 每个人有自己的专业领域，通过"会议"和"文档"协调

Agent 团队：
├── phase-router：理解意图、路由任务
├── design-manager：设计方案
├── implementation-executor：实现功能
├── test-agent（计划中）：验证质量
└── 每个 Agent 有自己的专业 Prompt，通过"状态文件"协调

1
2
3
4
5

当模型可以自主工作几天甚至几周：
早上："我想完成 X"
晚上：看结果

中间的过程？它自己处理。

1
2
3
4
5

传统研发：                         AI 工程化后：
├── 40% 信息收集                   ├── 10% 信息确认
├── 30% 重复劳动                   ├── 10% 结果审核  
├── 20% 核心决策        →          ├── 50% 核心决策
└── 10% 知识沉淀                   └── 30% 知识沉淀

1
2
3
4
5
6
7
8

传统模式的一天：                              AI 工程化模式的一天：
09:00-10:30 阅读需求文档，追问产品            09:00-09:30 /req-dev，确认需求边界
10:30-12:00 翻阅历史代码，理解逻辑            09:30-10:30 review AI 方案，调整决策点
14:00-15:30 询问老人"以前怎么做"              10:30-12:00 review AI 代码，优化核心逻辑
15:30-18:00 写代码，边写边查文档              14:00-15:00 AI 辅助测试，修复问题
18:00-19:00 遇到配置问题，排查                15:00-15:30 /optimize-flow 沉淀经验
19:00-20:00 继续写代码                       15:30-17:00 处理下一个需求
产出：完成 60%，知识留在脑子里                产出：完成 100%，经验沉淀到 context/

1
2

就像现在你用搜索引擎，不会想"我在使用一个信息检索系统"。
你只是在找答案。工具隐形了。

1
2
3
4
5
6
7
8
9
10

过去：记住 20 个命令，选择正确的那个
├── /speckit.constitution
├── /speckit.specify  
├── /speckit.plan
├── /speckit.tasks
└── ...

现在：只说你要什么
├── "/req-dev 实现商品发放" → Agent 自动判断是创建还是继续
└── 不需要知道底层调用了哪些 Skill

1
2
3
4
5
6
7
8
9

过去：做需求时，人要想起历史上有什么坑
├── "上次商品发放好像有个钱包问题..."
├── "Apollo 配置格式是什么来着..."
└── 认知负担在人身上

现在：experience-index 自动检索，主动提醒
├── "检测到商品发放场景，已加载相关经验..."
├── "风险提示：注意钱包类型匹配"
└── 知识在系统里，人只需确认

1
2
3
4
5
6
7
8
9

过去：严格按 Constitution → Specify → Plan → Tasks → Implement 执行
├── 人要知道"现在该执行哪个阶段"
├── 人要判断"前置条件是否满足"
└── 流程感知在人身上

现在：Agent 自主决策流程路由
├── 人说"继续做 REQ-001"
├── phase-router 自动判断当前阶段和下一步
└── 人感受到的是"工作在推进"，而非"在执行流程"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

今天：
人："我要做一个商品发放需求"
AI：执行一步，等待确认
人：确认，继续
AI：执行下一步，等待确认
...

明天：
人："我要做一个商品发放需求"
AI：分析、设计、实现、测试、提交 PR
人：Review 最终结果

后天：
人：（在 TAPD 创建需求单）
AI：（自动感知、自动完成、自动提交 Review）
人：（只在关键决策点介入）

1
2
3

上下文工程 → 让 AI 自动获取完整信息
复合工程 → 让每次实践都降低下次成本
项目级方案 → 管理所有仓库和外部系统

1
2
3
4
5
6
7
8
9

能够落地的最高效流程 → 已存在于高效的人的行为过程中
              ↓
      把高效流程 AI 化 → 推广到全团队应用
              ↓
  细节流程在具体业务线中迭代 → 自定义探索
              ↓
  实践中发现问题 → 提取可复用信息 → AI 工程化融入工具
                                  ↓
                      下次通用场景使用时可复用

1
2
3
4
5
6
7
8
9
10
11
12

{
  "name": "get_current_weather",
  "description": "获取指定城市的天气",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "城市名称"},
      "unit": {"enum": ["celsius", "fahrenheit"]}
    },
    "required": ["city"]
  }
}

1

{"city": "北京", "unit": "celsius"}

1
2
3
4
5
6
7
8
9
10
11
12
13

// 开发者输入：
public List<ItemCardVO> buildItemCards(List<ContentEntity> entities) {
    List<ItemCardVO> result = new ArrayList<>();
    // AI自动补全以下代码
    for (ContentEntity entity : entities) {
        ItemCardVO itemCard = new ItemCardVO();
        itemCard.setItemId(entity.getItemId());
        itemCard.setItemTitle(entity.getTitle());
        itemCard.setItemImg(entity.getPicUrl());
        result.add(itemCard);
    }
    return result;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// 原始代码（冗长难读）
public String getDiscountText(Long finalPrice, Long nnPrice) {
    if (finalPrice == null || nnPrice == null) {
        return "";
    }
    if (finalPrice <= nnPrice) {
        return "";
    }
    Long discount = finalPrice - nnPrice;
    if (discount <= 0) {
        return "";
    }
    String discountYuan = String.valueOf(discount / 100.0);
    return discountYuan + "元";
}
// AI重构后（简洁优雅）
public String getDiscountText(Long finalPrice, Long nnPrice) {
    if (finalPrice == null || nnPrice == null || finalPrice <= nnPrice) {
        return "";
    }
    Money discount = Money.ofFen(finalPrice).subtract(Money.ofFen(nnPrice));
    if (discount.getCent() <= 0) {
        return "";
    }
    return String.format("%s元", discount.getYuan());
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

需求：实现NN页面红包模块
背景：
- 需要展示用户可用的红包列表
- 红包按门槛从小到大排序
实现要求：
1. 创建数据服务类 NnRedPacketDataService，查询用户红包
2. 创建模块VO NnRedPacketVO，包含红包列表、总金额等字段
3. 创建模块构建器 NnRedPacketModuleBuilder，组装数据
技术细节：
- 数据服务需要实现 DataService<List<FundQueryDTO>> 接口
- 数据服务实现类需要依赖FpProvider，并执行红包查询，参数请参考已有实现
- 模块构建器需要继承 BaseModuleBuilder<NnRedPacketVO>
- 使用 @Component 注解标记为Spring Bean
- 遵循项目代码规范
请生成完整的代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

// 1. 数据服务
@Component
public class NnRedPacketDataService implements DataService<List<FundQueryDTO>> {
    @Autowired
    private FpProvider fpProvider;
    @Override
    public List<FundQueryDTO> execute(InvocationContext context, JSONObject req) {
        // 从配置获取红包池ID
        String poolIds = req.getString("nnRedPacketPoolIds");
        List<Long> fundPoolIds = Arrays.stream(poolIds.split(","))
            .map(Long::parseLong)
            .collect(Collectors.toList());
        // 查询用户红包
        return fpProvider.queryUserFundBuyPoolId(
            context, 
            fundPoolIds, 
            customRuleId, 
            securityCode
        );
    }
}
// 2. 模块VO
@Data
@Builder
public class NnRedPacketVO {
    private List<RedPacketItem> redPacketList;
    private String totalAmount;
    private String expandText;
}
// 3. 模块构建器
@Component
public class NnRedPacketModuleBuilder extends BaseModuleBuilder<NnRedPacketVO> {
    @Override
    public String getName() {
        return "nnRedPacket";
    }
    @Override
    protected NnRedPacketVO doBuild(InvocationContext context) {
        // 获取红包数据
        List<FundQueryDTO> funds = ContextUtils
            .<List<FundQueryDTO>>getBizResult(
                NnRedPacketDataService.class.getSimpleName(), 
                context, 
                500
            )
            .orElse(Collections.emptyList());
        if (CollectionUtils.isEmpty(funds)) {
            return null;
        }
        // 构建VO
        return NnRedPacketVO.builder()
            .redPacketList(buildRedPacketList(funds))
            .totalAmount(calculateTotalAmount(funds))
            .build();
    }
    private List<RedPacketItem> buildRedPacketList(List<FundQueryDTO> funds) {
        return funds.stream()
            .map(this::toRedPacketItem)
            .collect(Collectors.toList());
    }
    // ... 其他方法
}

1
2
3
4
5
6
7
8
9
10
11

// 第一次生成（简洁风格）
private String buildDiscountText(Money discount) {
    return String.format("省%s元", discount.getYuan());
}
// 第二次生成（冗长风格）  
private String buildDiscountText(Money discount) {
    BigDecimal yuan = BigDecimal.valueOf(discount.getCent())
        .divide(BigDecimal.valueOf(100), 2, RoundingMode.HALF_UP);
    String yuanStr = yuan.stripTrailingZeros().toPlainString();
    return "省" + yuanStr + "元";
}

1
2
3
4
5
6
7
8

.aone_copilot/
├── rules/
│   ├── code-style.aonerule           # 代码风格规范
│   ├── project-structure.aonerule    # 项目结构规范
│   └── features.aonerule              # 功能实现规范
└── tech/
    ├── xx秒杀-技术方案.md      # 具体需求的技术方案
    └── xx红包模块-技术方案.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 代码风格规范

## Java代码规范
- 类名使用大驼峰命名法（PascalCase）
- 方法名和变量名使用小驼峰命名法（camelCase）
- 常量使用全大写，单词间用下划线分隔（CONSTANT_CASE）

## 空值判断
- 集合判空统一使用：CollectionUtils.isEmpty() 或 isNotEmpty()
- 字符串判空统一使用：StringUtils.isBlank() 或 isNotBlank()
- 对象判空统一使用：Objects.isNull() 或 Objects.nonNull()

## 日志规范
- 使用 LogUtil 工具类记录日志
- 错误日志格式：LogUtil.error("类名, 方法名, 错误描述, 关键参数={}", param, exception)

## 注解使用
- Service类使用 @Component 注解
- 数据服务实现 DataService<T> 接口
- 模块构建器继承 BaseModuleBuilder<T>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 项目结构规范
## 包结构
com.alibaba.aladdin.app/
├── module/              # 模块构建器
│   ├── nn/             # NN业务模块
│   ├── seckill/        # 秒杀业务模块
│   └── common/         # 通用模块
├── domain/             # 领域对象
│   ├── module/         # 模块VO（继承ModuleObject）
│   └── [业务名]/       # 业务领域对象（BO、DTO）
├── dataservice/impl/   # 数据服务实现
└── provider/           # 外部服务提供者
## 命名规范
- 数据服务：[业务名]DataService（如 NnRedPacketDataService）
- 模块构建器：[业务名]ModuleBuilder（如 NnFeedsModuleBuilder）
- 模块VO：[业务名]VO（如 NnRedPacketVO）
- 业务BO：[业务名]BO（如 NnRoundFeatureBO）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 功能实现规范
## 数据服务层
- 必须实现 DataService<T> 接口
- 使用 @Component 注解
- execute方法的第一个参数是 InvocationContext
- execute方法的第二个参数是 JSONObject businessReq
示例：
```java
@Component
public class NnRedPacketDataService implements DataService<List<FundQueryDTO>> {
    @Override
    public List<FundQueryDTO> execute(InvocationContext context, JSONObject businessReq) {
        // 实现逻辑
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

- 必须继承 BaseModuleBuilder
- 使用 @Component 注解
- 实现 getName()、doBuild()、bottomTransform() 三个方法
- 通过 ContextUtils.getBizResult() 获取数据服务结果
示例：

@Component
public class NnRedPacketModuleBuilder extends BaseModuleBuilder<NnRedPacketVO> {
    @Override
    public String getName() {
        return "nnRedPacket";
    }
    @Override
    protected NnRedPacketVO doBuild(InvocationContext context) {
        List<FundQueryDTO> funds = ContextUtils
            .<List<FundQueryDTO>>getBizResult(
                NnRedPacketDataService.class.getSimpleName(),
                context,
                500
            )
            .orElse(Collections.emptyList());
        // 构建逻辑
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

## 业务定义
NN红包模块用于展示用户在NN业务场景下可用的红包列表。
## 业务领域对象
无（复用 FundQueryDTO）
## 模块领域对象
| 对象含义 | 实现方案 | 属性及类型 |
|---------|---------|-----------|
| NN红包模块VO | 新增 | 1. redPacketList：List<RedPacketItem> - 红包列表<br>2. totalAmount：String - 总金额<br>3. expandText：String - 展开文案 |
## 数据服务层
| 数据服务定义 | 实现方案 | execute |
|------------|---------|---------|
| NN红包查询服务 | 新增 | 1. 从配置获取红包池ID列表<br>2. 调用FpProvider查询用户红包<br>3. 过滤可用红包（状态=2，未过期）<br>4. 返回红包列表 |
## 模块构建器
| 模块构建器定义 | 实现方案 | doBuild逻辑 |
|--------------|---------|-------------|
| NN红包模块构建器 | 新增 | 1. 获取红包数据<br>2. 过滤门槛>20元的红包<br>3. 按门槛从小到大排序<br>4. 构建VO |

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── specs/
│   └── 001-nn-redpacket-module/
│       ├── checklists/
│       │   └── requirements.md
│       ├── contracts/
│       │   └── api-contract.md
│       ├── data-model.md
│       ├── plan.md
│       ├── quickstart.md
│       ├── research.md
│       └── spec.md
└── req/
    └── nn-redpacket.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

## 核心原则

### I. 模块化服务架构
所有服务必须遵循模块化设计原则，具有明确的关注点分离和定义良好的接口。每个模块应具有单一职责并可独立部署。模块必须以松耦合和高内聚的方式设计，以增强可维护性和可扩展性，遵循最小依赖原则。
### II. 阿里巴巴开发标准
所有代码必须遵循阿里巴巴Java开发指南（基于阿里巴巴Java编码规范）。这包括命名约定、异常处理实践、日志标准、安全最佳实践和性能优化模式。代码必须遵守样式一致性要求，以保持代码库的统一性。
### III. 质量保证实践
全面测试是强制性的：对所有业务逻辑进行单元测试，对服务交互进行集成测试，对API兼容性进行合同测试。代码覆盖率必须保持在80％以上，特别关注关键业务路径。代码质量工具必须集成到CI/CD管道中以执行标准，遵循阿里巴巴开发规范以确保质量和可靠性。
### IV. 模块设计原则
遵循单一职责原则，每个模块都有一个明确的目的。模块必须以松耦合和高内聚的方式设计，遵循关注点分离原则。模块边界应与业务能力和领域上下文对齐。所有模块都遵循最小依赖原则，仅导入必要的依赖项以减少系统复杂性。
### V. 项目架构设计原则
本项目采用分层架构设计，通过模块化组织代码，支持淘特投放业务的各种场景需求。架构层次包括：
1. **接入层**：处理请求接入和协议转换
2. **解决方案层**：业务解决方案的统一入口
3. **子解决方案层**：细粒度的业务处理能力
4. **模块构建层**：按业务功能划分的模块构建器
5. **数据服务层**：负责各种业务数据的获取、处理和封装
6. **外部服务层**：负责调用外部服务并进行模型转换
7. **领域模型层**：定义核心业务对象和数据传输对象
8. **基础设施层**：包含基础组件和框架封装
9. **通用模块层**：公共组件和工具类
### VI. 依赖管理
遵循最小依赖原则：每个模块应只拥有其实际需要的依赖项。避免模块之间的循环依赖。使用依赖注入实现松耦合。定期审核和更新依赖项以最小化安全漏洞。这确保了可维护和高效的代码结构。
### VII. 代码风格一致性
在整个项目中保持一致的代码风格，使用标准化的格式化规则。所有代码在合并前必须通过静态分析检查。一致地遵循设计模式，并对与标准实践的任何偏差提供清晰的证明。这确保了统一的代码规范和样式，符合项目标准。
### VIII. Speckit中文本地化
所有speckit相关文件、文档和配置都应使用中文，以支持本地开发团队。`.specify/`和`specs/`目录中的文件和相关speckit构件必须使用中文，以便本地开发人员更好地理解和维护，同时应为可能服务国际市场面向用户的组件保留国际化支持。
## 安全和合规要求
所有代码必须符合阿里巴巴的安全标准，并在部署前进行强制性安全审查。必须为所有暴露的端点实现适当的身份验证和授权。敏感数据必须根据内部合规要求进行处理。必须扫描依赖项中的安全漏洞。
## 开发工作流程
1. 所有代码更改必须遵循标准的阿里巴巴开发工作流程：功能分支、代码审查、自动化测试和CI/CD管道验证。拉取请求必须通过所有测试并获得指定审阅者的批准后才能合并。除非明确批准进行具有迁移计划的破坏性更改，否则所有更改必须向后兼容。每次更改都必须遵循模块设计原则并保持代码风格一致性。
2. 所有操作不要创建新分支，而是在当前分支下进行
3. 代码生成必须遵循code-generation-prompt.aonerule文件
## 治理
本宪法凌驾于所有其他开发实践之上，必须在存储库中的所有工作中遵循。对本宪法的任何修改都需要正式文档、团队批准和迁移计划。所有PR和代码审查必须验证是否符合这些原则。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# NN红包模块规格说明
## 功能概述
NN红包模块用于在NN频道页面展示用户可用的红包列表，帮助用户了解可以使用的优惠。
## 功能需求
### FR-1: 红包数据获取
**描述：** 系统应该能够查询用户在当前NN业务场景下可用的红包
**前置条件：**
- 用户已登录
- 配置了红包池ID（fundPoolIds）
- 配置了规则id（customRuleId）
- 配置了securityCode
**输入：**
- userId：用户ID
- fundPoolIds：红包池ID列表
- customRuleId：自定义规则ID
- securityCode：安全码
**处理逻辑：**
1. 调用FpProvider.queryUserFundBuyPoolId()查询红包
2. 过滤条件：
   - 红包状态（payStatus）= 2（可使用）
   - 红包未过期（当前时间在startTime和endTime之间）
   - 红包门槛 <= 配置的amountThreshold（默认20元）
**输出：**
- 返回符合条件的红包列表
**异常处理：**
- 如果FpProvider调用失败，返回空列表
- 如果用户未登录，返回空列表
...
...
...
**处理逻辑：**
1. 如果红包列表为空，不展示模块（返回null）
2. 构建NnRedPacketVO：
   - redPacketList：转换每个红包为RedPacketItem
   - totalAmount：计算所有红包金额总和
   - expandText：从配置获取展开文案
**输出：** NnRedPacketVO
## 非功能需求
### NFR-1: 性能要求
- 红包查询超时时间：500ms
- 如果超时，返回空列表，不影响页面其他模块
### NFR-2: 可扩展性
- 支持配置不同的红包池ID
- 支持配置不同的门槛限制
## 测试用例
### TC-1: 正常流程 - 有可用红包
**前置条件：**
- 用户ID：123456
- 配置的红包池ID：[1001, 1002]
- FpProvider返回2个可用红包：
  - 红包1：金额5元，门槛15元
  - 红包2：金额10元，门槛25元
**执行步骤：**
1. 调用 doBuild(context)
**预期结果：**
- 返回的VO不为null
- redPacketList包含2个红包
- totalAmount = "15.00"（5 + 10）
- 红包按门槛排序（红包1在前）
### TC-2: 边界条件 - 红包门槛超限
**前置条件：**
- FpProvider返回1个红包，门槛25元
- 配置的amountThreshold = 20元（2000分）
**预期结果：**
- 返回null（因为门槛超限，红包被过滤）
...
...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

@Component
public class NnRedPacketDataService implements DataService<List<FundQueryDTO>> {
    @Autowired
    private FpProvider fpProvider;
    @Override
    public List<FundQueryDTO> execute(InvocationContext context, JSONObject businessReq) {
        long userId = context.getUserId();
        if (userId <= 0) {
            return Collections.emptyList();
        }
        // 获取配置
        String poolIdsStr = businessReq.getString("nnRedPacketPoolIds");
        List<Long> fundPoolIds = parsePoolIds(poolIdsStr);
        Long customRuleId = businessReq.getLong("customRuleId");
        String securityCode = businessReq.getString("securityCode");
        // 查询红包
        List<FundQueryDTO> funds = fpProvider.queryUserFundBuyPoolId(
            context, fundPoolIds, customRuleId, securityCode
        );
        if (CollectionUtils.isEmpty(funds)) {
            return Collections.emptyList();
        }
        // 过滤可用红包（按规格FR-1的过滤条件）
        Long amountThreshold = businessReq.getLong("amountThreshold", 2000L);
        return funds.stream()
            .filter(fund -> fund.getPayStatus() == 2)  // 可使用状态
            .filter(fund -> isNotExpired(fund))         // 未过期
            .filter(fund -> fund.getAmountThreshold() <= amountThreshold)  // 门槛限制
            .collect(Collectors.toList());
    }
    private boolean isNotExpired(FundQueryDTO fund) {
        long now = System.currentTimeMillis();
        return fund.getStartTime() <= now && now <= fund.getEndTime();
    }
    // ... 其他方法
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

@Component
public class NnRedPacketModuleBuilder extends BaseModuleBuilder<NnRedPacketVO> {
    @Override
    public String getName() {
        return "nnRedPacket";
    }
    @Override
    protected NnRedPacketVO doBuild(InvocationContext context) {
        // 获取红包数据（FR-1）
        List<FundQueryDTO> funds = ContextUtils
            .<List<FundQueryDTO>>getBizResult(
                NnRedPacketDataService.class.getSimpleName(),
                context,
                500
            )
            .orElse(Collections.emptyList());
        // 如果无可用红包，不展示模块（FR-3）
        if (CollectionUtils.isEmpty(funds)) {
            return null;
        }
        // 红包排序（FR-2）
        List<FundQueryDTO> sortedFunds = sortFunds(funds, context);
        // 构建VO（FR-3）
        return NnRedPacketVO.builder()
            .redPacketList(buildRedPacketList(sortedFunds))
            .totalAmount(calculateTotalAmount(sortedFunds))
            .expandText(getExpandText(context))
            .build();
    }
    /**
     * 红包排序：NN专属红包优先，其次按门槛从小到大
     * 对应规格 FR-2
     */
    private List<FundQueryDTO> sortFunds(List<FundQueryDTO> funds, InvocationContext context) {
        JSONObject extraParams = getExtraParams(context);
        String nnPoolIdsStr = extraParams.getString("nnRedPacketPoolIds");
        Set<Long> nnPoolIds = parsePoolIds(nnPoolIdsStr).stream()
            .collect(Collectors.toSet());
        return funds.stream()
            .sorted(Comparator
                .comparing((FundQueryDTO fund) -> 
                    nnPoolIds.contains(fund.getFromFundId()) ? 0 : 1)
                .thenComparing(FundQueryDTO::getAmountThreshold))
            .collect(Collectors.toList());
    }
    // ... 其他方法
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

@RunWith(MockitoJUnitRunner.class)
public class NnRedPacketModuleBuilderTest {
    @Mock
    private InvocationContext context;
    @Mock
    private NnRedPacketDataService dataService;
    @InjectMocks
    private NnRedPacketModuleBuilder builder;
    /**
     * 测试用例 TC-1: 正常流程 - 有可用红包
     */
    @Test
    public void testBuild_WithAvailableFunds_ShouldReturnVO() {
        // 准备数据
        List<FundQueryDTO> mockFunds = Arrays.asList(
            createFund(1L, 500L, 1500L),   // 5元，门槛15元
            createFund(2L, 1000L, 2500L)   // 10元，门槛25元
        );
        // Mock
        when(dataService.execute(any(), any())).thenReturn(mockFunds);
        mockContext(context, "nnRedPacketPoolIds", "1,2");
        mockBizResult(context, NnRedPacketDataService.class.getSimpleName(), mockFunds);
        // 执行
        NnRedPacketVO result = builder.doBuild(context);
        // 验证（按规格预期结果）
        assertNotNull(result);
        assertEquals(2, result.getRedPacketList().size());
        assertEquals("15.00", result.getTotalAmount());
        // 验证排序：门槛低的在前
        assertEquals(1500L, result.getRedPacketList().get(0).getAmountThreshold());
    }
    /**
     * 测试用例 TC-2: 边界条件 - 红包门槛超限
     */
    @Test
    public void testBuild_ThresholdExceeded_ShouldReturnNull() {
        // 准备数据：门槛25元，超过配置的20元
        List<FundQueryDTO> mockFunds = Arrays.asList(
            createFund(1L, 500L, 2500L)
        );
        // Mock（配置amountThreshold=2000，即20元）
        JSONObject businessReq = new JSONObject();
        businessReq.put("amountThreshold", 2000L);
        when(dataService.execute(any(), eq(businessReq))).thenReturn(Collections.emptyList());
        mockBizResult(context, NnRedPacketDataService.class.getSimpleName(), Collections.emptyList());
        // 执行
        NnRedPacketVO result = builder.doBuild(context);
        // 验证（按规格预期结果）
        assertNull(result);
    }
    /**
     * 测试用例 TC-3: 异常场景 - FpProvider返回null
     */
    @Test
    public void testBuild_ProviderReturnsNull_ShouldReturnNull() {
        // Mock
        when(dataService.execute(any(), any())).thenReturn(null);
        mockBizResult(context, NnRedPacketDataService.class.getSimpleName(), null);
        // 执行
        NnRedPacketVO result = builder.doBuild(context);
        // 验证（按规格预期结果）
        assertNull(result);
    }
    /**
     * 测试用例 TC-4: 异常场景 - 用户未登录
     */
    @Test
    public void testBuild_UserNotLogin_ShouldReturnNull() {
        // Mock：userId = 0
        when(context.getUserId()).thenReturn(0L);
        when(dataService.execute(any(), any())).thenReturn(Collections.emptyList());
        mockBizResult(context, NnRedPacketDataService.class.getSimpleName(), Collections.emptyList());
        // 执行
        NnRedPacketVO result = builder.doBuild(context);
        // 验证（按规格预期结果）
        assertNull(result);
    }
    // 辅助方法
    private FundQueryDTO createFund(Long id, Long amount, Long threshold) {
        FundQueryDTO fund = new FundQueryDTO();
        fund.setFundId(id);
        fund.setAvailableAmount(amount);
        fund.setAmountThreshold(threshold);
        fund.setPayStatus(2);  // 可使用
        fund.setStartTime(System.currentTimeMillis() - 3600000);  // 1小时前开始
        fund.setEndTime(System.currentTimeMillis() + 3600000);    // 1小时后结束
        return fund;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# [需求名称]-技术方案
## 业务定义
[简要描述业务背景和目标，1-2句话]
## 业务领域对象
[如果需要新增/修改BO或DTO，在此说明]
## 模块领域对象
[需要新增/修改的VO对象]
| 对象含义 | 实现方案 | 属性及类型 |
|---------|---------|-----------|
| [对象名] | 新增/修改 | 1. 字段1：类型 - 说明<br>2. 字段2：类型 - 说明 |
## 数据服务层
[需要新增/修改的数据服务]
| 数据服务定义 | 实现方案 | execute逻辑 |
|------------|---------|-----------|
| [服务名] | 新增/复用 | 1. 步骤1<br>2. 步骤2 |
## 模块构建器
[需要新增/修改的模块构建器]
| 模块构建器定义 | 实现方案 | doBuild逻辑 |
|--------------|---------|-------------|
| [构建器名] | 新增/修改 | 1. 获取数据<br>2. 处理逻辑<br>3. 构建VO |

1

完成需求开发 → 提交AI："将本次代码逻辑汇总到汇总文档" → AI分析代码 → AI更新文档

1
2
3
4
5
6
7
8
9

我刚完成了NN红包模块的开发，请分析以下代码：
- NnRedPacketDataService.java
- NnRedPacketModuleBuilder.java
- NnRedPacketVO.java
然后将其业务逻辑汇总到"NN业务整体架构与逻辑文档.md"中，确保：
1. 描述模块的核心功能和业务价值
2. 说明数据流转过程
3. 列出关键的业务规则和判断逻辑
4. 保持与现有文档的风格一致

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# NN业务整体架构与逻辑文档
## 一、业务概述
[业务背景、目标、核心价值]
## 二、整体架构
### 2.1 技术架构
[分层架构图、技术栈]
### 2.2 模块组成
[各个模块的功能和关系]
## 三、核心模块详解
### 3.1 NN Feeds模块
#### 3.1.1 功能说明
[模块的核心功能]
#### 3.1.2 数据流转
[数据从哪里来，经过哪些处理，最终输出什么]
#### 3.1.3 关键逻辑
[重要的业务规则、计算逻辑、判断条件]
#### 3.1.4 代码位置
[对应的类和方法]
### 3.2 NN红包模块
[类似结构]
### 3.3 NN吊钩层模块
[类似结构]
## 四、数据服务层
[各个数据服务的功能和依赖]
## 五、关键流程
[重要的业务流程时序图]
## 六、配置说明
[配置项说明]
## 七、扩展点
[未来可能的扩展方向]

1
2
3
4
5
6
7
8
9
10
11
12
13
14

### 3.2 NN红包模块
#### 3.2.1 功能说明
NN红包模块用于在NN频道页面展示用户可用的红包列表，帮助用户了解可以使用的优惠，提升转化率。
#### 3.2.2 数据流转
用户请求 → NnRedPacketDataService 
         → 调用FpProvider查询用户红包
         → 过滤可用红包（状态=2，未过期，门槛<=20元）
         → 返回红包列表
         ↓
NnRedPacketModuleBuilder
         → 获取红包数据
         → 红包排序（NN专属优先，门槛从小到大）
         → 构建NnRedPacketVO
         → 返回前端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43