95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
# 项目 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 可仅通过 dbhub 对生产数据库执行只读诊断查询；不连接生产主机，生产发布、迁移、回滚及其他写操作由维护者执行并提供结果,除非明确要求。
|
||
- 不把密钥、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`](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/<capability>/spec.md`。
|
||
- 后续变更：`openspec/changes/<change>/`。
|
||
- 使用官方 `openspec-propose`、`openspec-apply-change`、更新、同步和归档 Skills。
|
||
- Change 的 `tasks.md` 是执行契约；按顺序验证，调整前取得用户确认。
|
||
- Requirement 必须描述可观察行为，不能用接口目录代替状态、权限、金额、失败与幂等语义。
|
||
|
||
## 常用验证
|
||
|
||
```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
|
||
```
|
||
|
||
启动、隔离数据库重置、smoke 与日志读取见 [`README.md`](README.md)。迁移使用 `scripts/migrate.sh` 和显式 `DB_*` 参数；生产迁移仅按生产运行说明由维护者手工执行。
|
||
- 测试验证：涉及迁移、Redis、部署或集成 Smoke 时，MUST 读取 [`docs/engineering/工程约束.md`](docs/engineering/工程约束.md) 的 ENG-TEST-001；维护者指定的测试环境是唯一验证面。
|
||
|
||
## 渐进披露
|
||
|
||
- 先读本文件，再按任务进入架构地图、业务 Spec、工程规则或第三方契约。
|
||
- 只加载当前用例需要的文件和调用链，不批量加载全部 Specs。
|
||
- 从 Route/Task/Callback 追踪至 Handler/Consumer、Application/Service/Query、Domain 与持久化事实。
|
||
- 规则缺口更新工程约束；行为变化新建 Change；不新增声明式 Skill。
|