docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,79 @@
+# 05 店铺中心
+
+## 模块职责
+
+将店铺密钥、店铺账号、最低价配置和店铺相关基础操作组织为店铺中心。最低价 ASIN 的复杂数据操作在 `04-asin-data-center.md` 定义，本文件只描述店铺侧入口和基础店铺管理边界。
+
+覆盖页面：
+
+- 店铺密钥：`shop-keys`
+- 店铺管理：`shop-manage`
+- 店铺分组选择器和店铺账号编辑
+- 店铺凭证展示、遮罩和安全操作
+
+## 依赖关系
+
+上游：菜单树和用户权限；Java 店铺控制器；分组/用户选择器；下载和 confirm 基础组件。
+
+旧实现：
+
+- `admin.html` 的 `panel-shop-keys`、`panel-shop-manage`。
+- `admin.js:loadShopKeys`、`loadShopManage`、`loadShopManageGroups`、`renderShopPasswordCell`、`bindShopKeyActions`、`bindShopManageActions`。
+
+Java API 主要来源：
+
+- `ShopKeyController`：`/api/admin/shop-keys`、`/api/admin/shop-key`。
+- `ShopManageController`：`/api/admin/shop-manages`、`/api/admin/shop-manage`、凭证和分组接口。
+
+## 核心接口：原实现 → 目标实现
+
+| 功能 | 原实现 | 目标实现 |
+|---|---|---|
+| 店铺密钥列表 | `admin.js:loadShopKeys` | `ShopKeysPage.vue` + `/api/admin/shop-keys` |
+| 新增/编辑密钥 | 原生 modal + DOM 表单 | Element Plus Dialog + `/api/admin/shop-key` |
+| 店铺列表 | `admin.js:loadShopManage` | `ShopManagePage.vue` + `/api/admin/shop-manages` |
+| 店铺新增/编辑/删除 | DOM modal、手写确认 | Dialog/Drawer + `/api/admin/shop-manage` |
+| 店铺凭证 | `renderShopPasswordCell` | 显式遮罩组件，按需显示 |
+| 店铺分组 | 旧多处 select 和自定义下拉 | 可复用 `ShopGroupSelect`，数据来源统一 |
+
+## 内部结构
+
+```text
+ShopCenter
+├── ShopKeysPage
+│   ├── FilterBar
+│   ├── KeysTable
+│   └── KeyEditorDialog
+└── ShopManagePage
+    ├── FilterBar
+    ├── ShopsTable
+    ├── ShopEditorDrawer
+    ├── ShopGroupSelect
+    └── CredentialReveal
+```
+
+敏感字段生命周期：
+
+1. 默认以遮罩或掩码展示。
+2. 用户主动点击后才显示短时内容。
+3. 不写入 Pinia、localStorage、URL 或日志。
+4. API 返回失败或离开页面时清理临时明文。
+
+## 类型映射
+
+| 原字段 | 目标类型/规则 |
+|---|---|
+| `shop_name`、`mall_name` | `ShopSummary` |
+| `zn_username`、账号、密码 | `ShopCredential`，敏感字段分离 |
+| `group_id` | `number | null`，统一转成表单值 |
+| 紫鸟令牌/密钥 | `SensitiveString`，禁止进入通用日志 |
+| 店铺分页响应 | `PaginatedResult<ShopSummary>` |
+
+## 迁移/实现注意事项
+
+1. 页面级权限只决定是否显示和进入店铺中心，不新增“查看密码”“编辑店铺”等按钮权限模型。
+2. 后端现有角色和数据权限校验必须保持；前端隐藏按钮不是安全措施。
+3. 编辑店铺和店铺密钥的表单不能共用一个无类型的大对象，避免提交多余字段。
+4. 删除、重置密钥、覆盖账号等不可逆操作必须使用明确的确认文案。
+5. 分组数据加载应有缓存但必须有失效机制；页面切换不应重复创建无限轮询或请求。
+6. 店铺凭证不能出现在错误消息、网络日志、埋点和前端异常上报中。