重置项目上下文与规范文档

ARCHITECTURE.md

@@ -0,0 +1,149 @@
+# 系统架构地图
+
+## 系统职责与非职责
+
+本系统保存物联网卡、设备、套餐、订单、钱包、分佣、审批、通知和审计的本地业务事实，并协调支付、运营商、Gateway、企业微信、短信和对象存储。第三方内部状态、审批流配置、支付清算和运营商网络行为不是本系统事实；外部契约见 [`docs/integrations/`](docs/integrations/)。
+
+## Composition Roots 与运行单元
+
+| 单元 | 入口 | 启动链与外部依赖 | 验证 |
+| --- | --- | --- | --- |
+| HTTP API | `cmd/api/main.go` | Viper 配置 → 日志目录 → PostgreSQL → Redis/Asynq Client → JWT/验证码 → Storage/Gateway → `internal/bootstrap.Bootstrap` → Fiber 中间件与路由；启动时写 `logs/openapi.yaml` | `go build ./cmd/api`；启动后请求 `/health`、`/ready` |
+| Worker | `cmd/worker/main.go` | PostgreSQL、Redis、Storage、Gateway → `internal/bootstrap.BootstrapWorker` → Task Handler、Outbox Relay、任务救援；角色决定单例调度模块 | `go build ./cmd/worker`；从应用日志核对角色、模块和任务注册 |
+| OpenAPI 生成 | `cmd/gendocs/main.go` | 使用占位 Handler 复用 `internal/routes.RegisterRoutesWithDoc`，生成接口文档 | `go run cmd/gendocs/main.go`；它证明路由元数据，不单独证明真实 Bootstrap 可达性 |
+| 治理 CLI | `cmd/foundation-check`、`cmd/audit-coverage`、`cmd/migration-finalize`、`cmd/audit-retention-simulate` | 读取源码、迁移或数据库状态并输出门禁/模拟结果 | 逐命令检查输入；`audit-coverage` 当前仍依赖已删除路径，见工程约束 BLOCKED 项 |
+
+启动、隔离数据库、smoke 与日志命令见 [`README.md`](README.md)。
+
+## Worker 角色
+
+`pkg/config/config.go` 接受 `all`、`leader`、`consumer`：
+
+- 三种角色都启动 Asynq 消费服务、Outbox Relay 和未完成导入任务救援。
+- `leader` 与 `all` 额外启动轮询初始化器、轮询调度器和 Asynq Scheduler。
+- `consumer` 不运行单例调度模块，适合横向扩展消费能力。
+- 实际启停判断位于 `cmd/worker/main.go` 的 `buildWorkerModuleStatus` 与 `runsSingletonModules`。
+
+## HTTP 路由与信任边界
+
+总入口是 `internal/routes/routes.go`：
+
+| 路由域 | 认证/信任边界 | 主要入口 | 当前 Spec 索引 |
+| --- | --- | --- | --- |
+| `/health`、`/ready` | 公开，只返回进程健康/就绪状态 | `internal/routes/health.go` | `openspec/specs/operations-audit/spec.md` |
+| `/api/auth` | 后台账号登录、刷新、登出与当前身份；认证中间件在路由组装配 | `internal/routes/auth.go` | `openspec/specs/identity-access/spec.md` |
+| `/api/admin` | 后台认证、角色权限、店铺/企业数据范围；业务层仍需资源级校验 | `internal/routes/admin.go` | `identity-access`、`asset-device`、`package-lifecycle`、`order-payment-wallet`、`operations-audit` |
+| `/api/c/v1` | 个人客户 Token 与资产归属边界 | `internal/routes/personal.go` | `openspec/specs/personal-customer/spec.md` |
+| `/api/open/v1` | 代理 Open API 独立认证/签名，不复用后台账号权限 | `internal/routes/open.go` | `openspec/specs/agent-open-api/spec.md` |
+| `/api/callback` | 无登录认证；每类渠道必须在 Handler/Adapter 内验签、解密、校验金额或事件身份 | `internal/routes/order.go`、`wecom_callback.go` 及运营商回调注册 | `openspec/specs/external-integration/spec.md`、`order-payment-wallet` |
+
+HTTP 入参、回调 Body/Header、上传文件和代理签名材料均是不可信输入。Handler 只做绑定、边界校验与响应；状态和金额不变量必须由业务用例重新判断。
+
+## 分层与实际共存结构
+
+- `internal/routes`：可达 HTTP 入口与 RouteSpec。
+- `internal/handler`：Fiber 信任边界、参数绑定和统一响应。
+- `internal/application`：新用例编排、事务脚本、Port 和可靠副作用边界。
+- `internal/domain`：状态、金额与并发不变量；不依赖 Fiber、GORM、Redis、Asynq 或外部 SDK。
+- `internal/query`：只读权限、联表、分页和 DTO 投影。
+- `internal/service`：旧用例；允许直接使用 Store/GORM，按完整用例渐进迁移。
+- `internal/infrastructure`：Port Adapter、GORM Repository、Outbox、审计与外部交互。
+- `internal/store/postgres`、`internal/model`：旧持久化模型与显式查询。
+- `internal/bootstrap`：API/Worker 依赖装配，不承载业务规则。
+- `pkg`：跨模块基础能力和第三方客户端。
+- `migrations`：Schema 演进事实。
+
+允许方向：Handler → Application/Query/旧 Service；Application → Domain + Port；Infrastructure → Application/Domain Port；旧 Service → Store/GORM。禁止 Domain 依赖框架或基础设施、Query 修改状态、Handler 拼装领域规则、Infrastructure 定义业务状态机。
+
+```bash
+! grep -RIlE 'gofiber|gorm.io|go-redis|hibiken/asynq' internal/domain --include='*.go'
+```
+
+## 关键业务模块导航
+
+以下表是入口地图，不替代业务 Specs；事务与副作用必须按具体调用链证明。
+
+| 业务能力 | HTTP/异步入口 | 用例与领域 | 持久化/外部边界 | Spec |
+| --- | --- | --- | --- | --- |
+| 后台身份、账号、角色、权限、店铺 | `routes/auth.go`、`account.go`、`role.go`、`permission.go`、`shop.go` | `handler/auth|admin`；旧 `service/auth|account|role|permission|shop`；新 `application/role|shop|accessaudit|accountaudit` | `store/postgres`、RBAC 中间件、审计 Writer | [`identity-access`](openspec/specs/identity-access/spec.md) |
+| 卡、设备、资产与企业授权 | `iot_card.go`、`device.go`、`asset*.go`、`enterprise_card.go`、`enterprise_device.go`；导入/轮询任务 | 旧 `service/iot_card|device|asset|enterprise_*`；`application/cardobservation` → `domain/cardobservation`；读取 `query/asset` | GORM、Gateway、运营商、Outbox | [`asset-device`](openspec/specs/asset-device/spec.md) |
+| 套餐、系列、授权、订购与到期 | `package*.go`、批量分配/调价/订购路由；激活、到期和失效任务 | 旧 `service/package|package_series|shop_*`；`domain/package`；`application/packageexpiry` | GORM、Asynq、Outbox/通知 | [`package-lifecycle`](openspec/specs/package-lifecycle/spec.md) |
+| 订单、支付、充值、钱包、退款、分佣与换货 | `order.go`、`agent_recharge.go`、`refund.go`、`commission.go`、`exchange.go`、支付回调 | 旧 `service/order|recharge|refund|commission_*|exchange`；`application/agentrecharge|wallet|refundapproval|approval|exchange`；`domain/agentrecharge|wallet|approval` | GORM、支付 Adapter、企微、Outbox、审计/资金事实 | [`order-payment-wallet`](openspec/specs/order-payment-wallet/spec.md) |
+| 个人客户 | `routes/personal.go` 及 C 端子路由 | `handler/app`；`service/client_*|personal_customer|customer_binding`；通知 Application/Query | Token、资产绑定、钱包、支付、Gateway | [`personal-customer`](openspec/specs/personal-customer/spec.md) |
+| 代理 Open API | `routes/open.go` | `handler/openapi` → `service/agent_open_api` | 独立认证、店铺数据范围、卡/套餐/钱包 Store | [`agent-open-api`](openspec/specs/agent-open-api/spec.md) |
+| 轮询、通知、导出、配置与审计调查 | `polling_*.go`、`notification.go`、`export_task.go`、`system_config.go`、`audit.go`；Scheduler/Task/Outbox | `application/notification|systemconfig|auditarchive|outbox`；`query/audit|notification|outbox|systemconfig`；旧 polling/export Service | Asynq、Outbox、审计库、Integration Log、对象存储 | [`operations-audit`](openspec/specs/operations-audit/spec.md) |
+| 外部集成接点 | 支付/运营商/企微回调，Gateway 调用，对象存储、短信 | `internal/gateway`、`internal/infrastructure/wecom|payment|carriercallback|integrationlog`、`pkg/alipay|wechat|fuiou|sms|storage` | 第三方网络和凭证；协议事实见 integrations | [`external-integration`](openspec/specs/external-integration/spec.md) |
+
+任务 7 会把当前过大的 Spec 索引拆成完整业务能力；拆分后必须同步本表链接。
+
+## 同步数据流
+
+```text
+HTTP Route
+→ 认证/数据范围中间件
+→ Handler（绑定与信任边界）
+→ Application / Query / 旧 Service
+→ Domain（仅适用于已迁移复杂写）
+→ Repository / Store / GORM
+→ pkg/response 或全局 ErrorHandler
+```
+
+并非所有写操作都在统一事务中：旧 Service 可能直接写 Store，新 Application 可能使用事务脚本，复杂写可能通过 Domain + Port。审计、状态条件和事务范围必须从具体用例证明，不能由这张地图推断。
+
+## 异步与可靠事件
+
+### Asynq Task
+
+Worker 当前处理的任务族包括：卡/设备导入、导出分片与收尾、资产批量购包、订单套餐失效、自动充值后购包、佣金、订单过期、五类轮询、告警、数据/通知清理、套餐到期提醒、每日流量落盘、企微审批同步/恢复、代理充值恢复、审计/集成归档和 Outbox 投递。
+
+发现真实注册与生产位置：
+
+```bash
+rg -o 'constants\.TaskType[A-Za-z0-9_]+' cmd/worker/main.go internal/task internal/bootstrap/worker.go internal/infrastructure | sort -u
+```
+
+直接 `EnqueueTask` 只证明已提交，不等于业务终态成功；最终状态由 Task Handler 的条件更新、记录或补偿决定。
+
+### Outbox
+
+当前事件族覆盖审批提交/终态、卡实名/流量/网络/系列、代理充值支付确认、代理主钱包扣款/预留/入账/退款，以及后台/个人通知。
+
+```bash
+rg -o 'constants\.OutboxEventType[A-Za-z0-9_]+' cmd/worker/main.go internal | sort -u
+```
+
+需要业务事实与可靠异步副作用原子提交的用例应同事务写 Outbox；是否已经做到必须逐调用链核对。Relay 和消费者按至少一次投递设计，消费者必须容忍重复。
+
+## 外部调用与回调
+
+- 支付：创建本地支付事实后调用渠道；回调需要验签、金额/业务号/状态校验，重复回调不得重复入账。
+- 企业微信：本地审批实例 → Outbox 提交 → 渠道审批；加密回调、轮询和人工同步进入统一状态同步语义。
+- Gateway/运营商：查询与控制结果来自外部；超时或未知结果不得理想化为成功。
+- 对象存储：上传/预签名 URL 是外部副作用，数据库只保存对象引用。
+- SMS：发送结果是外部通知结果，不等同业务事务成功。
+
+外部网络调用不应持有长数据库事务；确需提交后可靠执行时使用 Outbox/Task。实际例外按 As-Is Spec 记录。
+
+## 事务、审计与日志边界
+
+- Access Log：HTTP 调试事实。
+- Audit Event：操作者、资源、动作、前后值和结果。
+- Domain Ledger/钱包交易：金额与状态领域事实。
+- Integration Log：外部调用尝试和脱敏结果。
+- Outbox：提交后可靠副作用，不替代前三者。
+
+成功高风险操作是否与审计同事务必须逐用例核对。业务已回滚后的 failed/denied 审计使用独立短事务。不得用 Access Log 证明资金或状态事实。
+
+## 结构与生成验证
+
+```bash
+go build ./cmd/api ./cmd/worker
+go run cmd/gendocs/main.go
+openspec doctor --json
+openspec validate --all
+./scripts/context-health.sh
+! grep -RIlE 'gofiber|gorm.io|go-redis|hibiken/asynq' internal/domain --include='*.go'
+rg 'Register[A-Za-z]*Routes|register[A-Za-z]*Routes' internal/routes
+```
+
+OpenAPI 生成器使用占位 Handler，因此还要对照 `internal/bootstrap` 与真实路由装配。Schema 事实以 `migrations/` 和隔离数据库为准，禁止使用 Makefile 中的历史连接信息。