23 全站开发文档

面向参与本系统开发的工程师，约定环境、编码规范、前后端协作、构建发布的统一做法。

一、环境准备

组件	版本	备注
PHP	8.1+（验证至 8.5）	扩展：pdo_mysql、curl、json、mbstring、openssl、zip
MySQL / MariaDB	8.0 / 10.3+	表前缀 kd_
Node.js	18+（验证至 25）	仅前端开发/构建需要
Composer	2.x	本仓库可用根目录 composer.phar
Redis	可选	配置后用于配置缓存/队列扩展

一键起开发栈：

cd kede-finance
bash scripts/dev-all.sh         # PHP :8800 + 前台 :5273 + 后台 :5173

二、后端开发约定

控制器只做编排

控制器负责「收参 → 调服务 → 统一返回」，业务写进 app/common/service。返回一律用 ApiResponse trait：

use app\common\ApiResponse;

class Foo extends BaseController
{
    use ApiResponse;

    public function bar(): \think\Response
    {
        $id = (int) $this->request->param('id');
        $row = SomeService::get($id);
        if (!$row) {
            return $this->error('不存在', 404);
        }
        return $this->success('ok', $row);
    }
}

路由

约定式路由 /{app}/{控制器}/{动作}，无需在 route/ 注册（仅 / 与 /ping 是显式路由）。控制器名 ThemeTpl 对应 URL 段 theme_tpl（蛇形）。

数据访问

• 简单读写用 think\facade\Db::name('表名')（自动加前缀）；
• 实体逻辑用 app/common/model 下模型；
• 避免循环内查询（N+1），批量场景用 whereIn 一次取，参考 ProductService::getPricingBatch()。

配置与缓存

• 读写系统配置统一走 SettingService（带请求级 + 持久缓存，写入自动失效）；
• 不要直接写 kd_configs，否则缓存不会失效。

Schema 变更

新增列/索引写进 SchemaPatch（addColumnIfMissing / addIndexIfMissing，幂等），已装系统会在下次请求自动补齐；索引补丁靠 system.index_patch 标记只跑一次。

三、前端开发约定

两套 SPA：frontend/admin（后台）、frontend/home（前台+会员中心），均 Vue 3 + TS + Vite + Arco。

Arco 按需引入

main.ts 不再全量 app.use(ArcoVue) / app.use(ArcoVueIcon)；组件与图标由 unplugin-vue-components + ArcoResolver({ resolveIcons: true }) 自动按需引入，整包 arco.css 仍保留以保证样式完整。新增组件直接在模板用 <a-xxx> / <icon-xxx> 即可，无需手动注册。命令式 API（Message 等）照常显式 import。

构建分包

vite.config.ts 用 manualChunks 拆出 arco / vue-vendor / vendor，利于缓存与并行加载。构建命令：

cd frontend/admin && npm run build   # 产物 → public/admin/
cd frontend/home  && npm run build   # 产物 → public/（index.html + assets）

接口联调

开发态由 Vite 代理转发到 :8800：admin 代理 /admin /home /api /setup，home 代理 /admin /home /api /setup。请求统一封装在 src/api/，响应结构见 27 错误码大全。

四、扩展开发

扩展点	文档
功能/支付/短信/邮件/实名插件	04 插件系统、05 插件市场
支付网关驱动	06 支付网关
实名认证驱动	07 实名认证
短信/邮件驱动	08 通知短信邮件
开通模块（主机/云）	09 开通模块
主题 / SSR	10 主题与SSR
钩子	11 钩子系统

五、提交与发布

1. 后端改动：php composer.phar install 装好依赖，本地用 dev-all.sh 自测；
2. 前端改动：两个 SPA 各 npm run build 并自测；
3. 出包：bash deploy/package.sh（完整构建 + 生产依赖 + zip）或 SKIP_BUILD=1 bash deploy/package.sh（复用已构建产物）；
4. 文档站：改 wiki/*.md 后 bash scripts/build-docs-deploy-zip.sh 出文档包；
5. 线上更新优先走 26 更新产品开发文档 的热更新流程。

六、自测清单

• [ ] PHP 语法：对改动文件 php -l
• [ ] 前端类型+构建：npm run build（含 vue-tsc）
• [ ] 关键接口冒烟：/ping、/home/content/siteConfig、/admin/auth/login
• [ ] 生产前关闭 APP_DEBUG

---

下一篇：24 产品接口文档