项目 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 为准。

事实源优先级

可复现运行结果。
实际可达代码与生效配置。
migrations/ 与数据库 Schema。
openspec/specs/ 当前行为契约。
ARCHITECTURE.md 系统地图与依赖边界。
docs/engineering/工程约束.md 长期工程规则。
docs/integrations/ 第三方契约。
本文件只承担硬约束和导航。

冲突时按上述顺序修正文档，不顺手改变当前行为。历史聊天、已删除文档和归档 Change 不是事实源。

受保护边界

不主动重构需求未触碰的旧模块。
行为变化必须通过独立 OpenSpec Change；主 Specs 只描述当前行为。
当前 Bug 与兼容行为按实际结果记录，禁止在基线任务中顺手修复。
不修改既有迁移；新 Schema 变化使用新的成对迁移。
不访问生产服务、真实支付渠道或外部审批系统进行自动验证。
生产环境为 systemd 管理的手工二进制发布，和仓库 Docker/CI 测试环境不同；生产发布、迁移与回滚事实见 docs/deployment/production-runbook.md。Agent 不连接生产主机或数据库，生产操作由维护者执行并提供结果。
不把密钥、Token、证书或个人敏感数据写入代码、文档和日志。
docs/verification/context-reset/ 仅保存上下文健康检查证据，不是业务事实源；证据应随项目文档维护。
自动化测试当前为 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。

工程与外部契约

工程规则只维护在 docs/engineering/工程约束.md。
新增 Handler 同步可执行路由、cmd/api/docs.go 与 cmd/gendocs/main.go。
Handler 将错误交给全局 ErrorHandler，响应使用 pkg/response。
第三方字段、签名、错误与重试依据 docs/integrations/；外部文档不证明本系统已实现对应行为。
Makefile 的历史数据库连接信息不得使用；迁移只连接明确指定的隔离环境。

OpenSpec 工作流

当前行为：openspec/specs/<capability>/spec.md。
后续变更：openspec/changes/<change>/。
使用官方 openspec-propose、openspec-apply-change、更新、同步和归档 Skills。
Change 的 tasks.md 是执行契约；按顺序验证，调整前取得用户确认。
Requirement 必须描述可观察行为，不能用接口目录代替状态、权限、金额、失败与幂等语义。

常用验证

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

启动、隔离数据库重置、smoke 与日志读取见 README.md。迁移使用 scripts/migrate.sh 和显式 DB_* 参数；生产迁移仅按生产运行说明由维护者手工执行。

渐进披露

先读本文件，再按任务进入架构地图、业务 Spec、工程规则或第三方契约。
只加载当前用例需要的文件和调用链，不批量加载全部 Specs。
从 Route/Task/Callback 追踪至 Handler/Consumer、Application/Service/Query、Domain 与持久化事实。
规则缺口更新工程约束；行为变化新建 Change；不新增声明式 Skill。

4.6 KiB Raw Blame History Unescape Escape