docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04

2026-03-28 10:46:10 +08:00
parent 754bbcdf3b
commit e1ec024904
18 changed files with 5548 additions and 28 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,250 @@
+# 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*