update

openspec/changes/add-phone-asset-associations/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/add-phone-asset-associations/design.md

@@ -0,0 +1,32 @@
+## Context
+
+现有 H5 已有手机号绑定与全局开关；新关系不能由后台或换货推测建立。
+
+## Decisions
+
+- 新表以手机号、资产和有效状态保存关系，并对当前有效关系实施十项计数与唯一约束。
+- 验证/换绑在事务内锁定相关手机号关系；换绑先检查总数再整体迁移。
+- 批量导入复用逐行任务，读取按资产数据范围，日志仅保留脱敏手机号。
+
+## H5 与后台动作契约
+
+### H5 建联与换绑
+
+- 既有登录签发 token 时，按全局强制绑定开关及当前访问资产查询有效关联；开关开启且当前手机号未关联该资产时，响应 `need_bind_phone=true`，并限制依赖该资产的业务入口直至验证成功。开关关闭时不创建新关联，也不删除历史关联。
+- 既有 `bind_phone` 短信场景验证成功后，事务中锁定手机号和资产有效关系；同一手机号—资产已有效关联则幂等成功，否则先计算该手机号有效资产数。达到十项返回“该手机号最多关联10项有效资产”，不写关联或手机号变更。
+- 既有 `change_phone_old`、`change_phone_new` 两个验证码均验证成功后，事务锁定旧、新手机号关系；计算新号码当前有效关系数加旧号码待迁移有效关系数，超过十项则整体失败。通过时把旧号码全部有效关系原子失效/迁移至新号码，并记录旧、新号码脱敏审计；任一步失败不变更任一关系。
+
+### 后台查看与解除
+
+- `GET /phone-asset-associations`：仅超级管理员、平台用户，先按资产数据范围过滤；支持资产标识、手机号（仅权限内完整值）、关联状态、创建时间筛选，返回资产、手机号、建立时间、建立来源固定为 `h5_sms_verification` 和状态。
+- `DELETE /phone-asset-associations/:id`：请求必须含 `reason`（1～500 字符）和二次确认；锁定指定有效关联后复核资产数据范围，标记失效并审计操作者、资产、脱敏手机号、原因和时间。后台没有创建/补录接口。
+- `POST /phone-asset-associations/batch-unbind`：请求去重的资产集合、原因、二次确认；每个资产独立解除其全部有效关系，返回成功数、失败数与逐资产结果。越权、资产不存在和已无有效关系对调用方使用统一失败文案。
+- Excel 解绑复用既有异步导入：每行按资产标识处理，独立授权与事务，任务持久化行号、结果和失败原因；一行失败不得回滚已成功行。
+
+### 边界
+
+- 换货、资产导入、后台资产编辑和个人客户主手机号历史记录均不得创建、推断、复制或迁移该关系。新换货资产在首次 H5 访问时才依当前开关走验证。
+
+## Migration Plan
+
+新增成对迁移，不回填；隔离库验证开关、上限、换绑、权限解绑、换货边界及 up/down/up。

openspec/changes/add-phone-asset-associations/proposal.md

@@ -0,0 +1,25 @@
+## Scope
+
+- 迭代编号：`AUG26-009`。
+
+## Why
+
+现有全局绑定不能保留手机号与资产的验证关系，也无法安全支持按资产解除。
+
+## What Changes
+
+- 新增 H5 验证建立的手机号—资产关联及十项上限。
+- 新增客户原子换绑和后台受权限控制的单项/批量/Excel 解绑。
+- 保持全局强制绑定，换货不迁移关系，不回填历史。
+
+## Capabilities
+
+### New Capabilities
+- `phone-asset-association`: 已验证手机号与资产关联。
+
+### Modified Capabilities
+- 无。
+
+## Impact
+
+影响 H5 认证、资产查询、短信、导入、审计和 Schema。

openspec/changes/add-phone-asset-associations/specs/phone-asset-association/spec.md

@@ -0,0 +1,21 @@
+## Purpose
+
+保存仅由 H5 短信验证建立的手机号—资产当前有效关系，使全局强制绑定能逐资产执行，同时提供受资产数据范围控制的后台查看与解除能力。
+
+## ADDED Requirements
+
+### Requirement: H5 验证建立关联与数量上限
+系统 SHALL 保留既有全局 H5 强制绑定开关。开关开启时，客户首次登录一项未关联当前手机号的资产必须完成短信验证后建立关系；已关联资产不重复验证。开关关闭时登录不要求验证且不新增关系，已有关系保留。关联只能由 H5 验证建立，单手机号最多关联十项当前有效资产；上线不回填历史客户—资产关系。
+
+#### Scenario: 第十一项资产验证
+- **WHEN** 已关联十项有效资产的手机号验证另一项资产
+- **THEN** 系统拒绝本次新关联，已有十项关系不变
+
+### Requirement: 换绑、查看和解绑
+客户更换手机号时 MUST 同时验证旧、新号码，并原子将旧手机号全部有效资产关系迁至新号码；新号码现有关联数加迁移数超过十项时整次失败。后台仅超级管理员和平台用户可在资产数据范围内查看完整关联手机号、单项解绑、勾选批量解绑及 Excel 解绑；后台不得补录。
+
+单项解绑必须指定一条资产—手机号关系。批量和 Excel 按资产解除该资产全部当前有效手机号关系，必须二次确认、填写原因、逐条审计；逐资产独立执行，返回成功数、失败数和统一越权失败文案。换货不得迁移该关系，新资产首次访问仍按全局开关验证。
+
+#### Scenario: 换绑超过上限
+- **WHEN** 客户换绑后新手机号关联总数将超过十项
+- **THEN** 系统不迁移任何关系且旧、新手机号关系均保持原状

openspec/changes/add-phone-asset-associations/tasks.md

@@ -0,0 +1,12 @@
+## 1. 关联与 H5
+- [ ] 1.1 追踪 H5 登录/短信验证、客户换绑、资产数据范围和换货调用链。
+- [ ] 1.2 新增关联表、有效关系唯一/计数索引的成对迁移、模型和审计常量。
+- [ ] 1.3 实现全局开关下的验证建联、十项限制和原子换绑。
+
+## 2. 后台解绑
+- [ ] 2.1 实现资产详情/列表完整手机号投影、单项解绑、二次确认批量和逐行 Excel 解绑及统一越权结果。
+- [ ] 2.2 保持换货不迁移，补齐路由和 OpenAPI。
+
+## 3. 验证
+- [ ] 3.1 隔离库验证上限、换绑回滚、权限、批量部分成功、换货边界和 up/down/up。
+- [ ] 3.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-phone-asset-associations --strict` 与 `openspec doctor --json`；自动化测试按项目决策为 N/A。