@kunlv/atdc 1.0.0

package/prompts/X-test-plan.md

@@ -0,0 +1,436 @@
+# prompts/X-test-plan · 自测计划生成
+
+从此文件读取后直接开始执行，无需用户再次确认。
+
+---
+
+## Step 0：检测目标 change
+
+```bash
+ls openspec/changes/ | grep -v archive
+```
+
+- 无活跃 change → 提示"当前无活跃 change。请先使用 `/atdc:1-spec` 创建需求或直接说'生成自测计划 {分支名/功能名}'"，停止。
+- 有多个活跃 change → 让用户指定目标 change 名，或提示输入分支名/功能名。
+- 有且只有一个 → 自动选中。
+
+确认目标上下文：分支名/功能名/change 名。
+
+---
+
+## Step 1：读取变更上下文
+
+```bash
+CHANGE_NAME="<目标>"
+```
+
+读取以下文件（如存在）：
+- `openspec/changes/$CHANGE_NAME/tasks.md` — 理解有哪些任务和涉及文件
+- `openspec/changes/$CHANGE_NAME/proposal.md` — 理解功能背景
+- `openspec/changes/$CHANGE_NAME/design.md` — 理解技术方案和接口定义
+
+如果 change 目录不存在（直接指定分支/功能名），则：
+- 扫描 `git diff` 变更文件
+- 识别 controller、service、router 中的接口和方法
+
+---
+
+## Step 2：扫描涉及接口
+
+基于 tasks.md 的 `**Files**` 声明和 git diff，识别本次变更涉及的：
+
+1. **HTTP 路由**（`router/router.go`）：方法 + 路径 + 中间件
+2. **Service 方法签名**（`service/biz/`）：接口方法 + 参数
+3. **CLI 命令**（`cli/register.go`）：命令名 + 用途
+4. **RPC 调用**：外部依赖的 RPC 接口
+
+---
+
+## Step 3：Phase 1 — 生成自测计划文档
+
+**输出位置**：`.test_plans/{change名|分支名}-self-test-plan.md`
+
+> `.test_plans/` 通过 `~/atdc/central/link.sh` 自动软链到主仓库，所有分支+worktree 共享，不入 git。
+
+**文档必须包含**：
+
+1. **测试前准备**：DDL 脚本、Apollo 配置、预置 SQL、环境变量
+2. **按业务链路拆分的自测表格**：
+
+```markdown
+| # | 测试场景 | 触发方式 | 预期结果 | 验证方法 | 状态 |
+|---|---------|---------|---------|---------|:--:|
+```
+
+3. **触发方式必须是可执行命令**：curl / SQL / cli 命令，不写描述性文字
+4. **执行顺序建议**：按业务依赖排列（如先下单才能支付）
+5. **快速回归命令**：`go build` + `go test` + grep 日志关键词
+
+**输出后暂停，等用户确认。**
+
+> 确认方式：用户说"继续"/"下一步"/"生成测试文件"进入 Phase 2，说"改一下"则修改文档。
+
+---
+
+## Step 4：用户确认后，Phase 2 — 生成集成测试文件
+
+**输出位置**：`service/biz/{主模块名}/{主模块名}_integration_test.go`
+
+### 4a. 文件结构
+
+必须包含五部分，按顺序：
+
+```
+1. 包声明 + imports
+2. 环境变量 + 包级变量（var block）
+3. HTTP helpers：doGet / doPost / doPostInner（从模板复制）
+4. kugo 签名 helpers：kugoBuildSignature / kugoSign / signQuery / signQueryWithBody / mapToQuery / parseQuery
+5. 测试函数（每条链路一组），每个场景一个独立顶层函数
+```
+
+### 4b. 可直接复制的通用模板（无需改动）
+
+**以下代码块必须原样包含在生成的测试文件中。**
+
+> ⚠️ **签名校验（最高优先级，历次踩坑点）**
+>
+> 本项目外部路由挂载 `middleware.CheckClientSignature`，算法来自 kugo `httpclient/signature.go:buildSignature`。
+>
+> | 方法 | 签名串 |
+> |------|--------|
+> | GET  | `appkey + sorted(key=value...) + "" + appkey` |
+> | POST | `appkey + sorted(key=value...) + **原始 JSON body** + appkey` |
+>
+> - key 按字典序排列；`signature` 自身**不参与**签名；key/value 之间无 `&` 分隔符（直接拼接 `key=value`）。
+> - POST 时：**先 `json.Marshal` body，用同一字节串既签名又发送**；body 与 signature 不一致必报 `errcode=20006 invalid signature`。
+> - 响应 `data.RawSignatureStr` 可用于对照调试。
+> - 内部路由（`/inner/...`）用 `doPostInner`，**不签名**。
+
+#### 1. imports
+
+```go
+import (
+    "bytes"
+    "crypto/md5"
+    "encoding/hex"
+    "encoding/json"
+    "fmt"
+    "io"
+    "net/http"
+    "os"
+    "sort"
+    "strings"
+    "testing"
+    "time"
+)
+```
+
+#### 2. 变量与 init
+
+```go
+var (
+    host       string
+    client     *http.Client
+    testAppID  string
+    testAppKey string
+    testToken  string
+    // 跨场景共享状态（按需新增）
+)
+
+func init() {
+    host       = envOr("MEMBERSHIP_TEST_HOST", "http://127.0.0.1:80")
+    testAppID  = envOr("MEMBERSHIP_TEST_APPID", "3492")
+    testAppKey = envOr("MEMBERSHIP_TEST_APPKEY", "")
+    testToken  = envOr("MEMBERSHIP_TEST_TOKEN", "")
+    client = &http.Client{Timeout: 30 * time.Second}
+}
+
+func envOr(key, defaultVal string) string {
+    if v := os.Getenv(key); v != "" { return v }
+    return defaultVal
+}
+```
+
+#### 3. kugo 签名算法（精确复刻 kugo CheckClientSignature v0.1，不可修改）
+
+```go
+// kugoBuildSignature 复刻 kugo httpclient buildSignature
+// GET:  appkey + sorted(key=value...) + "" + appkey
+// POST: appkey + sorted(key=value...) + body + appkey
+// 源码：kugo@v1.6.35/httpclient/signature.go:buildSignature
+func kugoBuildSignature(params map[string]string, appkey, body string) string {
+    keys := make([]string, 0, len(params))
+    for k := range params {
+        if k == "signature" { continue }
+        keys = append(keys, k)
+    }
+    sort.Strings(keys)
+    raw := appkey
+    for _, k := range keys { raw += k + "=" + params[k] }
+    raw += body
+    raw += appkey
+    hash := md5.Sum([]byte(raw))
+    return hex.EncodeToString(hash[:])
+}
+
+// kugoSign GET 请求签名（body 为空）
+func kugoSign(params map[string]string, appkey string) string {
+    return kugoBuildSignature(params, appkey, "")
+}
+```
+
+#### 4. signQuery / signQueryWithBody（公参加签名）
+
+```go
+// signQuery GET 或无 body 场景
+func signQuery(params map[string]string) map[string]string {
+    return signQueryWithBody(params, "")
+}
+
+// signQueryWithBody POST 必须传入与请求体完全一致的原始 JSON 字符串
+func signQueryWithBody(params map[string]string, body string) map[string]string {
+    result := make(map[string]string, len(params)+8)
+    for k, v := range params { result[k] = v }
+    result["appid"]      = testAppID
+    result["clienttime"] = fmt.Sprintf("%d", time.Now().Unix())
+    result["clientver"]  = "1.0"
+    result["mid"]        = "1"
+    result["dfid"]       = "-"
+    result["uuid"]       = "test-integration-uuid"
+    if testToken != "" { result["token"] = testToken }
+    result["signature"] = kugoBuildSignature(result, testAppKey, body)
+    return result
+}
+```
+
+#### 5. parseQuery / mapToQuery
+
+```go
+func parseQuery(qs string) map[string]string {
+    m := map[string]string{}
+    for _, kv := range strings.Split(qs, "&") {
+        if kv == "" { continue }
+        pair := strings.SplitN(kv, "=", 2)
+        if len(pair) == 2 { m[pair[0]] = pair[1] } else { m[pair[0]] = "" }
+    }
+    return m
+}
+
+func mapToQuery(m map[string]string) string {
+    keys := make([]string, 0, len(m))
+    for k := range m { keys = append(keys, k) }
+    sort.Strings(keys)
+    res := ""
+    for _, k := range keys {
+        if res != "" { res += "&" }
+        res += fmt.Sprintf("%s=%s", k, m[k])
+    }
+    return res
+}
+```
+
+#### 6. HTTP helpers：doGet / doPost / doPostInner
+
+```go
+func doGet(t *testing.T, path string) map[string]any {
+    t.Helper()
+    parts := strings.SplitN(path, "?", 2)
+    basePath := parts[0]
+    params := map[string]string{}
+    if len(parts) > 1 { params = parseQuery(parts[1]) }
+    if params["userid"] == "" { params["userid"] = getDefaultUserID(t) }
+    signed := signQuery(params)
+    url := host + basePath + "?" + mapToQuery(signed)
+    req, _ := http.NewRequest("GET", url, nil)
+    resp, err := client.Do(req)
+    if err != nil { t.Fatalf("GET %s failed: %v", url, err) }
+    defer resp.Body.Close()
+    body, _ := io.ReadAll(resp.Body)
+    var m map[string]any
+    json.Unmarshal(body, &m)
+    t.Logf("GET %s → status=%d body=%s", url, resp.StatusCode, string(body))
+    return m
+}
+
+func doPost(t *testing.T, path string, payload map[string]any) map[string]any {
+    t.Helper()
+    b, _ := json.Marshal(payload)
+    params := map[string]string{}
+    if uid, ok := payload["userid"]; ok {
+        params["userid"] = fmt.Sprintf("%v", uid)
+    } else {
+        params["userid"] = getDefaultUserID(t)
+    }
+    querySigned := signQueryWithBody(params, string(b)) // POST: body 参与签名
+    url := host + path + "?" + mapToQuery(querySigned)
+    req, _ := http.NewRequest("POST", url, bytes.NewReader(b))
+    req.Header.Set("Content-Type", "application/json")
+    resp, err := client.Do(req)
+    if err != nil { t.Fatalf("POST %s failed: %v", url, err) }
+    defer resp.Body.Close()
+    respBody, _ := io.ReadAll(resp.Body)
+    var m map[string]any
+    json.Unmarshal(respBody, &m)
+    t.Logf("POST %s body=%s → status=%d resp=%s", url, string(b), resp.StatusCode, string(respBody))
+    return m
+}
+
+// doPostSigned 带额外 query 参数（如 client_code=h5_quanmin_ios）的 POST，body 同样参与签名
+func doPostSigned(t *testing.T, path string, payload map[string]any, extraQuery map[string]string) map[string]any {
+    t.Helper()
+    b, _ := json.Marshal(payload)
+    params := map[string]string{}
+    if uid, ok := payload["userid"]; ok {
+        params["userid"] = fmt.Sprintf("%v", uid)
+    } else {
+        params["userid"] = getDefaultUserID(t)
+    }
+    for k, v := range extraQuery { params[k] = v }
+    querySigned := signQueryWithBody(params, string(b))
+    url := host + path + "?" + mapToQuery(querySigned)
+    req, _ := http.NewRequest("POST", url, bytes.NewReader(b))
+    req.Header.Set("Content-Type", "application/json")
+    resp, err := client.Do(req)
+    if err != nil { t.Fatalf("POST %s failed: %v", url, err) }
+    defer resp.Body.Close()
+    respBody, _ := io.ReadAll(resp.Body)
+    var m map[string]any
+    json.Unmarshal(respBody, &m)
+    t.Logf("POST %s body=%s → status=%d resp=%s", url, string(b), resp.StatusCode, string(respBody))
+    return m
+}
+
+func doPostInner(t *testing.T, path string, payload map[string]any) string {
+    t.Helper()
+    b, _ := json.Marshal(payload)
+    url := host + path
+    resp, err := client.Post(url, "application/json", bytes.NewReader(b))
+    if err != nil { t.Fatalf("POST %s failed: %v", url, err) }
+    defer resp.Body.Close()
+    respBody, _ := io.ReadAll(resp.Body)
+    txt := strings.TrimSpace(string(respBody))
+    t.Logf("POST %s body=%s → status=%d text=%s", url, string(b), resp.StatusCode, txt)
+    return txt
+}
+```
+
+#### 7. 响应解析辅助函数
+
+```go
+func getString(m map[string]any, key string) string {
+    if v, ok := m[key]; ok { s, _ := v.(string); return s }
+    if d, ok := m["data"]; ok {
+        if dm, ok := d.(map[string]any); ok {
+            if v, ok := dm[key]; ok { s, _ := v.(string); return s }
+        }
+    }
+    return ""
+}
+func getFloat(m map[string]any, key string) float64 { v, _ := m[key].(float64); return v }
+func getCode(m map[string]any) float64              { return getFloat(m, "errcode") }
+```
+
+#### 8. getDefaultUserID（按需调整返回哪个 userID）
+
+```go
+func getDefaultUserID(t *testing.T) string {
+    t.Helper()
+    return os.Getenv("MEMBERSHIP_TEST_USERID")
+}
+```
+
+#### 9. 签名单测（必须生成，防止 POST 漏签 body）
+
+```go
+func TestKugoBuildSignature_PostIncludesBody(t *testing.T) {
+    if testAppKey == "" {
+        t.Skip("MEMBERSHIP_TEST_APPKEY not set")
+    }
+    body := `{"userid":1,"app_type":4}`
+    params := map[string]string{
+        "appid": testAppID, "clienttime": "1000000", "clientver": "1.0",
+        "mid": "1", "dfid": "-", "uuid": "test-integration-uuid", "userid": "1",
+    }
+    withBody := kugoBuildSignature(params, testAppKey, body)
+    withoutBody := kugoBuildSignature(params, testAppKey, "")
+    if withBody == withoutBody {
+        t.Fatal("POST signature must include body; got same hash as GET")
+    }
+}
+```
+
+### 4c. ⚠️ 测试函数组织规则（关键）
+
+**每个场景必须是独立的顶层 `TestXxx` 函数，禁止用 `t.Run` 子测试。**
+
+原因：`-run` 正则匹配时，父函数名会导致子测试连带执行，无法隔离。
+
+```go
+// ❌ 错误：t.Run 子测试，-run "场景1" 会连带执行场景2
+func TestXxx_链1(t *testing.T) {
+    t.Run("场景1", func(t *testing.T) { ... })
+    t.Run("场景2", func(t *testing.T) { ... })
+}
+
+// ✅ 正确：每个场景独立顶层函数
+func TestMembInt_L1S1_场景1(t *testing.T) { skipIfNoHost(t); l1s1(t) }
+func TestMembInt_L1S2_场景2(t *testing.T) { skipIfNoHost(t); l1s2(t) }
+
+func l1s1(t *testing.T) { ... }
+func l1s2(t *testing.T) { ... }
+```
+
+**命名规范**：`Test{缩写前缀}_L{链号}S{场景号}_{中文场景名}`
+
+- 前缀统一用 `TestMembInt` 或其他简短前缀
+- 实际逻辑放在小写 `lXsY` 函数中，方便复用和跳测
+- `skipIfNoHost` 在顶层函数调用，不在小写函数内
+
+**运行粒度**：
+
+```bash
+go test -run "TestMembInt_L1S1"   # 单个场景
+go test -run "TestMembInt_L1"     # 整条链路
+go test -run "TestMembInt_L[23]"  # 链2+链3
+go test -run "TestMembInt"        # 全部
+```
+
+---
+
+## Step 5：质量自查
+
+生成完成后运行：
+
+```bash
+go build ./...
+go test -run TestKugoBuildSignature ./service/biz/{module}/... -count=1
+```
+
+必须通过。有编译错误则修复。
+
+额外检查：
+- [ ] 所有 `TestXxx` 函数都是独立顶层函数（无 `t.Run` 嵌套）
+- [ ] **POST 使用 `signQueryWithBody(params, string(b))`，GET 使用 `signQuery(params)`**
+- [ ] **`TestKugoBuildSignature_PostIncludesBody` 已生成且通过**（POST 签名 ≠ GET 签名）
+- [ ] kugo 参数名用的是 `signature` 不是 `sign`
+- [ ] `host` 默认值不含路径后缀（如 `http://127.0.0.1:80`，完整 path 在请求里写 `/quanmin/v1/...`）
+- [ ] `CheckUserToken` 所需的 `userid` 和 `token` 已注入 query
+- [ ] 内嵌 H5 链路 extra query（如 `client_code=h5_quanmin_ios`）通过 `doPostSigned` 注入且参与签名
+- [ ] 内部接口用 `doPostInner`（不签名）
+- [ ] `testAppKey` / `testToken` 默认值为空，不写死密钥到代码
+- [ ] 需要 DB/内网环境的场景用 `t.Skip` 跳过
+
+---
+
+## Step 6：输出完成摘要
+
+```
+✅ 自测计划生成完成：
+
+📄 文档：.test_plans/{name}-self-test-plan.md（{N} 条链路，{M} 个场景）
+🧪 测试：service/biz/{module}/{module}_integration_test.go（{K} 个独立 Test 函数）
+
+运行：
+  go test -run TestKugoBuildSignature ./service/biz/{module}/... -count=1  # 先验证签名
+  go test -run "TestXxx_L1S1" ./service/biz/{module}/... -count=1 -v
+```

package/prompts/X-travel-planner.md

@@ -0,0 +1,22 @@
+# prompts/X-travel-planner · 旅行规划
+
+横向命令，任意时刻可触发：`/atdc:travel-planner <需求>`
+
+## 执行步骤
+
+### 1. 加载 Skill
+
+用 skill 工具加载 `travel-planner` skill（路径：`~/.config/opencode/skills/travel-planner/SKILL.md`）。
+
+### 2. 解析需求
+
+从 $ARGUMENTS 中提取旅行要素（目的地、天数、出发地、人员、偏好等）。
+
+### 3. 执行规划
+
+按照 SKILL.md 定义的工作流执行：
+- 需求澄清 → 信息研究（小红书+公开搜索）→ 智能规划（人流+人群适配）→ 攻略输出（HTML/文字）
+
+### 4. 交付
+
+根据用户需求输出：快速推荐（文字）或完整攻略（HTML页面）。

package/prompts/X-xlsx2sql-insert.md

@@ -0,0 +1,34 @@
+# prompts/X-xlsx2sql-insert · Excel → INSERT SQL
+
+横向命令，任意时刻可触发：`/atdc:xlsx2sql-insert <excel_file>`
+
+---
+
+## 执行步骤
+
+### 1. 确定输入
+
+检查用户参数：
+- Excel 文件路径
+- `--table <name>` 目标表名（必填）
+- `--sheet <name>` Sheet 名称（可选，默认第一个）
+- `--header-row <N>` 表头行号（可选，默认 2）
+- `--data-start <N>` 数据起始行（可选，默认 header+1）
+- `--output <path>` 输出文件路径（可选，默认 stdout）
+- 其他参数参考 `xlsx2sql --help`
+
+### 2. 调用工具
+
+```bash
+${ATDC_DIR}/tools/xlsx2sql <excel_file> --table <table> [options]
+```
+
+### 3. 输出
+
+生成 INSERT SQL 语句，可直接用于 `membership_init_sku --sql=xxx.sql`。
+
+### 4. 使用示例
+
+```bash
+/atdc:xlsx2sql-insert template.xlsx --table membership_product_sku --output init.sql
+```

package/prompts/X-xlsx2sql-update.md

@@ -0,0 +1,40 @@
+# prompts/X-xlsx2sql-update · Excel → UPDATE SQL
+
+横向命令，任意时刻可触发：`/atdc:xlsx2sql-update <excel_file>`
+
+---
+
+## 执行步骤
+
+### 1. 确定输入
+
+检查用户参数：
+- Excel 文件路径
+- `--table <name>` 目标表名（必填）
+- `--key <col1,col2>` 主键列（必填，逗号分隔）
+- `--set <col1,col2>` 限定更新列（可选，不指定则更新全部非key列）
+- `--sheet <name>` Sheet 名称（可选）
+- `--output <path>` 输出文件路径（可选，默认 stdout）
+
+### 2. 调用工具
+
+```bash
+${ATDC_DIR}/tools/xlsx2sql <excel_file> --table <table> --mode update --key <cols> [--set <cols>]
+```
+
+### 3. 输出
+
+生成 UPDATE SQL 语句，每行 Excel 数据对应一条 `UPDATE ... SET ... WHERE ...`。
+
+### 4. 使用示例
+
+```bash
+# 更新全部非key列
+/atdc:xlsx2sql-update template.xlsx --table membership_product_sku --key id
+
+# 只更新指定列
+/atdc:xlsx2sql-update template.xlsx --table membership_product_sku --key id --set list_price,sale_price
+
+# 输出到文件
+/atdc:xlsx2sql-update template.xlsx --table membership_product_sku --key id --output update.sql
+```

package/prompts/X-zoom-out.md

@@ -0,0 +1,119 @@
+---
+name: atd-zoom-out
+description: >
+  Tell the agent to zoom out and give broader context or a higher-level
+  perspective on code. Use when unfamiliar with a section of code, need to
+  understand how it fits into the bigger picture, or before modifying code
+  in a module you haven't worked with before.
+argument-hint: "Which file, function, or module do you want perspective on?"
+---
+
+# prompts/X-zoom-out · 代码全景分析
+
+横向命令：`/atdc:zoom-out <文件/函数/模块>`
+也由 `3-impl Step 5b0` 自动建议触发。
+
+---
+
+## Step 1：确认目标
+
+从用户输入或 3-impl 上下文中确定分析目标：
+- 单个文件路径
+- 单个函数/方法名
+- 整个模块目录
+
+---
+
+## Step 2：系统定位
+
+用 CodeGraph 分析目标在系统中的位置：
+
+```
+codegraph_context "<目标符号或文件>"
+```
+
+回答以下问题：
+1. 这个模块/文件在项目目录树中的位置和角色？
+2. 它的上游调用方是谁？（谁依赖它）
+3. 它的下游依赖是谁？（它依赖谁）
+4. 它属于哪个架构层？（handler / service / repository / domain）
+
+---
+
+## Step 3：数据流分析
+
+```
+codegraph_trace from:"<入口>" to:"<目标>"
+```
+
+追踪从入口到目标的数据流：
+- 数据从哪里进入系统？
+- 经过哪些变换/校验？
+- 最终落到哪里（DB / 缓存 / 外部服务）？
+
+---
+
+## Step 4：影响面评估
+
+```
+codegraph_impact "<目标符号>"
+```
+
+1-hop / 2-hop blast radius：
+- 修改此代码会直接影响哪些调用方？
+- 间接影响哪些用户流程？
+- 是否有测试覆盖这些路径？
+
+---
+
+## Step 5：与 CONTEXT.md 对比
+
+```bash
+grep -A5 "<模块名>" CONTEXT.md 2>/dev/null
+```
+
+- 此代码是否符合 CONTEXT.md 中描述的模块边界和职责？
+- 是否发现了 CONTEXT.md 未记录的模块关系？（如果是 → 建议更新 CONTEXT.md）
+
+---
+
+## Step 6：输出全景报告
+
+```
+🔭 Zoom-Out 全景报告 — <目标>
+
+### 位置
+- 目录：<路径>
+- 架构层：<handler/service/repository/domain>
+- 所属模块：<模块名>
+
+### 上游调用方（谁在用）
+| 调用方 | 文件:行 | 用途 |
+|--------|---------|------|
+| ... | ... | ... |
+
+### 下游依赖（用到了什么）
+| 被调用方 | 文件:行 | 用途 |
+|----------|---------|------|
+| ... | ... | ... |
+
+### 数据流
+<入口> → <步骤1> → <步骤2> → ... → <目标> → <结果>
+
+### 修改影响
+- 直接影响：<N> 个调用方
+- 间接影响流程：<列表>
+- 测试覆盖：<有/缺口>
+
+### 架构一致性
+- CONTEXT.md 一致：✅ / ⚠️ <不一致项>
+```
+
+---
+
+## 衔接 3-impl
+
+当由 `3-impl Step 5b0` 触发时：
+- 目标从 `**Files**:` 字段自动提取
+- 报告重点：修改影响 + 架构一致性
+- 完成后自动回到 3-impl 继续执行