张家训
236 lines
16 KiB
Markdown
236 lines
16 KiB
Markdown
# Freedom（KPI 绩效考核系统）AI 开发接手指南
|
||
|
||
> - 生成/更新日期：2026-09-03（请留意后续变更，环境信息随时间会过期）
|
||
> - 存放位置：`freedom-admin/docs/AI-开发接手指南.md` 与 `freedom-web/docs/AI-开发接手指南.md`（两仓库同步维护同一份内容）
|
||
> - 用途：当新的 AI 编码代理（如小龙虾 / openclaw）接手本项目、开发新功能模块时，**先完整阅读本文件**即可快速建立上下文。第 1 节是可整体复制给代理的 Prompt 模板，第 2 节之后是明细资料。
|
||
|
||
---
|
||
|
||
## 1. 接手 Prompt（可直接复制给 openclaw / 任意编码 Agent）
|
||
|
||
```
|
||
你是 Freedom（KPI 绩效考核系统）项目的开发工程师。项目为前后端分离架构，由两个独立 git 仓库组成：
|
||
freedom-admin（Spring Boot 2.7.10 / Java 8 / MyBatis-Plus / MySQL）与 freedom-web（Vue2 + iView(view-design) 后台）。
|
||
请先阅读各仓库 docs/AI-开发接手指南.md，了解环境、目录结构与开发 SOP 后再动手。
|
||
|
||
本次任务要求：
|
||
1. 明确需求范围与验收标准，拆解为前后端改造点；涉及数据库变更必须先给出 SQL 脚本并说明执行方式。
|
||
2. 后端新增接口：仿照 freedom-admin 现有 TSysDept/TSysUser 模块的 entity→mapper→service→controller 分层；
|
||
注意 controller 不带 /api 前缀、POST 参数按表单(POJO)接收、统一返回 Result{code,message,data}。
|
||
3. 前端新增页面：在 src/view 下建 .vue，在 src/api 对应目录建请求封装；新菜单/按钮权限登记在后端权限树
|
||
（t_sys_permission / 系统-权限管理界面），component 字段填写相对 src/view 的路径（无 .vue、无前导斜杠）。
|
||
4. 提交与验证：本地构建通过（mvn package / npm run build），提交信息规范，push master 会自动触发
|
||
Gitea Actions 构建并 docker compose 部署到生产（无独立预览环境，涉及生产数据变更务必谨慎并在提交说明中提示）。
|
||
5. 禁止把数据库密码/邮箱授权码等敏感信息写入代码或文档；一律引用 /opt/freedom/deploy/.env 或询问部署人。
|
||
|
||
环境速记：页面入口(公网) http://124.221.214.237:8880，后端直连 http://124.221.214.237:8800；
|
||
仓库远端 gitlab.jiaxun.site/yiciheng/freedom-*；内网 Gitea 192.168.1.158:3000(yiciheng/freedom-*) 跑 Actions。
|
||
项目现状与缺口（后端仅 RBAC、KPI 前端页面存在但后端接口缺失、api/basic 为已删生成器残留）见指南第 4/8 节，
|
||
动手前先与需求方核对，不要凭假设补全业务规则。
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 项目定位与总体架构
|
||
|
||
- 前后端分离的 **KPI 绩效考核管理系统**，目前生产可用的部分是「系统管理/RBAC」（用户、角色、部门、权限/菜单树），另有已写完前端但后端尚未落地的 KPI 业务页面。
|
||
- 一套源码同时维护 **2 个独立 git 仓库**（`freedom-admin`、`freedom-web`），根工作区同时还有辅助目录（`deploy/`、`docs/`、`_ci-test/`、`scripts/`、`act-runner-src-tmp/`、`logs/`），这些属于运维/CI 资产，不入业务仓库。
|
||
- 请求链路：
|
||
|
||
```
|
||
浏览器(Vue SPA, 端口 8880 对外)
|
||
↓ /api/xxx（nginx 去掉 /api 前缀）
|
||
freedom-web nginx 容器 (80) ──proxy_pass──▶ freedom-admin(Spring Boot, 8800) ──▶ MySQL freedom_db
|
||
页面静态资源由 nginx 直接托管；Excel 模板目录 /excelTemplate → nginx alias
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 当前环境快照（2026-09-03 实测）
|
||
|
||
### 3.1 代码托管与 CI/CD
|
||
|
||
| 项 | 值 | 说明 |
|
||
|---|---|---|
|
||
| 工作区远端 remote（实测） | `http://gitlab.jiaxun.site/yiciheng/freedom-admin.git`、`freedom-web.git`（HTTPS，需凭据） | 日常工作 push 到此 |
|
||
| 内网 Gitea | `http://192.168.1.158:3000`，仓库 `yiciheng/freedom-admin`、`yiciheng/freedom-web` | **Gitea Actions 实际在此触发** |
|
||
| 域名与内网关系 | `gitlab.jiaxun.site` 在办公网可能走内网 DNS/hosts；在公网 DNS 下可能解析到失效的拦截页。**依赖 git remote 的操作请在办公网环境验证**，若线上未更新，优先到内网 Gitea 看仓库提交与 Actions 运行记录 | 环境差异，勿假设 |
|
||
| Gitea Actions Runner | `local-runner`（act_runner v0.6.1，labels `ubuntu-latest`，宿主 `/etc/act_runner/runner-config.yml`） | docker socket 自动挂载 |
|
||
| 部署卷白名单 | `/opt/freedom`（runner `container.valid_volumes`） | |
|
||
| 工作流 | 各仓库 `.gitea/workflows/deploy.yml`；触发 `push master`（支持手动 `workflow_dispatch`） | |
|
||
| CI 注意事项 | act_runner **不会自动 clone 代码**，workflow 里是手动 `git clone`（oauth2 token + `host.docker.internal:3000`），克隆目录 `/opt/freedom/workspace-admin|web` | |
|
||
|
||
### 3.2 生产服务器（部署拓扑）
|
||
|
||
- 部署目录：`/opt/freedom/deploy/`，内含 `docker-compose.yml` + `.env`（`DB_URL / DB_USERNAME / DB_PASSWORD / IMAGE_TAG`）
|
||
- 容器（网络 `freedom-net`）：
|
||
|
||
| 容器 | 镜像 | 服务名 | 宿主端口 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `freedom-web` | `freedom-web:latest` | nginx | `8880` | 页面入口；`/api` → 后端（nginx 去前缀）；`/excelTemplate` alias |
|
||
| `freedom-admin` | `freedom-admin:latest` | Spring Boot | `8800` | 后端；日志 `/app/logs` 映射宿主 `deploy/logs/backend` |
|
||
|
||
- 公网访问：`http://124.221.214.237:8880`（frp 映射）。后端 8800 也映射了公网，一般不直接用。
|
||
- 数据库：MySQL，库 `freedom_db`；凭据由 `deploy/.env` 注入容器（后端 `application.yml` 中引用 `DB_URL` 等环境变量），**不要硬编码在镜像/代码里**。
|
||
- 容器内 `docker compose` 操作统一在 `/opt/freedom/deploy` 下执行。
|
||
|
||
### 3.3 本地开发环境
|
||
|
||
- 后端：JDK 8 + Maven（推荐 3.6.x）；启动类 `com.freedom.admin.FreedomAdminApplication`；本地端口 `8800`；连库 `freedom_db`（DB 信息在 `application.yml` / 部署机 `.env`）。
|
||
- 前端：**Node 16**（高版本 Node 可能构建失败）；建议 `npm config set registry https://registry.npmmirror.com`；`npm run serve` 默认 8080，dev `baseUrl = http://localhost:8800`（src/config/index.js）。
|
||
- 不想起后端时，可把 dev `baseUrl` 指到 `http://124.221.214.237:8800` 联调远程接口（接口不带 /api 前缀）。
|
||
|
||
---
|
||
|
||
## 4. 技术栈速览
|
||
|
||
### 后端 freedom-admin
|
||
- Spring Boot 2.7.10（Web / Security / Thymeleaf / Mail / Test）、**JDK 8**
|
||
- **MyBatis-Plus**（`BaseMapper`、`QueryWrapper`、`Page`）+ XML（`resources/mapper`）
|
||
- **Spring Security + JWT（jjwt）+ BCrypt**；自定义 `@PermitAll` 注解（忽略鉴权）
|
||
- Lombok、commons-lang3/collections4、beetl（历史遗留，谨慎使用）、guava、fastjson
|
||
- 登录/登出统一由 Security Handler 输出 JSON（已修复跨域重定向问题，见 §6）
|
||
|
||
### 前端 freedom-web
|
||
- Vue 2.x + vue-router + vuex + **iView4（`view-design`）** + less + echarts + mathjs + vue-particles（登录页粒子）
|
||
- 基于 iview-admin 模板改造；请求封装 `src/libs/axios.js` + `src/libs/api.request.js`
|
||
- **POST 请求体统一为表单编码**（axios `transformRequest` + `qs.stringify(data,{indices:false})`），后端按 POJO/form 绑定接收
|
||
- token：Cookie（`TOKEN_KEY`），`libs/util.js` 的 `getToken()`，每个请求放入 `Authorization` 头
|
||
|
||
---
|
||
|
||
## 5. 仓库结构（重要：先精读这些文件再动手）
|
||
|
||
### 5.1 后端（freedom-admin）
|
||
```
|
||
src/main/java/com/freedom/admin/
|
||
FreedomAdminApplication.java
|
||
common/ Result{code,message,data}+ok/error、ResultCode、MyException 等
|
||
base/ BaseController（含 getUsername() 取当前登录人）等
|
||
config/ WebSecurityConfig（Security/JWT 过滤器/CORS/permitAll 清单）、
|
||
MyAuthenticationSuccessHandler / MyAuthenticationFailureHandler（登录结果 JSON 化）
|
||
controller/ TSysUserController / TSysRoleController / TSysPermissionController / TSysDeptController
|
||
service/ TSysXxxService（接口）
|
||
service/impl/ TSysXxxServiceImpl（含用户-角色、角色-权限分配等事务）
|
||
entity/ TSysUser / TSysRole / TSysPermission / TSysDept / TSysUserRole / TSysRolePermission
|
||
mapper/ 接口 extends BaseMapper<TSysXxx>
|
||
src/main/resources/
|
||
application.yml 数据源/邮箱等（含敏感项，勿外泄）
|
||
mapper/*.xml 复杂 SQL
|
||
sql/init.sql 6 张 t_sys_* 建表 + 初始数据（默认管理员 admin）
|
||
Dockerfile maven3.6.3-jdk8(阿里云源) → openjdk8-jre
|
||
.gitea/workflows/deploy.yml
|
||
```
|
||
> ⚠️ `sql/init.sql` 可能滞后于生产库（尤其权限树数据），新建环境初始化后仍需要在「权限管理」界面补全菜单，或以生产库为准核对。
|
||
|
||
### 5.2 前端（freedom-web）
|
||
```
|
||
src/
|
||
config/index.js baseUrl：dev http://localhost:8800；prod /api
|
||
libs/ axios.js(拦截器/30s 超时/错误码)、api.request.js、util.js、router-util.js
|
||
router/routers.js 静态基础路由(/home /login 401 等)；业务路由由后端权限树动态注册
|
||
store/module/user.js handleLogin / getUserInfo / 登出清 token
|
||
store/module/app.js updateMenuList：权限树 → 动态 addRoutes(业务路由)
|
||
api/ 按业务域组织：sys/、kpi/、basic/（basic 为已删除的代码生成器残留，勿用）
|
||
view/ login/、home/、sys/(sys-user|sys-role|sys-dept|sys-permission)、kpi/(7 个页面)
|
||
components/login-form/
|
||
nginx.conf /api 反代后端、history 路由 try_files、/excelTemplate alias
|
||
Dockerfile node16 + npmmirror → nginx
|
||
.gitea/workflows/deploy.yml
|
||
```
|
||
- **动态菜单机制**：登录后 `getUserInfo` 拉取权限树 → `app.js` 先重置 matcher 再 `addRoutes`；
|
||
页面组件映射规则 = `@/view` + `component` 字段 + `.vue`。所以新增页面三件事缺一不可：
|
||
① `view/.../xxx.vue` 文件必须存在且路径一致；② 权限树登记（url=前端路由 path，component=相对 view 路径，无 `.vue` 无前导斜杠）；③ 给角色勾选后重新登录。
|
||
|
||
### 5.3 现状缺口（接手前务必与需求方核对）
|
||
1. 后端目前只有 **RBAC 系统管理**模块（4 个 TSysXxx controller、6 张表）。
|
||
2. 前端 **kpi/ 7 个页面 + api/kpi** 已存在，调用 `system/kpi-staff/*` 等接口，**后端无对应实现**（controller/mapper/表均无）——需确认是从零实现 KPI 后端，还是有现成实现待合入。
|
||
3. `api/basic/*` 三个文件是已被移除的「代码生成器」残留（freedom-web 历史提交 `ec2fc97 remove code generator module`），前端 view 中无对应页面。若后续要重启代码生成方向（多数据源/项目路径替换），属于**新开发**而非修复。
|
||
4. freedom-admin 本地有备份分支 `backup/pre-sync`，合入 master 前请先 diff 确认。
|
||
|
||
---
|
||
|
||
## 6. 如何新增一个功能模块（SOP）
|
||
|
||
### 6.1 后端
|
||
1. **建表**：字段风格参考 `t_sys_dept/t_sys_user`（逻辑删除 `del_flag`、审计字段 `create_by/create_time/update_by/update_time`）；DDL 落成 `sql/*.sql` 并更新 init.sql，不要只改库不留脚本。
|
||
2. **entity** `TSysXxx.java`：Lombok `@Data`、`@TableName`、`@TableId`、`@TableLogic`（参考 TSysUser）。
|
||
3. **mapper** `TSysXxxMapper extends BaseMapper<TSysXxx>`；复杂 SQL 放 `resources/mapper/TSysXxxMapper.xml`。
|
||
4. **service / impl**：参考 `TSysDeptService(Impl)` 分层，事务 `@Transactional`。
|
||
5. **controller** `TSysXxxController`：`@RequestMapping("xxx")` **不带 /api 前缀**；POST 用 POJO/表单参数接收（不要 @RequestBody JSON）；统一返回 `Result.ok()/Result.error()`；需免登录的接口加 `@PermitAll`，否则保持默认（走 JWT 鉴权）。
|
||
6. 权限粒度：若要做按钮级权限，参考现有 `@RequiresPermission` 或权限树 permissionType 用法，与现有代码保持一致。
|
||
|
||
### 6.2 前端
|
||
1. `src/view/<域>/<页面>.vue`：结构参考 `view/sys/sys-dept.vue`（Card + 查询表单 + Table + 分页 + Modal 编辑），组件直接用 `view-design`（全局注册，无需 import）。
|
||
2. `src/api/<域>/<api>.js`：仿照 `api/sys/sys-user.js`，如
|
||
`export const addXxx = data => axios.request({ url: 'xxx/add', headers: { Authorization: getToken() }, data, method: 'post' })`。
|
||
3. **登记菜单/按钮**：在系统「权限管理」中新增（或直接改 `t_sys_permission`，注意与前端字段对应）：
|
||
- 目录级：`url` 一般为前端路由前缀、`component` 留空；
|
||
- 页面级：`url = /<域>/<页面>`（vue-router path）、`component = <域>/<页面>`（相对 src/view，无 .vue、无前导斜杠）；
|
||
- 按钮级：作为页面子节点登记（permissionType/编码约定参考现网数据）。
|
||
4. **授权**：角色-权限勾选 → 重新登录生效。
|
||
5. 请求错误码统一走 axios 拦截器（见 §7），页面一般只需处理 `code === 200`。
|
||
|
||
### 6.3 联调与提交
|
||
- 本地：`mvn spring-boot:run` + `npm run serve`；远端联调改 `config/index.js` dev baseUrl。
|
||
- 验证闭环：登录态 → 菜单出现 → 增删改查 → 权限不足被拦。
|
||
- 提交规范：`feat: / fix: / docs: / style: / refactor: / ci:` 前缀 + 中文说明。
|
||
- push master 即自动构建部署生产（无预览环境）；涉及 SQL/权限变更时，在提交说明里写明需要人工执行的 SQL 与执行顺序。
|
||
|
||
---
|
||
|
||
## 7. 全局约定与易踩坑清单（务必遵守）
|
||
|
||
| # | 约定/坑 | 说明 |
|
||
|---|---|---|
|
||
| 1 | URL 无 /api 前缀 | `/api` 是 nginx 层的路径，后端 controller 不要写 /api |
|
||
| 2 | POST 表单编码 | 前端统一 qs.stringify；后端 POJO 绑定，别用 @RequestBody |
|
||
| 3 | 返回结构 | `Result{code,message,data}`；code：200 成功 / 415 账号或密码错误 / 511,512,513 token 相关问题 / 500 异常；前端会据此自动跳登录页 |
|
||
| 4 | 登录/登出是 JSON 流程 | Spring Security handler 直接输出 JSON（/login、/logout），**严禁改回 redirect**（会导致 CORS/跨域 302 与前端报错，历史已踩坑修复） |
|
||
| 5 | 登录失败文案 | `MyAuthenticationFailureHandler` 返回 code 415 + “账号或密码错误” |
|
||
| 6 | 动态路由 | 页面文件路径必须与权限树 component 完全一致，否则菜单点击无路由（白屏/跳 home） |
|
||
| 7 | 敏感信息 | DB/邮箱密码一律走部署机 `.env` 注入容器；禁止写进代码/提交/文档 |
|
||
| 8 | init.sql 可能滞后 | 权限树/菜单以生产库与「权限管理」界面为准 |
|
||
| 9 | Node 版本 | 前端必须 Node 16 附近，高版本可能构建失败 |
|
||
| 10 | CI 无自动检出 | 改 workflow 时保留手动 clone 逻辑；不要假设 $GITHUB_WORKSPACE 已含代码 |
|
||
|
||
---
|
||
|
||
## 8. 常用命令速查
|
||
|
||
```bash
|
||
# 本地后端
|
||
cd freedom-admin && mvn spring-boot:run
|
||
# 本地前端
|
||
cd freedom-web && npm install && npm run serve
|
||
# 生产（SSH 到部署机后）
|
||
cd /opt/freedom/deploy
|
||
docker compose ps
|
||
docker compose logs -f backend web
|
||
docker compose up -d --force-recreate backend # 手工发布后端
|
||
docker compose up -d --force-recreate web # 手工发布前端
|
||
cat .env # 数据库凭据（勿外泄）
|
||
# CI 排查
|
||
docker logs -f act_runner # runner 日志
|
||
# Gitea Actions 页面：检查最近一次运行是否成功、失败步骤输出
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 已知待办/需求池（开发前先确认）
|
||
|
||
1. （2026-09 完成）登录体验修复：登录错误 JSON 提示、登出 CORS/302 修复、登录页默认账号清空 + “海阔凭鱼跃，天高任鸟飞”诗句化、演示文案移除 —— 提交见 freedom-admin `59e796c/030916e`、freedom-web `7d07121/4223822`，**待线上验证**。
|
||
2. （口头需求，未开工）若重启代码生成方向：
|
||
- 系统内置多套 MyBatis 数据源信息（开发/SIT/生产等），生成时下拉选择，免手动填 `db_url/db_username/db_password`；
|
||
- 系统设置「项目管理」Tab 提供项目路径字符替换工具：快捷固定替换父目录（如 `D:/bestpay-srdcloud`）、替换账号（如 `srd17321104074`），支持对所有项目路径批量生效。
|
||
- 注意：旧代码生成模块曾存在后被移除（web `ec2fc97`），此需求属新建还是恢复需与用户确认。
|
||
3. （待确认）KPI 模块后端化：前端 7 个页面 + 6 个 API 已就绪，后端需补数据模型/表/接口，字段与业务流程请先访谈确认。
|
||
|
||
---
|
||
|
||
## 10. 附录：可参考的本地文档/文件
|
||
|
||
- `freedom-admin/docs/`：仓库内说明文档（含部署实录 CICD-DEPLOY 等）
|
||
- 工作区根 `docs/CICD-环境与进度.md`：环境与踩坑记录（含 runner、frp、镜像同步背景）
|
||
- `deploy/docker-compose.yml`、各仓库 `.gitea/workflows/deploy.yml`、`Dockerfile`、`nginx.conf`：发布链路一手配置
|