From 082b9b7902e15577fa5ad12d365c9427924ab12a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wei=5F=E4=BD=B3?= <weijia.svip@gmail.com>
Date: Thu, 13 Nov 2025 15:48:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E4=BA=A4=E6=98=93?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E8=8F=9C=E5=8D=95SQL=E8=84=9A=E6=9C=AC?=
 =?UTF-8?q?=E5=92=8C=E9=A1=B9=E7=9B=AE=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增交易管理菜单数据库变更SQL脚本
- 添加项目开发规范文档AGENTS.md
---
 AGENTS.md                         | 23 +++++++++++++++++++++++
 docs/sql/add_transaction_menu.sql | 24 ++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 docs/sql/add_transaction_menu.sql

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..06c8b6c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+FastAPI backend code lives in `app/`: routers under `app/api/v1`, orchestration in `app/controllers`, schemas/models in `app/schemas` and `app/models`, and shared helpers in `app/utils`. Config defaults stay in `app/settings/config.py`, migrations in `migrations/`, and the service boots through `run.py`. Frontend assets reside in `web/` with source code in `web/src`, static files in `web/public`, and build toggles in `web/settings`; deployment collateral sits in `deploy/`.
+
+## Build, Test, and Development Commands
+- `make install` (uv) or `pip install -r requirements.txt` prepares backend deps; `pnpm i` handles `web/`.
+- `make start` / `python run.py` launches the API against `db.sqlite3`; `cd web && pnpm dev` starts the SPA; `pnpm build` prepares production assets.
+- `make check` runs Black+isort in check mode plus Ruff; `make format` applies fixes; `make lint` is Ruff-only.
+- `make test` loads `.env` variables into the shell and executes `pytest -vv -s`; target files with `pytest tests/api/test_x.py -k keyword`.
+- Database maintenance: `make migrate` (generate Aerich migrations), `make upgrade` (apply), `make clean-db` (reset SQLite + migrations).
+
+## Coding Style & Naming Conventions
+Python follows Black (120 columns), isort’s Black profile, and Ruff; keep modules snake_case and Pydantic models PascalCase. Vue code respects the repo ESLint + UnoCSS presets, uses TypeScript script blocks, and keeps component directories kebab-case; run `pnpm lint` or `pnpm lint:fix` as needed.
+
+## Testing Guidelines
+Back-end features need pytest coverage mirroring the `app` layout—e.g., `tests/api/v1/test_users.py` for router logic and async tests following the patterns in `test_dynamic_default.py`. Seed deterministic data via fixtures instead of the shared `db.sqlite3`, and document any `.env` flags a test requires. Frontend changes should gain vitest or Playwright checks under `web/tests` before UI regressions reach `main`.
+
+## Commit & Pull Request Guidelines
+Stick to Conventional Commit prefixes already present (`feat:`, `refactor:`, `debug:`) and keep subject lines imperative with optional scopes (`feat(api):`). Each PR must summarize changes, list verification commands, reference related issues, and attach UI screenshots/GIFs when touching `web/`. Run `make check` and relevant tests locally, avoid committing `web/dist` or SQLite WAL files, and prefer small, reviewable diffs.
+
+## Security & Configuration Tips
+Secrets belong in `.env`, which `app/settings/config.py` loads automatically; rotate `SECRET_KEY`, JWT parameters, and database credentials before deployment. Swap the Tortoise connection from SQLite to MySQL/PostgreSQL by editing the provided templates and running `make migrate && make upgrade`. Lock down CORS (`CORS_ORIGINS`) before exposing the API publicly.
diff --git a/docs/sql/add_transaction_menu.sql b/docs/sql/add_transaction_menu.sql
new file mode 100644
index 0000000..3c15312
--- /dev/null
+++ b/docs/sql/add_transaction_menu.sql
@@ -0,0 +1,24 @@
+-- 新增交易管理菜单
+-- 创建时间: 2025-11-13
+
+-- 插入一级目录：交易管理
+INSERT INTO menu (id, name, menu_type, icon, path, 'order', parent_id, is_hidden, component, keepalive, redirect, created_at, updated_at)
+VALUES 
+  (16, '交易管理', 'catalog', 'carbon:receipt', '/transaction', 3, 0, 0, 'Layout', 0, '/transaction/invoice', datetime('now'), datetime('now'));
+
+-- 插入二级菜单：开票记录
+INSERT INTO menu (id, name, menu_type, icon, path, 'order', parent_id, is_hidden, component, keepalive, redirect, created_at, updated_at)
+VALUES 
+  (17, '开票记录', 'menu', 'carbon:document', 'invoice', 1, 16, 0, '/transaction/invoice', 0, NULL, datetime('now'), datetime('now'));
+
+-- 为管理员角色分配菜单权限
+INSERT INTO role_menu (role_id, menu_id) 
+VALUES 
+  (1, 16),
+  (1, 17);
+
+-- 为普通用户角色分配菜单权限
+INSERT INTO role_menu (role_id, menu_id) 
+VALUES 
+  (2, 16),
+  (2, 17);