# Codebase Structure

**Analysis Date:** 2026-03-27

## Directory Layout

```text
junhong_cmp_fiber/
├── cmd/                 # API、Worker、文档生成入口
├── internal/            # 核心业务代码（handler/service/store/model/routes/bootstrap/task）
├── pkg/                 # 可复用基础设施与跨模块工具
├── migrations/          # SQL 迁移脚本
├── docs/                # 业务文档、接入指南、架构说明
├── openspec/            # 当前能力规格与变更档案
├── specs/               # 早期 Speckit 规格文档
├── scripts/             # 检查与初始化脚本
├── docker/              # 部署相关辅助文件
├── logs/                # 运行期日志输出目录
└── .planning/codebase/  # 当前代码地图产物
```

## Directory Purposes

**`cmd/`:**
- Purpose: 进程级入口和独立命令。
- Contains: `cmd/api/main.go`, `cmd/api/docs.go`, `cmd/worker/main.go`, `cmd/gendocs/main.go`
- Key files: `cmd/api/main.go`, `cmd/worker/main.go`

**`internal/bootstrap/`:**
- Purpose: 依赖装配中心。
- Contains: API/Worker 的 stores、services、handlers、middlewares 初始化。
- Key files: `internal/bootstrap/bootstrap.go`, `internal/bootstrap/services.go`, `internal/bootstrap/worker.go`, `internal/bootstrap/types.go`

**`internal/routes/`:**
- Purpose: 路由域划分与 OpenAPI 绑定。
- Contains: 域入口 `admin.go`, `auth.go`, `personal.go` 以及各模块路由文件。
- Key files: `internal/routes/routes.go`, `internal/routes/registry.go`, `internal/routes/admin.go`, `internal/routes/personal.go`

**`internal/handler/`:**
- Purpose: HTTP Handler 层。
- Contains: `admin/`、`app/`、`auth/`、`callback/` 四个子域。
- Key files: `internal/handler/admin/account.go`, `internal/handler/auth/handler.go`, `internal/handler/callback/payment.go`

**`internal/service/`:**
- Purpose: 业务逻辑层。
- Contains: 按业务模块拆分的子目录，每个模块通常有一个 `service.go`。
- Key files: `internal/service/account/service.go`, `internal/service/order/service.go`, `internal/service/package/service.go`, `internal/service/polling/*.go`

**`internal/store/`:**
- Purpose: 数据访问层。
- Contains: 基础抽象 `store.go`、查询选项 `options.go`、以及 `postgres/` 下的具体实现。
- Key files: `internal/store/store.go`, `internal/store/options.go`, `internal/store/postgres/account_store.go`, `internal/store/postgres/order_store.go`

**`internal/model/`:**
- Purpose: 持久化模型与 DTO。
- Contains: 业务实体模型、基础模型、DTO 子目录。
- Key files: `internal/model/account.go`, `internal/model/order.go`, `internal/model/shop.go`, `internal/model/dto/account_dto.go`

**`internal/task/`:**
- Purpose: Asynq 任务处理逻辑。
- Contains: 轮询、导入、订单超时、邮件、佣金等任务处理器。
- Key files: `internal/task/polling_handler.go`, `internal/task/order_expire.go`, `internal/task/device_import.go`

**`internal/polling/`:**
- Purpose: 轮询调度器与专用运行时组件。
- Contains: `Scheduler`、激活处理器、流量重置处理器。
- Key files: `internal/polling/scheduler.go`

**`internal/gateway/`:**
- Purpose: 对外 Gateway HTTP 客户端封装。
- Contains: 请求签名、设备/卡查询与操作客户端。
- Key files: `internal/gateway/client.go`（由 `cmd/api/main.go`、`cmd/worker/main.go` 初始化）

**`pkg/`:**
- Purpose: 通用基础设施。
- Contains: 配置、数据库、日志、认证、错误、响应、OpenAPI、队列、对象存储、微信、短信、中间件辅助。
- Key files: `pkg/config/config.go`, `pkg/config/loader.go`, `pkg/database/postgres.go`, `pkg/middleware/auth.go`, `pkg/middleware/data_scope.go`, `pkg/openapi/generator.go`

**`migrations/`:**
- Purpose: 数据库结构演进。
- Contains: 成对的 `*.up.sql` / `*.down.sql` 与少量补数 SQL。
- Key files: `migrations/000000_create_legacy_tables.up.sql`, `migrations/000055_package_system_upgrade.up.sql`, `migrations/000088_rename_card_wallet_id_to_asset_wallet_id.up.sql`

**`docs/`:**
- Purpose: 面向开发和业务的说明文档。
- Contains: 功能总结、架构说明、接入指南、运维说明、第三方资料。
- Key files: `docs/api-documentation-guide.md`, `docs/auth-architecture.md`, `docs/polling-system/README.md`

**`openspec/`:**
- Purpose: 规范驱动开发资产。
- Contains: `config.yaml`、当前 specs、历史归档变更。
- Key files: `openspec/config.yaml`, `openspec/specs/**/spec.md`, `openspec/changes/archive/**`

## Key File Locations

**Entry Points:**
- `cmd/api/main.go`: API 服务主入口。
- `cmd/worker/main.go`: Worker 服务主入口。
- `cmd/gendocs/main.go`: 离线 OpenAPI 生成命令。

**Configuration:**
- `pkg/config/config.go`: 配置结构与校验规则。
- `pkg/config/loader.go`: 嵌入配置 + 环境变量覆盖加载。
- `openspec/config.yaml`: 规范生成器上下文与规则。

**Core Logic:**
- `internal/service/`: 所有业务服务主实现。
- `internal/store/postgres/`: 所有 PostgreSQL 访问实现。
- `internal/bootstrap/`: 依赖注入和装配。
- `internal/polling/scheduler.go`: 轮询核心调度逻辑。

**API Surface:**
- `internal/routes/`: 路由分组与注册。
- `internal/handler/admin/`, `internal/handler/app/`, `internal/handler/auth/`, `internal/handler/callback/`: 传输层处理器。

**Data Definitions:**
- `internal/model/*.go`: 表模型。
- `internal/model/dto/*.go`: 请求/响应 DTO。

**Documentation / Planning:**
- `docs/`: 功能文档。
- `openspec/specs/`: 现行规格。
- `openspec/changes/archive/`: 历史变更记录。

## Naming Conventions

**Files:**
- 模块按业务名命名：`internal/service/account/service.go`, `internal/handler/admin/account.go`
- 大部分 Store 文件采用 `{resource}_store.go`：`internal/store/postgres/account_store.go`
- DTO 文件采用 `{module}_dto.go`：`internal/model/dto/account_dto.go`
- 路由文件按模块命名：`internal/routes/account.go`, `internal/routes/polling_config.go`

**Directories:**
- 分层目录使用小写单数语义：`internal/service/`, `internal/store/`, `internal/model/`
- 传输域用子目录表达边界：`internal/handler/admin/`, `internal/handler/app/`, `internal/handler/callback/`
- 规格目录按能力名组织：`openspec/specs/account-management/`, `openspec/specs/order-payment/`

## Ownership / Responsibility Guide

**如果改接口路径或加新 API：**
- 先看 `internal/routes/registry.go` 与对应模块路由文件。
- 再同步检查 `docs/api-documentation-guide.md`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。

**如果改业务规则：**
- 主要落点在 `internal/service/{module}/service.go`。
- 如涉及跨模块，先看 `internal/bootstrap/services.go` 中该服务依赖谁。

**如果改查询或权限过滤：**
- 主要落点在 `internal/store/postgres/*.go`。
- 数据范围辅助逻辑集中在 `pkg/middleware/data_scope.go` 与 `pkg/middleware/permission_helper.go`。

**如果改表结构或模型：**
- SQL 先改 `migrations/`。
- Go 模型同步改 `internal/model/*.go`。
- DTO 变更再改 `internal/model/dto/*.go`。

**如果改异步任务：**
- 任务实现放 `internal/task/*.go`。
- 注册入口在 `pkg/queue/handler.go`。
- Worker 依赖拼装在 `internal/bootstrap/worker*.go`。

**如果改轮询系统：**
- 调度逻辑看 `internal/polling/scheduler.go`。
- 执行逻辑看 `internal/task/polling_handler.go`。
- 配置/监控/清理相关服务看 `internal/service/polling/*.go`。

## Where to Add New Code

**New Admin API Feature:**
- Primary code: `internal/handler/admin/{module}.go`, `internal/service/{module}/service.go`, `internal/store/postgres/{module}_store.go`, `internal/routes/{module}.go`
- Models / DTOs: `internal/model/{module}.go`, `internal/model/dto/{module}_dto.go`
- Wiring: `internal/bootstrap/services.go`, `internal/bootstrap/handlers.go`, `internal/bootstrap/types.go`, `internal/routes/admin.go`

**New Personal Client Feature:**
- Primary code: `internal/handler/app/{feature}.go`, `internal/service/{feature}/service.go` 或复用现有服务
- Routes: `internal/routes/personal.go`
- Auth-sensitive DTOs: `internal/model/dto/` 下新增对应 DTO 文件

**New Worker Task:**
- Implementation: `internal/task/{task_name}.go`
- Registration: `pkg/queue/handler.go`
- Dependencies: `internal/bootstrap/worker_services.go` 或 `internal/bootstrap/worker_stores.go`
- Constants: `pkg/constants/` 中对应任务类型定义

**New Shared Utility:**
- Shared helpers: `pkg/{subsystem}/`
- 仅限跨多个业务模块复用的基础能力，不要把业务逻辑塞进 `pkg/`

**New Business Spec / Plan Artifact:**
- Current capability spec: `openspec/specs/{capability}/spec.md`
- Historical change proposal: `openspec/changes/...`
- Developer-facing long-form doc: `docs/{feature-id}/` 或现有专题目录

## Practical Navigation Guide

**从请求入口追代码：**
1. 在 `internal/routes/*.go` 找路径。
2. 跳到对应 `internal/handler/...` 方法。
3. 看该 Handler 注入了哪个 Service。
4. 到 `internal/service/...` 看业务编排。
5. 再进入 `internal/store/postgres/...` 看 SQL 过滤与分页。
6. 最后回到 `internal/model/` / `internal/model/dto/` 看字段定义。

**从一个模块反查装配方式：**
1. 先找 `internal/bootstrap/services.go` 是否实例化该 Service。
2. 再看 `internal/bootstrap/handlers.go` 是否把它交给 Handler。
3. 再看 `internal/routes/admin.go` 或 `internal/routes/personal.go` 是否挂载了该模块。

**从一个异步任务反查来源：**
1. 看 `pkg/queue/handler.go` 的 `registerXxxHandler()`。
2. 跳到 `internal/task/{task}.go`。
3. 若任务由调度器触发，再看 `internal/polling/scheduler.go` 或 `cmd/worker/main.go` 的 Asynq Scheduler 注册。

## Special Directories

**`logs/`:**
- Purpose: 运行日志输出目录。
- Generated: Yes
- Committed: No（运行期产物）

**`migrations/`:**
- Purpose: 数据库迁移脚本。
- Generated: No
- Committed: Yes

**`docs/第三方文档/`:**
- Purpose: 外部供应商或接口资料归档。
- Generated: No
- Committed: Yes

**`openspec/changes/archive/`:**
- Purpose: 已归档历史变更。
- Generated: No
- Committed: Yes

**`.planning/codebase/`:**
- Purpose: 供规划/执行命令消费的代码地图文档。
- Generated: Yes
- Committed: Yes

## Structural Notes for Contributors

- 这个仓库的“物理结构”严格围绕 Go 后端单体展开；新增代码优先放进现有层级，不要新造平行架构。
- `internal/bootstrap/handlers.go` 当前会为客户端能力额外 new 一批 Store，这意味着某些接口不是纯 Service 注入；新增客户端功能前先确认是否要复用现有 `services` 聚合，还是遵循当前适配方式。
- OpenAPI 不是完全自动发现；新增 Handler、Route 之后，必须同步维护 `internal/bootstrap/types.go`、`internal/bootstrap/handlers.go`、`internal/routes/*.go`、`cmd/api/docs.go`、`cmd/gendocs/main.go`、`pkg/openapi/handlers.go`。
- 数据权限过滤不在统一 GORM 查询回调中自动生效；新增 Store 查询时，要主动选对 `ApplyShopFilter`、`ApplyEnterpriseFilter`、`ApplySellerShopFilter`、`ApplyOwnerShopFilter` 等函数。

---

*Structure analysis: 2026-03-27*