docs: 添加项目说明文档

README.md

@@ -0,0 +1,126 @@
+# Tansci — IT 资产管理平台
+
+企业级 IT 资产全生命周期管理系统，覆盖设备、许可证、配件、耗材的采购、分配、折旧、盘点、报修全流程。
+
+## 项目结构
+
+```
+tansci/
+├── antdv-next-admin/   # 前端管理后台 (Vue 3 + TypeScript + Ant Design Vue)
+├── our-itam/           # 后端服务 (Java Spring Boot + magic-api)
+├── fantastic-admin/    # 前端底层框架 (pnpm monorepo)
+├── ciyo-itasset/       # CIYO IT资产模块
+└── magic-script-skill/ # Claude Code 自定义 Skill
+```
+
+## 技术栈
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| 前端框架 | Vue 3.4 + TypeScript + Vite | 现代化 SPA 开发 |
+| UI 组件 | Ant Design Vue (antdv-next) | 企业级 UI 组件库 |
+| 状态管理 | Pinia | Vue 3 官方状态管理 |
+| 后端框架 | Spring Boot | Java 微服务框架 |
+| 低代码接口 | magic-api 2.2.2 | 在线编写 API 脚本，热加载 |
+| 认证鉴权 | Sa-Token | 轻量级权限认证框架 |
+| 数据库 | MySQL 8.0 | 关系型数据库 |
+
+## 功能模块
+
+### 资产管理
+- **设备管理** — 资产登记、状态跟踪（在库/在用/维修中/已报废）
+- **许可证管理** — 软件许可证、序列号、到期管理
+- **配件管理** — 配件库存、关联资产
+- **耗材管理** — 耗材库存、最小库存预警
+- **折旧规则** — 折旧月数、残值配置
+- **服务管理** — 云服务/订阅服务跟踪
+
+### 基础数据
+- **分类管理** — 多级分类（设备/许可证/配件/耗材/服务）
+- **位置管理** — 物理位置/楼栋/城市
+- **制造商** — 厂商信息、支持链接
+- **型号管理** — 型号关联制造商和分类
+- **供应商** — 供应商信息、联系方式
+
+### 业务管理
+- **故障报修** — 报修工单、状态流转
+- **资产盘点** — 盘点计划、执行跟踪
+- **资产分配** — 资产领用/归还
+- **资产申请** — 采购申请、审批流程
+- **交易记录** — 操作审计日志
+
+### 系统管理
+- 用户/角色/部门管理
+- 菜单与权限管理（RBAC 按钮级权限）
+- 字典管理（系统枚举值统一维护）
+
+## 快速开始
+
+### 环境要求
+
+- **前端**: Node.js >= 16, pnpm >= 8
+- **后端**: JDK >= 17, Maven >= 3.8
+- **数据库**: MySQL 8.0 (192.168.2.1:3307, 库名 `our_itam`)
+
+### 1. 数据库初始化
+
+```bash
+mysql -h 192.168.2.1 -P 3307 -u root -p our_itam < our-itam/db/init.sql
+```
+
+### 2. 启动后端服务
+
+```bash
+cd our-itam
+mvn spring-boot:run
+```
+
+后端默认端口 **9999**，API 前缀 `/magic-api/`。  
+magic-api 管理平台: http://localhost:9999/magic/web/index.html
+
+### 3. 启动前端服务
+
+```bash
+cd fantastic-admin
+pnpm install
+pnpm dev
+```
+
+启动后选择 `core-antdv-next` 进入 antdv-next-admin 前端，默认地址 http://localhost:9000/
+
+### 4. 测试账号
+
+| 账号 | 密码 | 角色 |
+|------|------|------|
+| admin | 123456 | 超级管理员 |
+
+## 开发指南
+
+### magic-api 开发注意事项
+
+- 文件位于 `our-itam/data/magic-api/api/`，按模块分目录
+- 每个分组目录必须有 `group.json`，接口文件为 `.ms` 后缀
+- `.ms` 文件包含 JSON 元数据头（name/method/path）和 magic-script 脚本体
+- 脚本语法限制：仅支持 `for (val in list)` 和 `for (index, val in list)`
+- 响应格式统一为 `{ code: 1, message: "success", data: ... }`
+- **文件变更后需重启后端才能生效**
+
+### 前端开发注意事项
+
+- 权限指令: `v-permission="'asset:device:add'"` 控制按钮显隐
+- ProTable 组件使用 `dataIndex: 'operations'` 渲染操作列
+- 表单下拉选项统一使用 `:options` 属性模式，避免 `<a-select-option>` 子组件
+- 字典数据通过 `getDictDataByType(typeCode)` 获取
+
+### 接口约定
+
+| 场景 | HTTP 方法 |
+|------|-----------|
+| 分页查询 | POST `/xxx/page` |
+| 新增/修改 | POST `/xxx/save` |
+| 删除 | POST `/xxx/delete` |
+| 列表查询 | GET `/xxx/list` |
+
+## 变更记录
+
+详见 `.claude/conversation-history/` 中的对话历史 JSONL 文件。