CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

勾股 OA 5.0，企业办公自动化系统。技术栈：ThinkPHP 8.1 多应用模式 + think-orm 4.0 + Layui 前端 + MySQL。PHP 要求 >=8.2。数据库表前缀 oa_（Db::name('Admin') → 表 oa_admin）。

常用命令

composer install                    # 安装依赖（已配腾讯云镜像）

php think migrate:run               # 执行数据库迁移（建表 / 改表）
php think migrate:create CreateXxx  # 新建迁移文件
php think seed:run --seeder=XxxData # 执行单个 seeder
php think seed:create XxxData       # 新建 seeder

rm -rf runtime/cache/*              # 清缓存（改了菜单/权限/系统配置后必须清才生效）

无单元测试框架。验证靠跑迁移 + 浏览器手测（见 新增审批类型指南.md 的验证清单）。
迁移与种子数据均以 Phinx 迁移文件形式放在 database/migrations/，文件名前缀 xxx_create_*（建表）/ xxx_seed_*（填数据）。
重装系统：删除 config/install.lock 后访问 /install/index。
环境配置走 .env（数据库、Redis 缓存），勿提交真实凭据。

架构

多应用结构

每个业务域是 app/ 下的一个独立应用（home finance adm customer contract project oa api mobile qiye disk user install）。default_app 是 home。另有 crud 代码生成器应用（脚手架工具，非业务域，含 command/ tpl/，用于生成 CRUD 骨架）。每个应用目录内自带：

app/{module}/
  controller/   控制器（继承 app\base\BaseController）
  model/        模型（继承 think\Model）
  validate/     验证器（可选）
  view/         模板（目录名 = Str::snake(类名)）
  common.php    ★ 该模块专属 helper 函数
  middleware.php

app/base/BaseController.php —— 所有控制器的基类。构造时跑 checkLogin()：校验 Session(gougu_admin)、超 10 小时强制重登、调 checkAuth() 用 systematic\Systematic 做权限节点校验（节点格式 module/controller/action，缓存在 RulesSrc{uid}）。控制器内可直接用 $this->uid / $this->did / $this->pid。
extend/ 是 PSR-0 自动加载目录（systematic\、backup\、smsservice\ 等公共库）。
自定义异常处理：app/exception/Http.php（在 app/provider.php 绑定）。

CRUD 约定（强约束，新增功能照抄现有样本）

Model 标准方法：datalist($where, $param)（paginate + each 翻译关联字段）、add()、edit()、getById($id)、delById($id, $type=0)。

写库用 self::strict(false)->field(true)；增删改成功/失败统一 return to_assign(...)，并调 add_log() 记操作日志。
软删除：delById 默认 update(['delete_time' => time()])，查询一律带 ['delete_time', '=', 0]。物理删除传 $type=1。

Controller add() 必须用 if/else 结构：AJAX 分支处理提交（不 return 模型结果），else 分支渲染视图。非 AJAX 分支必须给 $detail 所有字段初始化默认值（PHP 8 对 Undefined array key 是 fatal error）。

全局 helper（`app/common.php`）

get_params() 取请求参数、to_assign($code,$msg,$data) 统一 JSON 响应、table_assign() Layui 表格响应、add_log($type,$id,$param,$subject) 操作日志、get_admin($uid) 取用户信息、check_status_name() 审批状态文案、to_date() 时间戳格式化、get_system_config() 读系统配置（带缓存）。

审批系统（核心业务）

审批类型注册在数据库，不是配置文件。关键表关系：

oa_flow_module → oa_flow_cate（name 唯一标识 = 前端 oaCheck.init 的 check_name）
                      ├→ oa_flow（流程）  ├→ oa_template（消息模板）
                      └→ oa_{业务表}（含 check_* / admin_id / did / *_time 必填字段）
oa_admin_rule（菜单权限节点池）  oa_admin_group.rules（角色节点，逗号分隔）

业务表必含审批字段：check_status check_flow_id check_step_sort check_uids check_last_uid check_history_uids check_copy_uids check_time，外加 admin_id did create_time update_time delete_time。

新增审批类型必须照着 新增审批类型指南.md 走完整 10 步流程（迁移 → Model → Controller → 3 个 View → seeder 注册类型/菜单/权限 → 清缓存）。

finance 应用是审批类型最全的样本库，新增同类审批照抄其结构即可：报销 Expense、借款 Loan、付款 Payment、开票 Invoice、收入 Income、提现 Withdraw、费用返还 Feerefund、VCC 返点/提成付款 Vccpayment、调价 Priceadjust、授信&核销 Creditwriteoff。其中带枚举的类型均配套 Xxxcate 字典表控制器（如 Withdrawcate Feerefundcate）。

项目约定（踩坑点）

helper 函数必须放对应模块的 common.php（财务类放 app/finance/common.php）。放错模块 → 视图渲染时函数未定义 → 页面中途截断。
多词控制器命名用「首字母大写+其余全小写」（Vccpayment.php / class Vccpayment，不是 VccPayment）。原因：TP 从全小写 URL 解析控制器得到 Vccpayment，Linux 大小写敏感文件系统下找不到 VccPayment.php 会报「控制器不存在」。单词控制器（Expense Loan）不受影响。
枚举字段建 xxx_cate 字典表（含 type 字段区分同一审批类型下的多组枚举），业务表只存字典的 value（int，跨环境稳定），不存中文、不存自增 id。固定且极少的枚举（如是/否）才在 common.php 写 helper。
MySQL TEXT/BLOB 字段不能有默认值，迁移里用 'null' => true 并去掉 default。
Seeder 的 run() 必须声明 run(): void；$db->query(...) 返回 PDOStatement，取数组要 ->fetchAll(\PDO::FETCH_ASSOC)。
Seeder 里所有父节点 ID（菜单、模块、超管组）动态查询，不能写死（不同环境 ID 会漂移）。
财务五个新审批类型暂未开放删除（Withdraw Feerefund Vccpayment Priceadjust Creditwriteoff），已前后端双重关闭：列表页 datalist.html 的删除按钮与 del 事件监听用注释关掉（<script> 内用 // 与 /* */，非 HTML 注释）；控制器 del() 方法体首行直接 return to_assign(1, '删除功能暂未开放')，原逻辑用 /* */ 保留。新增同类财务审批默认沿用此约定；需开放时去掉两端注释即可恢复。
严格遵循 ThinkPHP 8.1 / PHP 8.2 特性，不用更高版本特性，避免兼容性问题。

CLAUDE.md 6.7 KB 文件歷史 原始文件