13 KiB
13 KiB
description
| description |
|---|
| 新版快速分析 Skill。甲方/第三方 AI 写的新版本，逻辑不完善、接口不规范、存在逻辑冲突时使用。快速分析、体验评估、逻辑补齐、抽取需求在稳定版迭代。Use when 新版分析、版本对比、迁移分析、甲方代码分析、快速分析新版、new-soul 分析. |
SKILL - 新版快速分析（甲方代码迁移）
针对「甲方/第三方用 AI 写的新版本，逻辑不完善、接口不规范、存在逻辑冲突」的场景，快速分析、抽取需求、在稳定版迭代。
1. 何时使用本 Skill
| 触发词 | 场景 |
|---|---|
| 新版分析、版本对比、迁移分析 | 需要系统对比 new-soul 与稳定版 |
| 甲方代码分析、快速分析新版 | 对方改了代码，逻辑不完善、接口不规范 |
| @new-soul 分析、抽取需求 | 从新版抽取需求，在稳定版更新迭代 |
典型困境：
- 对方有改接口，但不符合规范（路由、响应格式、鉴权）
- 存在逻辑冲突（如余额消费不写 orders、分润规则不统一）
- 纯界面需求变更，底层逻辑未考虑
- 稳定版也有新增功能，甲方版本并未更新 → 功能对齐与取舍需明确
- 需要在短时间内补齐完整逻辑
2. 核心原则
| 原则 | 说明 |
|---|---|
| 稳定版为基准 | 稳定版是生产环境，逻辑已验证；新版只做增量补齐 |
| 接口不以新版为准 | 新版接口编写必然很多没考虑（路由、鉴权、事务、分润、幂等）。接口设计必须以稳定版规范为准，按 api-dev SKILL 重新设计，不照搬新版实现 |
| 界面当需求，逻辑自己写 | 对方界面/交互可参考，业务逻辑按规范重写 |
| 先分析再实现 | 先出清单、方案、冲突表，再写代码 |
| 规范优先 | 接口不符合规范的一律按 api-dev/miniprogram-dev 修正 |
| 最小功能迁移 | 按最小功能单元迁移，每个功能迁移后都能完整运行；界面修改可先迁，大逻辑排后 |
接口处理方式：新版接口仅作「能力参考」（知道要什么），实现时在稳定版 soul-api 中按规范从零设计，不直接复用新版代码。
2.5 保护区域（迁移时禁止动或慎动）
以下模块是稳定版核心逻辑，新需求迁移时务必谨慎，不得影响：
| 保护区域 | 说明 | 处理方式 |
|---|---|---|
| 文章详情 @/# 标签 | @某人、#链接标签、contentParser、onMentionTap、onLinkTagTap、存客宝对接 | 禁止动。迁移时不得修改 read 页的 @/# 解析与点击逻辑 |
| 分销 | 推荐码绑定、分润计算、referral 相关接口与订单关联 | 禁止动。新增功能（如余额消费）若涉及购买，必须与分销逻辑兼容，不得覆盖或冲突 |
| 支付 | 微信支付、pay 接口、PayNotify 回调、订单创建与状态 | 禁止动。余额支付等新增支付方式需在现有支付流程上扩展，不得替换或破坏原有逻辑 |
迁移前检查：若新版改动涉及 read 页正文、contentParser、ckb/lead、referral、pay、orders，必须逐行对比，确认不覆盖保护区域。有冲突时以稳定版为准。
2.6 迁移前必做：需求评审
迁移前必须先做需求评审，评审通过后再开始迁移。
| 步骤 | 动作 | 产出 |
|---|---|---|
| 1 | 需求评审 | 召集评审，明确迁移范围与优先级 |
| 2 | 列出功能点 | 逐项列出：新增功能、修改功能、移除功能 |
| 3 | 列出样式变更 | 逐项列出：布局、配色、文案、交互变化 |
| 4 | 逐一确认 | 每个功能点、每项样式变更经确认后再迁 |
| 5 | 开始迁移 | 评审通过后，按确认清单逐项迁移 |
产出文档：开发文档/新版迁移-需求评审清单.md（功能点 + 样式变更表，含确认状态）
2.7 迁移顺序（最小功能 + 可运行优先）
| 顺序 | 类型 | 说明 |
|---|---|---|
| 先迁 | 界面修改 | 纯 WXML/WXSS/布局、文案、样式，不涉及新接口或新逻辑 → 可直接迁移 |
| 后迁 | 大逻辑 | 涉及新接口、DB、事务、支付、分润等 → 排后，逐个迁移 |
原则：
- 按最小功能拆：一个功能 = 一个可独立运行、可验证的单元
- 每次迁移后必须能完整运行：迁完即测，不积压半成品
- 界面优先：先迁界面类，快速见效；大逻辑逐个排期，降低风险
3. 功能对齐与取舍（必做）
背景：稳定版有新增功能，甲方版本未同步；甲方版本也有新功能。需先做双向对齐，再决定取舍。
3.0 功能三向分类
| 分类 | 说明 | 取舍原则 |
|---|---|---|
| 仅稳定版有 | 你已开发，甲方未更新 | 保留，不因迁移而删除 |
| 仅新版有 | 甲方新增，稳定版无 | 按需求评估：有价值则迁（界面当需求，逻辑重写）；无价值则弃 |
| 两者共有 | 同一功能，实现不同 | 以稳定版为准；若新版交互更好，可只迁界面/交互，逻辑仍用稳定版 |
3.0.1 取舍决策表（产出）
| 功能 | 分类 | 取舍 | 理由 |
|---|---|---|---|
| 链接人与事 | 仅稳定版有 | 保留 | 已上线，甲方无 |
| 钱包/余额 | 仅新版有 | 迁移 | 有业务价值，按规范重写 |
| 首页精选展开 | 两者共有 | 迁界面、逻辑用稳定版 | 新版交互可参考，数据源用 book/recommended 或 hot |
产出：在功能差异清单中增加「分类」「取舍」「理由」三列。
4. 分析流程（五步）
4.1 第一步：快速摸底（1～2 小时）
动作：双向对比 new-soul 与稳定版，建立差异清单（含功能三向分类）
| 对比维度 | 产出 |
|---|---|
| 页面 | 新增/移除/改版页面列表 |
| 接口 | 新增/修改/删除的 API 列表 |
| 字段 | 请求/响应/DB 字段差异 |
| 功能分类 | 仅稳定版有 / 仅新版有 / 两者共有 |
| 标注 | 每个变更：✅ 可用 / ⚠️ 不完整 / ❌ 逻辑错误 |
产出文档：开发文档/新版迁移-功能差异清单.md（可复用已有迁移文档补充）
4.2 第二步：逻辑分层检查
对每个功能按三层过一遍，避免漏改：
┌─────────────────────────────────────┐
│ 界面层：WXML/WXSS/JS、事件、数据绑定 │ ← 对方常只改这里
├─────────────────────────────────────┤
│ 接口层：调哪个 API、入参、返回、错误 │ ← 易漏：参数、鉴权、响应格式
├─────────────────────────────────────┤
│ 数据层：DB 表、字段、事务、幂等 │ ← 易漏：orders、分润、状态机
└─────────────────────────────────────┘
检查项：
- 界面改了，接口是否已提供且规范？
- 接口改了，DB/事务是否已同步？
- 是否有逻辑冲突（如 consume 不写 orders）？
4.3 第三步：体验评估
| 维度 | 检查点 |
|---|---|
| 交互 | 加载态、空态、错误态是否完整 |
| 反馈 | 操作成功/失败是否有提示 |
| 边界 | 未登录、余额不足、网络失败等处理 |
| 一致性 | 与稳定版其他页面的风格、文案是否统一 |
产出：在差异清单中增加「体验评估」列
4.4 第四步：接口规范与冲突清单
默认立场：新版接口不照搬。从新版只提取「需要什么能力」，在稳定版按 api-dev 规范重新设计。
接口规范检查（以 api-dev SKILL 为准）：
| 维度 | 稳定版约定 | 检查 |
|---|---|---|
| 路由分组 | miniprogram / admin / db | 小程序是否只调 miniprogram |
| 响应格式 | { success, data, message } |
是否统一 |
| 鉴权 | Bearer token、openId | 是否按约定 |
| 命名 | REST、资源名 | 是否统一 |
逻辑冲突识别：
| 冲突类型 | 示例 | 处理原则 |
|---|---|---|
| 数据不一致 | 余额扣了不写 orders | 同一事务内补齐 |
| 规则不统一 | 微信支付有分润、余额消费没有 | 统一规则 |
| 字段语义冲突 | 同一字段不同含义 | 定死语义，全项目统一 |
| 幂等缺失 | 回调重复执行 | 加幂等（订单号去重） |
产出文档：开发文档/新版迁移-接口规范与冲突清单.md
4.5 第五步：抽取需求，排期迭代
动作：
- 从差异清单中抽取「可迁移需求」
- 排除：技术债、规则不清、与稳定版冲突的部分
- 按最小功能拆分，保证每个任务迁移后能完整运行
- 排期顺序：界面修改优先 → 大逻辑排后；P0（逻辑不通）→ P1（功能缺失）→ P2（优化）
- 写入需求汇总，形成迁移任务清单
产出：
开发文档/1、需求/需求汇总.md追加需求开发文档/新版迁移-开发方案与清单.md或等价迁移清单
5. 产出物模板
5.1 功能差异清单（表格）
| 功能 | 分类 | 取舍 | 页面 | 接口 | 数据 | 甲方实现 | 体验 | 迁移动作 |
|---|---|---|---|---|---|---|---|---|
| 链接人与事 | 仅稳定版有 | 保留 | - | - | - | - | - | 不删 |
| 钱包 | 仅新版有 | 迁移 | wallet | balance/* | user_balance | ⚠️ 不完整 | 待补空态 | 迁界面+补 consume 写 orders |
5.2 接口规范与冲突清单（表格）
| 接口 | 甲方实现 | 规范要求 | 冲突说明 | 处理 |
|---|---|---|---|---|
| POST balance/consume | 只扣余额 | 扣余额+写 orders | check-purchased 判未购买 | 重写 consume |
5.3 需求评审清单（迁移前必产出）
| 类型 | 项 | 说明 | 确认 |
|---|---|---|---|
| 功能点 | 钱包页 | 新增余额、充值、交易记录 | ☐ |
| 功能点 | 我的页余额入口 | 第 4 项统计，点击进 wallet | ☐ |
| 样式变更 | 首页精选展开 | 默认 3 条，可展开更多 | ☐ |
| 样式变更 | Banner 按钮文案 | 「开始阅读」→「点击阅读」 | ☐ |
确认：每个项经评审确认后再迁；未确认不迁。
5.4 功能闭环 Checklist（每功能必过）
□ 界面：页面、交互、数据绑定
□ 接口：API 存在、参数正确、响应格式规范
□ 数据：DB/事务/幂等
□ 边界：未登录、余额不足、网络失败
□ 三端：小程序+后端+管理端（如需）是否都改到
□ 保护区域：未动 @/#、分销、支付 核心逻辑；若涉及则在原逻辑上扩展
6. 与其它 Skill 的衔接
| 阶段 | 衔接 Skill |
|---|---|
| 分析完成，开始实现 | change-checklist：变更完成必过三端关联检查 |
| 实现完成，经验沉淀 | assistant-doc-sync：吸收经验、同步需求文档 |
| 新增需求需三端规划 | product-manager：加个需求 → 三端分析 → 指派 |
| 跨端功能开发 | role-flow-control：后端先行 → 小程序 → 管理端 |
| 需求评审 | team-meeting：开会、需求评审 → 各角色发言 → 形成决议 |
7. 执行顺序（单次分析）
- Read 本 Skill 完整内容
- 功能对齐与取舍：先做三向分类（仅稳定版有/仅新版有/两者共有），产出取舍决策表
- 快速摸底：双向对比 new-soul 与稳定版，产出/更新功能差异清单（含分类、取舍列）
- 逻辑分层：每个功能过三层（界面/接口/数据）
- 体验评估：补充空态、错误态、边界处理
- 接口规范与冲突：产出接口规范与冲突清单
- 抽取需求：写入需求汇总，形成迁移任务清单
- 需求评审（迁移前必做）：列出功能点 + 样式变更，逐一确认，产出评审清单
- 回复用户：给出分析摘要 + 文档路径 + 建议执行顺序；迁移须在需求评审通过后开始
8. 文档写入位置
| 文档 | 路径 |
|---|---|
| 功能差异清单 | 开发文档/新版迁移-功能差异清单.md |
| 接口规范与冲突 | 开发文档/新版迁移-接口规范与冲突清单.md |
| 迁移方案/清单 | 开发文档/新版迁移-开发方案与清单.md 或 新版功能迁移到稳定版方案.md |
| 需求评审清单 | 开发文档/新版迁移-需求评审清单.md（功能点 + 样式变更，含确认状态） |
| 需求汇总 | 开发文档/1、需求/需求汇总.md |
若已有同名文档，在其基础上追加或更新，不重复创建。
9. 一句话总结
迁移前必做需求评审：列出功能点 + 样式变更，逐一确认后再迁。先做功能对齐与取舍，评审通过后按最小功能迁移；界面修改先迁、大逻辑排后；@/#、分销、支付为保护区域；用五步分析产出差异清单、接口冲突表、评审清单，再按 checklist 逐功能闭环。