开发文档

一、技术架构

• 技术栈：PHP 8.0+（推荐 8.1）+ MySQL 5.6+，Composer 依赖；自带轻量框架 kernel/（不依赖 ThinkPHP/Laravel），核心组件：Annotation（注解路由）、Container（依赖注入容器）、Database（查询构建器）、Cache / Component / Console / Context / Exception；
• 前端：二次元玻璃拟态风格店铺（PC + 手机自适应），资源在 assets/；后台在 /admin；
• 部署：原生 PHP 站点（Nginx/Apache 均可，Nginx 伪静态指向 index.php），仓库自带 Dockerfile / docker-compose.yml 可容器化。

二、目录结构

程序根/
├── index.php             # 入口（Web 根）
├── app/                  # 业务代码（控制器 / 服务 / 模型，按模块分目录）
├── config/               # 配置（数据库、缓存、文件路径等，database.php 返回数组）
├── kernel/               # 自研框架内核（注解路由 / 容器 / 数据库 / 缓存 / 控制台）
├── assets/               # 前端资源（样式、脚本、图片、主题）
├── runtime/              # 运行缓存与日志（要可写）
├── vendor/               # Composer 依赖
├── docker/ docker-compose.yml / Dockerfile
└── composer.json

三、数据库

• 表前缀 acg_（安装时可改），约 35 张表，主要包括：
• 用户与商户：acg_user（会员）、acg_manage（后台管理员，登录用邮箱）、acg_user_group / acg_manage_group（等级/权限组）；
• 商品与订单：商品、分类、订单、卡密（发货内容）、优惠券等表（前缀统一 acg_）；
• 资金：余额、充值、提现、佣金（分销）相关表。

四、关键机制

4.1 注解路由（Annotation）

控制器方法上用注解声明路由与权限（kernel 的 Annotation 组件扫描解析），加接口就在对应控制器上加方法 + 注解，不用改路由文件。

4.2 密码算法

会员/管理员密码支持两种格式：verifyPassword 同时认旧格式 sha1(md5(md5($pass).md5($salt))) 与新格式 bcrypt；user 表带 salt 列（NOT NULL），新建账号用 password_hash() 即可，旧账号首次登录后按新格式重写也没问题。

4.3 支付插件

支付渠道以插件形式接入（后台可配多个渠道与费率），回调统一走订单完成逻辑，发货内容来自商品的卡密池。

五、二次开发指引

• 改前台样式：assets/ 下对应样式与模板；换配色建议用 CSS 变量，别到处写死色值；
• 加页面/接口：app/ 下按模块加控制器与视图，路由用注解；
• 加后台功能：app/ 里对应后台模块 + 后台菜单表；权限项按注解里的权限点登记；
• 配置文件特性：config/database.php 是 include 返回数组、且没有 port 键——自己写旁挂脚本时取端口要 $d['port'] ?? 3306，并记得 ini_set('display_errors','0')，否则 PHP 警告会污染 JSON 输出；
• 注意：vendor/ 与 kernel/ 是依赖与内核，升级会覆盖，别改；业务代码与资源升级前备份。

六、登录与账号

• 前台登录：/user/authentication/login（用户名 + 密码 + 图形验证码）；
• 后台登录：/admin/authentication/login（用户名填邮箱 + 密码 + 图形验证码）；
• 演示站/自动化测试要过验证码：/user/captcha/image?action=login，后台是页面里的验证码图，同一浏览器会话内取图再提交。