=== Artiststore ===
Contributors: seven
Tags: woocommerce, artiststore, ecommerce, integration
Requires at least: 5.8
Tested up to: 7.0
Stable tag: 1.1.1
Requires PHP: 7.4
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

一键将 WooCommerce 店铺连接到 Artiststore 平台，完成授权后由平台侧同步商品、订单与发货等能力（具体以 Artiststore 服务为准）。

---

## 说明（Description）

Artiststore 是面向商家的 SaaS 平台；本插件在您的 **WordPress + WooCommerce** 站点与 **Artiststore 商家后台** 之间建立安全连接：

- 使用 WooCommerce 官方 `wc-auth` 授权流程获取 API 凭据；
- 连接成功后，平台可通过约定接口与您的店铺协同（商品、订单、发货状态等，以平台实际功能为准）；
- 在 WordPress 后台展示连接状态，并支持一键断开连接。

**适用场景**：已在 Artiststore 开通服务、需要在独立 WooCommerce 网店与平台之间完成店铺绑定的商家。

### 主要功能

- **OAuth 式连接**：从本站跳转至 Artiststore 商家后台，再经 WooCommerce 授权页完成授权，无需在插件内手动粘贴密钥（首次连接由平台回调写入凭据）。
- **状态可视**：后台菜单「Artiststore」中显示「已连接 / 未连接」及 WooCommerce 是否已启用。
- **安全断开**：断开时向平台请求作废密钥（尽力而为）；远端成功则清除本地保存的连接信息。
- **轻量实现**：仅处理授权与连接状态，不修改主题、不注入结账页脚本。
- **国际化（i18n）**：后台界面文案支持翻译；默认英文，内置简体中文语言包（`languages/`），随 WordPress 站点语言自动切换。

### 国际化与语言

- **文本域**：`artiststore`（见 `artiststore.php` 中 `Text Domain` / `Domain Path`）。
- **默认语言**：源码中界面字符串为英文；未安装对应语言包时显示英文。
- **内置语言包**：`languages/artiststore-zh_CN.po` / `.mo`（简体中文）。在 **设置 → 常规 → 站点语言** 选择「简体中文」后，后台 **Artiststore** 菜单页、连接状态、按钮与提示等将显示中文。
- **扩展翻译**：复制 `languages/artiststore.pot` 为 `artiststore-{locale}.po`，翻译后执行 `php languages/compile-mo.php` 生成 `.mo`；打包时 `build.sh` 也会自动编译语言文件。

### 数据存储与隐私（摘要）

- 插件将连接相关设置保存在 WordPress 选项 `artiststore_settings` 中（如连接状态、平台下发的标识与密钥、握手用随机串等）。
- 点击「连接」时，会向 Artiststore 商家后台 URL 传递站点标题、店铺地址、WooCommerce 与插件版本等**连接所必需的参数**（详见开发者文档）。
- 卸载插件时，若通过 WordPress 正常卸载流程执行，会删除上述选项（见 `uninstall.php`）。具体业务数据（平台上的订单、商品等）的保留策略以 Artiststore 服务条款与后台说明为准。

### 支持与文档

- 官网与插件页：<https://www.artiststore.com/plugin/wc>
- 接口与集成细节：插件内 [`includes/docs.md`](includes/docs.md)

---

## 安装（Installation）

1. 将插件文件夹上传到 `/wp-content/plugins/`，或通过 WordPress 后台「插件 → 安装插件」上传 ZIP。
2. 在「插件」列表中启用 **Artiststore**。
3. **必须先**安装并启用 **WooCommerce**（建议启用后再打开本插件页面，以免在未就绪环境下发起连接）。
4. 进入左侧菜单 **Artiststore**（商店图标），在 **未连接** 状态下点击 **「连接到 Artiststore」**。
5. 按浏览器跳转完成 Artiststore 与 WooCommerce 授权；返回后若显示 **已连接** 即表示绑定成功。
6. 需要解除绑定时，在同一页面点击 **「断开连接」** 并确认。

---

## 使用（Usage）

### 后台入口

- 路径：**WordPress 后台 → Artiststore**（顶层菜单，约在第 80 顺位，需 `manage_options` 权限）。
- 若未启用 WooCommerce，页面会显示警告提示；请先启用 WooCommerce 后再进行连接。

### 连接流程（商户视角）

1. 确认 WooCommerce 已启用，站点地址（**设置 → 常规**）中的「站点地址」「WordPress 地址」正确，且建议使用 HTTPS。
2. 打开 **Artiststore** 页面，点击 **「连接到 Artiststore」**，将跳转至 Artiststore 商家后台连接流程。
3. 在后续页面中按提示完成 WooCommerce 授权（同意应用访问店铺数据等）。
4. 授权完成后，Artiststore 服务端会通过本站 REST API 将结果写回插件；页面刷新或再次进入应显示 **已连接**。

### 断开与重连

- **断开**：点击 **「断开连接」**；若远端撤销失败，界面可能提示稍后重试。
- **重连**：断开后再次点击 **「连接到 Artiststore」** 即可重新走授权流程（若平台策略要求，以 Artiststore 后台说明为准）。

### 与缓存 / 安全插件

- 若连接异常，可暂时排除对 `/wp-json/` 或 `artiststore/v1` 路径的拦截，或将本站域名加入 Artiststore 侧允许列表（若平台提供该配置）。

---

## 环境与适配（Requirements）

使用前请确认环境满足下列要求：

- **WordPress** 5.8 或更高版本
- **PHP** 7.4 或更高版本
- **WooCommerce** 必须已安装并**启用**（本插件声明依赖 WooCommerce；请先完成 WooCommerce 安装与启用，再使用本插件进行连接）
- 具备 **管理站点选项** 的权限（通常为管理员，`manage_options`）
- 服务器或站点需允许 **出站 HTTPS** 访问 Artiststore 商家后台与 API 域名（用于跳转授权与断开时通知平台）
- WordPress **REST API** 应对外可用（默认开启）；若使用安全类、防火墙或 CDN 规则，请避免拦截 `POST /wp-json/artiststore/v1/connect`、`POST /wp-json/artiststore/v1/disconnect` 等与连接相关的请求

### 适配范围说明

- 本插件**不依赖**特定主题、结账方式或订单存储方式（如 HPOS），亦不直接操作前台结账界面。
- **WooCommerce 版本**：连接依赖 WooCommerce 自带的授权与 REST 能力；未在插件头信息中写死最低 WC 版本。请在目标环境中完成一次完整连接测试；生产环境以贵司与 Artiststore 后端约定的兼容版本为准。
- **Multisite（多站点）**：连接信息按**子站**存储；网络部署时请逐站安装、连接并验证跳转域名与回调地址。
- **暂存 / 克隆站点**：复制数据库后的站点可能仍含旧连接信息；建议在测试环境先 **断开连接** 或清空选项，避免与生产店铺冲突。

### 分发包说明

若您使用的是开发者提供的定制包，请确认 `includes/Options.php` 中的商家后台地址（`BUSINESS_BASE`）、连接路径（`CONNECT_PATH`）与 API 地址（`API_URL`、`DISCONNECT_PATH`）已指向**生产环境**；测试环境地址不应用于正式商户。

---

## 常见问题（FAQ）

### 未安装 WooCommerce 可以使用吗？

不可以。本插件声明依赖 **WooCommerce**，仅用于在 WooCommerce 已启用的前提下与 Artiststore 建立授权关系。请先安装并启用 WooCommerce。

### 为什么建议先启用 WooCommerce 再打开本插件页面？

连接流程需要读取 WooCommerce 版本等信息。请始终在 **WooCommerce 已启用** 后再使用「连接到 Artiststore」，以保证流程稳定。

### 连接失败怎么办？

请依次检查：站点地址是否正确且可公网访问、是否使用 HTTPS、WooCommerce 是否为受支持的稳定版本、浏览器能否打开 Artiststore 商家后台、安全插件或防火墙是否拦截 REST（`/wp-json/`）或出站请求。若仍失败，请联系 Artiststore 技术支持，并提供大致时间与站点域名（勿泄露密码或密钥）。

### 提示「远端撤销未成功」是什么意思？

断开连接时，插件会请求 Artiststore API 作废密钥。若网络或服务端暂时不可用，本地可能不会立即清空配置；请稍后重试断开，或联系支持。

### 断开连接后数据会怎样？

插件会尽力通知 Artiststore 服务端作废密钥；远端返回成功时，本地保存的连接信息会被清除。您在 Artiststore 平台上的账号、历史订单等业务数据是否保留，以平台规则为准。

### 卸载插件会删除什么？

执行标准卸载时，会删除选项 `artiststore_settings`（见 `uninstall.php`）。若仅「停用」插件，数据仍保留在数据库中。

### 本站使用 CDN / 反向代理，有影响吗？

若 WordPress 报告的站点 URL 与实际对外域名不一致，可能影响授权回调。请确保 **设置 → 常规** 中的地址与对外访问一致，并按代理/CDN 厂商说明转发 REST 请求。

### 开发者需要接口说明或自建对接怎么办？

请阅读插件内 **[`includes/docs.md`](includes/docs.md)**，其中包含 REST 路由、参数与安全相关说明；插件常量定义见 `artiststore.php` 与 `includes/Options.php`。

### 与其他 WooCommerce 插件会冲突吗？

本插件仅增加后台菜单与 REST 路由，一般不修改订单与商品数据。若遇异常，可尝试仅启用 WooCommerce 与本插件做对比排查。

---

## 开发者说明（Developer Notes）

**REST API 命名空间**：`artiststore/v1`（与常量 `ARTISTSTORE_NAMESPACE` 一致）。

**商户侧路由（摘要）**

- `POST /wp-json/artiststore/v1/connect` — 平台在授权成功后回写 `store_id`、`access_key` 等（请求体验证 token）。
- `POST /wp-json/artiststore/v1/disconnect` — 平台主动断开时的回调（参数与校验规则见 [`includes/docs.md`](includes/docs.md)）。

**后台 AJAX**

- `artiststore_disconnect` — 管理员在后台点击「断开连接」时使用（需 WordPress nonce）。

**国际化**

- 文本域 `artiststore`，语言文件目录 `languages/`；模板 `artiststore.pot`，内置 `artiststore-zh_CN.mo`。编译：`php languages/compile-mo.php`。

完整字段说明、token 计算方式与远端撤销请求格式见 **[`includes/docs.md`](includes/docs.md)**，请勿仅以本 README 做集成实现。

---

## 截图说明（Screenshots）

1. WordPress 后台「Artiststore」页面：连接状态、WooCommerce 状态徽标与「连接到 Artiststore」入口。
2. 已连接状态下显示「断开连接」按钮。
3. （可选）Artiststore 商家后台中的店铺连接相关界面（由平台提供，以线上为准）。

---

## 更新日志（Changelog）

### 1.1.1

- **国际化（i18n）**：加载文本域 `artiststore`；后台界面字符串改为可翻译的英文 msgid。
- 新增 `languages/`：`artiststore.pot` 模板、`artiststore-zh_CN` 简体中文语言包（`.po` / `.mo`）。
- 新增 `languages/compile-mo.php`；`build.sh` 打包前自动编译 `.po` 为 `.mo`。
- 与 `artiststore.php` 中 `Version` 一致；升级后连接逻辑与数据存储无变更，无需重新授权。

### 1.0.0

- 对外发布版本；与 `artiststore.php` 中 `Version` 一致。
- 依赖 WordPress 5.8+、PHP 7.4+；需安装并启用 WooCommerce。

---

## 升级提示（Upgrade Notice）

**1.1.1**：常规升级即可；若站点语言为简体中文，升级后后台 **Artiststore** 页面将自动显示中文界面。升级前建议备份；升级后在 **Artiststore** 菜单中确认连接状态仍为「已连接」（若此前已绑定）。

**1.0.0**：升级前请备份数据库与文件；升级后在 **Artiststore** 菜单中确认连接状态；若曾修改 `includes/Options.php` 中的环境地址，请在升级后重新核对以免指向错误环境。

---

## 打包发布

在 **`wp-content/plugins/`** 目录下执行（与官方插件目录结构一致：压缩包内顶层为 `artiststore/` 文件夹）：

```bash
zip -r artiststore-v1.1.1.zip artiststore/ \
  -x "artiststore/.git/*" \
  -x "artiststore/.git/**" \
  -x "artiststore/.idea/*" \
  -x "artiststore/.idea/**"
```

版本号请与 `artiststore.php` 中 `Version` 保持一致；或使用仓库内脚本（从主文件自动读取版本，并在**上一级目录**生成 zip）：

```bash
cd /path/to/wp-content/plugins/artiststore
./build.sh
# 生成：../artiststore-v1.1.1.zip
```

---

## WordPress.org 与 `readme.txt`

若需向 WordPress 插件目录提交，目录仍习惯使用根目录的 `readme.txt`（专用头信息与章节格式）。完整说明已合并于本 **`README.md`**；发布前可将本文件相应章节同步或节选至 `readme.txt`。
