推广分佣功能开发
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
---
|
||||
description: FastAdmin 管理后台规范:CRUD 控制器、视图、语言包、前端表格 JS
|
||||
globs: backend/application/admin/**,backend/public/assets/js/backend/**
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# FastAdmin 管理后台规范
|
||||
|
||||
## 新增模块
|
||||
|
||||
1. 先建表(`fa_` 前缀,`createtime`/`updatetime` 为 int,枚举字段 COMMENT 写成 `状态:0=关闭,1=招标中`)
|
||||
2. 用命令生成骨架,再在生成结果上修改:`php think crud -t demands -u 1`,菜单 `php think menu -c demands`
|
||||
3. 一个模块对应四处文件,命名保持一致:
|
||||
- 控制器 `admin/controller/[子目录/]Demands.php`
|
||||
- 视图 `admin/view/[子目录/]demands/{index,add,edit}.html`
|
||||
- 语言包 `admin/lang/zh-cn/[子目录/]demands.php`(字段名、`Status 1` 等枚举文案)
|
||||
- 表格 JS `public/assets/js/backend/[子目录/]demands.js`
|
||||
|
||||
## 控制器
|
||||
|
||||
- 继承 `app\common\controller\Backend`;在 `_initialize()` 中实例化 `$this->model`(使用 `app\common\model` 下的模型)并 `assign` 各 `xxxList`
|
||||
- 默认 `index/add/edit/del/multi` 由 trait 提供,只有需要定制时才覆盖;覆盖时以 `admin/library/traits/Backend.php` 中原方法为蓝本
|
||||
- 关联查询覆盖 `index()`:`$this->relationSearch = true`,`->with([...])`,并用 `visible()` 限定关联字段
|
||||
- 保存时用 `$this->model->allowField(true)->save($params)`,入参先经 `preExcludeFields()`
|
||||
- 自定义操作(审核、重新投标、取消等):
|
||||
|
||||
```php
|
||||
public function audit($ids)
|
||||
{
|
||||
$row = $this->model->get($ids);
|
||||
if (!$row) {
|
||||
$this->error(__('No Results were found'));
|
||||
}
|
||||
if ($this->request->isAjax()) {
|
||||
try {
|
||||
DemandService::auditPass($ids);
|
||||
} catch (\Exception $e) {
|
||||
$this->error($e->getMessage());
|
||||
}
|
||||
$this->success('审核成功');
|
||||
}
|
||||
$this->view->assign('row', $row->toArray());
|
||||
return $this->view->fetch();
|
||||
}
|
||||
```
|
||||
|
||||
- 业务流程(资金、状态流转、通知)必须调用 `common/service`,与 API 共用同一套逻辑,不在后台控制器里重写
|
||||
- `$this->success()` 放在 try 外,或在 catch 中对 `HttpResponseException` 原样抛出
|
||||
- 新增自定义方法后需在权限菜单中添加对应节点,否则非超管无权限
|
||||
|
||||
## 表格 JS
|
||||
|
||||
- 使用 `define([... 'table', 'form'], ...)` + `Table.api.init({ extend: {...} })`,列文案一律 `__('Field')`
|
||||
- 枚举列 `searchList` 与模型 `getXxxList()` 保持一致,配合 `Table.api.formatter.status/normal`
|
||||
- 自定义按钮放在 `operate` 列的 `buttons` 中,弹窗用 `btn-dialog`,Ajax 用 `btn-ajax` 并带 `confirm`
|
||||
- 表单页调用 `Controller.api.bindevent()` → `Form.api.bindevent($("form[role=form]"))`
|
||||
|
||||
## 视图
|
||||
|
||||
- 表单字段名使用 `row[field]`;图片/文件使用 FastAdmin 的 `faupload` 组件
|
||||
- 不在模板内写业务判断,下拉选项使用控制器 assign 的 `xxxList`
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
description: 后端 PHP 规范:API 控制器、Service 层、模型、事务、资金与安全(ThinkPHP 5 / FastAdmin)
|
||||
globs: backend/application/**/*.php
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# 后端 PHP 规范
|
||||
|
||||
## 语言版本与风格
|
||||
|
||||
- 兼容 PHP 7.4:可用箭头函数 `fn`、类型属性;**禁止** `match`、命名参数、构造器属性提升、`?->`、联合类型、`enum`、`readonly`
|
||||
- PSR-12 风格,4 空格缩进;类名 PascalCase,方法/变量 camelCase,数据库字段与请求字段 snake_case
|
||||
- 命名空间与目录一致:`app\api\controller`、`app\common\service`、`app\common\model\{子目录}`
|
||||
|
||||
## 分层职责
|
||||
|
||||
| 层 | 位置 | 职责 |
|
||||
| --- | --- | --- |
|
||||
| API 控制器 | `api/controller/` | 取参、校验、登录判断、组装返回;不写业务流程 |
|
||||
| Service | `common/service/XxxService.php` | 业务逻辑、状态流转、事务、状态常量 |
|
||||
| Model | `common/model/` | 表映射、关联、获取器/修改器、`*_text` 追加字段 |
|
||||
| Validate | `common/validate/` | 可复用的验证规则 |
|
||||
| 定时/队列 | `common/command/`、`common/job/` | 调用 Service,不内联业务 |
|
||||
|
||||
## API 控制器模板
|
||||
|
||||
`success()/error()` 通过抛出 `HttpResponseException` 输出,catch 里必须原样抛出:
|
||||
|
||||
```php
|
||||
class Demand extends Api
|
||||
{
|
||||
protected $noNeedLogin = []; // 免登录方法,支付回调等必须显式列出
|
||||
protected $noNeedRight = ['*'];
|
||||
|
||||
/**
|
||||
* 参与竞标
|
||||
* @ApiMethod (POST)
|
||||
* @param int $demand_id 需求ID
|
||||
*/
|
||||
public function joinBidding()
|
||||
{
|
||||
try {
|
||||
$params = $this->request->post();
|
||||
$validate = new Validate(['demand_id' => 'require|number'], ['demand_id.require' => '需求ID不能为空']);
|
||||
if (!$validate->check($params)) {
|
||||
$this->error($validate->getError());
|
||||
}
|
||||
$res = DemandBiddingService::join($params, $this->auth->id);
|
||||
$this->success('报名成功', $res);
|
||||
} catch (\Exception $e) {
|
||||
if ($e instanceof HttpResponseException) {
|
||||
throw $e;
|
||||
}
|
||||
$this->error($e->getMessage());
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 数组参数用 `$this->request->post('list/a', [])`;数值参数显式 `intval()`
|
||||
- 需要登录的接口不要放进 `$noNeedLogin`,也不要用 `$this->auth->id ?? -1` 绕过登录
|
||||
- 新增接口后在 `frontend/miniapp/config/api.js` 登记
|
||||
|
||||
## Service 模板
|
||||
|
||||
```php
|
||||
class DemandService
|
||||
{
|
||||
use ServiceTrait; // 提供 instance()/getOne()/getList(),并静态代理模型方法
|
||||
|
||||
/** @var Demands */
|
||||
public static $Model = Demands::class;
|
||||
|
||||
const STATUS_BIDDING = 1; //招标中
|
||||
const STATUS_MAP = [self::STATUS_BIDDING => '招标中'];
|
||||
}
|
||||
```
|
||||
|
||||
- 方法默认 `public static`,带中文 docblock(`@param`/`@return`/`@throws`)
|
||||
- 查询优先 `self::getOne($where, $with)`、`self::getList($where, $pageSize, $order, '', $with)`
|
||||
- 状态值用 Service 常量或 `CommonService::NO/ONGOING/SUCCESS/FAILED`、`STATUS_ON/OFF`,**禁止**新代码出现魔法数字 `status == 2`
|
||||
- 失败直接抛 `\Exception('中文原因')`(或 `exception()` 助手),不返回 `false`/错误数组
|
||||
- 涉及"操作他人数据"的方法必须接收 `$userId` 并校验归属(如 `$demand->user_id == $userId`),不能只凭前端传的 ID
|
||||
|
||||
## 事务与并发
|
||||
|
||||
- 前置校验放在事务外,写操作放在事务内;catch 中 `Db::rollback()` 后 `throw $e`
|
||||
- 余额、状态流转、库存/激活码分配:事务内用 `->lock(true)` 读取再判断,防止并发重复操作
|
||||
- 订阅消息、企业微信、OSS、微信转账等外部调用放在 `Db::commit()` **之后**,失败只记日志不回滚业务
|
||||
- 支付/转账回调必须幂等:先查订单当前状态,已处理直接返回成功
|
||||
|
||||
## 资金与账户
|
||||
|
||||
- 余额/冻结/积分/信誉分只通过 `AccountLogService::addLog()` + `AccountService::updateData()` 变更,二者在同一事务内
|
||||
- 金额计算用 bcmath(`bcadd/bcsub/bcmul`,精度 2),不用浮点直接加减比较
|
||||
- 结算价、订单金额从数据库商品/订单读取,不使用请求中的 `price`
|
||||
|
||||
## 模型
|
||||
|
||||
- `$name` 不带前缀;`$autoWriteTimestamp = 'integer'`,`$createTime = 'createtime'`,`$updateTime = 'updatetime'`
|
||||
- JSON/数组字段用 `$type = ['images' => 'array']`
|
||||
- 枚举字段配套 `getXxxList()`(文案走 `__()` 语言包)+ `getXxxTextAttr()`,并加入 `$append`
|
||||
- 关联方法 camelCase,并用 `->field()` 限定字段,避免泄露手机号、openid 等敏感字段
|
||||
|
||||
## 日志与配置
|
||||
|
||||
- `Log::info(__CLASS__ . ' 描述:' . json_encode($data, JSON_UNESCAPED_UNICODE))`;禁止 `var_dump`/`echo`/`dump` 残留
|
||||
- 站点配置读取 `config('site.xxx')`,环境配置读取 `Env::get()`;不在代码里硬编码密钥与域名
|
||||
- 原生 SQL 必须参数绑定;`like` 关键词使用 `['like', "%{$keywords}%"]` 数组条件,不拼接字符串
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
description: 微信小程序前端规范:页面结构、接口服务层、TDesign 组件、样式与交互
|
||||
globs: frontend/miniapp/**/*.{js,wxml,wxss,json,wxs}
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# 微信小程序前端规范
|
||||
|
||||
## 代码风格
|
||||
|
||||
- 遵循 `.prettierrc.yml` 与 `.eslintrc.js`:2 空格、单引号、分号、行宽 120、尾逗号、LF
|
||||
- 用 `const/let`,禁止 `var`;用模板字符串,比较用 `===`;ES Module `import/export`
|
||||
- 不提交调试日志:`console.log` 需删除,保留 `console.error/warn` 用于异常
|
||||
- 提交信息遵循 commitlint(`feat: 新增需求交付页`、`fix: ...`)
|
||||
|
||||
## 目录与命名
|
||||
|
||||
- 页面:`pages/{模块}/{页面}/index.{js,json,wxml,wxss}`,目录名 kebab-case,新页面必须在 `app.json` 的 `pages` 中注册
|
||||
- 页面私有组件放 `pages/{模块}/components/`,跨页面复用放 `components/`
|
||||
- 接口函数放 `services/{模块}/fetchXxx.js`,一个模块一个文件
|
||||
|
||||
## 接口调用
|
||||
|
||||
1. 在 `config/api.js` 登记地址:`DemandDeliver: ApiRootUrl + 'demand/deliver', //需求发货`
|
||||
2. 在 services 中封装,通过全局 `wx.$util.request(url, data, method)`:
|
||||
|
||||
```js
|
||||
/** 需求发货 */
|
||||
export function deliverDemand(params) {
|
||||
return wx.$util.request(wx.$api.DemandDeliver, params, 'POST');
|
||||
}
|
||||
```
|
||||
|
||||
3. 页面只 import services 函数,**禁止**在页面里直接 `wx.request` 或拼接接口地址
|
||||
4. 结果按 `res.code === 1` 判断成功,失败展示 `res.msg`:
|
||||
|
||||
```js
|
||||
async onSubmit() {
|
||||
wx.showLoading({ title: '提交中', mask: true });
|
||||
try {
|
||||
const res = await deliverDemand({ demand_id: this.data.id });
|
||||
if (res.code !== 1) {
|
||||
wx.showToast({ title: res.msg || '操作失败', icon: 'none' });
|
||||
return;
|
||||
}
|
||||
wx.showToast({ title: '发货成功', icon: 'success' });
|
||||
} catch (err) {
|
||||
console.error('deliverDemand failed:', err);
|
||||
wx.showToast({ title: '网络异常,请重试', icon: 'none' });
|
||||
} finally {
|
||||
wx.hideLoading();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 新代码使用 `async/await`,不再写 `.then(success, fail)` 嵌套
|
||||
- 提交类按钮加防重复点击(`submitting` 标志或 `t-button` 的 `loading`)
|
||||
|
||||
## 页面逻辑
|
||||
|
||||
- `data` 中每个字段写注释说明含义;列表页固定使用 `page`、`hasMore`、`isEmpty` 三个字段
|
||||
- 分页:`onReachBottom` 判断 `hasMore` 加载下一页;`onPullDownRefresh` 刷新后调用 `wx.stopPullDownRefresh()`
|
||||
- `setData` 只传变化的字段,单条更新用数据路径写法(如键名 `demandList[0].button`),不整体替换大列表
|
||||
- 跨页面刷新使用已有机制:`wx.$util.markDemandRefresh(id)`(`globalData.refreshDemandId`)或 `backAndRefresh()`,不新增其他全局通信方式
|
||||
- 按钮动作按后端返回的 `item.button.key` 分支,常量与后端 `DemandService::BUTTON_*` 保持一致
|
||||
- 删除模板生成的空生命周期函数(空的 `onReady/onHide/onUnload/onShareAppMessage`)
|
||||
|
||||
## WXML / 组件
|
||||
|
||||
- UI 优先使用 TDesign 组件,在页面 `index.json` 的 `usingComponents` 中按需引入(`tdesign-miniprogram/xxx/xxx`);图片优先 `/components/webp-image/index`
|
||||
- `wx:for` 必须写 `wx:key`(优先唯一 `id`);嵌套循环使用不同的 `wx:for-item/wx:for-index` 名
|
||||
- 事件参数通过 `data-*` 传递,在 js 中用 `e.currentTarget.dataset` 解构读取
|
||||
- 不在 WXML 中写复杂表达式,复杂格式化放 `.wxs` 或在 js 中预处理
|
||||
|
||||
## WXSS
|
||||
|
||||
- 尺寸使用 `rpx`;类名小写中划线,可用 BEM(`search-bar__input`、`refresh-btn--loading`)
|
||||
- 主题色沿用 TabBar 选中色 `#FF5F15` 与 TDesign CSS 变量(`--td-brand-color` 等),不随意新增色值
|
||||
- 避免行内 `style`,仅动态值(如 `max-height`)可用
|
||||
|
||||
## 安全与隐私
|
||||
|
||||
- 不在前端保存任何密钥;`token`、`userInfo` 仅存于 Storage
|
||||
- 手机号展示使用 `phoneEncryption()` 脱敏;用户输入在提交前做必要的非空/长度校验,但以后端校验为准
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
description: 代码帮项目总览、目录边界与前后端接口契约(全局生效)
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# 代码帮(code-bang)项目总览
|
||||
|
||||
软件商城 + 定制开发撮合平台。后端 `backend/`:FastAdmin(ThinkPHP 5.x,PHP >= 7.4,MySQL,表前缀 `fa_`);前端 `frontend/miniapp/`:微信原生小程序 + TDesign(基于零售模板二次开发)。
|
||||
|
||||
## 目录边界
|
||||
|
||||
- 业务代码只写在:`backend/application/{api,admin,common}`、`backend/public/assets/js/backend`、`frontend/miniapp/{pages,components,services,config,utils,custom-tab-bar}`
|
||||
- 禁止修改:`backend/vendor`、`backend/thinkphp`、`backend/addons/*`(第三方插件)、`frontend/miniapp/node_modules`、`miniprogram_npm`
|
||||
- FastAdmin 框架基类(`common/controller/*`、`admin/library/traits/Backend.php`、`common/library/*`)非必要不改,需要定制时在子类覆盖
|
||||
- 零售模板遗留的 mock(`model/`、`config.useMock`)不再扩展,新功能直接对接真实接口
|
||||
|
||||
## 接口契约(前后端必须一致)
|
||||
|
||||
- 地址:`{ApiRoot}/api/{controller}/{action}`,前端统一登记在 `frontend/miniapp/config/api.js`
|
||||
- 鉴权:请求头 `token`(来自 `wx.getStorageSync('token')`),由 `auth/wxLogin` 签发
|
||||
- 响应:`{ code, msg, time, data }`,`code === 1` 成功,`code === 0` 失败,`msg` 为可直接展示给用户的中文提示
|
||||
- 分页:后端 `paginate()` 返回 `{ total, per_page, current_page, last_page, data }`,前端用 `current_page < last_page` 判断是否还有更多;请求参数 `page`、`pageSize`
|
||||
- 字段命名:新接口统一 `snake_case`(与数据库一致);仅对接 TDesign 模板页面(商品/订单/购物车)时才用 `convert_keys_to_camelcase()` 转驼峰
|
||||
- 状态驱动的按钮由后端下发 `button: { key, name, theme }`,前端只按 `key` 判断动作,不按中文文案判断
|
||||
- 金额:数据库 `decimal(10,2)`,单位为元;价格、应付金额一律以服务端查库计算为准,不信任前端传入的价格
|
||||
|
||||
## 业务术语
|
||||
|
||||
需求 demand(招标 → 签约 → 工作 → 验收 → 收货 → 完成)、投标 bidding、合同 contract、开发者 developer、账户 account(余额/冻结/积分/信誉分)、激活码 soft code、设备 soft device(每码最多绑定 2 台)、订阅消息 subscribe message。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- 注释、提示文案、提交说明使用中文;标识符使用英文
|
||||
- 不提交密钥:AppSecret、商户密钥、OSS AccessKey 等只放 `backend/.env` 或后台配置(`config('site.xxx')`)
|
||||
- 改动接口字段时,同步检查前端 `services/` 与对应页面的使用处
|
||||
Reference in New Issue
Block a user