# 前置开通清单：云资源与资质（个人开发者版 v2）

> 创建日期：2026-08-14 ｜ **v2 修订：2026-08-15（需求变更：个人开发者主体降级路线）**
>
> **v2 变更原因**：App 为个人开发，腾讯云短信签名需要企业/个人主体资质材料，办不下来；前期用户量小，COS 对象存储暂无必要。整体策略从"腾讯云全家桶"降级为"**华为 AGC + 一个发信邮箱**"，其余全部本机/本地承载。
>
> **v2 三项需求变更**：
> 1. **登录兜底通道：短信验证码 → 邮箱验证码**（个人邮箱 SMTP 授权码即可，零成本、零审核）
> 2. **主登录通道维持华为账号登录**（已查证：个人开发者可用"标准登录"，见 §1）
> 3. **对象存储：COS 四桶 → 服务器本地磁盘**（文件存后端 data 目录，后端生成访问 URL）
>
> **数据库说明**（原清单本就不含云数据库）：PostgreSQL 16 已运行在 WSL 内，零云依赖、零费用，**无需任何动作**。不切 SQLite 的理由见 §4。

---

## 0. 总览：现在真正要办的外部事项只剩两件

| # | 事项 | 成本 | 审核周期 | 状态 |
| --- | --- | --- | --- | --- |
| A | 华为开发者账号 + AGC 创建应用 + 开通 Account Kit | 免费 | 实名认证 1~3 天 | ⬜ |
| B | 一个发信邮箱的 SMTP 授权码（QQ/163/Gmail 均可） | 免费 | 即时（5 分钟） | ⬜ |

**已从清单移除**（原 v1 的 §1、§2 整节）：腾讯云账号/实名/短信套餐包/短信签名/验证码模板/CAM 子账号/COS 四桶 —— 全部后移到"有真实用户量、需要公网部署"时再评估（见 §5）。

---

## 1. 华为开发者后台 + Account Kit 🔴 主登录通道（唯一必办外部事项）

**对应**：`T-P1-12/13`（华为账号登录）、用户系统 §2.1。

**个人开发者可用性结论（2026-08 查证）**：Account Kit 权限分级——

| 能力 | 个人开发者 |
| --- | --- |
| **华为账号标准登录**（获取 UnionID / 昵称 / 头像） | ✅ 可用 |
| 静默登录（自动授权） | ✅ 可用 |
| 一键登录（获取手机号）+ UnionID | ❌ 仅企业 |
| 获取收货地址等高级权限 | ❌ 仅企业 |

我们只需要 UnionID 做账号映射（`id_user_identity`，后端 `packages/identity/huawei.py` 已实现），**标准登录完全够用，不需要手机号**。

| # | 事项 | 要点 | 完成 |
| --- | --- | --- | :---: |
| 1.1 | 注册华为开发者账号（个人类型） | 身份证实名认证；审核 1~3 天 | ⬜ |
| 1.2 | AGC 创建应用 | 包名用最终包名 `com.xiangsilian.app`（上架后难改）；拿到 App ID | ⬜ |
| 1.3 | 开通 Account Kit | AGC「我的项目 → 添加服务」，选华为账号（标准登录即可，**不要**申请"获取手机号"权限——那是企业专属，申请必拒） | ⬜ |
| 1.4 | **证书指纹录入** | 调试证书 SHA256 必须配到 AGC（DevEco Studio 自动签名后，在 AGC「应用信息 → 证书指纹」处粘贴），否则真机拉不起授权页 | ⬜ |
| 1.5 | 发布证书指纹 | 上架时再办（发布证书申请时一并录入 AGC）——**注意漏配的表现是"调试包登录正常、发布包登录失败"** | ⬜ 后置 |
| 1.6 | Push Kit | 继续后置（通知授权默认关闭，`TD-17`），联调期再开 | ⬜ 后置 |

**验收**：用调试证书签名的 App 能拉起华为授权登录页，授权后拿到 UnionID 并映射到 `id_user_identity`。

---

## 2. 邮箱验证码（兜底登录通道，替代原短信方案）🟡 5 分钟办完

**对应**：`T-P1-12b/12c` 需求改写（原短信任务 → 邮箱任务）、`FR-ACC-14`。

**方案**：任一个人邮箱开启 SMTP 服务拿"授权码"，后端用它发验证码邮件。

| # | 事项 | 要点 | 完成 |
| --- | --- | --- | :---: |
| 2.1 | 选一个发信邮箱 | 推荐 QQ 邮箱或 163（国内到达率高、授权码机制成熟）；Gmail 也行但国内服务器投递慢 | ⬜ |
| 2.2 | 开启 SMTP 拿授权码 | QQ：设置 → 账号 → 开启 SMTP 服务 → 生成授权码；163 同理 | ⬜ |
| 2.3 | 授权码落位 | **只写后端仓库 `.env`**（已 gitignore）：`SMTP_HOST` / `SMTP_PORT(465)` / `SMTP_USER` / `SMTP_PASS`（授权码）/ `MAIL_FROM` | ⬜ |

**量级评估**：个人邮箱 SMTP 每日发信上限约百封级（QQ/163），验证码场景（每用户登录 1~2 封）前期绰绰有余；日发信超限或到达率不稳时，再换免费档邮件 API（Resend/SendGrid/阿里邮件推送），代码侧只是换一个 `EmailSender` 实现。

**防刷参数不变**（`FR-ACC-14` 原样沿用，键前缀从 `sms:` 改 `email:`）：同邮箱 60s 内 1 条、1 小时 ≤5、24h ≤10；同 IP 24h ≤20；同设备 24h ≤10。

**验收**：后端 `.env` 配好后，向自己的另一个邮箱发一封验证码邮件，能收到。

---

## 3. 文件存储：服务器本地磁盘（替代 COS 四桶）—— 无需办理，代码侧改造

**方案**：四桶变四个本地目录，上传走后端、下载 URL 由后端签发：

```
/home/xsl/meida_data/
├── temp/     # 用户原图：2 小时定时清理（CR-02，celery beat 已有 io 队列可挂）
├── user/     # 用户内容
├── kb/       # 知识素材（白底图等）
└── report/   # 报告产物（长图等）
```

- **上传**：客户端 `POST /api/v1/storage/upload`（multipart，带鉴权）——不再"直传+预签名"，应用服务器中转；前期流量小，无压力
- **下载**：后端签发短期带签名 URL（复用现有 `CosSigner` Protocol 的位置换 `LocalStorageDriver` 实现，业务代码零改动）
- **回迁路径**：`CosSigner` Protocol 保留，未来用户量上来切回 COS 只需换实现 + 搬数据，业务代码不动

**v1 骨架不受影响**：FE 当前照片键本来就是模拟的（`report_photo/{userId}/{随机}.jpg`），本地驱动下这些键直接对应 `meida_data/` 下的文件路径，行为一致。

---

## 4. 数据库：无需任何动作（且不建议切 SQLite）

- PostgreSQL 16 + pgvector **已经在 WSL 内运行**，承载全部迁移（0001~0006）与 32 维检索，零云依赖、零费用
- **不切 SQLite**：检索域（`packages/retrieval`）依赖 pgvector 做向量近邻搜索，SQLite 无等价物——切换等于大重构 + 检索能力回退成暴力扫描；而本机 PG 不产生任何费用，切了没有任何收益
- 真要减负的时机是公网部署时：CVM 自托管 PG 或云数据库，到时再议

---

## 5. 移除/后移项汇总（对照 v1）

| 原 v1 清单项 | 处置 | 理由 |
| --- | --- | --- |
| 腾讯云账号 + 实名认证 | **移除** | 随短信/COS 整体暂缓 |
| 短信套餐包 / 签名 / 模板 | **移除，需求变更为邮箱验证码**（§2） | 个人主体办不下签名 |
| 子账号 + CAM 最小授权 | 后移 Phase 5 | 腾讯云暂缓后无对象可授权 |
| COS 四桶 + temp 桶 2 小时生命周期实测 | **后移，需求变更为本地磁盘**（§3） | 前期用户量小；2 小时清理改 celery 定时任务 |
| AGC 应用 / 证书指纹 / Account Kit | **保留**（§1，唯一必办） | 华为账号是主登录通道 |
| Push Kit | 保留后置 | 不变 |

---

## 6. 需求变更引发的代码任务（后续排期，不在本清单内办）

| 任务 | 内容 | 影响面 |
| --- | --- | --- |
| E1 后端：邮箱登录 | `sms_login.py` → `email_login.py`：`SmsSender` Protocol → `EmailSender`（SMTP 实现 + `FakeEmailSender`）；手机号正则 → 邮箱正则；`union_id` 前缀 `"phone:"` → `"email:"`；Redis 键 `sms:*` → `email:*`；路由与错误码文案同步 | `packages/identity`，设计上零耦合华为通道，改动封闭 |
| E2 后端：本地存储驱动 | `QcloudCosSigner` → `LocalStorageDriver`（同 Protocol）；新增 multipart 上传端点；temp 目录 2 小时清理任务挂 celery beat | `packages/storage` |
| E3 FE：登录页邮箱输入 | 登录页手机号输入框 → 邮箱输入框 + 验证码（当前 FE 只有 dev-token 调试登录，正式登录 UI 本就是待办） | `pages/LoginPage` |
| E4 文档同步 | Sprint 执行计划 v1.1 / 开发任务拆解 v1.5 中 `T-P1-12b/12c`（短信）、`T-P1-04/27`（COS）的任务表述按本变更改写 | `docs/` |

---

## 办理顺序与完成标志

```
今天 ：2.1 → 2.2 → 2.3（邮箱授权码，5 分钟）
今天 ：1.1（华为开发者注册提交，等审核 1~3 天）
审核通过后：1.2 → 1.3 → 1.4（AGC 应用 + Account Kit + 调试指纹）
```

**整体完成标志**（两条全绿即本清单关闭）：
- [ ] 调试证书 App 拉起华为授权页，拿到 UnionID
- [ ] 测试邮箱收到验证码邮件

---

## 附：办理记录（办理时填写）

| 日期 | 事项 | 结果 / 备注 |
| --- | --- | --- |
| 2026-08-15 | 1.2 AGC 创建应用 | ✅ App ID `6917613748100335131`，包名 `com.xiangsilian.app`（与工程 `AppScope/app.json5` 核对一致）。App ID 无需写入代码，登记备查（后续接 Push Kit 时才用于 module.json5 的 client_id 配置） |
| 2026-08-15 | 工程签名现状核查 | ⚠️ `build-profile.json5` 的 signingConfigs 为空（从未做过 IDE 自动签名，CLI 构建均为 unsigned 包）。**开通 Account Kit 前必须先做自动签名**：DevEco Studio → File → Project Structure → Signing Configs → 勾选 Automatically generate signature（需登录华为开发者账号）→ 生成调试证书后提取 SHA256 指纹录入 AGC |
| | | |