# 项目 Agent 导航 ## 项目目标 君鸿卡管系统管理物联网卡、设备、套餐、订单、钱包、分佣、审批与外部渠道协作；代码保存本地业务事实，第三方系统只提供外部能力。 ## 交流与文本 - 永远使用中文交流。 - 代码注释、文档、日志和用户可见错误使用中文。 - Go 标识符使用英文并遵循 Go 命名习惯。 - Git 提交信息使用中文；未经明确要求不提交。 ## 不可替代技术栈 - Go 1.25、Fiber v2、GORM、Viper。 - PostgreSQL、Redis、Asynq。 - Zap + Lumberjack、Validator、sonic。 - 不以 net/http 替代 Fiber，不绕过 GORM 使用 database/sql。 - 依赖及实际版本只以 `go.mod` 为准。 ## 事实源优先级 1. 可复现运行结果。 2. 实际可达代码与生效配置。 3. `migrations/` 与数据库 Schema。 4. `openspec/specs/` 当前行为契约。 5. `ARCHITECTURE.md` 系统地图与依赖边界。 6. `docs/engineering/工程约束.md` 长期工程规则。 7. `docs/integrations/` 第三方契约。 8. 本文件只承担硬约束和导航。 冲突时按上述顺序修正文档，不顺手改变当前行为。历史聊天、已删除文档和归档 Change 不是事实源。 ## 受保护边界 - 不主动重构需求未触碰的旧模块。 - 行为变化必须通过独立 OpenSpec Change；主 Specs 只描述当前行为。 - 当前 Bug 与兼容行为按实际结果记录，禁止在基线任务中顺手修复。 - 不修改既有迁移；新 Schema 变化使用新的成对迁移。 - 不访问生产服务、真实支付渠道或外部审批系统进行自动验证。 - 生产环境为 systemd 管理的手工二进制发布，和仓库 Docker/CI 测试环境不同；生产发布、迁移与回滚事实见 [`docs/deployment/production-runbook.md`](docs/deployment/production-runbook.md)。Agent 不连接生产主机或数据库，生产操作由维护者执行并提供结果。 - 不把密钥、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)。 ## 工程与外部契约 - 工程规则只维护在 [`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//spec.md`。 - 后续变更：`openspec/changes//`。 - 使用官方 `openspec-propose`、`openspec-apply-change`、更新、同步和归档 Skills。 - Change 的 `tasks.md` 是执行契约；按顺序验证，调整前取得用户确认。 - Requirement 必须描述可观察行为，不能用接口目录代替状态、权限、金额、失败与幂等语义。 ## 常用验证 ```bash gofmt -w go build ./cmd/api ./cmd/worker go run cmd/gendocs/main.go openspec doctor --json openspec validate --all ./scripts/context-health.sh ``` 启动、隔离数据库重置、smoke 与日志读取见 [`README.md`](README.md)。迁移使用 `scripts/migrate.sh` 和显式 `DB_*` 参数；生产迁移仅按生产运行说明由维护者手工执行。 ## 渐进披露 - 先读本文件，再按任务进入架构地图、业务 Spec、工程规则或第三方契约。 - 只加载当前用例需要的文件和调用链，不批量加载全部 Specs。 - 从 Route/Task/Callback 追踪至 Handler/Consumer、Application/Service/Query、Domain 与持久化事实。 - 规则缺口更新工程约束；行为变化新建 Change；不新增声明式 Skill。