重置项目上下文与规范文档

AGENTS.md

@@ -1,389 +1,92 @@
+# 项目 Agent 导航
 
----
+## 项目目标
 
-# junhong_cmp_fiber 项目开发规范
+君鸿卡管系统管理物联网卡、设备、套餐、订单、钱包、分佣、审批与外部渠道协作；代码保存本地业务事实，第三方系统只提供外部能力。
 
-**重要**: 本文件包含核心规范。详细规范已提取为 Skills，在特定任务时按需加载。
+## 交流与文本
 
-## 专项规范 Skills（按需加载）
+- 永远使用中文交流。
+- 代码注释、文档、日志和用户可见错误使用中文。
+- Go 标识符使用英文并遵循 Go 命名习惯。
+- Git 提交信息使用中文；未经明确要求不提交。
 
-以下规范在相关任务时**自动触发**，无需手动加载：
+## 不可替代技术栈
 
-| 任务类型 | 触发 Skill | 说明 |
-|---------|-----------|------|
-| 创建/修改 DTO 文件 | `dto-standards` | description 标签、枚举字段、验证标签规范 |
-| 创建/修改 Model 模型 | `model-standards` | GORM 模型结构、字段标签、TableName 规范 |
-| 注册 API 路由 / **新增 Handler** | `api-routing` | Register() 函数、RouteSpec、**文档生成器更新** |
-| 测试接口/验证数据 | `db-validation` | PostgreSQL MCP 使用方法和验证示例 |
-| 数据库迁移 | `db-migration` | 迁移命令、文件规范、执行流程、失败处理 |
-| 维护规范文档 | `doc-management` | 规范文档流程和维护规则 |
-| 编写 Go 代码注释/文档注释 | `comment-standards` | 包/结构体/接口/函数/内联注释完整规范与示例 |
-| 创建涉及接口的 OpenSpec 提案 | `openspec-api-contract` | 探索阶段引导清单、提案必填章节与完成标准 |
+- Go 1.25、Fiber v2、GORM、Viper。
+- PostgreSQL、Redis、Asynq。
+- Zap + Lumberjack、Validator、sonic。
+- 不以 net/http 替代 Fiber，不绕过 GORM 使用 database/sql。
+- 依赖及实际版本只以 `go.mod` 为准。
 
----
+## 事实源优先级
 
-### ⚠️ 新增 Handler 时必须同步更新文档生成器
+1. 可复现运行结果。
+2. 实际可达代码与生效配置。
+3. `migrations/` 与数据库 Schema。
+4. `openspec/specs/` 当前行为契约。
+5. `ARCHITECTURE.md` 系统地图与依赖边界。
+6. `docs/engineering/工程约束.md` 长期工程规则。
+7. `docs/integrations/` 第三方契约。
+8. 本文件只承担硬约束和导航。
 
-新增 Handler 后，接口不会自动出现在 OpenAPI 文档中。**必须手动更新以下两个文件**：
+冲突时按上述顺序修正文档，不顺手改变当前行为。历史聊天、已删除文档和归档 Change 不是事实源。
 
-```go
-// cmd/api/docs.go 和 cmd/gendocs/main.go
-handlers := &bootstrap.Handlers{
-    // ... 添加新 Handler
-    NewHandler: admin.NewXxxHandler(nil),
-}
-```
+## 受保护边界
 
-**完整检查清单**: 参见 [`docs/api-documentation-guide.md`](docs/api-documentation-guide.md#新增-handler-检查清单)
+- 不主动重构需求未触碰的旧模块。
+- 行为变化必须通过独立 OpenSpec Change；主 Specs 只描述当前行为。
+- 当前 Bug 与兼容行为按实际结果记录，禁止在基线任务中顺手修复。
+- 不修改既有迁移；新 Schema 变化使用新的成对迁移。
+- 不访问生产服务、真实支付渠道或外部审批系统进行自动验证。
+- 不把密钥、Token、证书或个人敏感数据写入代码、文档和日志。
+- `.lh-harness/` 仅保存本地执行证据，不是事实源且不得纳入 Git。
+- 自动化测试当前为 N/A（用户决策）；不恢复旧测试，也不写虚假测试入口。
 
----
+## 架构选择
 
-## 语言要求
+- 复杂写：Handler → Application UseCase → Domain → Port/Infrastructure。
+- 简单写：Handler → Application 事务脚本 → Persistence。
+- 读取：Handler → Query → GORM/DTO；读取不得经聚合根修改状态。
+- 旧 `internal/service/` 按完整用例渐进迁移，不做模块级重构。
+- `internal/domain/` 不依赖 Fiber、GORM、Redis、Asynq 或具体外部 SDK。
+- 状态机、金额、库存、并发不变量与可靠事件在 Domain/Application 闭合。
+- 禁止为单一实现预建接口、工厂或深层目录。
 
-**必须遵守:**
+模块、运行单元、数据流和验证入口见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。
 
-- 永远用中文交互
-- 注释必须使用中文
-- 文档必须使用中文
-- 日志消息必须使用中文
-- 用户可见的错误消息必须使用中文
-- 变量名、函数名、类型名必须使用英文（遵循 Go 命名规范）
-- GIT提交的commit必须使用中文
+## 工程与外部契约
 
-## 技术栈
-
-**必须严格遵守，禁止替代方案:**
-
-| 类型 | 技术 |
-|------|------|
-| HTTP 框架 | Fiber v2.x |
-| ORM | GORM v1.25.x |
-| 配置管理 | Viper |
-| 日志 | Zap + Lumberjack.v2 |
-| JSON 序列化 | sonic（优先），encoding/json（必要时） |
-| 验证 | Validator |
-| 任务队列 | Asynq v0.24.x |
-| 数据库 | PostgreSQL 14+ |
-| 缓存 | Redis 6.0+ |
-
-**禁止:**
-
-- 直接使用 `database/sql`（必须通过 GORM）
-- 使用 `net/http` 替代 Fiber
-- 使用 `encoding/json` 替代 sonic（除非必要）
-
-## 架构演进：MVC 与 DDD 共存
-
-项目采用**触碰式渐进迁移**，不安排一次性全仓库重构。详细规则见 `docs/7月迭代/独立方案/基础规范/DDD规范.md`。
-
-### 三条执行通道
-
-- **复杂写操作**：`Handler → Application UseCase → Domain → Repository/Infrastructure`。适用于状态机、金额、库存、并发不变量、策略和可靠事件。
-- **简单写操作**：`Handler → Application 事务脚本 → Persistence`。单表 CRUD 不强行创建聚合。
-- **读取操作**：`Handler → Query → GORM/DTO`。列表、详情、联表、统计、报表和导出不经过聚合根。
-
-### 触碰式迁移约束
-
-1. 禁止主动迁移当前需求未触碰的旧模块；简单字段、筛选和局部修复默认沿用旧结构。
-2. 迁移单位是**完整用例**，不是整个模块、文件或数据表；一旦迁移，相关业务不变量必须完整收口，禁止一半留在旧 Service、一半放在 Domain。
-3. 当前需求触碰复杂写逻辑时，只迁移完成该需求所需的最小完整业务边界；旧 Service 可暂时作为内部代码迁移门面调用新 UseCase，但这不等于必须保留旧 HTTP 接口。
-4. 当前需求触碰复杂只读逻辑时，只迁移该查询到 `internal/query/<context>`；Query 可直接使用 GORM 做联表、聚合、权限过滤和 DTO 投影。
-5. 不为追求 DDD 形式创建无业务价值的接口、工厂和目录；架构选择不明确时先阅读 DDD 规范并写明判断依据。
-
-### 规划与任务拆分约束
-
-创建或修改 PRD、OpenSpec proposal/design/tasks、实施计划或本地 Issue/Ticket 前，必须完整阅读 `docs/7月迭代/独立方案/基础规范/DDD规范.md`，并遵守以下规则：
-
-1. 每个可实施单元必须标明适用的架构通道：复杂写、简单写、Query、Infrastructure 或 Application + Port/Adapter；同一纵向切片涉及多条通道时，标明主通道和辅助通道。
-2. 每个任务必须说明其收口的完整业务边界及明确不迁移的旧代码范围，禁止借任务拆分扩大为模块级或全仓重构。
-3. Ticket 必须按可独立验证的纵向切片拆分，不得按“先建表、再 Service、再 Handler”生成水平分层任务；宽范围机械迁移按 expand–migrate–contract 拆分并保持各阶段可验证。
-4. 复杂写的不变量、状态机、金额、并发和可靠事件必须完整进入 Domain/Application 边界；简单写不得强行创建聚合；读取不得经过聚合根或修改状态。
-5. 已评审 PRD 或 OpenSpec 已确定的架构选择是实施契约，拆票和实现阶段不得自行改变；确需调整时必须先说明影响并获得用户确认。
-6. 跨 PRD 或跨 Change 的依赖必须引用具体任务或 Ticket，禁止只写“依赖公共基础设施”等无法判定完成状态的模糊阻塞项。
-7. 任务正文只记录本切片适用的架构约束，不机械复制整份 DDD 规范；实现和评审仍以本文件及完整 DDD 规范为准。
-
-## 核心原则
-
-### 错误处理
-
-- 所有错误必须在 `pkg/errors/` 中定义
-- 使用统一错误码系统
-- Handler 层通过返回 `error` 传递给全局 ErrorHandler
-
-#### 错误报错规范（必须遵守）
-
-- Handler 层禁止直接返回/拼接底层错误信息给客户端（例如 `"参数验证失败: "+err.Error()`、`err.Error()`）
-- 参数校验失败：对外统一返回 `errors.New(errors.CodeInvalidParam)`（详细校验错误写日志）
-- Service/Application/Domain/Query 层禁止向接口调用方直接返回 `fmt.Errorf(...)`，必须转换为 `errors.New(...)` 或 `errors.Wrap(...)`
-- 约定用法：`errors.New(code[, msg])`、`errors.Wrap(code, err[, msg])`
-
-### 响应格式
-
-- 所有 API 响应使用 `pkg/response/` 的统一格式
-- 格式: `{code, msg, data, timestamp}`
-
-### 常量管理
-
-- 所有常量定义在 `pkg/constants/`
-- Redis key 使用函数生成: `Redis{Module}{Purpose}Key(params...)`
-- 禁止硬编码字符串和 magic numbers
-- **必须为所有常量添加中文注释**
-
-### 枚举与状态字段（必须遵守）
-
-**两个强制规则**：
-
-1. **int vs string**：状态类（生命周期）用 `int`，类型/方式类用 `string`
-2. **DTO description 必须从 constants 原文抄写**，禁止凭记忆填写枚举值（历史上已有 description 与 constants 不一致导致前端显示错误的案例）
-
-```go
-// ✅ description 从 constants 原文抄，格式统一用冒号+逗号
-Status int `json:"status" description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款)"`
-StatusName string `json:"status_name" description:"状态名称（中文）"` // Response DTO 必须加
-
-// ❌ 禁止：启用/禁用用 1=启用 2=禁用（全局约定是 0=禁用, 1=启用）
-// ❌ 禁止：description 枚举值与 constants 不一致
-```
-
-**完整规范**: 参见 [`docs/enum-status-standards.md`](docs/enum-status-standards.md)
-
-### 注释规范
-
-- **所有注释使用中文**，导出符号必须有文档注释（包、函数、类型、接口、常量）
-- 复杂逻辑解释"为什么"而非"做了什么"，禁止废话注释（复述代码本身）
-- Handler 方法注释必须包含 HTTP 方法和路径（`// Create 创建账号` + `// POST /api/admin/accounts`）
-- 未导出函数：< 15 行可省略，≥ 15 行或非显而易见算法必须注释
-- 修改代码时必须同步更新注释，过时注释比没有注释更有害
-
-**详细规范与示例**：见 `comment-standards` skill
-
-### Go 代码风格
-
-- 使用 `gofmt` 格式化
-- 遵循 [Effective Go](https://go.dev/doc/effective_go)
-- 包名: 简短、小写、单数、无下划线
-- 接口命名: 使用 `-er` 后缀（Reader、Writer、Logger）
-
-## 数据库设计
-
-**核心规则:**
-
-- ❌ 禁止建立外键约束
-- ❌ 禁止使用 GORM 关联关系标签（foreignKey、hasMany、belongsTo）
-- ✅ 关联通过存储 ID 字段手动维护
-- ✅ 关联数据在代码层面显式查询
-
-## Go 惯用法 vs Java 风格
-
-### ✅ Go 风格（推荐）
-
-- 扁平化包结构（最多 2-3 层）
-- 小而专注的接口（1-3 个方法）
-- 直接访问导出字段（不用 getter/setter）
-- 组合优于继承
-- 显式错误返回和检查
-
-### ❌ Java 风格（禁止）
-
-- 过度抽象（不必要的接口、工厂）
-- Getter/Setter 方法
-- 深层继承层次
-- 异常处理（panic/recover）
-- 类型前缀（IService、AbstractBase、ServiceImpl）
-
-## 性能要求
-
-- API P95 响应时间 < 200ms
-- API P99 响应时间 < 500ms
-- 数据库查询 < 50ms
-- 列表查询必须分页（默认 20，最大 100）
-- 避免 N+1 查询，使用批量操作
-
-## 文档要求
-
-- 每个功能在 `docs/{feature-id}/` 创建总结文档
-- 文档文件名和内容使用中文
-- 同步更新 README.md
-- 为导出的函数、类型编写文档注释
-- 需要进入评审的标准/完整技术方案必须覆盖关键流程、前后端契约、异常闭环、发布回滚和待决策项；简单改动不强行画图。详细要求见 `docs/技术方案评审规范.md`
-
-## 函数复杂度
-
-- 函数长度 ≤ 100 行（核心逻辑建议 ≤ 50 行）
-- `main()` 函数只做编排，不含具体实现
-- 遵循单一职责原则
-
-## 访问日志
-
-- 所有 HTTP 请求记录到 `access.log`
-- 记录完整的请求/响应（限制 50KB）
-- 包含: method, path, query, status, duration, request_id, ip, user_agent, user_id, bodies
-- 使用 JSON 格式，配置自动轮转
+- 工程规则只维护在 [`docs/engineering/工程约束.md`](docs/engineering/工程约束.md)。
+- 新增 Handler 同步可执行路由、`cmd/api/docs.go` 与 `cmd/gendocs/main.go`。
+- Handler 将错误交给全局 ErrorHandler，响应使用 `pkg/response`。
+- 第三方字段、签名、错误与重试依据 [`docs/integrations/`](docs/integrations/)；外部文档不证明本系统已实现对应行为。
+- Makefile 的历史数据库连接信息不得使用；迁移只连接明确指定的隔离环境。
 
 ## OpenSpec 工作流
 
-创建提案前的检查清单：
+- 当前行为：`openspec/specs/<capability>/spec.md`。
+- 后续变更：`openspec/changes/<change>/`。
+- 使用官方 `openspec-propose`、`openspec-apply-change`、更新、同步和归档 Skills。
+- Change 的 `tasks.md` 是执行契约；按顺序验证，调整前取得用户确认。
+- Requirement 必须描述可观察行为，不能用接口目录代替状态、权限、金额、失败与幂等语义。
 
-1. ✅ 技术栈合规
-2. ✅ 架构分层正确
-3. ✅ 使用统一错误处理
-4. ✅ 常量定义在 pkg/constants/
-5. ✅ Go 惯用法（非 Java 风格）
-6. ✅ 性能考虑
-7. ✅ 文档更新计划
-8. ✅ 中文优先
+## 常用验证
 
-## Code Review 检查清单
-
-### 错误处理
-
-- [ ] Service/Application/Domain/Query 层无 `fmt.Errorf` 对外返回
-- [ ] Handler 层参数校验不泄露细节
-- [ ] 错误码使用正确（4xx vs 5xx）
-- [ ] 错误日志完整（包含上下文）
-
-### 代码质量
-
-- [ ] 已按判断标准选择复杂写、简单写或 Query 通道，未扩大迁移范围
-- [ ] 复杂写规则收口 Domain；简单写使用 Application 事务脚本；只读逻辑不经过聚合根
-- [ ] Query 负责读取权限、分页和 DTO 投影，写操作仍在 Domain 重新校验
-- [ ] 函数长度 ≤ 100 行（核心逻辑 ≤ 50 行）
-- [ ] 常量定义在 `pkg/constants/`
-- [ ] 使用 Go 惯用法（非 Java 风格）
-
-### 枚举与状态
-
-- [ ] 状态类字段用 `int`，类型/方式类字段用 `string`
-- [ ] 禁用/启用使用 `0=禁用, 1=启用`（禁止 `1=启用, 2=禁用`）
-- [ ] DTO description 枚举列表已从 `pkg/constants/` 原文抄写，无遗漏、无错误
-- [ ] Response DTO 的 int 状态字段有对应的 `_name` 文字字段
-
-### 文档和注释
-
-- [ ] 所有注释使用中文
-- [ ] 导出函数/类型有文档注释
-- [ ] API 路径注释与真实路由一致
-
-### 幂等性
-
-- [ ] 创建类写操作有 Redis 业务键防重
-- [ ] 状态变更使用条件更新（`WHERE status = expected`）
-- [ ] 余额/库存变更使用乐观锁（version 字段）
-- [ ] 分布式锁使用 `defer` 确保释放
-- [ ] Redis Key 定义在 `pkg/constants/redis.go`
-
-### 越权防护规范
-
-**三层防护机制**（基础设施已就绪，无需自建）：
-1. **路由层中间件**：粗粒度拦截（如企业账号禁止访问账号管理）
-2. **Service 层业务检查**：`middleware.CanManageShop()` / `middleware.CanManageEnterprise()` 细粒度验证；示例见 `internal/service/account/service.go`
-3. **GORM Callback 自动过滤**：代理按店铺层级、企业按企业ID，已自动应用无需手动调用
-
-统一错误返回：`errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")`（不区分"不存在"与"无权限"，防止信息泄露）
-
-### 幂等性规范
-
-写操作按场景选择策略：
-- **状态流转操作** → 状态条件更新（首选）
-- **创建类操作（无状态可依赖）** → Redis 业务键防重 + 分布式锁（三层检测）
-- **余额/库存数值更新** → 乐观锁（`version` 字段）
-
-```go
-// 策略1示例（首选）：通过 WHERE 条件确保幂等，RowsAffected=0 说明已被处理
-result := tx.Model(&model.Order{}).
-    Where("id = ? AND payment_status = ?", orderID, model.PaymentStatusPending).
-    Updates(map[string]any{"payment_status": model.PaymentStatusPaid})
-if result.RowsAffected == 0 { /* 已处理，检查当前状态 */ }
+```bash
+gofmt -w <changed-go-files>
+go build ./cmd/api ./cmd/worker
+go run cmd/gendocs/main.go
+openspec doctor --json
+openspec validate --all
+./scripts/context-health.sh
 ```
 
-- Redis Key 定义在 `pkg/constants/redis.go`，分布式锁必须用 `defer` 释放
-- 参考实现：`internal/service/order/service.go`
+启动、隔离数据库重置、smoke 与日志读取见 [`README.md`](README.md)。迁移只使用 `scripts/migrate.sh` 加显式隔离数据库参数。
 
-### 异步任务载荷规范（Asynq）
+## 渐进披露
 
-**必须遵守：**
-
-- ✅ 调用 `queueClient.EnqueueTask()` 时，`payload` 必须传入 **struct 或 map**
-- ❌ **禁止传入 `[]byte`**：`EnqueueTask` 内部统一调用 `sonic.Marshal`，若传入 `[]byte` 会被 base64 编码成字符串，Handler 反序列化时类型不匹配直接崩溃
-
-```go
-// ✅ 正确：传 struct
-queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, MyPayload{OrderID: id})
-
-// ❌ 错误：预先序列化后传 []byte（二次 Marshal → base64 编码）
-payloadBytes, _ := sonic.Marshal(MyPayload{OrderID: id})
-queueClient.EnqueueTask(ctx, constants.TaskTypeXxx, payloadBytes)
-```
-
-直接用 `asynq.NewTask` 入队时（绕过 `EnqueueTask`）才需要自己 Marshal。
-
----
-
-### 审计日志规范
-
-**适用场景**：整个系统中的状态变更、敏感读取以及关键拒绝和失败，不限于七月迭代。实现前必须查阅并增量维护 `.scratch/tech-global-audit/审计覆盖基线.md`；选择不审计必须登记 N/A 理由，禁止留空。
-
-- Access Log 只负责 HTTP 调试，Audit Event 负责业务审计，Domain Ledger 负责金额和状态等领域事实，Integration Log 负责外部交互；四者不得混用或合并。
-- 旧模块在 Service/Application 事务脚本中、新 DDD 模块在 Application UseCase 中通过统一 Audit Writer Port/Adapter 接入；禁止新增裸 goroutine 审计写入。
-- 成功的资金、权限、关键配置、人工状态变更和其他高风险操作必须与业务事实同一 GORM 事务，审计失败则业务回滚。
-- 业务已回滚后的 `failed/denied` 审计使用独立短事务；二次失败保留原业务错误，并记录 critical 日志和指标。
-- Audit Event 至少记录稳定动作编码、操作者、来源、主要资源、前后数据、结果、风险及 request/correlation 标识；敏感值按统一 Sanitizer 删除或摘要化。
-- 新增或修改 PRD、Ticket 时必须明确 Audit Event、Domain Ledger、Integration Log、Outbox 的使用决定或 N/A 理由，并在最终发布门禁引用具体公共基础票。
-
----
-
-### ⚠️ 任务执行规范（必须遵守）
-
-**提案中的 tasks.md 是契约，不可擅自变更：**
-
-| 规则 | 说明 |
-|------|------|
-| ❌ 禁止跳过任务 | 每个任务都是经过规划的，不能因为"简单"或"显而易见"而跳过 |
-| ❌ 禁止简化任务 | 不能将多个任务合并或简化执行，除非获得明确许可 |
-| ❌ 禁止自作主张优化 | 发现可以优化的地方，必须先询问是否可以调整 |
-| ✅ 必须逐项完成 | 按照 tasks.md 中的顺序逐一执行并标记完成 |
-| ✅ 必须询问后变更 | 如需调整任务（简化/跳过/合并/优化），先询问用户确认 |
-
-**询问示例**：
-> "我注意到任务 2.1 和 2.2 可以合并为一步完成，是否可以这样优化？"
-> "任务 3.1 在当前实现中可能不需要，是否可以跳过？"
-
----
-
-## 测试代码规范（集成测试）
-
-以下规则专门适用于 `_test.go` 文件，与生产代码规范有局部差异：
-
-### 常量与魔法数字
-
-- 测试文件内的魔法数字（如 `0x7fffffff`）在文件顶部定义**局部常量**即可，不要求进 `pkg/constants/`：
-  ```go
-  // 文件顶部，仅限测试内使用
-  const testIDMask = 0x7fffffff
-  ```
-- 跨多个测试文件共用的常量或工具函数才提取到 `internal/testutil/`
-
-### 测试 Fixture Helper
-
-- `createXxxCard`、`createXxxPackage` 等 fixture 函数优先放 `internal/testutil/`
-- 同一 package 内 ≤3 处结构类似的 helper（如 ICCID 前缀不同）不强制提取，差异本身就是测试设计意图
-- 已在 `testutil` 中提供的能力（`NewPostgresTransaction`、`NewRedisClient`、`StringPointer`）必须复用，禁止本地重复定义
-
-### 数据库触发器操作
-
-- `ALTER TABLE ... DISABLE TRIGGER` 只允许在测试事务内使用（事务回滚后触发器状态自动恢复），必须加注释说明原因
-
-### HTTP 集成测试断言
-
-- 必须同时断言 **HTTP 响应体**和 **DB 状态**；Spec 承诺返回的字段不能只靠 DB 查询替代
-- 响应体断言至少验证所有 spec 要求的顶层字段非空或值正确，不必断言每个字段的精确中文名称
-
-### 层边界说明
-
-- 旧模块 `internal/service/xxx` 可以继续 import `internal/store/postgres`，这是项目触碰式迁移的既有模式
-- DDD 层边界禁令（禁止 import Fiber / GORM / Redis）**只对 `internal/domain/` 生效**，service 层不受此约束
-
----
-
-
-**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`
+- 先读本文件，再按任务进入架构地图、业务 Spec、工程规则或第三方契约。
+- 只加载当前用例需要的文件和调用链，不批量加载全部 Specs。
+- 从 Route/Task/Callback 追踪至 Handler/Consumer、Application/Service/Query、Domain 与持久化事实。
+- 规则缺口更新工程约束；行为变化新建 Change；不新增声明式 Skill。